aboutsummaryrefslogtreecommitdiff
path: root/webmentions_ssg/tasks/discovery.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/discovery.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/discovery.py62
1 files changed, 31 insertions, 31 deletions
diff --git a/webmentions_ssg/tasks/discovery.py b/webmentions_ssg/tasks/discovery.py
index 6d01e53..c683cb0 100644
--- a/webmentions_ssg/tasks/discovery.py
+++ b/webmentions_ssg/tasks/discovery.py
@@ -14,48 +14,48 @@ from flask import current_app
from ..net import (
ResponseTooLargeError,
- content_type_of,
is_http_url,
- is_temporary_status,
+ is_retryable_status,
+ media_type_of,
read_limited_body,
)
-LINK_SPLIT = re.compile(r",\s*(?=<)")
+LINK_HEADER_SPLIT = re.compile(r",\s*(?=<)")
DISCOVERY_HEADERS = {"Accept": "text/html, application/xhtml+xml;q=0.9"}
-class SenderError(Exception):
+class DeliveryError(Exception):
"""A Webmention cannot be sent."""
-class TemporarySenderError(SenderError):
+class RetryableDeliveryError(DeliveryError):
"""A Webmention send failed for a potentially temporary reason."""
-class PermanentSenderError(SenderError):
+class PermanentDeliveryError(DeliveryError):
"""A Webmention send failed permanently for this source revision."""
-def resolve_endpoint(response: httpx.Response, href: str) -> str:
+def resolve_endpoint_url(response: httpx.Response, href: str) -> str:
"""Resolve and validate a discovered Webmention endpoint.
:param response: Response from which the endpoint was discovered.
:param href: Endpoint reference to resolve.
:returns: Absolute Webmention endpoint URL.
- :raises PermanentSenderError: If the resolved endpoint is not an HTTP or HTTPS URL.
+ :raises PermanentDeliveryError: If the resolved endpoint is not an HTTP or HTTPS URL.
"""
try:
endpoint = urljoin(str(response.url), href.strip())
except ValueError as exc:
- raise PermanentSenderError(f"Invalid Webmention endpoint: {href!r}") from exc
+ raise PermanentDeliveryError(f"Invalid Webmention endpoint: {href!r}") from exc
if not is_http_url(endpoint):
- raise PermanentSenderError(f"Invalid Webmention endpoint: {endpoint!r}")
+ raise PermanentDeliveryError(f"Invalid Webmention endpoint: {endpoint!r}")
return endpoint
-def parse_link_value(value: str) -> tuple[str, set[str]] | None:
+def parse_link_header_value(value: str) -> tuple[str, set[str]] | None:
"""Parse a Link header value into its target and relations.
:param value: Link header value to parse.
@@ -84,7 +84,7 @@ def parse_link_value(value: str) -> tuple[str, set[str]] | None:
return href, relations
-def endpoint_from_headers(response: httpx.Response) -> str | None:
+def find_endpoint_in_headers(response: httpx.Response) -> str | None:
"""Find a Webmention endpoint in the response Link headers.
:param response: HTTP response whose headers should be inspected.
@@ -92,22 +92,22 @@ def endpoint_from_headers(response: httpx.Response) -> str | None:
Invalid candidates are ignored.
"""
for header in response.headers.get_list("Link"):
- for value in LINK_SPLIT.split(header):
- if (link := parse_link_value(value)) is None:
+ for value in LINK_HEADER_SPLIT.split(header):
+ if (link := parse_link_header_value(value)) is None:
continue
href, relations = link
if "webmention" in relations:
try:
- return resolve_endpoint(response, href)
- except PermanentSenderError:
+ return resolve_endpoint_url(response, href)
+ except PermanentDeliveryError:
continue
return None
-def endpoint_from_html(response: httpx.Response, body: bytes) -> str | None:
+def find_endpoint_in_html(response: httpx.Response, body: bytes) -> str | None:
"""Find a Webmention endpoint in an HTML document.
``link`` and ``a`` elements are inspected in document order.
@@ -123,8 +123,8 @@ def endpoint_from_html(response: httpx.Response, body: bytes) -> str | None:
'link[rel~="webmention" i][href], a[rel~="webmention" i][href]'
):
try:
- return resolve_endpoint(response, str(element["href"]))
- except PermanentSenderError:
+ return resolve_endpoint_url(response, str(element["href"]))
+ except PermanentDeliveryError:
continue
return None
@@ -135,14 +135,14 @@ def read_target_body(response: httpx.Response) -> bytes:
:param response: HTTP response to read with the configured target-size limit.
:returns: Response body, provided it is within the target-size limit.
- :raises PermanentSenderError: If the target document is too large.
+ :raises PermanentDeliveryError: If the target document is too large.
"""
try:
return read_limited_body(
- response, current_app.config["MAX_TARGET_BYTES"], label="Target"
+ response, current_app.config["MAX_DISCOVERY_TARGET_BYTES"], label="Target"
)
except ResponseTooLargeError as exc:
- raise PermanentSenderError(str(exc)) from exc
+ raise PermanentDeliveryError(str(exc)) from exc
def discover_webmention_endpoint(client: httpx.Client, target: str) -> str | None:
@@ -155,8 +155,8 @@ def discover_webmention_endpoint(client: httpx.Client, target: str) -> str | Non
:param client: HTTP client to use for discovery requests.
:param target: Target URL whose Webmention endpoint should be discovered.
:returns: Discovered Webmention endpoint, or ``None`` if none is advertised.
- :raises TemporarySenderError: If the target returns a temporary HTTP failure.
- :raises PermanentSenderError: If GET returns a permanent HTTP failure.
+ :raises RetryableDeliveryError: If the target returns a temporary HTTP failure.
+ :raises PermanentDeliveryError: If GET returns a permanent HTTP failure.
"""
try:
head_response = client.head(target, headers=DISCOVERY_HEADERS)
@@ -165,25 +165,25 @@ def discover_webmention_endpoint(client: httpx.Client, target: str) -> str | Non
# or drop it even when fetching the document with GET would succeed.
pass
else:
- if endpoint := endpoint_from_headers(head_response):
+ if endpoint := find_endpoint_in_headers(head_response):
return endpoint
with client.stream("GET", target, headers=DISCOVERY_HEADERS) as response:
- if endpoint := endpoint_from_headers(response):
+ if endpoint := find_endpoint_in_headers(response):
return endpoint
- if is_temporary_status(response.status_code):
- raise TemporarySenderError(f"Target returned HTTP {response.status_code}")
+ if is_retryable_status(response.status_code):
+ raise RetryableDeliveryError(f"Target returned HTTP {response.status_code}")
if not response.is_success:
- raise PermanentSenderError(f"Target returned HTTP {response.status_code}")
+ raise PermanentDeliveryError(f"Target returned HTTP {response.status_code}")
- media_type = content_type_of(response.headers)
+ media_type = media_type_of(response.headers)
if media_type not in {"text/html", "application/xhtml+xml"}:
return None
- return endpoint_from_html(response, read_target_body(response))
+ return find_endpoint_in_html(response, read_target_body(response))
def post_webmention(