aboutsummaryrefslogtreecommitdiff
path: root/webmentions_ssg/models.py
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--webmentions_ssg/models.py49
1 files changed, 40 insertions, 9 deletions
diff --git a/webmentions_ssg/models.py b/webmentions_ssg/models.py
index 622e3b8..33f27d1 100644
--- a/webmentions_ssg/models.py
+++ b/webmentions_ssg/models.py
@@ -85,6 +85,9 @@ class User(UserMixin, Base):
Only a one-way fingerprint is placed in Flask's signed cookie, never
the password hash itself. Rehashing the password invalidates all
previously issued session identifiers without a schema change.
+
+ :returns: Session identifier combining the user ID and password-hash
+ fingerprint.
"""
fingerprint = sha256(self.password_hash.encode("utf-8")).hexdigest()
return f"{self.id}:{fingerprint}"
@@ -93,7 +96,7 @@ class User(UserMixin, Base):
"""Check a plain-text password against the stored password hash.
:param password: Plain-text password to check.
- :return: Whether the password matches the stored hash.
+ :returns: Whether the password matches the stored hash.
"""
return check_password_hash(self.password_hash, password)
@@ -160,7 +163,12 @@ class ReceivedWebmention(Base):
def verification_reset_values(
*, at: datetime, recoveries: int = 0
) -> dict[str, object]:
- """Return the columns to reset when verification is explicitly reopened."""
+ """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.
+ :returns: Column values for resetting the verification state.
+ """
return {
"status": ReceivedStatus.RECEIVED,
"failure_reason": None,
@@ -169,7 +177,11 @@ class ReceivedWebmention(Base):
}
def reset_for_verification(self) -> None:
- """Reopen an existing row for manual verification."""
+ """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():
setattr(self, key, value)
@@ -304,14 +316,21 @@ class SentWebmention(Base):
return f"<SentWebmention {self.target!r}>"
def reopen(self, revision: int, active: bool) -> None:
- """Reopen delivery for a revision while preserving send history."""
+ """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.
+ """
self.desired_revision = revision
self.active = active
self.attempt_count = 0
self.next_retry_at = None
def resend(self) -> None:
- """Retry the current revision, clearing its previous delivery result."""
+ """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.processed_revision = None
self.status = None
@@ -331,7 +350,10 @@ class SentWebmention(Base):
@pending.inplace.expression
@classmethod
def _pending_expression(cls) -> sa.ColumnElement[bool]:
- """Express pending-revision status in database queries."""
+ """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,
@@ -347,13 +369,18 @@ def uuid7_to_datetime(identifier: UUID) -> datetime:
"""Convert a UUID version 7 timestamp to a datetime.
:param identifier: UUID whose embedded timestamp should be converted.
- :return: Timestamp as a timezone-aware UTC datetime.
+ :returns: Timestamp as a timezone-aware UTC datetime.
"""
return datetime.fromtimestamp(identifier.time / 1000, tz=UTC)
def received_url_digest(source: str, target: str) -> str:
- """Fingerprint an unambiguous, ordered source/target pair."""
+ """Fingerprint an unambiguous, ordered source/target pair.
+
+ :param source: Webmention source URL.
+ :param target: Webmention target URL.
+ :returns: SHA-256 hexadecimal digest of the ordered URL pair.
+ """
encoded = json.dumps(
[source, target], ensure_ascii=False, separators=(",", ":")
).encode("utf-8")
@@ -361,5 +388,9 @@ def received_url_digest(source: str, target: str) -> str:
def sent_target_digest(target: str) -> str:
- """Fingerprint an outgoing target (unique within each source ID)."""
+ """Fingerprint an outgoing target (unique within each source ID).
+
+ :param target: Outgoing Webmention target URL.
+ :returns: SHA-256 hexadecimal digest of the target URL.
+ """
return sha256(target.encode("utf-8")).hexdigest()