From ef90dc381322122ecfb9af039cf790de92807514 Mon Sep 17 00:00:00 2001 From: Dennis Fink Date: Sat, 21 Nov 2026 14:49:28 +0100 Subject: feat(sender): split source and delivery history Add per-Webmention detail pages so delivery state, failure guidance, status URLs, and delivery history no longer crowd the source overview. Track source lifecycle events separately for discovery, revision, deletion, and restoration, and add a source-level action to resend only failed Webmentions. --- .../4e6fbc9d207a_source_document_events.py | 53 +++++ webmentions_ssg/models/sources.py | 49 ++++- webmentions_ssg/tasks/scanner.py | 5 + webmentions_ssg/templates/moderation.html | 2 +- webmentions_ssg/templates/received.html | 8 +- webmentions_ssg/templates/sent.html | 37 ++-- webmentions_ssg/templates/sent_source.html | 227 ++++++--------------- .../templates/sent_webmention_detail.html | 176 ++++++++++++++++ webmentions_ssg/views/__init__.py | 4 +- webmentions_ssg/views/sent.py | 97 ++++++++- 10 files changed, 449 insertions(+), 209 deletions(-) create mode 100644 webmentions_ssg/migrations/versions/4e6fbc9d207a_source_document_events.py create mode 100644 webmentions_ssg/templates/sent_webmention_detail.html (limited to 'webmentions_ssg') diff --git a/webmentions_ssg/migrations/versions/4e6fbc9d207a_source_document_events.py b/webmentions_ssg/migrations/versions/4e6fbc9d207a_source_document_events.py new file mode 100644 index 0000000..eb162dd --- /dev/null +++ b/webmentions_ssg/migrations/versions/4e6fbc9d207a_source_document_events.py @@ -0,0 +1,53 @@ +# SPDX-FileCopyrightText: 2026 Dennis Fink +# +# SPDX-License-Identifier: BSD-3-Clause + +"""Record source-document lifecycle history separately from deliveries. + +Revision ID: 4e6fbc9d207a +Revises: c8fa49e1a203 +""" + +import sqlalchemy as sa +from alembic import op + +revision = "4e6fbc9d207a" +down_revision = "c8fa49e1a203" +branch_labels = None +depends_on = None + + +def upgrade() -> None: + op.create_table( + "source_document_events", + sa.Column("id", sa.Integer(), primary_key=True, autoincrement=True), + sa.Column("source_uuid", sa.Uuid(), nullable=False), + sa.Column("action", sa.String(length=80), nullable=False), + sa.Column("revision", sa.Integer(), nullable=False), + sa.Column("occurred_at", sa.DateTime(timezone=True), nullable=False), + sa.ForeignKeyConstraint( + ["source_uuid"], ["source_documents.uuid"], ondelete="CASCADE" + ), + ) + op.create_index( + "ix_source_document_events_source_id", + "source_document_events", + ["source_uuid", "id"], + ) + # The old schema did not retain lifecycle transitions. Seed one honest + # baseline snapshot per existing source; do not fabricate earlier events. + op.execute( + sa.text( + """INSERT INTO source_document_events + (source_uuid, action, revision, occurred_at) + SELECT uuid, 'Existing source at upgrade', revision, CURRENT_TIMESTAMP + FROM source_documents""" + ) + ) + + +def downgrade() -> None: + op.drop_index( + "ix_source_document_events_source_id", table_name="source_document_events" + ) + op.drop_table("source_document_events") diff --git a/webmentions_ssg/models/sources.py b/webmentions_ssg/models/sources.py index 9fc4212..9f2c2fc 100644 --- a/webmentions_ssg/models/sources.py +++ b/webmentions_ssg/models/sources.py @@ -23,7 +23,13 @@ from sqlalchemy import ( Uuid, ) from sqlalchemy.ext.hybrid import hybrid_property -from sqlalchemy.orm import Mapped, mapped_column, relationship, validates +from sqlalchemy.orm import ( + Mapped, + mapped_column, + object_session, + relationship, + validates, +) from ..extensions import Base from .utils import target_digest, uuid7_to_datetime @@ -65,6 +71,23 @@ class SourceDocument(Base): sent_webmentions: Mapped[list[SentWebmention]] = relationship( back_populates="source", cascade="all, delete-orphan" ) + history_events: Mapped[list[SourceDocumentEvent]] = relationship( + back_populates="source", cascade="all, delete-orphan" + ) + + def record_event(self, action: str, *, at: datetime | None = None) -> None: + """Record a source lifecycle change without including delivery events.""" + event = SourceDocumentEvent( + action=action, + revision=self.revision if self.revision is not None else 1, + occurred_at=at or datetime.now(UTC), + ) + if session := object_session(self): + # Do not load the entire history just to append one new event. + event.source = self + session.add(event) + else: + self.history_events.append(event) def __repr__(self) -> str: """Represent the source by its public URL.""" @@ -301,3 +324,27 @@ class SentWebmentionStatusEvent(Base): "ix_sent_webmention_status_events_webmention_id", "webmention_uuid", "id" ), ) + + +class SourceDocumentEvent(Base): + """Record discovery, revision, removal, and restoration of a source page.""" + + __tablename__ = "source_document_events" + + id: Mapped[int] = mapped_column(Integer(), primary_key=True, autoincrement=True) + source_uuid: Mapped[UUID] = mapped_column( + Uuid(as_uuid=True), + ForeignKey("source_documents.uuid", ondelete="CASCADE"), + nullable=False, + ) + action: Mapped[str] = mapped_column(String(80), nullable=False) + revision: Mapped[int] = mapped_column(Integer(), nullable=False) + occurred_at: Mapped[datetime] = mapped_column( + DateTime(timezone=True), nullable=False + ) + + source: Mapped[SourceDocument] = relationship(back_populates="history_events") + + __table_args__ = ( + Index("ix_source_document_events_source_id", "source_uuid", "id"), + ) diff --git a/webmentions_ssg/tasks/scanner.py b/webmentions_ssg/tasks/scanner.py index 9058b9b..6d4045e 100644 --- a/webmentions_ssg/tasks/scanner.py +++ b/webmentions_ssg/tasks/scanner.py @@ -49,6 +49,8 @@ def build_source(scanned: ScannedSource, scan_time: datetime) -> SourceDocument: deleted_at=None, ) + source.record_event("Discovered", at=scan_time) + for target in scanned.targets: source.sent_webmentions.append( SentWebmention(target=target, linked=True, desired_revision=1) @@ -83,10 +85,12 @@ def apply_scan_to_source( if source.deleted_at is None and source.content_hash == scanned.content_hash: return source + restored = source.deleted_at is not None source.revision += 1 source.content_hash = scanned.content_hash source.revised_at = scan_time source.deleted_at = None + source.record_event("Restored" if restored else "Revised", at=scan_time) existing = {webmention.target: webmention for webmention in source.sent_webmentions} @@ -219,6 +223,7 @@ def mark_missing_sources_deleted( source.revision += 1 source.revised_at = scan_time source.deleted_at = scan_time + source.record_event("Deleted", at=scan_time) marked += 1 for webmention in source.sent_webmentions: diff --git a/webmentions_ssg/templates/moderation.html b/webmentions_ssg/templates/moderation.html index 3c1e549..2fd922b 100644 --- a/webmentions_ssg/templates/moderation.html +++ b/webmentions_ssg/templates/moderation.html @@ -54,7 +54,7 @@ SPDX-License-Identifier: BSD-3-Clause method="post"> + class="btn btn-sm btn-danger">{{ "Unblock" if kind == "blocked" else "Remove" }} diff --git a/webmentions_ssg/templates/received.html b/webmentions_ssg/templates/received.html index e7ec5a8..323475a 100644 --- a/webmentions_ssg/templates/received.html +++ b/webmentions_ssg/templates/received.html @@ -81,7 +81,7 @@ SPDX-License-Identifier: BSD-3-Clause
Clear + class="btn btn-secondary">Clear
0 selected
Clear + class="btn btn-secondary">Clear
-
+
-

