From 9b00526ab79257b65cedd71595848f09ecf84279 Mon Sep 17 00:00:00 2001 From: Dennis Fink Date: Sun, 15 Nov 2026 21:18:19 +0100 Subject: 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. --- webmentions_ssg/models.py | 88 +++++++++++++++++++++++++---------------------- 1 file changed, 47 insertions(+), 41 deletions(-) (limited to 'webmentions_ssg/models.py') 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" {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"" + return f"" @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"" - 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. -- cgit v1.3.1