# SPDX-FileCopyrightText: 2026 Dennis Fink # # 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