Details

+

Source details

-
Source ID
-
- {{ source.uuid }} -
-
Content hash
-
- {{ source.content_hash }} -
Path
{{ source.path }} @@ -57,46 +45,53 @@ SPDX-License-Identifier: BSD-3-Clause
{{ source.url }}
+
Revision
+
+ {{ source.revision }} +
Created
+ title="{{ source.created_at | utc_timestamp }}">{{ source.created_at | relative_time }}
Last seen
+ title="{{ source.last_seen_at | utc_timestamp }}">{{ source.last_seen_at | relative_time }}
-
Revised
+
Last revised
+ title="{{ source.revised_at | utc_timestamp }}">{{ source.revised_at | relative_time }}
-
Deleted
-
- {% if source.deleted_at is none %} - Never - {% else %} + {% if source.deleted_at is not none %} +
Deleted
+
- {% endif %} + title="{{ source.deleted_at | utc_timestamp }}">{{ source.deleted_at | relative_time }} +
+ {% endif %} +
Source ID
+
+ {{ source.uuid }}
-
Revision
+
Content hash
- {{ source.revision }} + {{ source.content_hash }}
+ + Details {% endfor %} @@ -247,35 +157,18 @@ SPDX-License-Identifier: BSD-3-Clause

No Webmentions have been discovered for this source.

