aboutsummaryrefslogtreecommitdiff
path: root/webmentions_ssg/failure_guidance.py
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--webmentions_ssg/failure_guidance.py244
1 files changed, 244 insertions, 0 deletions
diff --git a/webmentions_ssg/failure_guidance.py b/webmentions_ssg/failure_guidance.py
new file mode 100644
index 0000000..2a507a4
--- /dev/null
+++ b/webmentions_ssg/failure_guidance.py
@@ -0,0 +1,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