aboutsummaryrefslogtreecommitdiff
path: root/webmentions_ssg/received_failure.py
diff options
context:
space:
mode:
authorDennis Fink2026-11-17 22:10:40 +0100
committerDennis Fink2026-11-17 22:10:40 +0100
commit63af533d98aac82b6d4f069b217d3e837285508d (patch)
tree4ac11960f9676d3bb5a6f62204ef139862734209 /webmentions_ssg/received_failure.py
parentacd1f42847786963fc4aaeed884c3091700c9e35 (diff)
downloadwebmentions-ssg-63af533d98aac82b6d4f069b217d3e837285508d.tar.gz
webmentions-ssg-63af533d98aac82b6d4f069b217d3e837285508d.zip
feat(receiver): explain received Webmention failures
Map known verification failures to human-readable explanations and show suggested next steps only for receiver-controlled problems while retaining raw reasons. Return a specific validation error when targets are outside `ALLOWED_TARGET_HOSTNAMES` and reuse the guidance for status history.
Diffstat (limited to '')
-rw-r--r--webmentions_ssg/received_failure.py105
1 files changed, 105 insertions, 0 deletions
diff --git a/webmentions_ssg/received_failure.py b/webmentions_ssg/received_failure.py
new file mode 100644
index 0000000..ccada94
--- /dev/null
+++ b/webmentions_ssg/received_failure.py
@@ -0,0 +1,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