aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--tests/forms/test_validators.py4
-rw-r--r--tests/test_received_failure.py53
-rw-r--r--tests/views/test_endpoint.py16
-rw-r--r--tests/views/test_received.py109
-rw-r--r--webmentions_ssg/forms/validators.py9
-rw-r--r--webmentions_ssg/received_failure.py105
-rw-r--r--webmentions_ssg/templates/includes/received_failure.html22
-rw-r--r--webmentions_ssg/templates/received_detail.html27
-rw-r--r--webmentions_ssg/views/received.py5
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 "&lt;script&gt;" 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,),