aboutsummaryrefslogtreecommitdiff
path: root/webmentions_ssg/tasks/discovery.py
diff options
context:
space:
mode:
Diffstat (limited to 'webmentions_ssg/tasks/discovery.py')
-rw-r--r--webmentions_ssg/tasks/discovery.py217
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)