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
|
# SPDX-FileCopyrightText: 2026 Dennis Fink <me+coding@dennisfink.me>
#
# SPDX-License-Identifier: BSD-3-Clause
"""Explain stored received Webmention failures without assuming source-site control.
Only suggest a next step when it addresses a receiver setting or operation the
site administrator can control. Source-site and ambiguous network failures get
an explanation, but no instructions to edit or repair an external website.
The persisted technical reason remains unchanged, including in status history.
"""
import re
from dataclasses import dataclass
@dataclass(frozen=True)
class FailureGuidance:
"""Explanation of a known failure, with an optional receiver-side action."""
explanation: str
next_step: str | None = None
KNOWN_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 := KNOWN_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
|