diff options
Diffstat (limited to '')
| -rw-r--r-- | webmentions_ssg/models.py | 49 |
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() |
