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
|
# 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,
content_type_of,
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.
:returns: 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.
: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 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.
: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_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.
: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(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.
:param response: HTTP response to read with the configured target-size limit.
:returns: Response body, provided it is within the target-size limit.
:raises PermanentSenderError: If the target document is too large.
"""
try:
return read_limited_body(
response, current_app.config["MAX_TARGET_BYTES"], label="Target"
)
except ResponseTooLargeError 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.
:returns: 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:
# 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 = content_type_of(response.headers)
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.
: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)
|