aboutsummaryrefslogtreecommitdiff
path: root/webmentions_ssg/tasks/discovery.py
blob: 98f3fd5b232ea752579409a414ecee1fd763163d (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
# 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 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.find_all(["link", "a"], href=True):
        relations = element.get("rel")

        if isinstance(relations, str):
            relations = relations.split()

        if not relations:
            continue

        if not any(
            isinstance(relation, str) and relation.lower() == "webmention"
            for relation in relations
        ):
            continue

        href = element.get("href")

        if not isinstance(href, str):
            continue

        try:
            return resolve_endpoint(response, 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)