# SPDX-FileCopyrightText: 2026 Dennis Fink # # SPDX-License-Identifier: BSD-3-Clause """Discover a target Webmention endpoint and submit a POST.""" import re from urllib.parse import urljoin import httpx from bs4 import BeautifulSoup from flask import current_app from ..net import is_http_url, is_temporary_status, read_limited_body LINK_SPLIT = re.compile(r",\s*(?=<)") DISCOVERY_HEADERS = {"Accept": "text/html, application/xhtml+xml;q=0.9"} class SenderError(Exception): """A Webmention cannot be sent.""" class TemporarySenderError(SenderError): """A Webmention send failed for a potentially temporary reason.""" class PermanentSenderError(SenderError): """A Webmention send failed permanently for this source revision.""" def resolve_endpoint(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. :return: Absolute Webmention endpoint URL. :raises PermanentSenderError: 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 if not is_http_url(endpoint): raise PermanentSenderError(f"Invalid Webmention endpoint: {endpoint!r}") return endpoint def parse_link_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. :return: 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 endpoint_from_headers(response: httpx.Response) -> str | None: """Find a Webmention endpoint in the response Link headers. :param response: HTTP response whose headers should be inspected. :return: 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_SPLIT.split(header): if (link := parse_link_value(value)) is None: continue href, relations = link if "webmention" in relations: try: return resolve_endpoint(response, href) except PermanentSenderError: continue return None def endpoint_from_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. :return: 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(response, str(element["href"])) except PermanentSenderError: continue return None def read_target_body(response: httpx.Response) -> bytes: """Return a bounded target body, using the shared HTTP size guard.""" try: return read_limited_body( response, current_app.config["MAX_TARGET_BYTES"], label="Target" ) except ValueError as exc: raise PermanentSenderError(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. :return: 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. """ try: head_response = client.head(target, headers=DISCOVERY_HEADERS) except httpx.RequestError, TemporarySenderError: # 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 := endpoint_from_headers(head_response): return endpoint with client.stream("GET", target, headers=DISCOVERY_HEADERS) as response: if endpoint := endpoint_from_headers(response): return endpoint if is_temporary_status(response.status_code): raise TemporarySenderError(f"Target returned HTTP {response.status_code}") if not response.is_success: raise PermanentSenderError(f"Target returned HTTP {response.status_code}") media_type = ( response.headers.get("Content-Type", "").partition(";")[0].strip().lower() ) if media_type not in {"text/html", "application/xhtml+xml"}: return None return endpoint_from_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. :return: 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 == 201 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)