aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDennis Fink2026-11-19 19:42:41 +0100
committerDennis Fink2026-11-19 20:59:24 +0100
commit88f54d9a7699944b7d56f978e724b1c0b54dde98 (patch)
tree88ecc527903a91a6f6622ca288b278e5875aff3d
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 '')
-rw-r--r--tests/tasks/test_sender.py24
-rw-r--r--tests/test_failure_guidance.py116
-rw-r--r--tests/test_received_failure.py53
-rw-r--r--tests/views/test_sent.py409
-rw-r--r--webmentions_ssg/failure_guidance.py244
-rw-r--r--webmentions_ssg/forms/sent.py4
-rw-r--r--webmentions_ssg/migrations/versions/c8fa49e1a203_sent_webmention_status_history.py71
-rw-r--r--webmentions_ssg/models/sources.py60
-rw-r--r--webmentions_ssg/received_failure.py105
-rw-r--r--webmentions_ssg/tasks/sender.py15
-rw-r--r--webmentions_ssg/templates/includes/failure_guidance.html (renamed from webmentions_ssg/templates/includes/received_failure.html)10
-rw-r--r--webmentions_ssg/templates/received_detail.html2
-rw-r--r--webmentions_ssg/templates/sent.html22
-rw-r--r--webmentions_ssg/templates/sent_source.html442
-rw-r--r--webmentions_ssg/views/received.py2
-rw-r--r--webmentions_ssg/views/sent.py123
16 files changed, 1326 insertions, 376 deletions
diff --git a/tests/tasks/test_sender.py b/tests/tasks/test_sender.py
index 0d68933..5be2177 100644
--- a/tests/tasks/test_sender.py
+++ b/tests/tasks/test_sender.py
@@ -11,12 +11,14 @@ from unittest.mock import MagicMock, Mock
import httpx
import pytest
+import sqlalchemy as sa
from flask import Flask
from webmentions_ssg import db
from webmentions_ssg.models.sources import (
SentWebmention,
SentWebmentionStatus,
+ SentWebmentionStatusEvent,
SourceDocument,
)
@@ -184,6 +186,16 @@ def test_send_webmention_persists_success(
assert webmention.last_sent_at is not None
assert webmention.attempt_count == 1
assert webmention.next_retry_at is None
+ history = db.session.scalars(
+ sa.select(SentWebmentionStatusEvent).where(
+ SentWebmentionStatusEvent.webmention_uuid == identifier
+ )
+ ).all()
+ assert len(history) == 1
+ assert history[0].action == "Delivery succeeded"
+ assert history[0].status == SentWebmentionStatus.SENT
+ assert history[0].attempt_count == 1
+ assert history[0].endpoint_response_status == HTTPStatus.CREATED
def test_send_webmention_marks_unsupported_target_processed(
@@ -221,6 +233,10 @@ def test_send_webmention_marks_unsupported_target_processed(
assert webmention.endpoint_response_status is None
assert webmention.status_url is None
assert webmention.last_attempted_at is not None
+ history = db.session.scalars(sa.select(SentWebmentionStatusEvent)).all()
+ assert len(history) == 1
+ assert history[0].action == "No endpoint discovered"
+ assert history[0].status == SentWebmentionStatus.NO_ENDPOINT
def test_send_webmention_persists_permanent_failure(
@@ -252,6 +268,10 @@ def test_send_webmention_persists_permanent_failure(
assert webmention.webmention_endpoint == ENDPOINT_URL
assert webmention.endpoint_response_status == HTTPStatus.BAD_REQUEST
assert webmention.status_url is None
+ history = db.session.scalars(sa.select(SentWebmentionStatusEvent)).all()
+ assert len(history) == 1
+ assert history[0].action == "Delivery failed"
+ assert history[0].failure_reason == webmention.failure_reason
def test_send_webmention_persists_temporary_failure_with_backoff(
@@ -291,6 +311,10 @@ def test_send_webmention_persists_temporary_failure_with_backoff(
webmention.next_retry_at.replace(tzinfo=None)
- webmention.last_attempted_at.replace(tzinfo=None)
).total_seconds() == 3600
+ history = db.session.scalars(sa.select(SentWebmentionStatusEvent)).all()
+ assert len(history) == 1
+ assert history[0].action == "Delivery failed; automatic retry scheduled"
+ assert history[0].attempt_count == 1
def test_backoff_delay_is_exponential_and_capped(
diff --git a/tests/test_failure_guidance.py b/tests/test_failure_guidance.py
new file mode 100644
index 0000000..008412f
--- /dev/null
+++ b/tests/test_failure_guidance.py
@@ -0,0 +1,116 @@
+# SPDX-FileCopyrightText: 2026 Dennis Fink <me+coding@dennisfink.me>
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+import pytest
+
+from webmentions_ssg.failure_guidance import (
+ describe_received_failure,
+ describe_sent_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
+
+
+@pytest.mark.parametrize(
+ ("reason", "expected_fragment", "operator_step"),
+ [
+ ("No Webmention endpoint discovered", "does not advertise", False),
+ ("Target returned HTTP 404", "not found", False),
+ ("Target returned HTTP 410", "permanently gone", False),
+ ("Target returned HTTP 403", "denied access", False),
+ ("Target returned HTTP 429", "rate-limiting", True),
+ ("Target returned HTTP 503", "server error", True),
+ ("Target returned HTTP 400", "did not complete delivery", False),
+ ("Webmention endpoint returned HTTP 302", "did not complete delivery", False),
+ ("Webmention endpoint returned HTTP 400", "rejected the submission", True),
+ ("Webmention endpoint returned HTTP 422", "rejected the submission", True),
+ ("Webmention endpoint returned HTTP 404", "not found", False),
+ ("Webmention endpoint returned HTTP 408", "timed out", True),
+ ("Webmention endpoint returned HTTP 429", "rate-limiting", True),
+ ("Webmention endpoint returned HTTP 500", "server error", True),
+ ("Webmention endpoint returned HTTP 503.", "server error", True),
+ ("Target document is too large", "response-size limit", True),
+ ("Invalid target URL: 'ftp://example.com'", "valid HTTP", True),
+ ("Invalid Webmention endpoint: 'ftp://example.com'", "malformed", False),
+ ("Could not resolve hostname 'example.com'", "DNS resolution", True),
+ ("Non-public network address for 'localhost'", "non-public", True),
+ ("No public addresses available for 'example.com'", "public address", False),
+ ("Retry limit reached (6 attempts)", "exhausted", True),
+ ("Webmention request failed", "could not complete", True),
+ ("timed out", "timed out", True),
+ ("The read operation timed out", "read timeout", True),
+ ("[Errno 111] Connection refused", "refused", True),
+ ("All connection attempts failed", "could not establish", True),
+ ("Server disconnected without sending a response", "closed", False),
+ ],
+)
+def test_sent_failure_guidance(
+ reason: str, expected_fragment: str, operator_step: bool
+) -> None:
+ guidance = describe_sent_failure(reason)
+ assert guidance is not None
+ assert expected_fragment in guidance.explanation
+ assert bool(guidance.next_step) is operator_step
+
+
+@pytest.mark.parametrize(
+ "reason",
+ [
+ "",
+ "Unrecognized sender failure",
+ "Target returned HTTP 999",
+ "Retry limit reached",
+ ],
+)
+def test_unknown_sent_failures_keep_raw_reason(reason: str) -> None:
+ assert describe_sent_failure(reason) is None
+
+
+def test_received_and_sent_reasons_do_not_cross_classify() -> None:
+ assert describe_received_failure("No Webmention endpoint discovered") is None
+ assert describe_sent_failure("Source domain is blocked") is None
diff --git a/tests/test_received_failure.py b/tests/test_received_failure.py
deleted file mode 100644
index 095d7e1..0000000
--- a/tests/test_received_failure.py
+++ /dev/null
@@ -1,53 +0,0 @@
-# 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_sent.py b/tests/views/test_sent.py
index 9f9e65f..644fc6f 100644
--- a/tests/views/test_sent.py
+++ b/tests/views/test_sent.py
@@ -12,6 +12,7 @@ from unittest.mock import Mock
from urllib.parse import parse_qs, urlsplit
import pytest
+import sqlalchemy as sa
from bs4 import BeautifulSoup, Tag
from flask import Flask
from flask.testing import FlaskClient
@@ -20,6 +21,7 @@ from webmentions_ssg import db
from webmentions_ssg.models.sources import (
SentWebmention,
SentWebmentionStatus,
+ SentWebmentionStatusEvent,
SourceDocument,
)
from webmentions_ssg.models.user import User
@@ -90,15 +92,18 @@ def test_sent_source_documents_table_hides_secondary_columns_on_mobile(
assert table is not None
headers = table.select("thead th")
cells = table.select("tbody tr:first-child td")
- assert len(headers) == len(cells) == 7
+ assert len(headers) == len(cells) == 8
for index in (2, 4, 5, 6): # URL, revision, created, last seen
for cell in (headers[index], cells[index]):
assert {"d-none", "d-md-table-cell"} <= set(
cell.get_attribute_list("class")
)
- for index in (0, 1, 3): # Path, count, status stay visible
+ for index in (0, 1, 3, 7): # Status, path, counts, details stay visible
assert "d-none" not in cells[index].get_attribute_list("class")
assert "text-break" in cells[1].get_attribute_list("class")
+ details = cells[7].select_one('a.btn[href^="/sent/"]')
+ assert details is not None
+ assert details.get_text(strip=True) == "Details"
def test_sent_source_lists_webmentions(app: Flask, client: FlaskClient) -> None:
@@ -211,9 +216,7 @@ def test_resend_sent_webmention_rejects_invalid_form(
source_identifier, webmention_identifier = create_resendable_sent_webmention(app)
mock_admin_action_form(sent_module, monkeypatch, valid=False)
- response = client.post(
- f"/sent/{source_identifier}/{webmention_identifier}/resend"
- )
+ response = client.post(f"/sent/{source_identifier}/{webmention_identifier}/resend")
assert response.status_code == HTTPStatus.BAD_REQUEST
@@ -270,9 +273,7 @@ def test_resend_sent_webmention_reopens_current_revision(
webmention.next_retry_at = datetime.now(UTC) + timedelta(hours=24)
db.session.commit()
- response = client.post(
- f"/sent/{source_identifier}/{webmention_identifier}/resend"
- )
+ response = client.post(f"/sent/{source_identifier}/{webmention_identifier}/resend")
assert response.status_code == HTTPStatus.FOUND
assert response.headers["Location"].endswith(f"/sent/{source_identifier}")
@@ -290,6 +291,15 @@ def test_resend_sent_webmention_reopens_current_revision(
assert webmention.webmention_endpoint is None
assert webmention.endpoint_response_status is None
assert webmention.status_url is None
+ events = db.session.scalars(
+ sa.select(SentWebmentionStatusEvent).where(
+ SentWebmentionStatusEvent.webmention_uuid == webmention_identifier
+ )
+ ).all()
+ assert len(events) == 1
+ assert events[0].status is None
+ assert events[0].action == "Manually queued for resend"
+ assert events[0].revision == 3
send_webmention.assert_called_once_with(webmention_identifier)
@@ -400,9 +410,9 @@ def test_sent_filter_by_delivery_state_without_duplicate_rows(
soup = BeautifulSoup(response.get_data(as_text=True), "html.parser")
paths = []
for row in soup.select("tbody tr"):
- link = row.select_one("td a")
- assert link is not None
- paths.append(link.get_text(strip=True))
+ path = row.select_one("td:nth-child(2)")
+ assert path is not None
+ paths.append(path.get_text(strip=True))
assert set(paths) == {f"blog/{name}/index.html" for name in expected}
assert len(paths) == len(expected)
assert (
@@ -515,9 +525,9 @@ def test_sent_sort_orders_by_count_and_path(app: Flask, client: FlaskClient) ->
response = client.get("/sent", query_string={"sort": sort, "order": order})
assert response.status_code == HTTPStatus.OK
soup = BeautifulSoup(response.get_data(as_text=True), "html.parser")
- link = soup.select_one("tbody tr td a")
- assert link is not None
- assert link.get_text(strip=True) == f"blog/{expected_first}/index.html"
+ path = soup.select_one("tbody tr td:nth-child(2)")
+ assert path is not None
+ assert path.get_text(strip=True) == f"blog/{expected_first}/index.html"
def test_sent_filter_pagination_and_navigation_preserve_parameters(
@@ -598,8 +608,7 @@ def test_rescan_sources_preserves_filter_query(
scan = Mock()
monkeypatch.setattr(sent_module, "manual_scan_sources", scan)
response = client.post(
- "/sent/rescan",
- query_string={"status": "retrying", "per_page": 37, "page": 2},
+ "/sent/rescan", query_string={"status": "retrying", "per_page": 37, "page": 2}
)
assert response.status_code == HTTPStatus.FOUND
assert parse_qs(urlsplit(response.headers["Location"]).query) == {
@@ -706,3 +715,371 @@ def test_sent_empty_filter_result_keeps_rescan_modal(
html = response.get_data(as_text=True)
assert "No source documents match these filters." in html
assert 'id="confirmation-modal"' in html
+
+
+def test_sent_list_and_source_use_confirmation_actions_and_detail_history(
+ app: Flask, client: FlaskClient
+) -> None:
+ log_in(app, client)
+ source_id, mention_id = create_resendable_sent_webmention(app)
+ with app.app_context():
+ mention = db.session.get(SentWebmention, mention_id)
+ assert mention is not None
+ mention.record_status_event("Delivery failed")
+ db.session.commit()
+
+ listing = BeautifulSoup(client.get("/sent").get_data(as_text=True), "html.parser")
+ button = listing.select_one('button[data-action="/sent/failed/resend"]')
+ assert button is not None
+ assert button.get("data-bs-target") == "#confirmation-modal"
+ details = listing.select_one('tbody a.btn[href^="/sent/"]')
+ assert details is not None
+ assert urlsplit(_href(details)).path == f"/sent/{source_id}"
+
+ detail = BeautifulSoup(
+ client.get(f"/sent/{source_id}").get_data(as_text=True), "html.parser"
+ )
+ assert detail.select_one("section.card #source-details-heading") is not None
+ assert detail.select_one("section #sent-webmentions-heading") is not None
+ assert detail.select_one("section #status-history-heading") is not None
+ history = detail.select("#status-history-heading ~ ol li")
+ assert len(history) == 1
+ assert "Delivery failed" in history[0].get_text()
+ assert "https://example.com/resend" in history[0].get_text()
+ assert detail.select_one("section table tbody tr") is not None
+ resend = detail.select_one('button[data-action*="resend-all"]')
+ assert resend is not None
+ assert resend.get_text(strip=True) == "Resend all"
+
+
+@pytest.mark.parametrize(
+ "path", ["/sent/failed/resend", f"/sent/{uuid.uuid7()}/resend-all"]
+)
+def test_bulk_resend_requires_login(client: FlaskClient, path: str) -> None:
+ response = client.post(path)
+ assert response.status_code == HTTPStatus.FOUND
+ assert "/login" in response.headers["Location"]
+
+
+@pytest.mark.parametrize("valid", [False, True])
+def test_global_resend_all_failed_ignores_filters_and_preserves_other_statuses(
+ app: Flask,
+ client: FlaskClient,
+ sent_module: ModuleType,
+ monkeypatch: pytest.MonkeyPatch,
+ valid: bool,
+) -> None:
+ log_in(app, client)
+ first = make_source(
+ app, "first", statuses=(SentWebmentionStatus.FAILED, SentWebmentionStatus.SENT)
+ )
+ second = make_source(
+ app,
+ "second",
+ statuses=(SentWebmentionStatus.FAILED,),
+ retrying=True,
+ processed=False,
+ )
+ make_source(app, "third", statuses=(SentWebmentionStatus.NO_ENDPOINT, None))
+ mock_admin_action_form(sent_module, monkeypatch, valid=valid)
+ send = Mock()
+ monkeypatch.setattr(sent_module, "send_webmention", send)
+
+ response = client.post(
+ "/sent/failed/resend",
+ query_string={"status": "deleted", "q": "no-match", "page": 2},
+ )
+ assert response.status_code == (
+ HTTPStatus.FOUND if valid else HTTPStatus.BAD_REQUEST
+ )
+ if valid:
+ assert parse_qs(urlsplit(response.headers["Location"]).query) == {
+ "status": ["deleted"],
+ "q": ["no-match"],
+ "page": ["2"],
+ }
+ with app.app_context():
+ all_mentions = db.session.scalars(sa.select(SentWebmention)).all()
+ affected = [m for m in all_mentions if m.source_uuid in (first, second)]
+ failed = [m for m in affected if m.target.endswith("/0")]
+ untouched = [m for m in all_mentions if m not in failed]
+ assert len(failed) == 2
+ for mention in failed:
+ assert (mention.status is None) is valid
+ if valid:
+ assert mention.processed_revision is None
+ assert mention.attempt_count == 0
+ assert mention.next_retry_at is None
+ assert any(m.status == SentWebmentionStatus.SENT for m in untouched)
+ assert any(m.status == SentWebmentionStatus.NO_ENDPOINT for m in untouched)
+ events = db.session.scalars(sa.select(SentWebmentionStatusEvent)).all()
+ assert len(events) == (2 if valid else 0)
+ assert {event.webmention_uuid for event in events} == (
+ {m.uuid for m in failed} if valid else set()
+ )
+ assert {call.args[0] for call in send.call_args_list} == (
+ {m.uuid for m in failed} if valid else set()
+ )
+ assert send.call_count == (2 if valid else 0)
+
+
+def test_source_resend_all_includes_successful_and_pending_but_only_this_source(
+ app: Flask,
+ client: FlaskClient,
+ sent_module: ModuleType,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ log_in(app, client)
+ source_id = make_source(
+ app,
+ "bulk",
+ statuses=(
+ SentWebmentionStatus.SENT,
+ SentWebmentionStatus.FAILED,
+ SentWebmentionStatus.NO_ENDPOINT,
+ None,
+ ),
+ )
+ other_source = make_source(app, "other", statuses=(SentWebmentionStatus.FAILED,))
+ mock_admin_action_form(sent_module, monkeypatch, valid=True)
+ send = Mock()
+ monkeypatch.setattr(sent_module, "send_webmention", send)
+
+ response = client.post(
+ f"/sent/{source_id}/resend-all",
+ query_string={
+ "status": "failing",
+ "source_page": 2,
+ "page": 3,
+ "history_page": 4,
+ },
+ )
+ assert response.status_code == HTTPStatus.FOUND
+ assert urlsplit(response.headers["Location"]).path == f"/sent/{source_id}"
+ assert parse_qs(urlsplit(response.headers["Location"]).query) == {
+ "status": ["failing"],
+ "source_page": ["2"],
+ "page": ["3"],
+ "history_page": ["4"],
+ }
+ with app.app_context():
+ mentions = db.session.scalars(
+ sa.select(SentWebmention).where(SentWebmention.source_uuid == source_id)
+ ).all()
+ assert len(mentions) == 4
+ assert all(m.status is None and m.processed_revision is None for m in mentions)
+ assert all(m.attempt_count == 0 for m in mentions)
+ assert all(m.sent_revision is None for m in mentions)
+ other = db.session.scalar(
+ sa.select(SentWebmention).where(SentWebmention.source_uuid == other_source)
+ )
+ assert other is not None and other.status == SentWebmentionStatus.FAILED
+ history = db.session.scalars(sa.select(SentWebmentionStatusEvent)).all()
+ assert {event.webmention_uuid for event in history} == {
+ m.uuid for m in mentions
+ }
+ assert {call.args[0] for call in send.call_args_list} == {m.uuid for m in mentions}
+ assert send.call_count == 4
+
+
+def test_source_resend_all_rejects_unknown_source_and_invalid_form(
+ app: Flask,
+ client: FlaskClient,
+ sent_module: ModuleType,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ log_in(app, client)
+ source_id = make_source(app, "protected", statuses=(SentWebmentionStatus.FAILED,))
+ form = mock_admin_action_form(sent_module, monkeypatch, valid=False)
+ send = Mock()
+ monkeypatch.setattr(sent_module, "send_webmention", send)
+ assert (
+ client.post(f"/sent/{source_id}/resend-all").status_code
+ == HTTPStatus.BAD_REQUEST
+ )
+ form.validate_on_submit.assert_called_once_with()
+ mock_admin_action_form(sent_module, monkeypatch, valid=True)
+ assert (
+ client.post(f"/sent/{uuid.uuid7()}/resend-all").status_code
+ == HTTPStatus.NOT_FOUND
+ )
+ with app.app_context():
+ mention = db.session.scalar(sa.select(SentWebmention))
+ assert mention is not None and mention.status == SentWebmentionStatus.FAILED
+ send.assert_not_called()
+
+
+def test_sent_source_history_is_paginated_independently_of_webmentions(
+ app: Flask, client: FlaskClient
+) -> None:
+ log_in(app, client)
+ source_id, mention_id = create_resendable_sent_webmention(app)
+ with app.app_context():
+ mention = db.session.get(SentWebmention, mention_id)
+ assert mention is not None
+ for n in range(27):
+ mention.record_status_event(f"Historical delivery {n}")
+ db.session.commit()
+
+ first_page = client.get(f"/sent/{source_id}")
+ assert first_page.status_code == HTTPStatus.OK
+ soup = BeautifulSoup(first_page.get_data(as_text=True), "html.parser")
+ history = soup.select("#status-history-heading ~ ol li")
+ assert len(history) == 25
+ assert "Historical delivery 26" in history[0].get_text()
+ assert "Historical delivery 0" not in first_page.get_data(as_text=True)
+ links = [_href(link) for link in soup.select("#status-history-heading ~ div a")]
+ assert any("history_page=2" in link for link in links)
+
+ second_page = client.get(f"/sent/{source_id}?history_page=2")
+ assert second_page.status_code == HTTPStatus.OK
+ soup = BeautifulSoup(second_page.get_data(as_text=True), "html.parser")
+ history = soup.select("#status-history-heading ~ ol li")
+ assert len(history) == 2
+ assert "Historical delivery 0" in history[-1].get_text()
+ assert len(soup.select("section table tbody tr")) == 1
+
+
+def test_sent_source_history_links_keep_webmentions_page(
+ app: Flask, client: FlaskClient
+) -> None:
+ log_in(app, client)
+ source_id, mention_id = create_resendable_sent_webmention(app)
+ with app.app_context():
+ source = db.session.get(SourceDocument, source_id)
+ mention = db.session.get(SentWebmention, mention_id)
+ assert source is not None and mention is not None
+ source.sent_webmentions.extend(
+ SentWebmention(
+ target=f"https://example.org/extra/{number}",
+ linked=True,
+ desired_revision=3,
+ )
+ for number in range(25)
+ )
+ for number in range(27):
+ mention.record_status_event(f"History event {number}")
+ db.session.commit()
+
+ response = client.get(f"/sent/{source_id}?page=2&source_page=3")
+ assert response.status_code == HTTPStatus.OK
+ soup = BeautifulSoup(response.get_data(as_text=True), "html.parser")
+ history_links = [
+ (_href(link), parse_qs(urlsplit(_href(link)).query))
+ for link in soup.select("#status-history-heading ~ div a")
+ if urlsplit(_href(link)).path == f"/sent/{source_id}"
+ ]
+ next_history = next(
+ href
+ for href, query in history_links
+ if query.get("history_page") == ["2"]
+ )
+ query = parse_qs(urlsplit(next_history).query)
+ assert query["page"] == ["2"]
+ assert query["source_page"] == ["3"]
+
+ following = client.get(next_history)
+ assert following.status_code == HTTPStatus.OK
+ next_soup = BeautifulSoup(following.get_data(as_text=True), "html.parser")
+ assert len(next_soup.select("#status-history-heading ~ ol li")) == 2
+ assert len(next_soup.select("section table tbody tr")) == 1
+
+
+def test_sent_source_explains_current_failed_delivery(
+ app: Flask, client: FlaskClient
+) -> None:
+ log_in(app, client)
+ identifier = create_sent_source(app)
+
+ response = client.get(f"/sent/{identifier}")
+
+ assert response.status_code == HTTPStatus.OK
+ soup = BeautifulSoup(response.get_data(as_text=True), "html.parser")
+ assert "Webmention endpoint rejected the submission" in soup.get_text()
+ assert "Check that your published source page links" in soup.get_text()
+ assert "Suggested next step:" in soup.get_text()
+ reason = soup.find("details")
+ assert reason is not None
+ assert "Webmention endpoint returned HTTP 400" in reason.get_text()
+ # Keep the existing target table and its resend action.
+ assert soup.select_one(".table-responsive table tbody tr button[data-action]")
+
+
+def test_sent_source_explains_historical_failures_and_escapes_raw_reason(
+ app: Flask, client: FlaskClient
+) -> None:
+ log_in(app, client)
+ identifier = create_sent_source(app)
+ raw_reason = "Unexpected transport failure <script>alert('x')</script>"
+ with app.app_context():
+ mention = db.session.scalar(
+ sa.select(SentWebmention).where(SentWebmention.source_uuid == identifier)
+ )
+ assert mention is not None
+ db.session.add_all(
+ [
+ SentWebmentionStatusEvent(
+ webmention_uuid=mention.uuid,
+ status=SentWebmentionStatus.FAILED,
+ action="Delivery failed; automatic retry scheduled",
+ revision=2,
+ attempt_count=1,
+ failure_reason="Webmention endpoint returned HTTP 503",
+ endpoint_response_status=503,
+ occurred_at=datetime(2026, 11, 12, tzinfo=UTC),
+ ),
+ SentWebmentionStatusEvent(
+ webmention_uuid=mention.uuid,
+ status=SentWebmentionStatus.FAILED,
+ action="Delivery failed",
+ revision=2,
+ attempt_count=2,
+ failure_reason=raw_reason,
+ occurred_at=datetime(2026, 11, 13, tzinfo=UTC),
+ ),
+ ]
+ )
+ db.session.commit()
+
+ response = client.get(f"/sent/{identifier}")
+
+ assert response.status_code == HTTPStatus.OK
+ html = response.get_data(as_text=True)
+ soup = BeautifulSoup(html, "html.parser")
+ history = soup.select_one("#status-history-heading")
+ assert history is not None
+ assert "Webmention endpoint returned a server error" in soup.get_text()
+ assert "Automatic retries run while attempts remain" in soup.get_text()
+ assert raw_reason in soup.get_text()
+ assert "Check the application logs for details before resending." in soup.get_text()
+ assert "<script>" not in html
+ assert "&lt;script&gt;" in html
+
+
+def test_sent_source_explains_no_endpoint_without_suggesting_remote_edits(
+ app: Flask, client: FlaskClient
+) -> None:
+ log_in(app, client)
+ identifier = create_sent_source(app)
+ with app.app_context():
+ mention = db.session.scalar(
+ sa.select(SentWebmention).where(SentWebmention.source_uuid == identifier)
+ )
+ assert mention is not None
+ mention.status = SentWebmentionStatus.NO_ENDPOINT
+ mention.failure_reason = "No Webmention endpoint discovered"
+ db.session.commit()
+
+ response = client.get(f"/sent/{identifier}")
+
+ assert response.status_code == HTTPStatus.OK
+ soup = BeautifulSoup(response.get_data(as_text=True), "html.parser")
+ assert "does not advertise a usable Webmention endpoint" in soup.get_text()
+ assert "No Webmention endpoint discovered" in soup.get_text()
+ # The unrelated failed mention may have guidance; the no-endpoint row must not.
+ no_endpoint_row = next(
+ row
+ for row in soup.select(".table-responsive table tbody tr")
+ if "No Webmention endpoint discovered" in row.get_text()
+ )
+ assert "Suggested next step:" not in no_endpoint_row.get_text()
diff --git a/webmentions_ssg/failure_guidance.py b/webmentions_ssg/failure_guidance.py
new file mode 100644
index 0000000..2a507a4
--- /dev/null
+++ b/webmentions_ssg/failure_guidance.py
@@ -0,0 +1,244 @@
+# SPDX-FileCopyrightText: 2026 Dennis Fink <me+coding@dennisfink.me>
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Explain received and sent Webmention failures without changing their reasons.
+
+Only suggest actions the local site operator can reasonably take. Remote-site
+failures are described without presuming control of another website. The original
+technical reason remains available in the UI, including for historical events.
+"""
+
+import re
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class FailureGuidance:
+ """Explanation of a known failure, with an optional operator action."""
+
+ explanation: str
+ next_step: str | None = None
+
+
+RECEIVED_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 := RECEIVED_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
+
+
+SENT_REASONS = {
+ "No Webmention endpoint discovered": FailureGuidance(
+ "The target page does not advertise a usable Webmention endpoint "
+ "in its HTTP Link headers or HTML."
+ ),
+ "Target document is too large": FailureGuidance(
+ "The target page exceeds the configured response-size limit for endpoint "
+ "discovery.",
+ "Review MAX_DISCOVERY_TARGET_BYTES if you trust the target and need "
+ "to support larger pages.",
+ ),
+ "Webmention request failed": FailureGuidance(
+ "The sender could not complete a request to the target or its "
+ "Webmention endpoint.",
+ "Check the sender's network connection and application logs before resending.",
+ ),
+ "timed out": FailureGuidance(
+ "The connection or request timed out before the sender received a response.",
+ "Check local network connectivity. Resend after the remote service responds.",
+ ),
+ "The read operation timed out": FailureGuidance(
+ "The remote server did not deliver its response before the read timeout.",
+ "Resend after the remote service is responding normally.",
+ ),
+ "All connection attempts failed": FailureGuidance(
+ "The sender could not establish a connection to the remote server.",
+ "Check local network connectivity and resend if the remote server "
+ "becomes reachable.",
+ ),
+ "Server disconnected without sending a response": FailureGuidance(
+ "The remote server closed the connection without sending an HTTP response."
+ ),
+}
+
+
+def _describe_sent_http_failure(subject: str, code: int) -> FailureGuidance:
+ """Explain an HTTP status in the context of outgoing delivery."""
+ if code == 404:
+ return FailureGuidance(f"The {subject} was not found (HTTP 404).")
+ if code == 410:
+ return FailureGuidance(f"The {subject} is permanently gone (HTTP 410).")
+ if code in (401, 403):
+ return FailureGuidance(f"The {subject} denied access (HTTP {code}).")
+ if code == 408:
+ return FailureGuidance(
+ f"The {subject} timed out the request (HTTP 408).",
+ "Automatic retries run while attempts remain. If exhausted, resend "
+ "once the remote service is available.",
+ )
+ if code == 429:
+ return FailureGuidance(
+ f"The {subject} is rate-limiting requests (HTTP 429).",
+ "Automatic retries run while attempts remain. If exhausted, resend "
+ "after the remote rate limit clears.",
+ )
+ if 500 <= code <= 599:
+ return FailureGuidance(
+ f"The {subject} returned a server error (HTTP {code}).",
+ "Automatic retries run while attempts remain. If exhausted, resend "
+ "after the remote service recovers.",
+ )
+ if subject == "Webmention endpoint" and code in (400, 422):
+ return FailureGuidance(
+ f"The Webmention endpoint rejected the submission (HTTP {code}).",
+ "Check that your published source page links to the target URL. "
+ "If the link needs correcting, update the source and rescan "
+ "before resending.",
+ )
+ return FailureGuidance(
+ f"The {subject} returned HTTP {code}, which did not complete delivery."
+ )
+
+
+def describe_sent_failure(reason: str) -> FailureGuidance | None:
+ """Explain known outgoing errors; leave unrecognized technical reasons raw.
+
+ Sender errors may originate during target discovery, endpoint submission,
+ public-address validation, or HTTP transport. Never assume a remote server
+ can be repaired by this site's operator.
+ """
+ reason_normalized = reason.removesuffix(".")
+ if guidance := SENT_REASONS.get(reason_normalized):
+ return guidance
+
+ if match := re.fullmatch(
+ r"(Target|Webmention endpoint) returned HTTP ([1-5]\d{2})", reason_normalized
+ ):
+ subject = "target page" if match.group(1) == "Target" else "Webmention endpoint"
+ return _describe_sent_http_failure(subject, int(match.group(2)))
+
+ if re.fullmatch(r"Retry limit reached \(\d+ attempts\)", reason_normalized):
+ return FailureGuidance(
+ "The sender exhausted its configured delivery attempts without "
+ "a recorded success.",
+ "Check the sender logs and the underlying delivery issue, then resend.",
+ )
+
+ if reason.startswith("Invalid target URL:"):
+ return FailureGuidance(
+ "The target URL is not a valid HTTP or HTTPS URL.",
+ "Correct the target link in the source document and rescan "
+ "before resending.",
+ )
+
+ if reason.startswith("Invalid Webmention endpoint:"):
+ return FailureGuidance(
+ "The advertised Webmention endpoint URL is malformed or uses "
+ "an unsupported scheme."
+ )
+
+ if reason.startswith("Could not resolve hostname "):
+ return FailureGuidance(
+ "DNS resolution failed for a hostname used during delivery.",
+ "Check the target link for typos and this sender's DNS connectivity. "
+ "Resend after the hostname resolves.",
+ )
+
+ if reason.startswith("Non-public network address for "):
+ return FailureGuidance(
+ "The hostname resolves to a non-public address, which the sender "
+ "blocks for security.",
+ "Verify that the target link points to a public URL. "
+ "Keep the private-address protection enabled.",
+ )
+
+ if reason.startswith("No public addresses available for "):
+ return FailureGuidance(
+ "The sender could not find a usable public address for the remote host."
+ )
+
+ if re.fullmatch(r"\[Errno \d+\] Connection refused", reason_normalized):
+ return FailureGuidance(
+ "The remote host refused the sender's connection.",
+ "Check network connectivity and resend after the remote service "
+ "is available.",
+ )
+
+ return None
diff --git a/webmentions_ssg/forms/sent.py b/webmentions_ssg/forms/sent.py
index 65a2708..bed4579 100644
--- a/webmentions_ssg/forms/sent.py
+++ b/webmentions_ssg/forms/sent.py
@@ -58,9 +58,7 @@ class SentFilterForm(FlaskForm):
)
order = HiddenField(default="desc", validators=[AnyOf(("asc", "desc"))])
per_page = IntegerField(
- "Rows per page",
- default=default_sent_page_size,
- validators=[NumberRange(min=1)],
+ "Rows per page", default=default_sent_page_size, validators=[NumberRange(min=1)]
)
def validate_per_page(self, field: IntegerField) -> None:
diff --git a/webmentions_ssg/migrations/versions/c8fa49e1a203_sent_webmention_status_history.py b/webmentions_ssg/migrations/versions/c8fa49e1a203_sent_webmention_status_history.py
new file mode 100644
index 0000000..454367d
--- /dev/null
+++ b/webmentions_ssg/migrations/versions/c8fa49e1a203_sent_webmention_status_history.py
@@ -0,0 +1,71 @@
+# SPDX-FileCopyrightText: 2026 Dennis Fink <me+coding@dennisfink.me>
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Record outgoing Webmention delivery history.
+
+Revision ID: c8fa49e1a203
+Revises: 2b4c6e8a0d12
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+revision = "c8fa49e1a203"
+down_revision = "2b4c6e8a0d12"
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+ op.create_table(
+ "sent_webmention_status_events",
+ sa.Column("id", sa.Integer(), primary_key=True, autoincrement=True),
+ sa.Column("webmention_uuid", sa.Uuid(), nullable=False),
+ sa.Column(
+ "status",
+ sa.Enum(
+ "sent",
+ "no_endpoint",
+ "failed",
+ name="sent_webmention_status",
+ native_enum=False,
+ ),
+ nullable=True,
+ ),
+ sa.Column("action", sa.String(length=80), nullable=False),
+ sa.Column("revision", sa.Integer(), nullable=False),
+ sa.Column("attempt_count", sa.Integer(), nullable=False),
+ sa.Column("failure_reason", sa.Text(), nullable=True),
+ sa.Column("endpoint_response_status", sa.Integer(), nullable=True),
+ sa.Column("occurred_at", sa.DateTime(timezone=True), nullable=False),
+ sa.ForeignKeyConstraint(
+ ["webmention_uuid"], ["sent_webmentions.uuid"], ondelete="CASCADE"
+ ),
+ )
+ op.create_index(
+ "ix_sent_webmention_status_events_webmention_id",
+ "sent_webmention_status_events",
+ ["webmention_uuid", "id"],
+ )
+ # A pre-upgrade delivery has only its current result available.
+ op.execute(
+ sa.text(
+ """INSERT INTO sent_webmention_status_events
+ (webmention_uuid, status, action, revision, attempt_count,
+ failure_reason, endpoint_response_status, occurred_at)
+ SELECT uuid, status, 'Existing status at upgrade',
+ desired_revision, attempt_count, failure_reason,
+ endpoint_response_status,
+ COALESCE(last_attempted_at, last_sent_at, CURRENT_TIMESTAMP)
+ FROM sent_webmentions"""
+ )
+ )
+
+
+def downgrade():
+ op.drop_index(
+ "ix_sent_webmention_status_events_webmention_id",
+ table_name="sent_webmention_status_events",
+ )
+ op.drop_table("sent_webmention_status_events")
diff --git a/webmentions_ssg/models/sources.py b/webmentions_ssg/models/sources.py
index be56e24..9fc4212 100644
--- a/webmentions_ssg/models/sources.py
+++ b/webmentions_ssg/models/sources.py
@@ -5,7 +5,7 @@
"""Source documents and outgoing Webmention state."""
from collections.abc import Collection
-from datetime import datetime
+from datetime import UTC, datetime
from enum import StrEnum
from uuid import UUID, uuid7
@@ -15,6 +15,7 @@ from sqlalchemy import (
DateTime,
Enum,
ForeignKey,
+ Index,
Integer,
String,
Text,
@@ -182,6 +183,23 @@ class SentWebmention(Base):
)
source: Mapped[SourceDocument] = relationship(back_populates="sent_webmentions")
+ status_events: Mapped[list[SentWebmentionStatusEvent]] = relationship(
+ back_populates="webmention", cascade="all, delete-orphan"
+ )
+
+ def record_status_event(self, action: str, *, at: datetime | None = None) -> None:
+ """Save a snapshot of this mention's current delivery state."""
+ self.status_events.append(
+ SentWebmentionStatusEvent(
+ status=self.status,
+ action=action,
+ revision=self.desired_revision,
+ attempt_count=self.attempt_count,
+ failure_reason=self.failure_reason,
+ endpoint_response_status=self.endpoint_response_status,
+ occurred_at=at or datetime.now(UTC),
+ )
+ )
__table_args__ = (
UniqueConstraint(
@@ -243,3 +261,43 @@ class SentWebmention(Base):
def created_at(self) -> datetime:
"""Return the creation time encoded in the Webmention UUID."""
return uuid7_to_datetime(self.uuid)
+
+
+class SentWebmentionStatusEvent(Base):
+ """Persist delivery outcomes and manual requeues for an outgoing Webmention."""
+
+ __tablename__ = "sent_webmention_status_events"
+
+ id: Mapped[int] = mapped_column(Integer(), primary_key=True, autoincrement=True)
+ webmention_uuid: Mapped[UUID] = mapped_column(
+ Uuid(as_uuid=True),
+ ForeignKey("sent_webmentions.uuid", ondelete="CASCADE"),
+ nullable=False,
+ )
+ status: Mapped[SentWebmentionStatus | None] = mapped_column(
+ Enum(
+ SentWebmentionStatus,
+ name="sent_webmention_status",
+ values_callable=lambda enum_type: [member.value for member in enum_type],
+ native_enum=False,
+ ),
+ nullable=True,
+ )
+ action: Mapped[str] = mapped_column(String(80), nullable=False)
+ revision: Mapped[int] = mapped_column(Integer(), nullable=False)
+ attempt_count: Mapped[int] = mapped_column(Integer(), nullable=False)
+ failure_reason: Mapped[str | None] = mapped_column(Text(), nullable=True)
+ endpoint_response_status: Mapped[int | None] = mapped_column(
+ Integer(), nullable=True
+ )
+ occurred_at: Mapped[datetime] = mapped_column(
+ DateTime(timezone=True), nullable=False
+ )
+
+ webmention: Mapped[SentWebmention] = relationship(back_populates="status_events")
+
+ __table_args__ = (
+ Index(
+ "ix_sent_webmention_status_events_webmention_id", "webmention_uuid", "id"
+ ),
+ )
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
diff --git a/webmentions_ssg/tasks/sender.py b/webmentions_ssg/tasks/sender.py
index fc70f27..3ee5ac1 100644
--- a/webmentions_ssg/tasks/sender.py
+++ b/webmentions_ssg/tasks/sender.py
@@ -147,7 +147,7 @@ def reserve_send_attempt(
if webmention.attempt_count >= max_attempts:
# A dead worker may have already consumed the final attempt. Never
# finish a newer revision or a retry whose deadline is still in future.
- db.session.execute(
+ updated = db.session.execute(
sa.update(SentWebmention)
.where(
SentWebmention.uuid == webmention.uuid,
@@ -170,6 +170,9 @@ def reserve_send_attempt(
)
.execution_options(synchronize_session=False)
)
+ if rows_affected(updated) == 1:
+ db.session.refresh(webmention)
+ webmention.record_status_event("Retry limit reached")
db.session.commit()
return None
@@ -326,6 +329,16 @@ def record_delivery_outcome(
)
webmention.last_sent_at = datetime.now(UTC)
+ if result.status == SentWebmentionStatus.SENT:
+ action = "Delivery succeeded"
+ elif result.status == SentWebmentionStatus.NO_ENDPOINT:
+ action = "No endpoint discovered"
+ elif terminal:
+ action = "Delivery failed"
+ else:
+ action = "Delivery failed; automatic retry scheduled"
+ webmention.record_status_event(action)
+
db.session.commit()
return True
diff --git a/webmentions_ssg/templates/includes/received_failure.html b/webmentions_ssg/templates/includes/failure_guidance.html
index 65ed7a3..9a36d89 100644
--- a/webmentions_ssg/templates/includes/received_failure.html
+++ b/webmentions_ssg/templates/includes/failure_guidance.html
@@ -4,8 +4,12 @@ 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 %}
+{% macro render_failure(reason, direction="received") %}
+ {% if direction == "sent" %}
+ {% set guidance = reason | sent_failure_guidance %}
+ {% else %}
+ {% set guidance = reason | received_failure_guidance %}
+ {% endif %}
{% if guidance %}
<div class="text-break">{{ guidance.explanation }}</div>
{% if guidance.next_step %}
@@ -17,6 +21,6 @@ SPDX-License-Identifier: BSD-3-Clause
</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>
+ <div class="small text-body-secondary mt-1">Check the application logs for details before {{ 'resending' if direction == 'sent' else 'reverifying' }}.</div>
{% endif %}
{% endmacro %}
diff --git a/webmentions_ssg/templates/received_detail.html b/webmentions_ssg/templates/received_detail.html
index 38830bf..623ab73 100644
--- a/webmentions_ssg/templates/received_detail.html
+++ b/webmentions_ssg/templates/received_detail.html
@@ -5,7 +5,7 @@ SPDX-License-Identifier: BSD-3-Clause
-->
{% extends "base.html" %}
-{% from "includes/received_failure.html" import render_failure %}
+{% from "includes/failure_guidance.html" import render_failure %}
{% set status_presentation = {
"received": {
"badge": "text-bg-info",
diff --git a/webmentions_ssg/templates/sent.html b/webmentions_ssg/templates/sent.html
index 9db0156..9dbbe8e 100644
--- a/webmentions_ssg/templates/sent.html
+++ b/webmentions_ssg/templates/sent.html
@@ -68,6 +68,18 @@ SPDX-License-Identifier: BSD-3-Clause
class="btn btn-outline-secondary">Clear</a>
</div>
</form>
+ <div class="d-flex flex-wrap gap-2 mb-3"
+ aria-label="Sent Webmention actions">
+ <button type="button"
+ class="btn btn-sm btn-primary ms-auto"
+ data-bs-toggle="modal"
+ data-bs-target="#confirmation-modal"
+ data-action="{{ url_for('webmentions.resend_all_failed_webmentions', page=sources.page if sources.page > 1 else none, **filters) }}"
+ data-title="Resend all failed webmentions?"
+ data-message="All failed outgoing Webmentions across every source and page will be queued again, regardless of the current filters."
+ data-confirm-label="Resend all failed"
+ data-confirm-class="btn-primary">Resend all failed</button>
+ </div>
{% if sources.items %}
<div class="table-responsive">
<table class="table table-bordered table-striped table-hover align-middle">
@@ -80,6 +92,7 @@ SPDX-License-Identifier: BSD-3-Clause
{{ sortable_header('Revision', 'revision', 'd-none d-md-table-cell') }}
{{ sortable_header('Created', 'created', 'd-none d-md-table-cell') }}
{{ sortable_header('Last seen', 'last_seen', 'd-none d-md-table-cell') }}
+ <th scope="col">Details</th>
</tr>
</thead>
<tbody>
@@ -98,9 +111,7 @@ SPDX-License-Identifier: BSD-3-Clause
<td>
<span class="badge {{ badge_class }}">{{ status_text }}</span>
</td>
- <td class="text-break">
- <a href="{{ url_for('webmentions.sent_source_detail', source_uuid=source.uuid, source_page=sources.page, **filters) }}">{{ source.path }}</a>
- </td>
+ <td class="text-break">{{ source.path }}</td>
<td class="text-break d-none d-md-table-cell">
<a href="{{ source.url }}">{{ source.url }}</a>
</td>
@@ -132,6 +143,11 @@ SPDX-License-Identifier: BSD-3-Clause
{{ source.last_seen_at | relative_time }}
</time>
</td>
+ <td>
+ <a class="btn btn-sm btn-primary"
+ href="{{ url_for('webmentions.sent_source_detail', source_uuid=source.uuid, source_page=sources.page, **filters) }}"
+ aria-label="Details for source {{ source.path }}">Details</a>
+ </td>
</tr>
{% endfor %}
</tbody>
diff --git a/webmentions_ssg/templates/sent_source.html b/webmentions_ssg/templates/sent_source.html
index a24bde3..600934c 100644
--- a/webmentions_ssg/templates/sent_source.html
+++ b/webmentions_ssg/templates/sent_source.html
@@ -6,6 +6,7 @@ SPDX-License-Identifier: BSD-3-Clause
{% extends "base.html" %}
{% from "bootstrap5/pagination.html" import render_pagination %}
+{% from "includes/failure_guidance.html" import render_failure %}
{% set sent_status_presentation = {
"sent": {
"row_class": "table-success",
@@ -28,204 +29,277 @@ SPDX-License-Identifier: BSD-3-Clause
<div class="mb-3">
<a href="{{ url_for('webmentions.sent_list', page=source_page, **filters) }}">← Back to Sent Webmentions</a>
</div>
- <div class="d-flex justify-content-between align-items-start mb-3">
+ <div class="d-flex flex-wrap justify-content-between align-items-center gap-2 mb-4">
<h1 class="mb-0">Sent Webmention Source</h1>
+ {% if source.deleted_at is none %}
+ <span class="badge fs-6 text-bg-success">Active</span>
+ {% else %}
+ <span class="badge fs-6 text-bg-danger">Deleted</span>
+ {% endif %}
</div>
- <div class="d-flex justify-content-between align-items-start mb-3">
- <dl class="row">
- <dt class="col-sm-2">UUID</dt>
- <dd class="col-sm-4">
- {{ source.uuid }}
- </dd>
- <dt class="col-sm-2">Hash</dt>
- <dd class="col-sm-4">
- {{ source.content_hash }}
- </dd>
- <dt class="col-sm-2">Path</dt>
- <dd class="col-sm-4">
- {{ source.path }}
- </dd>
- <dt class="col-sm-2">URL</dt>
- <dd class="col-sm-4">
- <a href="{{ source.url }}" class="text-break">{{ source.url }}</a>
- </dd>
- <dt class="col-sm-2">Created at</dt>
- <dd class="col-sm-4">
- <time datetime="{{ source.created_at | utc_isoformat }}"
- title="{{ source.created_at | utc_timestamp }}">
- {{ source.created_at | relative_time }}
- </time>
- </dd>
- <dt class="col-sm-2">Last seen at</dt>
- <dd class="col-sm-4">
- <time datetime="{{ source.last_seen_at | utc_isoformat }}"
- title="{{ source.last_seen_at | utc_timestamp }}">
- {{ source.last_seen_at | relative_time }}
- </time>
- </dd>
- <dt class="col-sm-2">Revised at</dt>
- <dd class="col-sm-4">
- <time datetime="{{ source.revised_at | utc_isoformat }}"
- title="{{ source.revised_at | utc_timestamp }}">
- {{ source.revised_at | relative_time }}
- </time>
- </dd>
- <dt class="col-sm-2">Deleted at</dt>
- <dd class="col-sm-4">
- {% if source.deleted_at is none %}
- N/A
- {% else %}
- <time datetime="{{ source.deleted_at | utc_isoformat }}"
- title="{{ source.deleted_at | utc_timestamp }}">
- {{ source.deleted_at | relative_time }}
+ <section class="card mb-4" aria-labelledby="source-details-heading">
+ <div class="card-body">
+ <h2 class="h4 card-title mb-3" id="source-details-heading">Details</h2>
+ <dl class="row mb-0">
+ <dt class="col-md-3">Source ID</dt>
+ <dd class="col-md-9">
+ <code class="text-break">{{ source.uuid }}</code>
+ </dd>
+ <dt class="col-md-3">Content hash</dt>
+ <dd class="col-md-9">
+ <code class="text-break">{{ source.content_hash }}</code>
+ </dd>
+ <dt class="col-md-3">Path</dt>
+ <dd class="col-md-9 text-break">
+ {{ source.path }}
+ </dd>
+ <dt class="col-md-3">URL</dt>
+ <dd class="col-md-9 text-break">
+ <a href="{{ source.url }}">{{ source.url }}</a>
+ </dd>
+ <dt class="col-md-3">Created</dt>
+ <dd class="col-md-9">
+ <time datetime="{{ source.created_at | utc_isoformat }}"
+ title="{{ source.created_at | utc_timestamp }}">
+ {{ source.created_at | relative_time }}
</time>
- {% endif %}
- </dd>
- <dt class="col-sm-2">Revision</dt>
- <dd class="col-sm-4">
- {{ source.revision }}
- </dd>
- </dl>
- </div>
- <div class="d-flex justify-content-between align-items-start mb-3">
- <h2 class="mb-0">Sent Webmentions</h2>
- <span class="text-body-secondary">{{ webmentions.total }} webmentions</span>
+ </dd>
+ <dt class="col-md-3">Last seen</dt>
+ <dd class="col-md-9">
+ <time datetime="{{ source.last_seen_at | utc_isoformat }}"
+ title="{{ source.last_seen_at | utc_timestamp }}">
+ {{ source.last_seen_at | relative_time }}
+ </time>
+ </dd>
+ <dt class="col-md-3">Revised</dt>
+ <dd class="col-md-9">
+ <time datetime="{{ source.revised_at | utc_isoformat }}"
+ title="{{ source.revised_at | utc_timestamp }}">
+ {{ source.revised_at | relative_time }}
+ </time>
+ </dd>
+ <dt class="col-md-3">Deleted</dt>
+ <dd class="col-md-9">
+ {% if source.deleted_at is none %}
+ <span class="text-body-secondary">Never</span>
+ {% else %}
+ <time datetime="{{ source.deleted_at | utc_isoformat }}"
+ title="{{ source.deleted_at | utc_timestamp }}">
+ {{ source.deleted_at | relative_time }}
+ </time>
+ {% endif %}
+ </dd>
+ <dt class="col-md-3">Revision</dt>
+ <dd class="col-md-9">
+ {{ source.revision }}
+ </dd>
+ </dl>
+ </div>
+ </section>
+ <div class="d-flex flex-wrap gap-2 mb-4" aria-label="Source actions">
+ <button type="button"
+ class="btn btn-sm btn-primary"
+ data-bs-toggle="modal"
+ data-bs-target="#confirmation-modal"
+ data-action="{{ url_for('webmentions.resend_all_source_webmentions', source_uuid=source.uuid, source_page=source_page, page=webmentions.page, history_page=history.page, **filters) }}"
+ data-title="Resend all webmentions for this source?"
+ data-message="Every outgoing Webmention for this source will be queued again, including successful sends and mentions on other pages."
+ data-confirm-label="Resend all"
+ data-confirm-class="btn-primary">Resend all</button>
</div>
- {% if webmentions.items %}
- <div class="table-responsive">
- <table class="table table-bordered table-striped table-hover align-middle">
- <thead>
- <tr>
- <th scope="col">Status</th>
- <th scope="col">Target</th>
- <th scope="col" class="d-none d-md-table-cell">Active</th>
- <th scope="col" class="d-none d-md-table-cell">Revisions</th>
- <th scope="col" class="d-none d-md-table-cell">Delivery</th>
- <th scope="col" class="d-none d-md-table-cell">Last activity</th>
- <th scope="col">Actions</th>
- </tr>
- </thead>
- <tbody>
- {% for webmention in webmentions %}
- {% set style = sent_status_presentation.get(webmention.status, {"row_class": "table-info", "badge_class": "text-bg-info", "label": "Pending" }) %}
- <tr class="{{ style.row_class }}">
- <td class="text-break">
- <span class="badge {{ style.badge_class }}">{{ style.label }}</span>
- {% if webmention.failure_reason is not none %}
- <div class="small mt-2">{{ webmention.failure_reason }}</div>
- {% endif %}
- {% if webmention.awaiting_processing and webmention.attempt_count > 0 and webmention.next_retry_at is not none %}
- <div class="small mt-2">
- Retry scheduled after attempt {{ webmention.attempt_count }}:
- <time datetime="{{ webmention.next_retry_at | utc_isoformat }}"
- title="{{ webmention.next_retry_at | utc_timestamp }}">
- {{ webmention.next_retry_at | relative_time }}
- </time>
+ <section aria-labelledby="sent-webmentions-heading" class="mb-4">
+ <div class="d-flex justify-content-between align-items-center gap-2 mb-3">
+ <h2 class="h4 mb-0" id="sent-webmentions-heading">Sent Webmentions</h2>
+ <span class="text-body-secondary">{{ webmentions.total }} webmentions</span>
+ </div>
+ {% if webmentions.items %}
+ <div class="table-responsive">
+ <table class="table table-bordered table-striped table-hover align-middle">
+ <thead>
+ <tr>
+ <th scope="col">Status</th>
+ <th scope="col">Target</th>
+ <th scope="col" class="d-none d-md-table-cell">Active</th>
+ <th scope="col" class="d-none d-md-table-cell">Revisions</th>
+ <th scope="col" class="d-none d-md-table-cell">Delivery</th>
+ <th scope="col" class="d-none d-md-table-cell">Last activity</th>
+ <th scope="col">Actions</th>
+ </tr>
+ </thead>
+ <tbody>
+ {% for webmention in webmentions %}
+ {% set style = sent_status_presentation.get(webmention.status, {"row_class": "table-info", "badge_class": "text-bg-info", "label": "Pending" }) %}
+ <tr class="{{ style.row_class }}">
+ <td class="text-break">
+ <span class="badge {{ style.badge_class }}">{{ style.label }}</span>
+ {% if webmention.failure_reason is not none %}
+ <div class="small mt-2">{{ render_failure(webmention.failure_reason, "sent") }}</div>
+ {% endif %}
+ {% if webmention.awaiting_processing and webmention.attempt_count > 0 and webmention.next_retry_at is not none %}
+ <div class="small mt-2">
+ Retry scheduled after attempt {{ webmention.attempt_count }}:
+ <time datetime="{{ webmention.next_retry_at | utc_isoformat }}"
+ title="{{ webmention.next_retry_at | utc_timestamp }}">
+ {{ webmention.next_retry_at | relative_time }}
+ </time>
+ </div>
+ {% endif %}
+ </td>
+ <td class="text-break">
+ <a href="{{ webmention.target }}">{{ webmention.target }}</a>
+ </td>
+ <td class="d-none d-md-table-cell">
+ {% if webmention.linked %}
+ <span class="badge text-bg-success">Active</span>
+ {% else %}
+ <span class="badge text-bg-danger">Removed</span>
+ {% endif %}
+ </td>
+ <td class="small text-nowrap d-none d-md-table-cell">
+ <div>
+ <strong>Desired:</strong>
+ {{ webmention.desired_revision }}
</div>
- {% endif %}
- </td>
- <td class="text-break">
- <a href="{{ webmention.target }}">{{ webmention.target }}</a>
- </td>
- <td class="d-none d-md-table-cell">
- {% if webmention.linked %}
- <span class="badge text-bg-success">Active</span>
- {% else %}
- <span class="badge text-bg-danger">Removed</span>
- {% endif %}
- </td>
- <td class="small text-nowrap d-none d-md-table-cell">
- <div>
- <strong>Desired:</strong>
- {{ webmention.desired_revision }}
- </div>
- <div>
- <strong>Processed:</strong>
- {{ webmention.processed_revision
- if webmention.processed_revision is not none
- else "—" }}
- </div>
- <div>
- <strong>Sent:</strong>
- {{ webmention.sent_revision
- if webmention.sent_revision is not none
- else "—" }}
- </div>
- </td>
- <td class="small d-none d-md-table-cell">
- {% if webmention.webmention_endpoint is not none %}
- <div class="mb-1">
- <strong>Endpoint:</strong>
- <a href="{{ webmention.webmention_endpoint }}"
- class="text-break">{{ webmention.webmention_endpoint }}</a>
+ <div>
+ <strong>Processed:</strong>
+ {{ webmention.processed_revision
+ if webmention.processed_revision is not none
+ else "—" }}
</div>
- {% endif %}
- {% if webmention.endpoint_response_status is not none %}
+ <div>
+ <strong>Sent:</strong>
+ {{ webmention.sent_revision
+ if webmention.sent_revision is not none
+ else "—" }}
+ </div>
+ </td>
+ <td class="small d-none d-md-table-cell">
+ {% if webmention.webmention_endpoint is not none %}
+ <div class="mb-1">
+ <strong>Endpoint:</strong>
+ <a href="{{ webmention.webmention_endpoint }}"
+ class="text-break">{{ webmention.webmention_endpoint }}</a>
+ </div>
+ {% endif %}
+ {% if webmention.endpoint_response_status is not none %}
+ <div class="mb-1">
+ <strong>HTTP:</strong>
+ {{ webmention.endpoint_response_status }}
+ </div>
+ {% endif %}
+ {% if webmention.status_url is not none %}
+ <div>
+ <strong>Status:</strong>
+ {% if webmention.status_url | is_http_url %}
+ <a href="{{ webmention.status_url }}" class="text-break">{{ webmention.status_url }}</a>
+ {% else %}
+ <span class="text-break">{{ webmention.status_url }}</span>
+ {% endif %}
+ </div>
+ {% endif %}
+ </td>
+ <td class="small text-nowrap d-none d-md-table-cell">
<div class="mb-1">
- <strong>HTTP:</strong>
- {{ webmention.endpoint_response_status }}
+ <strong>Attempted:</strong>
+ <br>
+ {% if webmention.last_attempted_at is not none %}
+ <time datetime="{{ webmention.last_attempted_at | utc_isoformat }}"
+ title="{{ webmention.last_attempted_at | utc_timestamp }}">
+ {{ webmention.last_attempted_at | relative_time }}
+ </time>
+ {% else %}
+ —
+ {% endif %}
</div>
- {% endif %}
- {% if webmention.status_url is not none %}
<div>
- <strong>Status:</strong>
- {% if webmention.status_url | is_http_url %}
- <a href="{{ webmention.status_url }}" class="text-break">{{ webmention.status_url }}</a>
+ <strong>Sent:</strong>
+ <br>
+ {% if webmention.last_sent_at is not none %}
+ <time datetime="{{ webmention.last_sent_at | utc_isoformat }}"
+ title="{{ webmention.last_sent_at | utc_timestamp }}">
+ {{ webmention.last_sent_at | relative_time }}
+ </time>
{% else %}
- <span class="text-break">{{ webmention.status_url }}</span>
+ —
{% endif %}
</div>
+ </td>
+ <td>
+ <button type="button"
+ class="btn btn-sm btn-primary"
+ data-bs-toggle="modal"
+ data-bs-target="#confirmation-modal"
+ data-action="{{ url_for('webmentions.resend_webmention', source_uuid=source.uuid, webmention_uuid=webmention.uuid, source_page=source_page, page=webmentions.page, history_page=history.page, **filters) }}"
+ data-title="Resend Webmention?"
+ data-message="This Webmention will be queued again for delivery to {{ webmention.target }}."
+ data-confirm-label="Resend"
+ data-confirm-class="btn-primary">Resend</button>
+ </td>
+ </tr>
+ {% endfor %}
+ </tbody>
+ </table>
+ </div>
+ {% if webmentions.pages > 1 %}
+ <div class="mt-3">{{ render_pagination(webmentions, args=dict(filters, source_page=source_page, history_page=history.page)) }}</div>
+ {% endif %}
+ {% else %}
+ <p class="text-body-secondary">No Webmentions have been discovered for this source.</p>
+ {% endif %}
+ </section>
+ <section aria-labelledby="status-history-heading">
+ <h2 class="h4 mb-3" id="status-history-heading">Status history</h2>
+ {% if history.items %}
+ <ol class="list-group list-group-numbered mb-3">
+ {% for event in history.items %}
+ {% set style = sent_status_presentation.get(event.status, {"badge_class": "text-bg-info", "label": "Pending"}) %}
+ <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 {{ style.badge_class }}">{{ style.label }}</span>
+ <strong>{{ event.action }}</strong>
+ <time class="ms-auto text-body-secondary small"
+ datetime="{{ event.occurred_at | utc_isoformat }}"
+ title="{{ event.occurred_at | utc_timestamp }}">
+ {{ event.occurred_at | relative_time }}
+ </time>
+ </div>
+ <div class="text-break small mb-1">
+ <a href="{{ event.webmention.target }}">{{ event.webmention.target }}</a>
+ </div>
+ <div class="small text-body-secondary">
+ Revision {{ event.revision }} · Attempt {{ event.attempt_count }}
+ {% if event.endpoint_response_status is not none %}
+ · HTTP {{ event.endpoint_response_status }}
{% endif %}
- </td>
- <td class="small text-nowrap d-none d-md-table-cell">
- <div class="mb-1">
- <strong>Attempted:</strong>
- <br>
- {% if webmention.last_attempted_at is not none %}
- <time datetime="{{ webmention.last_attempted_at | utc_isoformat }}"
- title="{{ webmention.last_attempted_at | utc_timestamp }}">
- {{ webmention.last_attempted_at | relative_time }}
- </time>
- {% else %}
- —
- {% endif %}
- </div>
- <div>
- <strong>Sent:</strong>
- <br>
- {% if webmention.last_sent_at is not none %}
- <time datetime="{{ webmention.last_sent_at | utc_isoformat }}"
- title="{{ webmention.last_sent_at | utc_timestamp }}">
- {{ webmention.last_sent_at | relative_time }}
- </time>
- {% else %}
- —
- {% endif %}
- </div>
- </td>
- <td>
- <button type="button"
- class="btn btn-sm btn-primary"
- data-bs-toggle="modal"
- data-bs-target="#confirmation-modal"
- data-action="{{ url_for('webmentions.resend_webmention', source_uuid=source.uuid, webmention_uuid=webmention.uuid, source_page=source_page, page=webmentions.page, **filters) }}"
- data-title="Resend Webmention?"
- data-message="This Webmention will be queued again for delivery to {{ webmention.target }}."
- data-confirm-label="Resend"
- data-confirm-class="btn-primary">Resend</button>
- </td>
- </tr>
- {% endfor %}
- </tbody>
- </table>
- </div>
- {% if webmentions.pages > 1 %}
- <div class="mt-3">{{ render_pagination(webmentions, args=dict(filters, source_page=source_page)) }}</div>
+ </div>
+ {% if event.failure_reason %}
+ <div class="small mt-2">{{ render_failure(event.failure_reason, "sent") }}</div>
+ {% endif %}
+ </div>
+ </li>
+ {% endfor %}
+ </ol>
+ {% if history.pages > 1 %}
+ <div class="mt-3">
+ {{ render_pagination(
+ history,
+ endpoint='webmentions.sent_source_history_pagination',
+ args=dict(
+ filters,
+ source_uuid=source.uuid,
+ source_page=source_page if source_page > 1 else none,
+ webmentions_page=webmentions.page if webmentions.page > 1 else none
+ ),
+ fragment='status-history-heading'
+ ) }}
+ </div>
+ {% endif %}
+ {% else %}
+ <p class="text-body-secondary">No historical delivery events were recorded for this source. Current Webmention statuses appear above.</p>
{% endif %}
- {% include "includes/confirmation_modal.html" %}
- {% else %}
- <p class="text-body-secondary">No Webmentions have been discovered for this source.</p>
- {% endif %}
+ </section>
+ {% include "includes/confirmation_modal.html" %}
{% endblock %}
{% block scripts %}
diff --git a/webmentions_ssg/views/received.py b/webmentions_ssg/views/received.py
index c273618..84fe358 100644
--- a/webmentions_ssg/views/received.py
+++ b/webmentions_ssg/views/received.py
@@ -16,6 +16,7 @@ from flask_login import login_required
from ..db_helpers import rows_affected
from ..extensions import db
+from ..failure_guidance import describe_received_failure
from ..forms.admin import ConfirmActionForm
from ..forms.received import (
RECEIVED_STATUS_CHOICES,
@@ -29,7 +30,6 @@ 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
diff --git a/webmentions_ssg/views/sent.py b/webmentions_ssg/views/sent.py
index 27dffb3..614d486 100644
--- a/webmentions_ssg/views/sent.py
+++ b/webmentions_ssg/views/sent.py
@@ -13,19 +13,47 @@ import sqlalchemy as sa
from flask import abort, current_app, flash, redirect, render_template, request, url_for
from flask.typing import ResponseReturnValue
from flask_login import login_required
+from sqlalchemy.orm import selectinload
from ..extensions import db
+from ..failure_guidance import describe_sent_failure
from ..forms.admin import ConfirmActionForm
-from ..forms.sent import (
- SENT_STATUS_CHOICES,
- SentFilterForm,
- default_sent_page_size,
+from ..forms.sent import SENT_STATUS_CHOICES, SentFilterForm, default_sent_page_size
+from ..models.sources import (
+ SentWebmention,
+ SentWebmentionStatus,
+ SentWebmentionStatusEvent,
+ SourceDocument,
)
-from ..models.sources import SentWebmention, SentWebmentionStatus, SourceDocument
from ..tasks.scanner import manual_scan_sources
from ..tasks.sender import send_webmention
from .blueprint import webmentions_bp
+webmentions_bp.add_app_template_filter(describe_sent_failure, "sent_failure_guidance")
+
+# Bootstrap-Flask's render_pagination() always emits a `page` parameter.
+# This build-only endpoint lets the history pager use the standard macro while
+# preserving the sent-Webmentions table's own `page` query parameter.
+webmentions_bp.add_url_rule(
+ "/sent/<uuid:source_uuid>",
+ endpoint="sent_source_history_pagination",
+ build_only=True,
+)
+
+
+@webmentions_bp.url_defaults
+def sent_history_pagination_url_defaults(
+ endpoint: str, values: dict[str, object]
+) -> None:
+ """Map the macro's page number to the history pagination parameter."""
+ if endpoint != "webmentions.sent_source_history_pagination":
+ return
+
+ values["history_page"] = values.pop("page")
+ webmentions_page = values.pop("webmentions_page", None)
+ if webmentions_page is not None:
+ values["page"] = webmentions_page
+
class SentFilterArgs(TypedDict, total=False):
"""Validated sent-page query parameters; keys match GET form fields."""
@@ -217,11 +245,23 @@ def sent_source_detail(source_uuid: uuid.UUID) -> ResponseReturnValue:
per_page=25,
)
+ history = db.paginate(
+ sa.select(SentWebmentionStatusEvent)
+ .join(SentWebmention)
+ .options(selectinload(SentWebmentionStatusEvent.webmention))
+ .where(SentWebmention.source_uuid == source.uuid)
+ .order_by(SentWebmentionStatusEvent.id.desc()),
+ page=request.args.get("history_page", 1, type=int),
+ per_page=25,
+ error_out=False,
+ )
+
return render_template(
"sent_source.html",
title="Sent Webmention Source",
source=source,
webmentions=webmentions,
+ history=history,
filters=filters,
source_page=source_page,
action_form=ConfirmActionForm(),
@@ -257,6 +297,7 @@ def resend_webmention(
# revision. send_webmention() otherwise exits when this revision has already
# been processed.
webmention.clear_result_for_resend()
+ webmention.record_status_event("Manually queued for resend")
db.session.commit()
@@ -266,11 +307,83 @@ def resend_webmention(
page = request.args.get("page", 1, type=int)
source_page = request.args.get("source_page", 1, type=int)
+ history_page = request.args.get("history_page", 1, type=int)
+ return redirect(
+ url_for(
+ "webmentions.sent_source_detail",
+ source_uuid=source_uuid,
+ page=page if page > 1 else None,
+ history_page=history_page if history_page > 1 else None,
+ source_page=source_page if source_page > 1 else None,
+ **filters,
+ )
+ )
+
+
+def queue_sent_webmentions(
+ *, source_uuid: uuid.UUID | None = None, failed_only: bool = True
+) -> list[uuid.UUID]:
+ """Reopen sends in one transaction, then dispatch each task once.
+
+ A global retry selects only failed rows; a source-level retry can select
+ every delivery, regardless of status, list filters, or pagination.
+ """
+ query = sa.select(SentWebmention)
+ if failed_only:
+ query = query.where(SentWebmention.status == SentWebmentionStatus.FAILED)
+ if source_uuid is not None:
+ query = query.where(SentWebmention.source_uuid == source_uuid)
+
+ identifiers = []
+ for webmention in db.session.scalars(query.order_by(SentWebmention.uuid)).all():
+ webmention.clear_result_for_resend()
+ webmention.record_status_event("Manually queued for resend (bulk)")
+ identifiers.append(webmention.uuid)
+
+ db.session.commit()
+ for identifier in identifiers:
+ send_webmention(identifier)
+ return identifiers
+
+
+@webmentions_bp.post("/sent/failed/resend")
+@login_required
+def resend_all_failed_webmentions() -> ResponseReturnValue:
+ """Resend every failed outgoing Webmention, across all source documents."""
+ if not ConfirmActionForm().validate_on_submit():
+ abort(HTTPStatus.BAD_REQUEST)
+
+ filters = sent_filter_args(sent_filter_form())
+ identifiers = queue_sent_webmentions()
+ flash(f"{len(identifiers)} failed Webmentions queued for resend.", "success")
+
+ page = request.args.get("page", 1, type=int)
+ return redirect(
+ url_for("webmentions.sent_list", page=page if page > 1 else None, **filters)
+ )
+
+
+@webmentions_bp.post("/sent/<uuid:source_uuid>/resend-all")
+@login_required
+def resend_all_source_webmentions(source_uuid: uuid.UUID) -> ResponseReturnValue:
+ """Resend all outgoing Webmentions for one source document."""
+ if not ConfirmActionForm().validate_on_submit():
+ abort(HTTPStatus.BAD_REQUEST)
+
+ filters = sent_filter_args(sent_filter_form())
+ db.get_or_404(SourceDocument, source_uuid)
+ identifiers = queue_sent_webmentions(source_uuid=source_uuid, failed_only=False)
+ flash(f"{len(identifiers)} Webmentions queued for resend.", "success")
+
+ page = request.args.get("page", 1, type=int)
+ history_page = request.args.get("history_page", 1, type=int)
+ source_page = request.args.get("source_page", 1, type=int)
return redirect(
url_for(
"webmentions.sent_source_detail",
source_uuid=source_uuid,
page=page if page > 1 else None,
+ history_page=history_page if history_page > 1 else None,
source_page=source_page if source_page > 1 else None,
**filters,
)