{% endif %} -
-

Status history

+
+

Source history

{% if history.items %} -
    +
      {% for event in history.items %} - {% set style = sent_status_presentation.get(event.status, {"badge_class": "text-bg-info", "label": "Pending"}) %} -
    1. -
      -
      - {{ style.label }} - {{ event.action }} - -
      - -
      - Revision {{ event.revision }} · Attempt {{ event.attempt_count }} - {% if event.endpoint_response_status is not none %} - · HTTP {{ event.endpoint_response_status }} - {% endif %} -
      - {% if event.failure_reason %} -
      {{ render_failure(event.failure_reason, "sent") }}
      - {% endif %} +
    2. +
      + {{ event.action }} + Revision {{ event.revision }} +
    3. {% endfor %} @@ -291,12 +184,12 @@ SPDX-License-Identifier: BSD-3-Clause source_page=source_page if source_page > 1 else none, webmentions_page=webmentions.page if webmentions.page > 1 else none ), - fragment='status-history-heading' + fragment='source-history-heading' ) }}
{% endif %} {% else %} -

No historical delivery events were recorded for this source. Current Webmention statuses appear above.

+

No source lifecycle events have been recorded yet. Delivery history is available on each Webmention's detail page.

{% endif %} {% include "includes/confirmation_modal.html" %} diff --git a/webmentions_ssg/templates/sent_webmention_detail.html b/webmentions_ssg/templates/sent_webmention_detail.html new file mode 100644 index 0000000..fc7d7a4 --- /dev/null +++ b/webmentions_ssg/templates/sent_webmention_detail.html @@ -0,0 +1,176 @@ + +{% extends "base.html" %} + +{% from "bootstrap5/pagination.html" import render_pagination %} +{% from "includes/failure_guidance.html" import render_failure %} +{% set sent_status_presentation = { + "sent": { + "badge_class": "text-bg-success", + "label": "Sent" + }, + "no_endpoint": { + "badge_class": "text-bg-warning", + "label": "Unsupported" + }, + "failed": { + "badge_class": "text-bg-danger", + "label": "Failed" + } +} %} + +{% block content %} +
+ ← Back to source Webmentions +
+
+

Sent Webmention

+ {% set style = sent_status_presentation.get(webmention.status, {"badge_class": "text-bg-info", "label": "Pending"}) %} + {{ style.label }} +
+
+
+

Delivery details

+
+
Source
+
+ {{ source.url }} +
+
Target
+
+ {{ webmention.target }} +
+
Link
+
+ {{ 'Linked' if webmention.linked else 'Removed' }} +
+
Created
+
+ +
+
Revisions
+
+ Desired {{ webmention.desired_revision }} · Processed {{ webmention.processed_revision if webmention.processed_revision is not none else '—' }} · Sent {{ webmention.sent_revision if webmention.sent_revision is not none else '—' }} +
+
Attempts
+
+ {{ webmention.attempt_count }} +
+ {% if webmention.next_retry_at is not none and webmention.awaiting_processing %} +
Next retry
+
+ +
+ {% endif %} +
Last attempted
+
+ {% if webmention.last_attempted_at is not none %} + +{% else %}—{% endif %} +
+
Last sent
+
+ {% if webmention.last_sent_at is not none %} + +{% else %}—{% endif %} +
+ {% if webmention.webmention_endpoint is not none %} +
Endpoint
+
+ {{ webmention.webmention_endpoint }} +
+ {% endif %} + {% if webmention.endpoint_response_status is not none %} +
Endpoint HTTP
+
+ {{ webmention.endpoint_response_status }} +
+ {% endif %} + {% if webmention.status_url is not none %} +
Status URL
+
+ {% if webmention.status_url | is_http_url %}{{ webmention.status_url }}{% else %}{{ webmention.status_url }}{% endif %} +
+ {% endif %} + {% if webmention.failure_reason %} +
Failure
+
+ {{ render_failure(webmention.failure_reason, "sent") }} +
+ {% endif %} +
Webmention ID
+
+ {{ webmention.uuid }} +
+
+
+
+
+ +
+
+

