From 9b00526ab79257b65cedd71595848f09ecf84279 Mon Sep 17 00:00:00 2001 From: Dennis Fink Date: Sun, 15 Nov 2026 21:18:19 +0100 Subject: refactor(core)!: clarify Webmention domain terminology Rename ambiguous models, statuses, task modules, fields, and helpers so names reflect source documents, verification, endpoint discovery, and delivery state. Migrate persisted status values and database identifiers without losing existing Webmention data. BREAKING CHANGE: persisted status values and database schema names have changed, and several public Python names have been renamed. --- webmentions_ssg/tasks/endpoint_discovery.py | 217 ++++++++++++++++++++++++++++ 1 file changed, 217 insertions(+) create mode 100644 webmentions_ssg/tasks/endpoint_discovery.py (limited to 'webmentions_ssg/tasks/endpoint_discovery.py') diff --git a/webmentions_ssg/tasks/endpoint_discovery.py b/webmentions_ssg/tasks/endpoint_discovery.py new file mode 100644 index 0000000..c683cb0 --- /dev/null +++ b/webmentions_ssg/tasks/endpoint_discovery.py @@ -0,0 +1,217 @@ +# SPDX-FileCopyrightText: 2026 Dennis Fink +# +# SPDX-License-Identifier: BSD-3-Clause + +"""Discover a target Webmention endpoint and submit a POST.""" + +import re +from http import HTTPStatus +from urllib.parse import urljoin + +import httpx +from bs4 import BeautifulSoup +from flask import current_app + +from ..net import ( + ResponseTooLargeError, + is_http_url, + is_retryable_status, + media_type_of, + read_limited_body, +) + +LINK_HEADER_SPLIT = re.compile(r",\s*(?=<)") +DISCOVERY_HEADERS = {"Accept": "text/html, application/xhtml+xml;q=0.9"} + + +class DeliveryError(Exception): + """A Webmention cannot be sent.""" + + +class RetryableDeliveryError(DeliveryError): + """A Webmention send failed for a potentially temporary reason.""" + + +class PermanentDeliveryError(DeliveryError): + """A Webmention send failed permanently for this source revision.""" + + +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 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 PermanentDeliveryError(f"Invalid Webmention endpoint: {href!r}") from exc + + if not is_http_url(endpoint): + raise PermanentDeliveryError(f"Invalid Webmention endpoint: {endpoint!r}") + + return endpoint + + +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. + :returns: Link target and relation names, or ``None`` if the value is invalid. + """ + value = value.strip() + + if not value.startswith("<"): + return None + + href, separator, parameters = value[1:].partition(">") + + if not separator: + return None + + relations: set[str] = set() + + for parameter in parameters.split(";"): + name, separator, value = parameter.partition("=") + + if separator and name.strip().lower() == "rel": + relations.update( + relation.lower() for relation in value.strip().strip("\"'").split() + ) + + return href, relations + + +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. + :returns: First valid advertised Webmention endpoint, or ``None`` if none is found. + Invalid candidates are ignored. + """ + for header in response.headers.get_list("Link"): + 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_url(response, href) + except PermanentDeliveryError: + continue + + return 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. + + :param response: HTTP response from which the document was retrieved. + :param body: HTML document body. + :returns: First valid advertised Webmention endpoint, or ``None`` if none is found. + Invalid candidates are ignored. + """ + document = BeautifulSoup(body, "html5lib") + + for element in document.select( + 'link[rel~="webmention" i][href], a[rel~="webmention" i][href]' + ): + try: + return resolve_endpoint_url(response, str(element["href"])) + except PermanentDeliveryError: + continue + + return None + + +def read_target_body(response: httpx.Response) -> bytes: + """Return a bounded target body, using the shared HTTP size guard. + + :param response: HTTP response to read with the configured target-size limit. + :returns: Response body, provided it is within the target-size limit. + :raises PermanentDeliveryError: If the target document is too large. + """ + try: + return read_limited_body( + response, current_app.config["MAX_DISCOVERY_TARGET_BYTES"], label="Target" + ) + except ResponseTooLargeError as exc: + raise PermanentDeliveryError(str(exc)) from exc + + +def discover_webmention_endpoint(client: httpx.Client, target: str) -> str | None: + """Discover the Webmention endpoint advertised by a target URL. + + Endpoint discovery first checks the response to a HEAD request and then falls + back to a GET request, inspecting both HTTP Link headers and supported HTML + documents. + + :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 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) + except httpx.RequestError: + # HEAD is only an optimization. Servers and intermediaries may reject + # or drop it even when fetching the document with GET would succeed. + pass + else: + if endpoint := find_endpoint_in_headers(head_response): + return endpoint + + with client.stream("GET", target, headers=DISCOVERY_HEADERS) as response: + if endpoint := find_endpoint_in_headers(response): + return endpoint + + if is_retryable_status(response.status_code): + raise RetryableDeliveryError(f"Target returned HTTP {response.status_code}") + + if not response.is_success: + raise PermanentDeliveryError(f"Target returned HTTP {response.status_code}") + + media_type = media_type_of(response.headers) + + if media_type not in {"text/html", "application/xhtml+xml"}: + return None + + return find_endpoint_in_html(response, read_target_body(response)) + + +def post_webmention( + client: httpx.Client, *, endpoint: str, source: str, target: str +) -> tuple[int, str | None]: + """Send a Webmention to a discovered endpoint. + + :param client: HTTP client to use for the request. + :param endpoint: Webmention endpoint URL. + :param source: Source URL of the Webmention. + :param target: Target URL of the Webmention. + :returns: HTTP response status code and optional status URL. + """ + with client.stream( + "POST", endpoint, data={"source": source, "target": target} + ) as response: + status_url = None + + if response.status_code == HTTPStatus.CREATED and ( + location := response.headers.get("Location") + ): + try: + candidate = urljoin(str(response.url), location) + except ValueError: + # A malformed Location must not fail an otherwise successful send. + pass + else: + if is_http_url(candidate): + status_url = candidate + + return (response.status_code, status_url) -- cgit v1.3.1