diff options
| author | Dennis Fink | 2026-11-17 22:10:40 +0100 |
|---|---|---|
| committer | Dennis Fink | 2026-11-17 22:10:40 +0100 |
| commit | 63af533d98aac82b6d4f069b217d3e837285508d (patch) | |
| tree | 4ac11960f9676d3bb5a6f62204ef139862734209 | |
| parent | acd1f42847786963fc4aaeed884c3091700c9e35 (diff) | |
| download | webmentions-ssg-63af533d98aac82b6d4f069b217d3e837285508d.tar.gz webmentions-ssg-63af533d98aac82b6d4f069b217d3e837285508d.zip | |
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.
| -rw-r--r-- | tests/forms/test_validators.py | 4 | ||||
| -rw-r--r-- | tests/test_received_failure.py | 53 | ||||
| -rw-r--r-- | tests/views/test_endpoint.py | 16 | ||||
| -rw-r--r-- | tests/views/test_received.py | 109 | ||||
| -rw-r--r-- | webmentions_ssg/forms/validators.py | 9 | ||||
| -rw-r--r-- | webmentions_ssg/received_failure.py | 105 | ||||
| -rw-r--r-- | webmentions_ssg/templates/includes/received_failure.html | 22 | ||||
| -rw-r--r-- | webmentions_ssg/templates/received_detail.html | 27 | ||||
| -rw-r--r-- | webmentions_ssg/views/received.py | 5 |
9 files changed, 337 insertions, 13 deletions
diff --git a/tests/forms/test_validators.py b/tests/forms/test_validators.py index 4234552..8822310 100644 --- a/tests/forms/test_validators.py +++ b/tests/forms/test_validators.py @@ -28,7 +28,9 @@ def test_allowed_hostname_accepts_configured_hostname(app: Flask) -> None: def test_allowed_hostname_rejects_unconfigured_hostname(app: Flask) -> None: app.config["ALLOWED_TARGET_HOSTNAMES"] = ["dennisfink.me"] form = URLForm(MultiDict({"url": "https://example.com/post"})) - with app.app_context(), pytest.raises(ValidationError, match="Invalid input"): + with app.app_context(), pytest.raises( + ValidationError, match="Target hostname is not in ALLOWED_TARGET_HOSTNAMES" + ): AllowedTargetHostname()(form, form.url) diff --git a/tests/test_received_failure.py b/tests/test_received_failure.py new file mode 100644 index 0000000..095d7e1 --- /dev/null +++ b/tests/test_received_failure.py @@ -0,0 +1,53 @@ +# SPDX-FileCopyrightText: 2026 Dennis Fink <me+coding@dennisfink.me> +# +# SPDX-License-Identifier: BSD-3-Clause + +import pytest + +from webmentions_ssg.received_failure import describe_received_failure + + +@pytest.mark.parametrize( + ("reason", "expected_fragment", "local_step"), + [ + ("Source does not mention target", "link to the target URL", False), + ("Source returned HTTP 410", "permanently gone", False), + ("Source document is too large", "maximum response size", False), + ("Source resolves to a non-public address", "non-public address", False), + ("Source hostname could not be resolved", "DNS", False), + ("Source could not be fetched", "could not fetch", False), + ("Invalid source hostname", "valid hostname", False), + ("Source domain is blocked", "blocklist", True), + ("Source domain is not allowlisted", "allowed source-domain", True), + ("Verification recovery limit reached", "automatic recovery stopped", True), + ("Target hostname is not in ALLOWED_TARGET_HOSTNAMES", "target hostname", True), + ( + "Target hostname is not in ALLOWED_TARGET_HOSTNAMES.", + "target hostname", + True, + ), + ("Source returned HTTP 404", "not found", False), + ("Source returned HTTP 401", "denied access", False), + ("Source returned HTTP 403", "denied access", False), + ("Source returned HTTP 429", "limiting requests", False), + ("Source returned HTTP 503", "server error", False), + ("Source returned HTTP 400", "returned HTTP 400", False), + ( + "Unsupported source content type: application/json", + "application/json", + False, + ), + ], +) +def test_only_receiver_controlled_failures_suggest_steps( + reason: str, expected_fragment: str, local_step: bool +) -> None: + guidance = describe_received_failure(reason) + assert guidance is not None + assert expected_fragment in guidance.explanation + assert bool(guidance.next_step) is local_step + + +@pytest.mark.parametrize("reason", ["unknown failure", "", "Source returned HTTP 999"]) +def test_unknown_received_failures_are_not_misclassified(reason: str) -> None: + assert describe_received_failure(reason) is None diff --git a/tests/views/test_endpoint.py b/tests/views/test_endpoint.py index 4a2abde..cb6f426 100644 --- a/tests/views/test_endpoint.py +++ b/tests/views/test_endpoint.py @@ -50,6 +50,22 @@ def test_endpoint_returns_form_errors( assert response.get_json() == errors +def test_endpoint_explains_disallowed_target_hostname_without_storing_a_mention( + app: Flask, client: FlaskClient +) -> None: + response = client.post( + "/endpoint", + data={"source": SOURCE_URL, "target": "https://unconfigured.example/post"}, + ) + + assert response.status_code == HTTPStatus.BAD_REQUEST + assert response.get_json() == { + "target": ["Target hostname is not in ALLOWED_TARGET_HOSTNAMES."] + } + with app.app_context(): + assert db.session.scalar(sa.select(ReceivedWebmention)) is None + + def test_endpoint_creates_webmention( app: Flask, client: FlaskClient, diff --git a/tests/views/test_received.py b/tests/views/test_received.py index f23119d..5ae42f7 100644 --- a/tests/views/test_received.py +++ b/tests/views/test_received.py @@ -1122,6 +1122,115 @@ def test_received_detail_shows_full_reason_timestamps_and_public_status( assert "No historical transitions were recorded" in html +@pytest.mark.parametrize( + ("reason", "explanation", "next_step"), + [ + ( + "Source does not mention target", + "does not contain a recognized link", + None, + ), + ( + "Source returned HTTP 404", + "source page was not found", + None, + ), + ( + "Source returned HTTP 503", + "source server returned a server error", + None, + ), + ( + "Source hostname could not be resolved", + "could not be resolved through DNS", + None, + ), + ( + "Source document is too large", + "configured maximum response size", + None, + ), + ( + "Source domain is blocked", + "receiver's blocklist", + "Review the blocklist in Moderation", + ), + ( + "Source domain is not allowlisted", + "allowed source-domain list", + "Review the allowlist in Moderation", + ), + ( + "Verification recovery limit reached", + "automatic recovery stopped", + "Check the verification workers", + ), + ( + "Target hostname is not in ALLOWED_TARGET_HOSTNAMES", + "target hostname is not configured", + "Check ALLOWED_TARGET_HOSTNAMES", + ), + ], +) +def test_received_detail_only_suggests_receiver_controlled_steps( + app: Flask, + client: FlaskClient, + reason: str, + explanation: str, + next_step: str | None, +) -> None: + log_in(app, client) + identifier = create_received_webmention(app, status="failed", failure_reason=reason) + + response = client.get(f"/received/{identifier}") + + assert response.status_code == HTTPStatus.OK + soup = BeautifulSoup(response.get_data(as_text=True), "html.parser") + assert explanation in soup.get_text() + if next_step is not None: + assert "Suggested next step:" in soup.get_text() + assert next_step in soup.get_text() + else: + assert "Suggested next step:" not in soup.get_text() + details = soup.find("details") + assert details is not None + assert reason in details.get_text() + + + +def test_received_detail_explains_historical_failure_and_escapes_raw_text( + app: Flask, client: FlaskClient +) -> None: + from webmentions_ssg.models.received import ( + ReceivedWebmentionStatus, + ReceivedWebmentionStatusEvent, + ) + + log_in(app, client) + identifier = create_received_webmention(app, status="verified") + raw_reason = "Unsupported source content type: text/<script>alert('x')</script>" + with app.app_context(): + db.session.add( + ReceivedWebmentionStatusEvent( + webmention_uuid=identifier, + status=ReceivedWebmentionStatus.FAILED, + action="Verification completed", + failure_reason=raw_reason, + occurred_at=datetime(2026, 11, 10, tzinfo=UTC), + ) + ) + db.session.commit() + + response = client.get(f"/received/{identifier}") + html = response.get_data(as_text=True) + soup = BeautifulSoup(html, "html.parser") + assert "unsupported content type" in soup.get_text() + assert "Suggested next step:" not in soup.get_text() + assert raw_reason in soup.get_text() + assert "<script>" not in html + assert "<script>" in html + + def test_received_detail_keeps_filters_and_returns_after_actions( app: Flask, client: FlaskClient, 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 <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 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 @@ +<!-- +SPDX-FileCopyrightText: 2026 Dennis Fink <me+coding@dennisfink.me> + +SPDX-License-Identifier: BSD-3-Clause +--> + +{% macro render_failure(reason) %} + {% set guidance = reason | received_failure_guidance %} + {% if guidance %} + <div class="text-break">{{ guidance.explanation }}</div> + {% if guidance.next_step %} + <div class="mt-1 text-break"><strong>Suggested next step:</strong> {{ guidance.next_step }}</div> + {% endif %} + <details class="mt-2"> + <summary class="small text-body-secondary">Technical reason</summary> + <div class="small text-break text-pre-formatted">{{ reason }}</div> + </details> + {% else %} + <div class="text-break text-pre-formatted">{{ reason }}</div> + <div class="small text-body-secondary mt-1">Check the application logs for details before reverifying.</div> + {% 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 <dt class="col-md-3">Failure reason</dt> <dd class="col-md-9"> {% if webmention.failure_reason %} - <div class="text-break text-pre-formatted">{{ webmention.failure_reason }}</div> + {{ render_failure(webmention.failure_reason) }} {% else %} <span class="text-body-secondary">None</span> {% endif %} @@ -121,17 +122,21 @@ SPDX-License-Identifier: BSD-3-Clause <ol class="list-group list-group-numbered mb-3"> {% for event in history %} {% set event_style = status_presentation.get(event.status, {"badge": "text-bg-secondary", "label": "Unknown"}) %} - <li class="list-group-item"> - <div class="d-flex flex-wrap align-items-center gap-2 mb-1"> - <span class="badge {{ event_style.badge }}">{{ event_style.label }}</span> - <strong>{{ event.action }}</strong> - <time class="ms-auto text-body-secondary small" - datetime="{{ event.occurred_at.isoformat() }}">{{ event.occurred_at.strftime("%Y-%m-%d %H:%M:%S") }} UTC</time> + <li class="list-group-item d-flex gap-2"> + <div class="flex-grow-1" style="min-width: 0;"> + <div class="d-flex flex-wrap align-items-center gap-2 mb-1"> + <span class="badge {{ event_style.badge }}">{{ event_style.label }}</span> + <strong>{{ event.action }}</strong> + <time class="ms-auto text-body-secondary small" + datetime="{{ event.occurred_at.isoformat() }}"> + {{ event.occurred_at.strftime("%Y-%m-%d %H:%M:%S") }} UTC + </time> + </div> + <div class="small text-body-secondary">Recovery attempts: {{ event.recovery_attempts }}</div> + {% if event.failure_reason %} + <div class="mt-2">{{ render_failure(event.failure_reason) }}</div> + {% endif %} </div> - <div class="small text-body-secondary">Recovery attempts: {{ event.recovery_attempts }}</div> - {% if event.failure_reason %} - <div class="mt-2 text-break text-pre-formatted">{{ event.failure_reason }}</div> - {% endif %} </li> {% endfor %} </ol> 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,), |
