diff options
Diffstat (limited to 'webmentions_ssg/tasks/discovery.py')
| -rw-r--r-- | webmentions_ssg/tasks/discovery.py | 217 |
1 files changed, 0 insertions, 217 deletions
diff --git a/webmentions_ssg/tasks/discovery.py b/webmentions_ssg/tasks/discovery.py deleted file mode 100644 index c683cb0..0000000 --- a/webmentions_ssg/tasks/discovery.py +++ /dev/null @@ -1,217 +0,0 @@ -# SPDX-FileCopyrightText: 2026 Dennis Fink <me+coding@dennisfink.me> -# -# 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) |
