diff options
Diffstat (limited to '')
| -rw-r--r-- | webmentions_ssg/models/sources.py | 208 |
1 files changed, 208 insertions, 0 deletions
diff --git a/webmentions_ssg/models/sources.py b/webmentions_ssg/models/sources.py new file mode 100644 index 0000000..f0fd618 --- /dev/null +++ b/webmentions_ssg/models/sources.py @@ -0,0 +1,208 @@ +# SPDX-FileCopyrightText: 2026 Dennis Fink <me+coding@dennisfink.me> +# +# 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"<SourceDocument {self.url!r}>" + + @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"<SentWebmention {self.target!r}>" + + 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) |
