diff options
Diffstat (limited to 'webmentions_ssg/tasks/receiver.py')
| -rw-r--r-- | webmentions_ssg/tasks/receiver.py | 42 |
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"]) |
