aboutsummaryrefslogtreecommitdiff
path: root/webmentions_ssg/models/received.py
diff options
context:
space:
mode:
authorDennis Fink2026-11-17 17:09:59 +0100
committerDennis Fink2026-11-17 17:09:59 +0100
commit6d6d079a3a99d3d3a922a640b6925eb2adf044de (patch)
tree33cc19241f4ce86ea43b2f194087c58e3fdc8a4d /webmentions_ssg/models/received.py
parent227092b57acc886469e16bcc4c0d3256e86d3d1e (diff)
downloadwebmentions-ssg-6d6d079a3a99d3d3a922a640b6925eb2adf044de.tar.gz
webmentions-ssg-6d6d079a3a99d3d3a922a640b6925eb2adf044de.zip
refactor(core)!: split forms and models by feature
Replace monolithic form and model modules with focused packages for receiver, moderation, source, user, and shared validation concerns. Rename source policy concepts to domain moderation, including routes, models, tables, configuration, templates, and tests. BREAKING CHANGE: form and model import paths, moderation routes, and `SOURCE_ALLOWLIST_ENABLED` have changed; use `ALLOWLIST_ENABLED` and the new feature-specific modules.
Diffstat (limited to '')
-rw-r--r--webmentions_ssg/models/received.py131
1 files changed, 131 insertions, 0 deletions
diff --git a/webmentions_ssg/models/received.py b/webmentions_ssg/models/received.py
new file mode 100644
index 0000000..a9047ad
--- /dev/null
+++ b/webmentions_ssg/models/received.py
@@ -0,0 +1,131 @@
+# SPDX-FileCopyrightText: 2026 Dennis Fink <me+coding@dennisfink.me>
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Incoming Webmention state and persistence."""
+
+from datetime import UTC, datetime
+from enum import StrEnum
+from uuid import UUID
+
+from sqlalchemy import (
+ DateTime,
+ Enum,
+ Index,
+ Integer,
+ String,
+ Text,
+ UniqueConstraint,
+ Uuid,
+)
+from sqlalchemy.orm import Mapped, mapped_column, validates
+
+from ..extensions import Base
+from .utils import source_target_digest, uuid7_to_datetime
+
+
+class ReceivedWebmentionStatus(StrEnum):
+ """Persisted lifecycle state of an incoming Webmention."""
+
+ RECEIVED = "received"
+ VERIFYING = "verifying"
+ VERIFIED = "verified"
+ FAILED = "failed"
+ SOURCE_REMOVED = "source_removed"
+
+
+class ReceivedWebmention(Base):
+ """Represent a Webmention received for verification."""
+
+ __tablename__ = "received_webmentions"
+
+ uuid: Mapped[UUID] = mapped_column(Uuid(as_uuid=True), primary_key=True)
+
+ source: Mapped[str] = mapped_column(Text(), nullable=False)
+ target: Mapped[str] = mapped_column(Text(), nullable=False)
+ source_target_digest: Mapped[str] = mapped_column(String(64), nullable=False)
+
+ @validates("source", "target")
+ def _refresh_url_digest(self, key: str, value: str) -> str:
+ source = value if key == "source" else self.__dict__.get("source")
+ target = value if key == "target" else self.__dict__.get("target")
+ if source is not None and target is not None:
+ self.source_target_digest = source_target_digest(source, target)
+ return value
+
+ 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,
+ default=ReceivedWebmentionStatus.RECEIVED,
+ )
+ # Counts stale-row requeues, not Huey's bounded in-task retries. A fresh
+ # explicit submission resets this counter.
+ recovery_attempts: Mapped[int] = mapped_column(
+ Integer, nullable=False, default=0, server_default="0"
+ )
+ failure_reason: Mapped[str | None] = mapped_column(
+ Text(), nullable=True, default=None
+ )
+
+ updated_at: Mapped[datetime] = mapped_column(
+ DateTime(timezone=True),
+ default=lambda: datetime.now(UTC),
+ onupdate=lambda: datetime.now(UTC),
+ nullable=False,
+ )
+
+ notification_sent_at: Mapped[datetime | None] = mapped_column(
+ DateTime(timezone=True), nullable=True, default=None
+ )
+
+ __table_args__ = (
+ UniqueConstraint(
+ "source_target_digest", name="uq_webmention_source_target_digest"
+ ),
+ Index("ix_received_webmentions_status_updated_at", "status", "updated_at"),
+ )
+
+ def __repr__(self) -> str:
+ """Represent the received Webmention by source and target."""
+ return f"<ReceivedWebmention {self.source!r} -> {self.target!r}>"
+
+ @staticmethod
+ def reopen_verification_values(
+ *, at: datetime, recovery_attempts: int = 0
+ ) -> dict[str, object]:
+ """Return the columns to reset when verification is explicitly reopened.
+
+ :param at: Timestamp to record for the newly opened verification.
+ :param recovery_attempts: Number of stale-lease recovery attempts to retain.
+ :returns: Column values for resetting the verification state.
+ """
+ return {
+ "status": ReceivedWebmentionStatus.RECEIVED,
+ "failure_reason": None,
+ "recovery_attempts": recovery_attempts,
+ "updated_at": at,
+ }
+
+ def reopen_verification(self) -> None:
+ """Reopen an existing row for manual verification.
+
+ Clear the previous outcome and restore the received state with a fresh
+ timestamp.
+ """
+ for key, value in self.reopen_verification_values(at=datetime.now(UTC)).items():
+ setattr(self, key, value)
+
+ @property
+ def verified(self) -> bool:
+ """Return whether the Webmention has been successfully verified."""
+ return self.status == ReceivedWebmentionStatus.VERIFIED
+
+ @property
+ def created_at(self) -> datetime:
+ """Return the creation time encoded in the Webmention UUID."""
+ return uuid7_to_datetime(self.uuid)