aboutsummaryrefslogtreecommitdiff
path: root/webmentions_ssg/tasks/sender.py
diff options
context:
space:
mode:
Diffstat (limited to 'webmentions_ssg/tasks/sender.py')
-rw-r--r--webmentions_ssg/tasks/sender.py41
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: