aboutsummaryrefslogtreecommitdiff
path: root/webmentions_ssg/tasks/receiver.py
diff options
context:
space:
mode:
authorDennis Fink2026-11-15 20:42:20 +0100
committerDennis Fink2026-11-15 20:42:20 +0100
commit509d93b2976e353d29441a7a7b7e78ca466dc4fd (patch)
tree753e637aefabd4293f808addbf9c310eaf0aa552 /webmentions_ssg/tasks/receiver.py
parentc74feda222745ab7cca8993df83d9ea5f9d07e5b (diff)
downloadwebmentions-ssg-509d93b2976e353d29441a7a7b7e78ca466dc4fd.tar.gz
webmentions-ssg-509d93b2976e353d29441a7a7b7e78ca466dc4fd.zip
refactor(core)!: standardize application terminology
Rename configuration keys, task helpers, forms, network utilities, and view endpoints to make their responsibilities and domains more explicit. Align source-management routes and templates with the new terminology and rename the target-matching module and related task abstractions consistently. BREAKING CHANGE: configuration keys have been renamed and sent-source routes move from `/sent` to `/sources`, with corresponding blueprint endpoint changes.
Diffstat (limited to '')
-rw-r--r--webmentions_ssg/tasks/receiver.py72
1 files changed, 39 insertions, 33 deletions
diff --git a/webmentions_ssg/tasks/receiver.py b/webmentions_ssg/tasks/receiver.py
index eb228b3..313a8e4 100644
--- a/webmentions_ssg/tasks/receiver.py
+++ b/webmentions_ssg/tasks/receiver.py
@@ -20,13 +20,13 @@ from ..net import (
AddressResolutionError,
ResponseTooLargeError,
UnsafeAddressError,
- build_client,
- content_type_of,
- is_temporary_status,
+ build_public_http_client,
+ is_retryable_status,
+ media_type_of,
read_limited_body,
)
from ..version import APP_NAME, VERSION
-from .mentions import html_mentions_target, text_mentions_target
+from .target_matching import html_mentions_target, text_mentions_target
class VerificationError(Exception):
@@ -37,14 +37,14 @@ class SourceGoneError(VerificationError):
"""The source explicitly reports that it has been removed."""
-class TemporaryFetchError(Exception):
+class RetryableFetchError(Exception):
"""Fetching the source may succeed when retried later."""
RECOVERY_EXHAUSTED_REASON = "Verification recovery limit reached"
-def fetch_source(source_url: str) -> tuple[httpx.Response, bytes]:
+def fetch_source_document(source_url: str) -> tuple[httpx.Response, bytes]:
"""Fetch a webmention source document.
The request follows redirects while enforcing the configured timeout,
@@ -53,13 +53,13 @@ def fetch_source(source_url: str) -> tuple[httpx.Response, bytes]:
:param source_url: URL of the source document.
: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 RetryableFetchError: 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.
"""
try:
with (
- build_client(
+ build_public_http_client(
f"{APP_NAME}/{VERSION} ReceivedWebmention",
accept="text/html, application/xhtml+xml;q=0.9, text/plain;q=0.8",
) as client,
@@ -69,8 +69,8 @@ def fetch_source(source_url: str) -> tuple[httpx.Response, bytes]:
pass
elif response.status_code == HTTPStatus.GONE:
raise SourceGoneError("Source returned HTTP 410")
- elif is_temporary_status(response.status_code):
- raise TemporaryFetchError(
+ elif is_retryable_status(response.status_code):
+ raise RetryableFetchError(
f"Source returned HTTP {response.status_code}"
)
else:
@@ -78,7 +78,9 @@ def fetch_source(source_url: str) -> tuple[httpx.Response, bytes]:
try:
return response, read_limited_body(
- response, current_app.config["MAX_SOURCE_BYTES"], label="Source"
+ response,
+ current_app.config["MAX_RECEIVED_SOURCE_BYTES"],
+ label="Source",
)
except ResponseTooLargeError as exc:
raise VerificationError(str(exc)) from exc
@@ -86,7 +88,7 @@ def fetch_source(source_url: str) -> tuple[httpx.Response, bytes]:
except UnsafeAddressError as exc:
raise VerificationError("Source resolves to a non-public address") from exc
except AddressResolutionError as exc:
- raise TemporaryFetchError("Source hostname could not be resolved") from exc
+ raise RetryableFetchError("Source hostname could not be resolved") from exc
def source_mentions_target(source_url: str, target_url: str) -> bool:
@@ -100,11 +102,11 @@ def source_mentions_target(source_url: str, target_url: str) -> bool:
: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.
+ :raises RetryableFetchError: If fetching the source fails temporarily.
"""
- response, body = fetch_source(source_url)
+ response, body = fetch_source_document(source_url)
- media_type = content_type_of(response.headers)
+ media_type = media_type_of(response.headers)
match media_type:
case "text/html" | "application/xhtml+xml":
@@ -127,13 +129,13 @@ def source_mentions_target(source_url: str, target_url: str) -> bool:
class VerificationClaim:
"""Source and lease version for one atomically claimed verification."""
- identifier: uuid.UUID
+ webmention_uuid: uuid.UUID
source: str
target: str
- started_at: datetime
+ lease_started_at: datetime
-def claim_eligible_row(webmention_uuid: uuid.UUID) -> VerificationClaim | None:
+def claim_for_verification(webmention_uuid: uuid.UUID) -> VerificationClaim | None:
"""Claim an eligible row, returning its source, target, and lease version.
:param webmention_uuid: Identifier of the received Webmention to claim.
@@ -157,10 +159,10 @@ def claim_eligible_row(webmention_uuid: uuid.UUID) -> VerificationClaim | None:
return None
claim = VerificationClaim(
- identifier=webmention_uuid,
+ webmention_uuid=webmention_uuid,
source=webmention.source,
target=webmention.target,
- started_at=datetime.now(UTC),
+ lease_started_at=datetime.now(UTC),
)
changed = db.session.execute(
sa.update(ReceivedWebmention)
@@ -172,7 +174,7 @@ def claim_eligible_row(webmention_uuid: uuid.UUID) -> VerificationClaim | None:
.values(
status=ReceivedStatus.VERIFYING,
failure_reason=None,
- updated_at=claim.started_at,
+ updated_at=claim.lease_started_at,
)
)
@@ -184,12 +186,14 @@ def claim_eligible_row(webmention_uuid: uuid.UUID) -> VerificationClaim | None:
return claim
-def check_source(claim: VerificationClaim) -> tuple[ReceivedStatus, str | None]:
+def determine_verification_outcome(
+ claim: VerificationClaim,
+) -> tuple[ReceivedStatus, str | None]:
"""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
+ :raises RetryableFetchError: If the source fetch fails transiently and should be
retried.
:raises httpx.RequestError: If a transient HTTP request error should be retried.
"""
@@ -199,12 +203,12 @@ def check_source(claim: VerificationClaim) -> tuple[ReceivedStatus, str | None]:
return ReceivedStatus.DELETED, str(exc)
except VerificationError as exc:
return ReceivedStatus.FAILED, str(exc)
- except TemporaryFetchError, httpx.RequestError:
+ except RetryableFetchError, httpx.RequestError:
raise # These errors must be persisted and then retried by Huey.
except Exception as exc:
# InvalidURL is not a RequestError; unexpected source errors are terminal.
current_app.logger.exception(
- "Unexpected error verifying ReceivedWebmention %s", claim.identifier
+ "Unexpected error verifying ReceivedWebmention %s", claim.webmention_uuid
)
return ReceivedStatus.FAILED, str(exc) or type(exc).__name__
@@ -226,9 +230,9 @@ def release_claim(
changed = db.session.execute(
sa.update(ReceivedWebmention)
.where(
- ReceivedWebmention.uuid == claim.identifier,
+ ReceivedWebmention.uuid == claim.webmention_uuid,
ReceivedWebmention.status == ReceivedStatus.VERIFYING,
- ReceivedWebmention.updated_at == claim.started_at,
+ ReceivedWebmention.updated_at == claim.lease_started_at,
)
.values(status=status, failure_reason=reason, updated_at=datetime.now(UTC))
)
@@ -246,15 +250,15 @@ def verify_webmention(webmention_uuid: uuid.UUID) -> None:
lease.
:param webmention_uuid: Identifier of the received webmention to verify.
- :raises TemporaryFetchError: If fetching the source fails temporarily.
+ :raises RetryableFetchError: If fetching the source fails temporarily.
:raises httpx.RequestError: If an HTTP request fails while fetching.
"""
- if (claim := claim_eligible_row(webmention_uuid)) is None:
+ if (claim := claim_for_verification(webmention_uuid)) is None:
return
try:
- status, reason = check_source(claim)
- except (TemporaryFetchError, httpx.RequestError) as exc:
+ status, reason = determine_verification_outcome(claim)
+ except (RetryableFetchError, httpx.RequestError) as exc:
release_claim(
claim, ReceivedStatus.FAILED, str(exc) or "Source could not be fetched"
)
@@ -263,7 +267,7 @@ def verify_webmention(webmention_uuid: uuid.UUID) -> None:
release_claim(claim, status, reason)
-def recover_stale_webmentions() -> int:
+def recover_stale_verifications() -> int:
"""Requeue verification attempts that were abandoned or lost from the queue.
Recover both stale ``verifying`` rows (workers that died) and stale
@@ -280,7 +284,9 @@ def recover_stale_webmentions() -> int:
:returns: Number of webmentions requeued.
"""
now = datetime.now(UTC)
- cutoff = now - timedelta(seconds=current_app.config["VERIFICATION_TIMEOUT_SECONDS"])
+ cutoff = now - timedelta(
+ seconds=current_app.config["VERIFICATION_STALE_AFTER_SECONDS"]
+ )
stale = db.session.execute(
sa.select(