diff options
| author | Dennis Fink | 2026-11-19 19:42:41 +0100 |
|---|---|---|
| committer | Dennis Fink | 2026-11-19 20:59:24 +0100 |
| commit | 88f54d9a7699944b7d56f978e724b1c0b54dde98 (patch) | |
| tree | 88ecc527903a91a6f6622ca288b278e5875aff3d /webmentions_ssg/failure_guidance.py | |
| parent | 8ec35babe87ff8139ec23cc10b858b7481f132db (diff) | |
| download | webmentions-ssg-88f54d9a7699944b7d56f978e724b1c0b54dde98.tar.gz webmentions-ssg-88f54d9a7699944b7d56f978e724b1c0b54dde98.zip | |
feat(sender): add bulk resend and delivery history
Allow admins to resend all failed Webmentions globally or requeue every
delivery for a source using the shared confirmation workflow.
Record outgoing status history, expand sent source details, and provide
human-readable guidance for current and historical delivery failures.
Diffstat (limited to 'webmentions_ssg/failure_guidance.py')
| -rw-r--r-- | webmentions_ssg/failure_guidance.py | 244 |
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 |
