From 88f54d9a7699944b7d56f978e724b1c0b54dde98 Mon Sep 17 00:00:00 2001 From: Dennis Fink Date: Thu, 19 Nov 2026 19:42:41 +0100 Subject: 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. --- webmentions_ssg/failure_guidance.py | 244 ++++++++++++ webmentions_ssg/forms/sent.py | 4 +- .../c8fa49e1a203_sent_webmention_status_history.py | 71 ++++ webmentions_ssg/models/sources.py | 60 ++- webmentions_ssg/received_failure.py | 105 ----- webmentions_ssg/tasks/sender.py | 15 +- .../templates/includes/failure_guidance.html | 26 ++ .../templates/includes/received_failure.html | 22 - webmentions_ssg/templates/received_detail.html | 2 +- webmentions_ssg/templates/sent.html | 22 +- webmentions_ssg/templates/sent_source.html | 442 ++++++++++++--------- webmentions_ssg/views/received.py | 2 +- webmentions_ssg/views/sent.py | 123 +++++- 13 files changed, 812 insertions(+), 326 deletions(-) create mode 100644 webmentions_ssg/failure_guidance.py create mode 100644 webmentions_ssg/migrations/versions/c8fa49e1a203_sent_webmention_status_history.py delete mode 100644 webmentions_ssg/received_failure.py create mode 100644 webmentions_ssg/templates/includes/failure_guidance.html delete mode 100644 webmentions_ssg/templates/includes/received_failure.html (limited to 'webmentions_ssg') 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 +# +# 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 +# +# 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 -# -# 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/failure_guidance.html b/webmentions_ssg/templates/includes/failure_guidance.html new file mode 100644 index 0000000..9a36d89 --- /dev/null +++ b/webmentions_ssg/templates/includes/failure_guidance.html @@ -0,0 +1,26 @@ + + +{% 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 %} +
{{ guidance.explanation }}
+ {% if guidance.next_step %} +
Suggested next step: {{ guidance.next_step }}
+ {% endif %} +
+ Technical reason +
{{ reason }}
+
+ {% else %} +
{{ reason }}
+
Check the application logs for details before {{ 'resending' if direction == 'sent' else 'reverifying' }}.
+ {% endif %} +{% endmacro %} diff --git a/webmentions_ssg/templates/includes/received_failure.html b/webmentions_ssg/templates/includes/received_failure.html deleted file mode 100644 index 65ed7a3..0000000 --- a/webmentions_ssg/templates/includes/received_failure.html +++ /dev/null @@ -1,22 +0,0 @@ - - -{% macro render_failure(reason) %} - {% set guidance = reason | received_failure_guidance %} - {% if guidance %} -
{{ guidance.explanation }}
- {% if guidance.next_step %} -
Suggested next step: {{ guidance.next_step }}
- {% endif %} -
- Technical reason -
{{ reason }}
-
- {% else %} -
{{ reason }}
-
Check the application logs for details before reverifying.
- {% endif %} -{% endmacro %} diff --git a/webmentions_ssg/templates/received_detail.html b/webmentions_ssg/templates/received_detail.html index 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 +
+ +
{% if sources.items %}
@@ -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') }} + @@ -98,9 +111,7 @@ SPDX-License-Identifier: BSD-3-Clause - + @@ -132,6 +143,11 @@ SPDX-License-Identifier: BSD-3-Clause {{ source.last_seen_at | relative_time }} + {% endfor %} 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 -
+

Sent Webmention Source

+ {% if source.deleted_at is none %} + Active + {% else %} + Deleted + {% endif %}
-
-
-
UUID
-
- {{ source.uuid }} -
-
Hash
-
- {{ source.content_hash }} -
-
Path
-
- {{ source.path }} -
-
URL
-
- {{ source.url }} -
-
Created at
-
- -
-
Last seen at
-
- -
-
Revised at
-
- -
-
Deleted at
-
- {% if source.deleted_at is none %} - N/A - {% else %} -
+
Last seen
+
+ +
+
Revised
+
+ +
+
Deleted
+
+ {% if source.deleted_at is none %} + Never + {% else %} + + {% endif %} +
+
Revision
+
+ {{ source.revision }} +
+
+
+ +
+
- {% if webmentions.items %} -
-
Details
{{ status_text }} - {{ source.path }} - {{ source.path }} {{ source.url }} + Details +
- - - - - - - - - - - - - {% for webmention in webmentions %} - {% set style = sent_status_presentation.get(webmention.status, {"row_class": "table-info", "badge_class": "text-bg-info", "label": "Pending" }) %} - - - - - - {% endfor %} - -
StatusTargetActiveRevisionsDeliveryLast activityActions
- {{ style.label }} - {% if webmention.failure_reason is not none %} -
{{ webmention.failure_reason }}
- {% endif %} - {% if webmention.awaiting_processing and webmention.attempt_count > 0 and webmention.next_retry_at is not none %} -
- Retry scheduled after attempt {{ webmention.attempt_count }}: - +
+
+

