aboutsummaryrefslogtreecommitdiff
path: root/webmentions_ssg/tasks/receiver.py
diff options
context:
space:
mode:
Diffstat (limited to 'webmentions_ssg/tasks/receiver.py')
-rw-r--r--webmentions_ssg/tasks/receiver.py42
1 files changed, 32 insertions, 10 deletions
diff --git a/webmentions_ssg/tasks/receiver.py b/webmentions_ssg/tasks/receiver.py
index 31fb64c..eb228b3 100644
--- a/webmentions_ssg/tasks/receiver.py
+++ b/webmentions_ssg/tasks/receiver.py
@@ -51,11 +51,11 @@ def fetch_source(source_url: str) -> tuple[httpx.Response, bytes]:
redirect limit, and maximum response size.
:param source_url: URL of the source document.
- :return: HTTP response and response body.
+ :returns: HTTP response and response body.
:raises SourceGoneError: If the source returns HTTP 410.
:raises TemporaryFetchError: If the source returns a temporary HTTP error.
- :raises VerificationError: If the source returns another unsuccessful HTTP
- status or exceeds the configured maximum response size.
+ :raises VerificationError: If the source returns another unsuccessful HTTP status or
+ exceeds the configured maximum response size.
"""
try:
with (
@@ -97,9 +97,8 @@ def source_mentions_target(source_url: str, target_url: str) -> bool:
:param source_url: URL of the source document.
:param target_url: Exact target URL to look for.
- :return: Whether the source mentions the target URL.
- :raises VerificationError: If the source has an unsupported or missing
- content type.
+ :returns: Whether the source mentions the target URL.
+ :raises VerificationError: If the source has an unsupported or missing content type.
:raises SourceGoneError: If the source explicitly reports that it is gone.
:raises TemporaryFetchError: If fetching the source fails temporarily.
"""
@@ -135,7 +134,11 @@ class VerificationClaim:
def claim_eligible_row(webmention_uuid: uuid.UUID) -> VerificationClaim | None:
- """Claim an eligible row, returning its source, target, and lease version."""
+ """Claim an eligible row, returning its source, target, and lease version.
+
+ :param webmention_uuid: Identifier of the received Webmention to claim.
+ :returns: Verification claim, or ``None`` if the row cannot be claimed.
+ """
webmention = db.session.get(ReceivedWebmention, webmention_uuid)
if webmention is None:
@@ -182,7 +185,14 @@ def claim_eligible_row(webmention_uuid: uuid.UUID) -> VerificationClaim | None:
def check_source(claim: VerificationClaim) -> tuple[ReceivedStatus, str | None]:
- """Map verification results and permanent errors to a final status/reason."""
+ """Map verification results and permanent errors to a final status/reason.
+
+ :param claim: Claim containing the source and target URLs to verify.
+ :returns: Final verification status and optional reason.
+ :raises TemporaryFetchError: If the source fetch fails transiently and should be
+ retried.
+ :raises httpx.RequestError: If a transient HTTP request error should be retried.
+ """
try:
mentions_target = source_mentions_target(claim.source, claim.target)
except SourceGoneError as exc:
@@ -206,7 +216,13 @@ def check_source(claim: VerificationClaim) -> tuple[ReceivedStatus, str | None]:
def release_claim(
claim: VerificationClaim, status: ReceivedStatus, reason: str | None
) -> bool:
- """Persist an outcome only if this worker still owns the verification lease."""
+ """Persist an outcome only if this worker still owns the verification lease.
+
+ :param claim: Verification lease acquired by this worker.
+ :param status: Final status to persist for the claimed Webmention.
+ :param reason: Optional explanation for a failed or deleted Webmention.
+ :returns: ``True`` if the worker still owned the lease and persisted the outcome.
+ """
changed = db.session.execute(
sa.update(ReceivedWebmention)
.where(
@@ -226,6 +242,9 @@ def verify_webmention(webmention_uuid: uuid.UUID) -> None:
Temporary fetch failures are recorded and re-raised for Huey's retries.
+ Retry transient fetch errors; persist only results belonging to the currently held
+ lease.
+
:param webmention_uuid: Identifier of the received webmention to verify.
:raises TemporaryFetchError: If fetching the source fails temporarily.
:raises httpx.RequestError: If an HTTP request fails while fetching.
@@ -255,7 +274,10 @@ def recover_stale_webmentions() -> int:
Persist a recovery count so repeatedly lost or crashing tasks eventually
terminate rather than being requeued forever.
- :return: Number of webmentions requeued.
+ Eligible expired verification leases are returned to the queue, subject to recovery
+ limits.
+
+ :returns: Number of webmentions requeued.
"""
now = datetime.now(UTC)
cutoff = now - timedelta(seconds=current_app.config["VERIFICATION_TIMEOUT_SECONDS"])