aboutsummaryrefslogtreecommitdiff
path: root/webmentions_ssg/models/sources.py
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--webmentions_ssg/models/sources.py208
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)