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
232
233
234
235
236
237
238
239
240
241
242
243
244
|
# SPDX-FileCopyrightText: 2026 Dennis Fink <me+coding@dennisfink.me>
#
# SPDX-License-Identifier: BSD-3-Clause
"""Explain received and sent Webmention failures without changing their reasons.
Only suggest actions the local site operator can reasonably take. Remote-site
failures are described without presuming control of another website. The original
technical reason remains available in the UI, including for historical events.
"""
import re
from dataclasses import dataclass
@dataclass(frozen=True)
class FailureGuidance:
"""Explanation of a known failure, with an optional operator action."""
explanation: str
next_step: str | None = None
RECEIVED_REASONS = {
"Source does not mention target": FailureGuidance(
"The source page does not contain a recognized link to the target URL."
),
"Source returned HTTP 410": FailureGuidance(
"The source server reports that the page is permanently gone (HTTP 410)."
),
"Source document is too large": FailureGuidance(
"The source page exceeds the receiver's configured maximum response size."
),
"Source resolves to a non-public address": FailureGuidance(
"The source hostname resolves to a non-public address, "
"which the receiver blocks for security."
),
"Source hostname could not be resolved": FailureGuidance(
"The source hostname could not be resolved through DNS."
),
"Source could not be fetched": FailureGuidance(
"The receiver could not fetch the source page; the cause may be external "
"or network-related."
),
"Invalid source hostname": FailureGuidance(
"The submitted source URL does not have a valid hostname."
),
"Source domain is blocked": FailureGuidance(
"The source hostname matches a domain on this receiver's blocklist.",
"Review the blocklist in Moderation. "
"If the block was unintended, remove it and reverify.",
),
"Source domain is not allowlisted": FailureGuidance(
"The source hostname is not on this receiver's allowed source-domain list.",
"Review the allowlist in Moderation. "
"If the domain should be accepted, add it and reverify.",
),
"Verification recovery limit reached": FailureGuidance(
"Verification stalled too many times and automatic recovery stopped.",
"Check the verification workers, queue, and application logs. "
"Reverify after resolving a local issue.",
),
"Target hostname is not in ALLOWED_TARGET_HOSTNAMES": FailureGuidance(
"The target hostname is not configured to receive Webmentions.",
"Check ALLOWED_TARGET_HOSTNAMES. "
"Add this hostname only if you receive Webmentions for that site.",
),
}
def describe_received_failure(reason: str) -> FailureGuidance | None:
"""Return an explanation for known reasons, or ``None`` for unknown ones.
A missing next step is intentional: receiving operators usually cannot
repair pages or HTTP responses on someone else's website. Unknown reasons
stay raw, rather than being assigned a speculative explanation or action.
"""
if guidance := RECEIVED_REASONS.get(reason.removesuffix(".")):
return guidance
if match := re.fullmatch(r"Source returned HTTP ([1-5]\d{2})", reason):
code = int(match.group(1))
if code == 404:
return FailureGuidance("The source page was not found (HTTP 404).")
if code in (401, 403):
return FailureGuidance(f"The source server denied access (HTTP {code}).")
if code == 429:
return FailureGuidance("The source server is limiting requests (HTTP 429).")
if 500 <= code <= 599:
return FailureGuidance(
f"The source server returned a server error (HTTP {code})."
)
return FailureGuidance(
f"The source server returned HTTP {code} instead of a successful response."
)
prefix = "Unsupported source content type: "
if reason.startswith(prefix):
media_type = reason[len(prefix) :]
return FailureGuidance(
f"The source uses an unsupported content type ({media_type})."
)
return None
SENT_REASONS = {
"No Webmention endpoint discovered": FailureGuidance(
"The target page does not advertise a usable Webmention endpoint "
"in its HTTP Link headers or HTML."
),
"Target document is too large": FailureGuidance(
"The target page exceeds the configured response-size limit for endpoint "
"discovery.",
"Review MAX_DISCOVERY_TARGET_BYTES if you trust the target and need "
"to support larger pages.",
),
"Webmention request failed": FailureGuidance(
"The sender could not complete a request to the target or its "
"Webmention endpoint.",
"Check the sender's network connection and application logs before resending.",
),
"timed out": FailureGuidance(
"The connection or request timed out before the sender received a response.",
"Check local network connectivity. Resend after the remote service responds.",
),
"The read operation timed out": FailureGuidance(
"The remote server did not deliver its response before the read timeout.",
"Resend after the remote service is responding normally.",
),
"All connection attempts failed": FailureGuidance(
"The sender could not establish a connection to the remote server.",
"Check local network connectivity and resend if the remote server "
"becomes reachable.",
),
"Server disconnected without sending a response": FailureGuidance(
"The remote server closed the connection without sending an HTTP response."
),
}
def _describe_sent_http_failure(subject: str, code: int) -> FailureGuidance:
"""Explain an HTTP status in the context of outgoing delivery."""
if code == 404:
return FailureGuidance(f"The {subject} was not found (HTTP 404).")
if code == 410:
return FailureGuidance(f"The {subject} is permanently gone (HTTP 410).")
if code in (401, 403):
return FailureGuidance(f"The {subject} denied access (HTTP {code}).")
if code == 408:
return FailureGuidance(
f"The {subject} timed out the request (HTTP 408).",
"Automatic retries run while attempts remain. If exhausted, resend "
"once the remote service is available.",
)
if code == 429:
return FailureGuidance(
f"The {subject} is rate-limiting requests (HTTP 429).",
"Automatic retries run while attempts remain. If exhausted, resend "
"after the remote rate limit clears.",
)
if 500 <= code <= 599:
return FailureGuidance(
f"The {subject} returned a server error (HTTP {code}).",
"Automatic retries run while attempts remain. If exhausted, resend "
"after the remote service recovers.",
)
if subject == "Webmention endpoint" and code in (400, 422):
return FailureGuidance(
f"The Webmention endpoint rejected the submission (HTTP {code}).",
"Check that your published source page links to the target URL. "
"If the link needs correcting, update the source and rescan "
"before resending.",
)
return FailureGuidance(
f"The {subject} returned HTTP {code}, which did not complete delivery."
)
def describe_sent_failure(reason: str) -> FailureGuidance | None:
"""Explain known outgoing errors; leave unrecognized technical reasons raw.
Sender errors may originate during target discovery, endpoint submission,
public-address validation, or HTTP transport. Never assume a remote server
can be repaired by this site's operator.
"""
reason_normalized = reason.removesuffix(".")
if guidance := SENT_REASONS.get(reason_normalized):
return guidance
if match := re.fullmatch(
r"(Target|Webmention endpoint) returned HTTP ([1-5]\d{2})", reason_normalized
):
subject = "target page" if match.group(1) == "Target" else "Webmention endpoint"
return _describe_sent_http_failure(subject, int(match.group(2)))
if re.fullmatch(r"Retry limit reached \(\d+ attempts\)", reason_normalized):
return FailureGuidance(
"The sender exhausted its configured delivery attempts without "
"a recorded success.",
"Check the sender logs and the underlying delivery issue, then resend.",
)
if reason.startswith("Invalid target URL:"):
return FailureGuidance(
"The target URL is not a valid HTTP or HTTPS URL.",
"Correct the target link in the source document and rescan "
"before resending.",
)
if reason.startswith("Invalid Webmention endpoint:"):
return FailureGuidance(
"The advertised Webmention endpoint URL is malformed or uses "
"an unsupported scheme."
)
if reason.startswith("Could not resolve hostname "):
return FailureGuidance(
"DNS resolution failed for a hostname used during delivery.",
"Check the target link for typos and this sender's DNS connectivity. "
"Resend after the hostname resolves.",
)
if reason.startswith("Non-public network address for "):
return FailureGuidance(
"The hostname resolves to a non-public address, which the sender "
"blocks for security.",
"Verify that the target link points to a public URL. "
"Keep the private-address protection enabled.",
)
if reason.startswith("No public addresses available for "):
return FailureGuidance(
"The sender could not find a usable public address for the remote host."
)
if re.fullmatch(r"\[Errno \d+\] Connection refused", reason_normalized):
return FailureGuidance(
"The remote host refused the sender's connection.",
"Check network connectivity and resend after the remote service "
"is available.",
)
return None
|