# SPDX-FileCopyrightText: 2026 Dennis Fink # # SPDX-License-Identifier: BSD-3-Clause """Source documents and outgoing Webmention state.""" from collections.abc import Collection from datetime import UTC, datetime from enum import StrEnum from uuid import UUID, uuid7 import sqlalchemy as sa from sqlalchemy import ( Boolean, DateTime, Enum, ForeignKey, Index, Integer, String, Text, UniqueConstraint, Uuid, ) from sqlalchemy.ext.hybrid import hybrid_property from sqlalchemy.orm import Mapped, mapped_column, relationship, validates from ..extensions import Base from .utils import target_digest, uuid7_to_datetime class SentWebmentionStatus(StrEnum): """Represent the outcome of a Webmention send attempt.""" SENT = "sent" NO_ENDPOINT = "no_endpoint" FAILED = "failed" class SourceDocument(Base): """Represent a generated source document containing outgoing Webmentions.""" __tablename__ = "source_documents" uuid: Mapped[UUID] = mapped_column( Uuid(as_uuid=True), primary_key=True, default=uuid7 ) path: Mapped[str] = mapped_column(Text(), nullable=False, unique=True) url: Mapped[str] = mapped_column(Text(), nullable=False, unique=True) content_hash: Mapped[str] = mapped_column(String(32), nullable=False) revision: Mapped[int] = mapped_column(Integer(), nullable=False, default=1) last_seen_at: Mapped[datetime] = mapped_column( DateTime(timezone=True), nullable=False ) revised_at: Mapped[datetime] = mapped_column( DateTime(timezone=True), nullable=False ) deleted_at: Mapped[datetime | None] = mapped_column( DateTime(timezone=True), nullable=True, default=None ) sent_webmentions: Mapped[list[SentWebmention]] = relationship( back_populates="source", cascade="all, delete-orphan" ) def __repr__(self) -> str: """Represent the source by its public URL.""" return f"" @classmethod def sent_webmention_statistics( cls, source_uuids: Collection[UUID] ) -> sa.Select[UUID, int, int, int, int, int]: """Aggregate delivery counts for a page of sources in one SQL query. The outer join includes sources without Webmentions, with zero counts. Retrying is independent of delivery status, matching the list badges. """ retrying = sa.and_( SentWebmention.awaiting_processing, SentWebmention.attempt_count > 0, SentWebmention.next_retry_at.is_not(None), ) return ( sa.select( cls.uuid.label("source_uuid"), sa.func.count(SentWebmention.uuid).label("total"), sa.func.count( sa.case((SentWebmention.status == SentWebmentionStatus.SENT, 1)) ).label("sent"), sa.func.count( sa.case( (SentWebmention.status == SentWebmentionStatus.NO_ENDPOINT, 1) ) ).label("no_endpoint"), sa.func.count( sa.case((SentWebmention.status == SentWebmentionStatus.FAILED, 1)) ).label("failed"), sa.func.count(sa.case((retrying, 1))).label("retrying"), ) .outerjoin(SentWebmention, SentWebmention.source_uuid == cls.uuid) .where(cls.uuid.in_(source_uuids)) .group_by(cls.uuid) ) @property def created_at(self) -> datetime: """Return the creation time encoded in the source UUID.""" return uuid7_to_datetime(self.uuid) class SentWebmention(Base): """Represent an outgoing Webmention associated with a source.""" __tablename__ = "sent_webmentions" uuid: Mapped[UUID] = mapped_column( Uuid(as_uuid=True), primary_key=True, default=uuid7 ) source_uuid: Mapped[UUID] = mapped_column( Uuid(as_uuid=True), ForeignKey("source_documents.uuid", ondelete="CASCADE"), nullable=False, index=True, ) target: Mapped[str] = mapped_column(Text(), nullable=False) target_digest: Mapped[str] = mapped_column(String(64), nullable=False) @validates("target") def _update_target_digest(self, key: str, value: str) -> str: self.target_digest = target_digest(value) return value linked: Mapped[bool] = mapped_column(Boolean(), nullable=False, default=True) desired_revision: Mapped[int] = mapped_column(Integer(), nullable=False) processed_revision: Mapped[int | None] = mapped_column( Integer(), nullable=True, default=None ) sent_revision: Mapped[int | None] = mapped_column( Integer(), nullable=True, default=None ) status: Mapped[SentWebmentionStatus | None] = mapped_column( Enum( SentWebmentionStatus, name="sent_webmention_status", values_callable=lambda enum_type: [member.value for member in enum_type], native_enum=False, ), nullable=True, default=None, ) failure_reason: Mapped[str | None] = mapped_column( Text(), nullable=True, default=None ) webmention_endpoint: Mapped[str | None] = mapped_column( Text(), nullable=True, default=None ) endpoint_response_status: Mapped[int | None] = mapped_column( Integer(), nullable=True, default=None ) status_url: Mapped[str | None] = mapped_column(Text(), nullable=True, default=None) # Retry state belongs to the desired revision, not to the target forever. attempt_count: Mapped[int] = mapped_column(Integer(), nullable=False, default=0) next_retry_at: Mapped[datetime | None] = mapped_column( DateTime(timezone=True), nullable=True, default=None ) last_attempted_at: Mapped[datetime | None] = mapped_column( DateTime(timezone=True), nullable=True, default=None ) last_sent_at: Mapped[datetime | None] = mapped_column( DateTime(timezone=True), nullable=True, default=None ) source: Mapped[SourceDocument] = relationship(back_populates="sent_webmentions") status_events: Mapped[list[SentWebmentionStatusEvent]] = relationship( back_populates="webmention", cascade="all, delete-orphan" ) def record_status_event(self, action: str, *, at: datetime | None = None) -> None: """Save a snapshot of this mention's current delivery state.""" self.status_events.append( SentWebmentionStatusEvent( status=self.status, action=action, revision=self.desired_revision, attempt_count=self.attempt_count, failure_reason=self.failure_reason, endpoint_response_status=self.endpoint_response_status, occurred_at=at or datetime.now(UTC), ) ) __table_args__ = ( UniqueConstraint( "source_uuid", "target_digest", name="uq_sent_webmention_source_uuid_target_digest", ), ) def __repr__(self) -> str: """Represent the sent Webmention by its target URL.""" return f"" def reset_for_revision(self, revision: int, linked: bool) -> None: """Reopen delivery for a revision while preserving send history. :param revision: Source revision to make the desired delivery revision. :param linked: Whether the target still appears in the current source. """ self.desired_revision = revision self.linked = linked self.attempt_count = 0 self.next_retry_at = None def clear_result_for_resend(self) -> None: """Retry the current revision, clearing its previous delivery result. Reset attempt and response state without changing the desired source revision. """ self.reset_for_revision(self.desired_revision, self.linked) self.processed_revision = None self.status = None self.failure_reason = None self.webmention_endpoint = None self.endpoint_response_status = None self.status_url = None @hybrid_property def awaiting_processing(self) -> bool: """Return whether the Webmention has an unprocessed source revision.""" return ( self.processed_revision is None or self.processed_revision < self.desired_revision ) @awaiting_processing.inplace.expression @classmethod def _awaiting_processing_expression(cls) -> sa.ColumnElement[bool]: """Express pending-revision status in database queries. :returns: SQLAlchemy expression selecting unprocessed source revisions. """ return sa.or_( cls.processed_revision.is_(None), cls.processed_revision < cls.desired_revision, ) @property def created_at(self) -> datetime: """Return the creation time encoded in the Webmention UUID.""" return uuid7_to_datetime(self.uuid) class SentWebmentionStatusEvent(Base): """Persist delivery outcomes and manual requeues for an outgoing Webmention.""" __tablename__ = "sent_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("sent_webmentions.uuid", ondelete="CASCADE"), nullable=False, ) status: Mapped[SentWebmentionStatus | None] = mapped_column( Enum( SentWebmentionStatus, name="sent_webmention_status", values_callable=lambda enum_type: [member.value for member in enum_type], native_enum=False, ), nullable=True, ) action: Mapped[str] = mapped_column(String(80), nullable=False) revision: Mapped[int] = mapped_column(Integer(), nullable=False) attempt_count: Mapped[int] = mapped_column(Integer(), nullable=False) failure_reason: Mapped[str | None] = mapped_column(Text(), nullable=True) endpoint_response_status: Mapped[int | None] = mapped_column( Integer(), nullable=True ) occurred_at: Mapped[datetime] = mapped_column( DateTime(timezone=True), nullable=False ) webmention: Mapped[SentWebmention] = relationship(back_populates="status_events") __table_args__ = ( Index( "ix_sent_webmention_status_events_webmention_id", "webmention_uuid", "id" ), )