aboutsummaryrefslogtreecommitdiff
path: root/webmentions_ssg/models.py
diff options
context:
space:
mode:
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.