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.
---
tests/views/test_endpoint.py | 16 +++++++
tests/views/test_received.py | 109 +++++++++++++++++++++++++++++++++++++++++++
2 files changed, 125 insertions(+)
(limited to 'tests/views')
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/"
+ 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 "