aboutsummaryrefslogtreecommitdiff
path: root/webmentions_ssg/models
diff options
context:
space:
mode:
authorDennis Fink2026-11-15 21:18:19 +0100
committerDennis Fink2026-11-15 21:18:19 +0100
commit9b00526ab79257b65cedd71595848f09ecf84279 (patch)
treef9dfc5c0934499d47499bf083bd864f72947958c /webmentions_ssg/models
parent509d93b2976e353d29441a7a7b7e78ca466dc4fd (diff)
downloadwebmentions-ssg-9b00526ab79257b65cedd71595848f09ecf84279.tar.gz
webmentions-ssg-9b00526ab79257b65cedd71595848f09ecf84279.zip
refactor(core)!: clarify Webmention domain terminology
Rename ambiguous models, statuses, task modules, fields, and helpers so names reflect source documents, verification, endpoint discovery, and delivery state. Migrate persisted status values and database identifiers without losing existing Webmention data. BREAKING CHANGE: persisted status values and database schema names have changed, and several public Python names have been renamed.
Diffstat (limited to '')
-rw-r--r--webmentions_ssg/models.py88
1 files changed, 47 insertions, 41 deletions
diff --git a/webmentions_ssg/models.py b/webmentions_ssg/models.py
index 33f27d1..2b375dd 100644
--- a/webmentions_ssg/models.py
+++ b/webmentions_ssg/models.py
@@ -32,21 +32,21 @@ from werkzeug.security import check_password_hash, generate_password_hash
from .extensions import Base
-class ReceivedStatus(StrEnum):
+class ReceivedWebmentionStatus(StrEnum):
"""Persisted lifecycle state of an incoming Webmention."""
RECEIVED = "received"
VERIFYING = "verifying"
VERIFIED = "verified"
FAILED = "failed"
- DELETED = "deleted"
+ SOURCE_REMOVED = "source_removed"
class SentWebmentionStatus(StrEnum):
"""Represent the outcome of a Webmention send attempt."""
SENT = "sent"
- UNSUPPORTED = "unsupported"
+ NO_ENDPOINT = "no_endpoint"
FAILED = "failed"
@@ -110,25 +110,25 @@ class ReceivedWebmention(Base):
source: Mapped[str] = mapped_column(Text(), nullable=False)
target: Mapped[str] = mapped_column(Text(), nullable=False)
- url_digest: Mapped[str] = mapped_column(String(64), nullable=False)
+ source_target_digest: Mapped[str] = mapped_column(String(64), nullable=False)
@validates("source", "target")
- def _update_url_digest(self, key: str, value: str) -> str:
+ 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.url_digest = received_url_digest(source, target)
+ self.source_target_digest = source_target_digest(source, target)
return value
- status: Mapped[ReceivedStatus] = mapped_column(
+ status: Mapped[ReceivedWebmentionStatus] = mapped_column(
Enum(
- ReceivedStatus,
+ ReceivedWebmentionStatus,
name="received_webmention_status",
values_callable=lambda enum_type: [member.value for member in enum_type],
native_enum=False,
),
nullable=False,
- default=ReceivedStatus.RECEIVED,
+ default=ReceivedWebmentionStatus.RECEIVED,
)
# Counts stale-row requeues, not Huey's bounded in-task retries. A fresh
# explicit submission resets this counter.
@@ -151,7 +151,9 @@ class ReceivedWebmention(Base):
)
__table_args__ = (
- UniqueConstraint("url_digest", name="uq_webmention_url_digest"),
+ UniqueConstraint(
+ "source_target_digest", name="uq_webmention_source_target_digest"
+ ),
Index("ix_received_webmentions_status_updated_at", "status", "updated_at"),
)
@@ -160,35 +162,35 @@ class ReceivedWebmention(Base):
return f"<ReceivedWebmention {self.source!r} -> {self.target!r}>"
@staticmethod
- def verification_reset_values(
- *, at: datetime, recoveries: int = 0
+ 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 recoveries: Number of stale-lease recovery attempts to retain.
+ :param recovery_attempts: Number of stale-lease recovery attempts to retain.
:returns: Column values for resetting the verification state.
"""
return {
- "status": ReceivedStatus.RECEIVED,
+ "status": ReceivedWebmentionStatus.RECEIVED,
"failure_reason": None,
- "recovery_attempts": recoveries,
+ "recovery_attempts": recovery_attempts,
"updated_at": at,
}
- def reset_for_verification(self) -> None:
+ 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.verification_reset_values(at=datetime.now(UTC)).items():
+ 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 == ReceivedStatus.VERIFIED
+ return self.status == ReceivedWebmentionStatus.VERIFIED
@property
def created_at(self) -> datetime:
@@ -196,10 +198,10 @@ class ReceivedWebmention(Base):
return uuid7_to_datetime(self.uuid)
-class Source(Base):
+class SourceDocument(Base):
"""Represent a generated source document containing outgoing Webmentions."""
- __tablename__ = "sources"
+ __tablename__ = "source_documents"
uuid: Mapped[UUID] = mapped_column(
Uuid(as_uuid=True), primary_key=True, default=uuid7
@@ -227,7 +229,7 @@ class Source(Base):
def __repr__(self) -> str:
"""Represent the source by its public URL."""
- return f"<Source {self.url!r}>"
+ return f"<SourceDocument {self.url!r}>"
@property
def created_at(self) -> datetime:
@@ -244,9 +246,9 @@ class SentWebmention(Base):
Uuid(as_uuid=True), primary_key=True, default=uuid7
)
- source_id: Mapped[UUID] = mapped_column(
+ source_uuid: Mapped[UUID] = mapped_column(
Uuid(as_uuid=True),
- ForeignKey("sources.uuid", ondelete="CASCADE"),
+ ForeignKey("source_documents.uuid", ondelete="CASCADE"),
nullable=False,
index=True,
)
@@ -256,10 +258,10 @@ class SentWebmention(Base):
@validates("target")
def _update_target_digest(self, key: str, value: str) -> str:
- self.target_digest = sent_target_digest(value)
+ self.target_digest = target_digest(value)
return value
- active: Mapped[bool] = mapped_column(Boolean(), nullable=False, default=True)
+ 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(
@@ -284,8 +286,10 @@ class SentWebmention(Base):
Text(), nullable=True, default=None
)
- endpoint: Mapped[str | None] = mapped_column(Text(), nullable=True, default=None)
- response_status: Mapped[int | None] = mapped_column(
+ 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)
@@ -303,11 +307,13 @@ class SentWebmention(Base):
DateTime(timezone=True), nullable=True, default=None
)
- source: Mapped[Source] = relationship(back_populates="sent_webmentions")
+ source: Mapped[SourceDocument] = relationship(back_populates="sent_webmentions")
__table_args__ = (
UniqueConstraint(
- "source_id", "target_digest", name="uq_sent_webmention_source_target_digest"
+ "source_uuid",
+ "target_digest",
+ name="uq_sent_webmention_source_uuid_target_digest",
),
)
@@ -315,41 +321,41 @@ class SentWebmention(Base):
"""Represent the sent Webmention by its target URL."""
return f"<SentWebmention {self.target!r}>"
- def reopen(self, revision: int, active: bool) -> None:
+ 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 active: Whether the target still appears in the current source.
+ :param linked: Whether the target still appears in the current source.
"""
self.desired_revision = revision
- self.active = active
+ self.linked = linked
self.attempt_count = 0
self.next_retry_at = None
- def resend(self) -> 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.reopen(self.desired_revision, self.active)
+ self.reset_for_revision(self.desired_revision, self.linked)
self.processed_revision = None
self.status = None
self.failure_reason = None
- self.endpoint = None
- self.response_status = None
+ self.webmention_endpoint = None
+ self.endpoint_response_status = None
self.status_url = None
@hybrid_property
- def pending(self) -> bool:
+ 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
)
- @pending.inplace.expression
+ @awaiting_processing.inplace.expression
@classmethod
- def _pending_expression(cls) -> sa.ColumnElement[bool]:
+ def _awaiting_processing_expression(cls) -> sa.ColumnElement[bool]:
"""Express pending-revision status in database queries.
:returns: SQLAlchemy expression selecting unprocessed source revisions.
@@ -374,7 +380,7 @@ def uuid7_to_datetime(identifier: UUID) -> datetime:
return datetime.fromtimestamp(identifier.time / 1000, tz=UTC)
-def received_url_digest(source: str, target: str) -> str:
+def source_target_digest(source: str, target: str) -> str:
"""Fingerprint an unambiguous, ordered source/target pair.
:param source: Webmention source URL.
@@ -387,7 +393,7 @@ def received_url_digest(source: str, target: str) -> str:
return sha256(encoded).hexdigest()
-def sent_target_digest(target: str) -> str:
+def target_digest(target: str) -> str:
"""Fingerprint an outgoing target (unique within each source ID).
:param target: Outgoing Webmention target URL.