From 5e24e8307f650e72881f747661a2b6e52db15f2d Mon Sep 17 00:00:00 2001 From: Dennis Fink Date: Tue, 17 Nov 2026 19:43:04 +0100 Subject: feat(receiver): add Webmention detail and status history Add an authenticated detail view with full failure information, timestamps, actions, public status links, and recorded lifecycle transitions. Persist verification and resubmission events, backfill existing rows during migration, and clean up history when received Webmentions are deleted. --- webmentions_ssg/models/received.py | 75 +++++++++++++++++++++++++++++++++++++- 1 file changed, 73 insertions(+), 2 deletions(-) (limited to 'webmentions_ssg/models') diff --git a/webmentions_ssg/models/received.py b/webmentions_ssg/models/received.py index a9047ad..5aa0649 100644 --- a/webmentions_ssg/models/received.py +++ b/webmentions_ssg/models/received.py @@ -8,9 +8,11 @@ from datetime import UTC, datetime from enum import StrEnum from uuid import UUID +import sqlalchemy as sa from sqlalchemy import ( DateTime, Enum, + ForeignKey, Index, Integer, String, @@ -18,9 +20,9 @@ from sqlalchemy import ( UniqueConstraint, Uuid, ) -from sqlalchemy.orm import Mapped, mapped_column, validates +from sqlalchemy.orm import Mapped, mapped_column, relationship, validates -from ..extensions import Base +from ..extensions import Base, db from .utils import source_target_digest, uuid7_to_datetime @@ -83,6 +85,10 @@ class ReceivedWebmention(Base): DateTime(timezone=True), nullable=True, default=None ) + status_events: Mapped[list[ReceivedWebmentionStatusEvent]] = relationship( + back_populates="webmention", cascade="all, delete-orphan" + ) + __table_args__ = ( UniqueConstraint( "source_target_digest", name="uq_webmention_source_target_digest" @@ -129,3 +135,68 @@ class ReceivedWebmention(Base): def created_at(self) -> datetime: """Return the creation time encoded in the Webmention UUID.""" return uuid7_to_datetime(self.uuid) + + +class ReceivedWebmentionStatusEvent(Base): + """A persisted lifecycle transition for a received Webmention. + + Events record observed transitions rather than reconstructing missing history + from the current status. They are private to the authenticated admin view. + """ + + __tablename__ = "received_webmention_status_events" + + id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True) + webmention_uuid: Mapped[UUID] = mapped_column( + Uuid(as_uuid=True), + ForeignKey("received_webmentions.uuid", ondelete="CASCADE"), + nullable=False, + ) + status: Mapped[ReceivedWebmentionStatus] = mapped_column( + Enum( + ReceivedWebmentionStatus, + name="received_webmention_status", + values_callable=lambda enum_type: [member.value for member in enum_type], + native_enum=False, + ), + nullable=False, + ) + action: Mapped[str] = mapped_column(String(80), nullable=False) + failure_reason: Mapped[str | None] = mapped_column(Text(), nullable=True) + recovery_attempts: Mapped[int] = mapped_column(Integer, nullable=False, default=0) + occurred_at: Mapped[datetime] = mapped_column( + DateTime(timezone=True), nullable=False + ) + + webmention: Mapped[ReceivedWebmention] = relationship( + back_populates="status_events" + ) + + __table_args__ = ( + Index( + "ix_received_webmention_status_events_webmention_id", + "webmention_uuid", + "id", + ), + ) + + +def purge_orphaned_received_events() -> None: + """Remove status events whose parent Webmention no longer exists. + + Provides a fallback when database-level ON DELETE CASCADE is not + enforced (e.g. SQLite with foreign-key enforcement disabled). + + Run after deleting parent rows in the same transaction so that + events belonging to surviving rows are preserved. + """ + db.session.execute( + sa.delete(ReceivedWebmentionStatusEvent).where( + ~sa.exists( + sa.select(ReceivedWebmention.uuid).where( + ReceivedWebmention.uuid + == ReceivedWebmentionStatusEvent.webmention_uuid + ) + ) + ) + ) -- cgit v1.3.1