aboutsummaryrefslogtreecommitdiff
path: root/webmentions_ssg/received_failure.py
diff options
context:
space:
mode:
authorDennis Fink2026-11-19 19:42:41 +0100
committerDennis Fink2026-11-19 20:59:24 +0100
commit88f54d9a7699944b7d56f978e724b1c0b54dde98 (patch)
tree88ecc527903a91a6f6622ca288b278e5875aff3d /webmentions_ssg/received_failure.py
parent8ec35babe87ff8139ec23cc10b858b7481f132db (diff)
downloadwebmentions-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/received_failure.py')
-rw-r--r--webmentions_ssg/received_failure.py105
1 files changed, 0 insertions, 105 deletions
diff --git a/webmentions_ssg/received_failure.py b/webmentions_ssg/received_failure.py
deleted file mode 100644
index ccada94..0000000
--- a/webmentions_ssg/received_failure.py
+++ /dev/null
@@ -1,105 +0,0 @@
-# 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