Sent Webmentions

+ {{ webmentions.total }} webmentions +
+ {% if webmentions.items %} +
+ + + + + + + + + + + + + + {% for webmention in webmentions %} + {% set style = sent_status_presentation.get(webmention.status, {"row_class": "table-info", "badge_class": "text-bg-info", "label": "Pending" }) %} + + + + + - - - - + + + + + {% endfor %} + +
StatusTargetActiveRevisionsDeliveryLast activityActions
+ {{ style.label }} + {% if webmention.failure_reason is not none %} +
{{ render_failure(webmention.failure_reason, "sent") }}
+ {% endif %} + {% if webmention.awaiting_processing and webmention.attempt_count > 0 and webmention.next_retry_at is not none %} +
+ Retry scheduled after attempt {{ webmention.attempt_count }}: + +
+ {% endif %} +
+ {{ webmention.target }} + + {% if webmention.linked %} + Active + {% else %} + Removed + {% endif %} + +
+ Desired: + {{ webmention.desired_revision }}
- {% endif %} -
- {{ webmention.target }} - - {% if webmention.linked %} - Active - {% else %} - Removed - {% endif %} - -
- Desired: - {{ webmention.desired_revision }} -
-
- Processed: - {{ webmention.processed_revision - if webmention.processed_revision is not none - else "—" }} -
-
- Sent: - {{ webmention.sent_revision - if webmention.sent_revision is not none - else "—" }} -
-
- {% if webmention.webmention_endpoint is not none %} -
- Endpoint: - {{ webmention.webmention_endpoint }} +
+ Processed: + {{ webmention.processed_revision + if webmention.processed_revision is not none + else "—" }}
- {% endif %} - {% if webmention.endpoint_response_status is not none %} +
+ Sent: + {{ webmention.sent_revision + if webmention.sent_revision is not none + else "—" }} +
+
+ {% if webmention.webmention_endpoint is not none %} + + {% endif %} + {% if webmention.endpoint_response_status is not none %} +
+ HTTP: + {{ webmention.endpoint_response_status }} +
+ {% endif %} + {% if webmention.status_url is not none %} +
+ Status: + {% if webmention.status_url | is_http_url %} + {{ webmention.status_url }} + {% else %} + {{ webmention.status_url }} + {% endif %} +
+ {% endif %} +
- HTTP: - {{ webmention.endpoint_response_status }} + Attempted: +
+ {% if webmention.last_attempted_at is not none %} + + {% else %} + — + {% endif %}
- {% endif %} - {% if webmention.status_url is not none %}
- Status: - {% if webmention.status_url | is_http_url %} - {{ webmention.status_url }} + Sent: +
+ {% if webmention.last_sent_at is not none %} + {% else %} - {{ webmention.status_url }} + — {% endif %}
+
+ +
+
+ {% if webmentions.pages > 1 %} +
{{ render_pagination(webmentions, args=dict(filters, source_page=source_page, history_page=history.page)) }}
+ {% endif %} + {% else %} +

No Webmentions have been discovered for this source.

+ {% endif %} +
+
+

Status history

+ {% if history.items %} +
    + {% for event in history.items %} + {% set style = sent_status_presentation.get(event.status, {"badge_class": "text-bg-info", "label": "Pending"}) %} +
  1. +
    +
    + {{ style.label }} + {{ event.action }} + +
    + +
    + Revision {{ event.revision }} · Attempt {{ event.attempt_count }} + {% if event.endpoint_response_status is not none %} + · HTTP {{ event.endpoint_response_status }} {% endif %} -
-
- Attempted: -
- {% if webmention.last_attempted_at is not none %} - - {% else %} - — - {% endif %} -
-
- Sent: -
- {% if webmention.last_sent_at is not none %} - - {% else %} - — - {% endif %} -
-
- -
-
- {% if webmentions.pages > 1 %} -
{{ render_pagination(webmentions, args=dict(filters, source_page=source_page)) }}
+ + {% if event.failure_reason %} +
{{ render_failure(event.failure_reason, "sent") }}
+ {% endif %} + + + {% endfor %} + + {% if history.pages > 1 %} +
+ {{ 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' + ) }} +
+ {% endif %} + {% else %} +

No historical delivery events were recorded for this source. Current Webmention statuses appear above.

{% endif %} - {% include "includes/confirmation_modal.html" %} - {% else %} -

No Webmentions have been discovered for this source.

- {% endif %} + + {% 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/", + 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//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, ) -- cgit v1.3.1