From 63af533d98aac82b6d4f069b217d3e837285508d Mon Sep 17 00:00:00 2001 From: Dennis Fink Date: Tue, 17 Nov 2026 22:10:40 +0100 Subject: 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. --- webmentions_ssg/forms/validators.py | 9 +- webmentions_ssg/received_failure.py | 105 +++++++++++++++++++++ .../templates/includes/received_failure.html | 22 +++++ webmentions_ssg/templates/received_detail.html | 27 +++--- webmentions_ssg/views/received.py | 5 + 5 files changed, 156 insertions(+), 12 deletions(-) create mode 100644 webmentions_ssg/received_failure.py create mode 100644 webmentions_ssg/templates/includes/received_failure.html (limited to 'webmentions_ssg') diff --git a/webmentions_ssg/forms/validators.py b/webmentions_ssg/forms/validators.py index e65e9cb..a22c942 100644 --- a/webmentions_ssg/forms/validators.py +++ b/webmentions_ssg/forms/validators.py @@ -102,7 +102,14 @@ class AllowedTargetHostname: if hostname in current_app.config["ALLOWED_TARGET_HOSTNAMES"]: return - raise ValidationError(self.message or field.gettext("Invalid input.")) + raise ValidationError( + self.message + or field.gettext( + "Target hostname is not in ALLOWED_TARGET_HOSTNAMES." + if hostname is not None + else "Invalid input." + ) + ) class RejectNonPublicIPLiteral: 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 +# +# 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 diff --git a/webmentions_ssg/templates/includes/received_failure.html b/webmentions_ssg/templates/includes/received_failure.html new file mode 100644 index 0000000..65ed7a3 --- /dev/null +++ b/webmentions_ssg/templates/includes/received_failure.html @@ -0,0 +1,22 @@ + + +{% macro render_failure(reason) %} + {% set guidance = reason | received_failure_guidance %} + {% if guidance %} +
{{ guidance.explanation }}
+ {% if guidance.next_step %} +
Suggested next step: {{ guidance.next_step }}
+ {% endif %} +
+ Technical reason +
{{ reason }}
+
+ {% else %} +
{{ reason }}
+
Check the application logs for details before reverifying.
+ {% endif %} +{% endmacro %} diff --git a/webmentions_ssg/templates/received_detail.html b/webmentions_ssg/templates/received_detail.html index 091e2e4..32d3e05 100644 --- a/webmentions_ssg/templates/received_detail.html +++ b/webmentions_ssg/templates/received_detail.html @@ -5,6 +5,7 @@ SPDX-License-Identifier: BSD-3-Clause --> {% extends "base.html" %} +{% from "includes/received_failure.html" import render_failure %} {% set status_presentation = { "received": { "badge": "text-bg-info", @@ -78,7 +79,7 @@ SPDX-License-Identifier: BSD-3-Clause
Failure reason
{% if webmention.failure_reason %} -
{{ webmention.failure_reason }}
+ {{ render_failure(webmention.failure_reason) }} {% else %} None {% endif %} @@ -121,17 +122,21 @@ SPDX-License-Identifier: BSD-3-Clause
    {% for event in history %} {% set event_style = status_presentation.get(event.status, {"badge": "text-bg-secondary", "label": "Unknown"}) %} -
  1. -
    - {{ event_style.label }} - {{ event.action }} - +
  2. +
    +
    + {{ event_style.label }} + {{ event.action }} + +
    +
    Recovery attempts: {{ event.recovery_attempts }}
    + {% if event.failure_reason %} +
    {{ render_failure(event.failure_reason) }}
    + {% endif %}
    -
    Recovery attempts: {{ event.recovery_attempts }}
    - {% if event.failure_reason %} -
    {{ event.failure_reason }}
    - {% endif %}
  3. {% endfor %}
diff --git a/webmentions_ssg/views/received.py b/webmentions_ssg/views/received.py index 84c5750..ef63893 100644 --- a/webmentions_ssg/views/received.py +++ b/webmentions_ssg/views/received.py @@ -29,10 +29,15 @@ from ..models.received import ( purge_orphaned_received_events, ) from ..moderation_policy import domain_from_url +from ..received_failure import describe_received_failure from ..tasks.verification import verify_webmention from .blueprint import webmentions_bp from .moderation import block_domains +webmentions_bp.add_app_template_filter( + describe_received_failure, "received_failure_guidance" +) + RECEIVED_STATUS_FILTERS = { "pending": (ReceivedWebmentionStatus.RECEIVED,), "verifying": (ReceivedWebmentionStatus.VERIFYING,), -- cgit v1.3.1