diff options
| author | Dennis Fink | 2026-11-18 08:01:26 +0100 |
|---|---|---|
| committer | Dennis Fink | 2026-11-18 08:01:26 +0100 |
| commit | b908ee61770dc78f8d8fbbbfc4f3c00d7877d42a (patch) | |
| tree | 322d85654e5518c2836ce57beafaa7e2abaab741 /webmentions_ssg | |
| parent | 63af533d98aac82b6d4f069b217d3e837285508d (diff) | |
| download | webmentions-ssg-b908ee61770dc78f8d8fbbbfc4f3c00d7877d42a.tar.gz webmentions-ssg-b908ee61770dc78f8d8fbbbfc4f3c00d7877d42a.zip | |
feat(core): add dashboard overview
Replace the root redirect with an authenticated dashboard showing
received and outgoing status counts, recent activity, pending sends,
retries, and queue depth.
Persist the last completed source scan so operational status survives
restarts and only advances after a successful, conclusive scan.
Diffstat (limited to 'webmentions_ssg')
| -rw-r--r-- | webmentions_ssg/migrations/versions/2b4c6e8a0d12_last_completed_source_scan.py | 38 | ||||
| -rw-r--r-- | webmentions_ssg/models/scan_state.py | 23 | ||||
| -rw-r--r-- | webmentions_ssg/tasks/scanner.py | 6 | ||||
| -rw-r--r-- | webmentions_ssg/templates/base.html | 2 | ||||
| -rw-r--r-- | webmentions_ssg/templates/dashboard.html | 148 | ||||
| -rw-r--r-- | webmentions_ssg/views/__init__.py | 3 | ||||
| -rw-r--r-- | webmentions_ssg/views/dashboard.py | 123 | ||||
| -rw-r--r-- | webmentions_ssg/views/session.py | 9 |
8 files changed, 342 insertions, 10 deletions
diff --git a/webmentions_ssg/migrations/versions/2b4c6e8a0d12_last_completed_source_scan.py b/webmentions_ssg/migrations/versions/2b4c6e8a0d12_last_completed_source_scan.py new file mode 100644 index 0000000..168647f --- /dev/null +++ b/webmentions_ssg/migrations/versions/2b4c6e8a0d12_last_completed_source_scan.py @@ -0,0 +1,38 @@ +# SPDX-FileCopyrightText: 2026 Dennis Fink <me+coding@dennisfink.me> +# +# SPDX-License-Identifier: BSD-3-Clause + +"""Track the last successful source scan. + +Revision ID: 2b4c6e8a0d12 +Revises: ef8a9b6c2d41 +""" + +import sqlalchemy as sa +from alembic import op + +revision = "2b4c6e8a0d12" +down_revision = "ef8a9b6c2d41" +branch_labels = None +depends_on = None + + +def upgrade(): + op.create_table( + "scan_state", + sa.Column("id", sa.Integer(), primary_key=True), + sa.Column("last_completed_at", sa.DateTime(timezone=True), nullable=False), + ) + # Seed a best-effort historical completion time from previously scanned + # sources. The next completed scan will update the authoritative value. + op.execute( + sa.text( + "INSERT INTO scan_state (id, last_completed_at) " + "SELECT 1, MAX(last_seen_at) FROM source_documents " + "HAVING COUNT(*) > 0" + ) + ) + + +def downgrade(): + op.drop_table("scan_state") diff --git a/webmentions_ssg/models/scan_state.py b/webmentions_ssg/models/scan_state.py new file mode 100644 index 0000000..924c15d --- /dev/null +++ b/webmentions_ssg/models/scan_state.py @@ -0,0 +1,23 @@ +# SPDX-FileCopyrightText: 2026 Dennis Fink <me+coding@dennisfink.me> +# +# SPDX-License-Identifier: BSD-3-Clause + +"""Persist the last completed source scan for this single-site service.""" + +from datetime import datetime + +from sqlalchemy import DateTime, Integer +from sqlalchemy.orm import Mapped, mapped_column + +from ..extensions import Base + + +class ScanState(Base): + """The single row tracking the most recent successful source scan.""" + + __tablename__ = "scan_state" + + id: Mapped[int] = mapped_column(Integer, primary_key=True) + last_completed_at: Mapped[datetime] = mapped_column( + DateTime(timezone=True), nullable=False + ) diff --git a/webmentions_ssg/tasks/scanner.py b/webmentions_ssg/tasks/scanner.py index 1f98702..9058b9b 100644 --- a/webmentions_ssg/tasks/scanner.py +++ b/webmentions_ssg/tasks/scanner.py @@ -14,6 +14,7 @@ from huey.exceptions import RetryTask, TaskLockedException from sqlalchemy.orm import selectinload from ..extensions import db, huey +from ..models.scan_state import ScanState from ..models.sources import SentWebmention, SourceDocument from ..net import is_http_url from .sender import send_webmention @@ -304,6 +305,11 @@ def _scan_and_enqueue() -> None: db.session.commit() pending_count = enqueue_due_sends(scan_time) + # Mark a scan complete only after reconciliation and task enqueueing have + # succeeded. An inconclusive or interrupted scan keeps the previous value. + db.session.merge(ScanState(id=1, last_completed_at=datetime.now(UTC))) + db.session.commit() + current_app.logger.info( "Webmention source scan complete: %d sources scanned, " "%d missing sources, %d pending sends", diff --git a/webmentions_ssg/templates/base.html b/webmentions_ssg/templates/base.html index 4fffb38..115f193 100644 --- a/webmentions_ssg/templates/base.html +++ b/webmentions_ssg/templates/base.html @@ -43,6 +43,8 @@ SPDX-License-Identifier: BSD-3-Clause </a> {% if current_user.is_authenticated %} <div class="navbar-nav flex-row gap-3"> + <a class="nav-link{% if request.endpoint == 'webmentions.index' %} active{% endif %}" + href="{{ url_for('webmentions.index') }}">Dashboard</a> <a class="nav-link{% if request.endpoint in ('webmentions.received_list', 'webmentions.received_detail') %} active{% endif %}" href='{{ url_for("webmentions.received_list") }}'>Received</a> <a class="nav-link{% if request.endpoint and request.endpoint.startswith('webmentions.moderation') %} active{% endif %}" diff --git a/webmentions_ssg/templates/dashboard.html b/webmentions_ssg/templates/dashboard.html new file mode 100644 index 0000000..a7f968e --- /dev/null +++ b/webmentions_ssg/templates/dashboard.html @@ -0,0 +1,148 @@ +<!-- +SPDX-FileCopyrightText: 2026 Dennis Fink <me+coding@dennisfink.me> + +SPDX-License-Identifier: BSD-3-Clause +--> +{% extends "base.html" %} + +{% block content %} + <div class="d-flex justify-content-between align-items-center mb-4"> + <h1 class="mb-0">Dashboard</h1> + <span class="text-body-secondary">Single-site overview</span> + </div> + + <div class="row g-4 mb-4"> + <section class="col-lg-6" aria-labelledby="received-summary"> + <div class="card h-100"> + <div class="card-body"> + <div class="d-flex justify-content-between align-items-center mb-3"> + <h2 class="h4 mb-0" id="received-summary">Received</h2> + <a href="{{ url_for('webmentions.received_list') }}">View all</a> + </div> + <p class="display-6 mb-3">{{ received_total }} <span class="fs-6 text-body-secondary">total</span></p> + <div class="row row-cols-2 g-3"> + <div class="col"> + <a href="{{ url_for('webmentions.received_list', status='pending') }}">Pending</a> + <div class="h3">{{ received_counts.received }}</div> + </div> + <div class="col"> + <a href="{{ url_for('webmentions.received_list', status='verifying') }}">Verifying</a> + <div class="h3">{{ received_counts.verifying }}</div> + </div> + <div class="col"> + <a href="{{ url_for('webmentions.received_list', status='verified') }}">Verified</a> + <div class="h3">{{ received_counts.verified }}</div> + </div> + <div class="col"> + <a href="{{ url_for('webmentions.received_list', status='declined') }}">Declined</a> + <div class="h3">{{ received_counts.failed + received_counts.source_removed }}</div> + <p class="small text-body-secondary mb-0">Failed: {{ received_counts.failed }} ยท Source removed: {{ received_counts.source_removed }}</p> + </div> + </div> + </div> + </div> + </section> + + <section class="col-lg-6" aria-labelledby="sent-summary"> + <div class="card h-100"> + <div class="card-body"> + <div class="d-flex justify-content-between align-items-center mb-3"> + <h2 class="h4 mb-0" id="sent-summary">Outgoing</h2> + <a href="{{ url_for('webmentions.source_list') }}">View sources</a> + </div> + <p class="display-6 mb-3">{{ sent_total }} <span class="fs-6 text-body-secondary">total</span></p> + <div class="row row-cols-2 g-3"> + <div class="col"> + <div>Sent</div> + <div class="h3">{{ sent_counts.sent }}</div> + </div> + <div class="col"> + <div>No endpoint</div> + <div class="h3">{{ sent_counts.no_endpoint }}</div> + </div> + <div class="col"> + <div>Failed (final)</div> + <div class="h3">{{ sent_counts.failed }}</div> + </div> + <div class="col"> + <div>Not attempted</div> + <div class="h3">{{ not_attempted }}</div> + </div> + <div class="col"> + <div>Pending</div> + <div class="h3">{{ pending_sends }}</div> + <p class="small text-body-secondary mb-0">Waiting to retry: {{ waiting_retries }}</p> + </div> + </div> + </div> + </div> + </section> + </div> + + <section class="mb-4" aria-labelledby="recent-activity"> + <h2 class="h4" id="recent-activity">Recent activity</h2> + <div class="table-responsive"> + <table class="table table-bordered align-middle"> + <thead> + <tr> + <th scope="col">Activity (UTC)</th> + <th scope="col">Last 7 days</th> + <th scope="col">Last 30 days</th> + </tr> + </thead> + <tbody> + <tr> + <th scope="row">New received Webmentions</th> + <td>{{ recent[7].received }}</td> + <td>{{ recent[30].received }}</td> + </tr> + <tr> + <th scope="row">Webmentions last sent successfully</th> + <td>{{ recent[7].sent }}</td> + <td>{{ recent[30].sent }}</td> + </tr> + </tbody> + </table> + </div> + </section> + + <section aria-labelledby="operations"> + <h2 class="h4" id="operations">Operations</h2> + <div class="row g-3"> + <div class="col-md-4"> + <div class="card h-100"> + <div class="card-body"> + <h3 class="h6 text-body-secondary">Source documents</h3> + <p class="h3 mb-0">{{ source_count }}</p> + </div> + </div> + </div> + <div class="col-md-4"> + <div class="card h-100"> + <div class="card-body"> + <h3 class="h6 text-body-secondary">Last completed source scan</h3> + {% if last_scan %} + <time datetime="{{ last_scan.isoformat() }}" class="fs-5"> + {{ last_scan.strftime("%Y-%m-%d %H:%M:%S") }} UTC + </time> + {% else %} + <p class="text-body-secondary mb-0">No completed scan yet</p> + {% endif %} + </div> + </div> + </div> + <div class="col-md-4"> + <div class="card h-100"> + <div class="card-body"> + <h3 class="h6 text-body-secondary">Huey pending tasks</h3> + {% if queue_size is not none %} + <p class="h3 mb-0">{{ queue_size }}</p> + {% else %} + <p class="text-body-secondary mb-0">Unavailable</p> + {% endif %} + </div> + </div> + </div> + </div> + </section> +{% endblock %} diff --git a/webmentions_ssg/views/__init__.py b/webmentions_ssg/views/__init__.py index a4954b6..5abaa14 100644 --- a/webmentions_ssg/views/__init__.py +++ b/webmentions_ssg/views/__init__.py @@ -4,10 +4,11 @@ """Collect and expose the routes for the blueprint.""" -from . import endpoint, moderation, received, session, sources, user +from . import dashboard, endpoint, moderation, received, session, sources, user from .blueprint import webmentions_bp __all__ = [ + "dashboard", "endpoint", "moderation", "received", diff --git a/webmentions_ssg/views/dashboard.py b/webmentions_ssg/views/dashboard.py new file mode 100644 index 0000000..26b0134 --- /dev/null +++ b/webmentions_ssg/views/dashboard.py @@ -0,0 +1,123 @@ +# SPDX-FileCopyrightText: 2026 Dennis Fink <me+coding@dennisfink.me> +# +# SPDX-License-Identifier: BSD-3-Clause + +"""A private, single-site overview of incoming and outgoing Webmentions.""" + +from datetime import UTC, datetime, timedelta +from uuid import UUID + +import sqlalchemy as sa +from flask import current_app, render_template +from flask.typing import ResponseReturnValue +from flask_login import login_required + +from ..extensions import db, huey +from ..models.received import ReceivedWebmention, ReceivedWebmentionStatus +from ..models.scan_state import ScanState +from ..models.sources import SentWebmention, SentWebmentionStatus, SourceDocument +from .blueprint import webmentions_bp + + +def uuid7_lower_bound(at: datetime) -> UUID: + """Get the smallest UUIDv7 with a creation time at or after ``at``. + + Received Webmentions store their creation time in their UUIDv7 primary key, + not in a separate timestamp column. UUIDv7 orders by Unix milliseconds. + """ + milliseconds = int(at.timestamp() * 1000) + return UUID(int=(milliseconds << 80) | (7 << 76)) + + +@webmentions_bp.get("/") +@login_required +def index() -> ResponseReturnValue: + """Show persisted site activity, delivery health, and worker queue depth.""" + now = datetime.now(UTC) + + received_counts = dict( + db.session.execute( + sa.select(ReceivedWebmention.status, sa.func.count()).group_by( + ReceivedWebmention.status + ) + ).all() + ) + + sent_counts = dict( + db.session.execute( + sa.select(SentWebmention.status, sa.func.count()) + .where(~SentWebmention.awaiting_processing) + .group_by(SentWebmention.status) + ).all() + ) + + pending_sends = db.session.scalar( + sa.select(sa.func.count()) + .select_from(SentWebmention) + .where(SentWebmention.awaiting_processing) + ) + + # A claimed attempt also has a future deadline, but isn't necessarily a + # retry. Only show failed attempts awaiting their next scheduled retry. + waiting_retries = db.session.scalar( + sa.select(sa.func.count()) + .select_from(SentWebmention) + .where( + SentWebmention.awaiting_processing, + SentWebmention.status == SentWebmentionStatus.FAILED, + SentWebmention.next_retry_at > now, + ) + ) + + recent: dict[int, dict[str, int]] = {} + for days in (7, 30): + cutoff = now - timedelta(days=days) + recent[days] = { + "received": db.session.scalar( + sa.select(sa.func.count()) + .select_from(ReceivedWebmention) + .where(ReceivedWebmention.uuid >= uuid7_lower_bound(cutoff)) + ) + or 0, + "sent": db.session.scalar( + sa.select(sa.func.count()) + .select_from(SentWebmention) + .where(SentWebmention.last_sent_at >= cutoff) + ) + or 0, + } + + try: + queue_size = huey.huey.pending_count() + except Exception: + current_app.logger.exception("Could not read Huey pending queue depth") + queue_size = None + + scan = db.session.get(ScanState, 1) + last_scan = scan.last_completed_at if scan is not None else None + # SQLite drops timezone information when reading DateTime columns. + if last_scan is not None and last_scan.tzinfo is None: + last_scan = last_scan.replace(tzinfo=UTC) + + sources = db.session.scalar(sa.select(sa.func.count()).select_from(SourceDocument)) + + return render_template( + "dashboard.html", + title="Dashboard", + received_counts={ + status.value: received_counts.get(status, 0) + for status in ReceivedWebmentionStatus + }, + received_total=sum(received_counts.values()), + sent_counts={ + status.value: sent_counts.get(status, 0) for status in SentWebmentionStatus + }, + sent_total=sum(sent_counts.values()) + (pending_sends or 0), + not_attempted=sent_counts.get(None, 0), + pending_sends=pending_sends or 0, + waiting_retries=waiting_retries or 0, + recent=recent, + source_count=sources or 0, + last_scan=last_scan, + queue_size=queue_size, + ) diff --git a/webmentions_ssg/views/session.py b/webmentions_ssg/views/session.py index 78d1ed6..99c0a1c 100644 --- a/webmentions_ssg/views/session.py +++ b/webmentions_ssg/views/session.py @@ -17,15 +17,6 @@ from ..models.user import User from .blueprint import webmentions_bp -@webmentions_bp.route("/") -def index() -> ResponseReturnValue: - """Redirect to the received Webmentions view. - - :returns: Redirect response to the received Webmentions view. - """ - return redirect(url_for("webmentions.received_list")) - - @webmentions_bp.route("/login", methods=["GET", "POST"]) @limiter.limit( lambda: current_app.config["LOGIN_USERNAME_RATE_LIMIT"], |
