diff options
Diffstat (limited to 'webmentions_ssg/tasks/sender.py')
| -rw-r--r-- | webmentions_ssg/tasks/sender.py | 41 |
1 files changed, 35 insertions, 6 deletions
diff --git a/webmentions_ssg/tasks/sender.py b/webmentions_ssg/tasks/sender.py index 339dfe6..cf8ab9d 100644 --- a/webmentions_ssg/tasks/sender.py +++ b/webmentions_ssg/tasks/sender.py @@ -40,7 +40,7 @@ def attempt_is_current(webmention: SentWebmention, revision: int) -> bool: :param webmention: Sent Webmention being processed. :param revision: Source revision represented by the current attempt. - :return: Whether the attempt is still current and requires processing. + :returns: Whether the attempt is still current and requires processing. """ db.session.refresh(webmention) @@ -48,7 +48,11 @@ def attempt_is_current(webmention: SentWebmention, revision: int) -> bool: def retry_delay(attempt: int) -> timedelta: - """Calculate the capped exponential delay after a numbered send attempt.""" + """Calculate the capped exponential delay after a numbered send attempt. + + :param attempt: One-based send attempt number. + :returns: Delay until the next attempt, capped by the configured maximum. + """ base = max(1, int(current_app.config["SEND_RETRY_BASE_SECONDS"])) maximum = max(base, int(current_app.config["SEND_RETRY_MAX_SECONDS"])) return timedelta(seconds=min(base * 2 ** (attempt - 1), maximum)) @@ -63,6 +67,8 @@ def send_webmention(webmention_uuid: uuid.UUID) -> None: scanner requeues them when due; Huey does not retry them independently. The retry budget is per desired source revision. + Run the delivery workflow under a lock associated with the outgoing Webmention. + :param webmention_uuid: Identifier of the sent Webmention to process. """ # Huey locks have static names when used as decorators. Acquire one keyed by @@ -107,7 +113,12 @@ class DeliveryResult: def is_due(webmention: SentWebmention, now: datetime) -> bool: - """Return whether an unprocessed Webmention has reached its retry deadline.""" + """Return whether an unprocessed Webmention has reached its retry deadline. + + :param webmention: Outgoing Webmention whose retry eligibility is checked. + :param now: Current timestamp against which the retry deadline is compared. + :returns: ``True`` if the Webmention is pending and its retry deadline has elapsed. + """ if not webmention.pending: return False @@ -124,6 +135,10 @@ def claim_attempt(webmention: SentWebmention, now: datetime) -> SendAttempt | No An attempt's next retry deadline is persisted *before* the HTTP request so a lost worker cannot cause an immediate duplicate send. + + :param webmention: Outgoing Webmention to reserve for sending. + :param now: Timestamp at which the attempt is claimed. + :returns: Reserved attempt details, or ``None`` if no attempt can be started. """ revision = webmention.desired_revision max_attempts = max(1, int(current_app.config["SEND_MAX_ATTEMPTS"])) @@ -199,7 +214,13 @@ def claim_attempt(webmention: SentWebmention, now: datetime) -> SendAttempt | No def deliver_webmention( source: str, target: str, *, webmention_uuid: uuid.UUID ) -> DeliveryResult: - """Discover and POST a Webmention, returning an outcome without DB writes.""" + """Discover and POST a Webmention, returning an outcome without DB writes. + + :param source: Public source URL advertising the target link. + :param target: Target URL to notify. + :param webmention_uuid: Identifier used for delivery logging. + :returns: Delivery status, endpoint, response details, and any failure reason. + """ endpoint: str | None = None response_status: int | None = None status_url: str | None = None @@ -275,7 +296,14 @@ def record_outcome( *, terminal: bool, ) -> bool: - """Record an outcome only while the claimed source revision is current.""" + """Record an outcome only while the claimed source revision is current. + + :param webmention: Outgoing Webmention being updated. + :param attempt: Claimed revision and attempt details. + :param result: Result of the delivery attempt. + :param terminal: Whether this outcome ends attempts for the current revision. + :returns: ``True`` if the outcome was recorded for the current revision. + """ # A scanner may have reopened or superseded the revision during I/O. if not attempt_is_current(webmention, attempt.revision): return False @@ -305,7 +333,8 @@ def record_outcome( def _send_locked(webmention_uuid: uuid.UUID) -> bool: """Process a due Webmention while holding its per-UUID task lock. - :return: Whether this worker recorded a delivery outcome. + :param webmention_uuid: Identifier of the outgoing Webmention being processed. + :returns: Whether this worker recorded a delivery outcome. """ webmention = db.session.get(SentWebmention, webmention_uuid) if webmention is None: |
