# SPDX-FileCopyrightText: 2026 Dennis Fink # # SPDX-License-Identifier: BSD-3-Clause """Source documents and outgoing Webmention state.""" from datetime import datetime from enum import StrEnum from uuid import UUID, uuid7 import sqlalchemy as sa from sqlalchemy import ( Boolean, DateTime, Enum, ForeignKey, 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"" @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") __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)