Delivery history

+ {% if history.items %} +
    + {% for event in history.items %} + {% set event_style = sent_status_presentation.get(event.status, {"badge_class": "text-bg-info", "label": "Pending"}) %} +
  1. +
    + {{ event_style.label }} + {{ event.action }} + +
    +
    + Revision {{ event.revision }} · Attempt {{ event.attempt_count }} + {% if event.endpoint_response_status is not none %}· HTTP {{ event.endpoint_response_status }}{% endif %} +
    + {% if event.failure_reason %} +
    {{ render_failure(event.failure_reason, "sent") }}
    + {% endif %} +
  2. + {% endfor %} +
+ {% if history.pages > 1 %} +
+ {{ render_pagination( + history, + endpoint='webmentions.sent_webmention_history_pagination', + args=dict( + filters, + source_uuid=source.uuid, + webmention_uuid=webmention.uuid, + source_page=source_page if source_page > 1 else none, + webmentions_page=webmentions_page if webmentions_page > 1 else none + ), + fragment='status-history-heading' + ) }} +
+ {% endif %} + {% else %} +

No delivery events have been recorded for this Webmention yet.

+ {% endif %} +
+ {% include "includes/confirmation_modal.html" %} +{% endblock %} + +{% block scripts %} + {{ super() }} + +{% endblock %} diff --git a/webmentions_ssg/views/__init__.py b/webmentions_ssg/views/__init__.py index 1701838..0f8efbc 100644 --- a/webmentions_ssg/views/__init__.py +++ b/webmentions_ssg/views/__init__.py @@ -4,7 +4,7 @@ """Collect and expose the routes for the blueprint.""" -from . import dashboard, endpoint, moderation, received, session, sent, user +from . import dashboard, endpoint, moderation, received, sent, session, user from .blueprint import webmentions_bp __all__ = [ @@ -12,8 +12,8 @@ __all__ = [ "endpoint", "moderation", "received", - "session", "sent", + "session", "user", "webmentions_bp", ] diff --git a/webmentions_ssg/views/sent.py b/webmentions_ssg/views/sent.py index 614d486..10ad34b 100644 --- a/webmentions_ssg/views/sent.py +++ b/webmentions_ssg/views/sent.py @@ -13,7 +13,6 @@ import sqlalchemy as sa from flask import abort, current_app, flash, redirect, render_template, request, url_for from flask.typing import ResponseReturnValue from flask_login import login_required -from sqlalchemy.orm import selectinload from ..extensions import db from ..failure_guidance import describe_sent_failure @@ -24,6 +23,7 @@ from ..models.sources import ( SentWebmentionStatus, SentWebmentionStatusEvent, SourceDocument, + SourceDocumentEvent, ) from ..tasks.scanner import manual_scan_sources from ..tasks.sender import send_webmention @@ -39,6 +39,11 @@ webmentions_bp.add_url_rule( endpoint="sent_source_history_pagination", build_only=True, ) +webmentions_bp.add_url_rule( + "/sent//", + endpoint="sent_webmention_history_pagination", + build_only=True, +) @webmentions_bp.url_defaults @@ -46,7 +51,10 @@ def sent_history_pagination_url_defaults( endpoint: str, values: dict[str, object] ) -> None: """Map the macro's page number to the history pagination parameter.""" - if endpoint != "webmentions.sent_source_history_pagination": + if endpoint not in ( + "webmentions.sent_source_history_pagination", + "webmentions.sent_webmention_history_pagination", + ): return values["history_page"] = values.pop("page") @@ -246,11 +254,9 @@ def sent_source_detail(source_uuid: uuid.UUID) -> ResponseReturnValue: ) history = db.paginate( - sa.select(SentWebmentionStatusEvent) - .join(SentWebmention) - .options(selectinload(SentWebmentionStatusEvent.webmention)) - .where(SentWebmention.source_uuid == source.uuid) - .order_by(SentWebmentionStatusEvent.id.desc()), + sa.select(SourceDocumentEvent) + .where(SourceDocumentEvent.source_uuid == source.uuid) + .order_by(SourceDocumentEvent.id.desc()), page=request.args.get("history_page", 1, type=int), per_page=25, error_out=False, @@ -268,6 +274,39 @@ def sent_source_detail(source_uuid: uuid.UUID) -> ResponseReturnValue: ) +@webmentions_bp.route("/sent//") +@login_required +def sent_webmention_detail( + source_uuid: uuid.UUID, webmention_uuid: uuid.UUID +) -> ResponseReturnValue: + """Show one target's delivery status and its own historical events.""" + filters = sent_filter_args(sent_filter_form()) + source = db.get_or_404(SourceDocument, source_uuid) + webmention = db.get_or_404(SentWebmention, webmention_uuid) + if webmention.source_uuid != source.uuid: + abort(HTTPStatus.NOT_FOUND) + + history = db.paginate( + sa.select(SentWebmentionStatusEvent) + .where(SentWebmentionStatusEvent.webmention_uuid == webmention.uuid) + .order_by(SentWebmentionStatusEvent.id.desc()), + page=request.args.get("history_page", 1, type=int), + per_page=25, + error_out=False, + ) + return render_template( + "sent_webmention_detail.html", + title="Sent Webmention", + source=source, + webmention=webmention, + history=history, + filters=filters, + source_page=request.args.get("source_page", 1, type=int), + webmentions_page=request.args.get("page", 1, type=int), + action_form=ConfirmActionForm(), + ) + + @webmentions_bp.post("/sent///resend") @login_required def resend_webmention( @@ -308,6 +347,18 @@ def resend_webmention( page = request.args.get("page", 1, type=int) source_page = request.args.get("source_page", 1, type=int) history_page = request.args.get("history_page", 1, type=int) + if request.args.get("return_to") == "detail": + return redirect( + url_for( + "webmentions.sent_webmention_detail", + source_uuid=source_uuid, + webmention_uuid=webmention_uuid, + page=page if page > 1 else None, + source_page=source_page if source_page > 1 else None, + history_page=history_page if history_page > 1 else None, + **filters, + ) + ) return redirect( url_for( "webmentions.sent_source_detail", @@ -325,8 +376,9 @@ def queue_sent_webmentions( ) -> list[uuid.UUID]: """Reopen sends in one transaction, then dispatch each task once. - A global retry selects only failed rows; a source-level retry can select - every delivery, regardless of status, list filters, or pagination. + By default, only failed rows are selected, optionally scoped to a source. + A source-level resend-all can explicitly include every status. Selection + does not depend on list filters or pagination. """ query = sa.select(SentWebmention) if failed_only: @@ -388,3 +440,30 @@ def resend_all_source_webmentions(source_uuid: uuid.UUID) -> ResponseReturnValue **filters, ) ) + + +@webmentions_bp.post("/sent//resend-failed") +@login_required +def resend_failed_source_webmentions(source_uuid: uuid.UUID) -> ResponseReturnValue: + """Resend only failed outgoing Webmentions for one source document.""" + if not ConfirmActionForm().validate_on_submit(): + abort(HTTPStatus.BAD_REQUEST) + + filters = sent_filter_args(sent_filter_form()) + db.get_or_404(SourceDocument, source_uuid) + identifiers = queue_sent_webmentions(source_uuid=source_uuid) + flash(f"{len(identifiers)} failed Webmentions queued for resend.", "success") + + page = request.args.get("page", 1, type=int) + history_page = request.args.get("history_page", 1, type=int) + source_page = request.args.get("source_page", 1, type=int) + return redirect( + url_for( + "webmentions.sent_source_detail", + source_uuid=source_uuid, + page=page if page > 1 else None, + history_page=history_page if history_page > 1 else None, + source_page=source_page if source_page > 1 else None, + **filters, + ) + ) -- cgit v1.3.1