# SPDX-FileCopyrightText: 2026 Dennis Fink # # SPDX-License-Identifier: BSD-3-Clause """Authenticated sent Webmention views, grouped by source document.""" import uuid from datetime import UTC, date, datetime, time from http import HTTPStatus from typing import TypedDict, cast 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 ..models.sources import ( SentWebmention, SentWebmentionStatus, SentWebmentionStatusEvent, 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.""" status: str q: str date_from: str date_to: str sort: str order: str per_page: str def sent_filter_form() -> SentFilterForm: """Validate GET filters without requiring CSRF on the search form.""" form = SentFilterForm(formdata=request.args, meta={"csrf": False}) if not form.validate(): abort(HTTPStatus.BAD_REQUEST) form.q.data = (form.q.data or "").strip() return form def sent_filter_args(form: SentFilterForm) -> SentFilterArgs: """Serialize non-default values for pagination, sorting, and navigation.""" values: dict[str, str] = {} for name in SentFilterArgs.__annotations__: field = form[name] value = field.data default = field.default() if callable(field.default) else field.default if value is None or value == "" or value == default: continue values[name] = value.isoformat() if isinstance(value, date) else str(value) return cast(SentFilterArgs, values) @webmentions_bp.route("/sent") @login_required def sent_list() -> ResponseReturnValue: """Display sent Webmentions grouped by source document.""" filter_form = sent_filter_form() filters = sent_filter_args(filter_form) query = sa.select(SourceDocument) # EXISTS avoids duplicate source rows when several Webmentions match. sent = sa.select(SentWebmention.uuid).where( SentWebmention.source_uuid == SourceDocument.uuid ) if status := filters.get("status"): if status == "failing": query = query.where( sent.where( SentWebmention.status == SentWebmentionStatus.FAILED ).exists() ) elif status == "retrying": query = query.where( sent.where( SentWebmention.awaiting_processing, SentWebmention.attempt_count > 0, SentWebmention.next_retry_at.is_not(None), ).exists() ) else: # deleted query = query.where(SourceDocument.deleted_at.is_not(None)) if text := filters.get("q"): query = query.where( sa.or_( SourceDocument.path.icontains(text, autoescape=True), SourceDocument.url.icontains(text, autoescape=True), sent.where( SentWebmention.target.icontains(text, autoescape=True) ).exists(), ) ) if start := filters.get("date_from"): query = query.where( SourceDocument.last_seen_at >= datetime.combine(date.fromisoformat(start), time.min, UTC) ) if end := filters.get("date_to"): query = query.where( SourceDocument.last_seen_at <= datetime.combine(date.fromisoformat(end), time.max, UTC) ) count = ( sa.select(sa.func.count(SentWebmention.uuid)) .where(SentWebmention.source_uuid == SourceDocument.uuid) .scalar_subquery() ) sort_columns = { "path": SourceDocument.path, "url": SourceDocument.url, "webmentions": count, "revision": SourceDocument.revision, "created": SourceDocument.uuid, "last_seen": SourceDocument.last_seen_at, "status": sa.case((SourceDocument.deleted_at.is_(None), 0), else_=1), } sort_key = filters.get("sort", "last_seen") sort_order = filters.get("order", "desc") column = sort_columns[sort_key] query = query.order_by(column.asc() if sort_order == "asc" else column.desc()) if sort_key != "created": query = query.order_by(SourceDocument.uuid.desc()) page_size = int(filters.get("per_page", default_sent_page_size())) sources = db.paginate( query, per_page=page_size, max_per_page=current_app.config["SOURCES_MAX_PAGE_SIZE"], ) statistics = {} if sources.items: statistics = { row.source_uuid: row for row in db.session.execute( SourceDocument.sent_webmention_statistics( [source.uuid for source in sources.items] ) ) } sort_urls = {} for key in sort_columns: if key == sort_key: next_order = "asc" if sort_order == "desc" else "desc" else: next_order = "asc" if key in ("path", "url", "status") else "desc" sort_filters: SentFilterArgs = {**filters, "sort": key, "order": next_order} sort_urls[key] = url_for("webmentions.sent_list", **sort_filters) return render_template( "sent.html", title="Sent Webmentions", sources=sources, statistics=statistics, filters=filters, sort_key=sort_key, sort_order=sort_order, sort_urls=sort_urls, status_choices=SENT_STATUS_CHOICES, page_size=page_size, max_source_page_size=current_app.config["SOURCES_MAX_PAGE_SIZE"], filter_form=filter_form, action_form=ConfirmActionForm(), ) @webmentions_bp.post("/sent/rescan") @login_required def rescan_sources() -> ResponseReturnValue: """Queue a manual scan of sent Webmention sources. :returns: Redirect response to the sent Webmentions view. """ if not ConfirmActionForm().validate_on_submit(): abort(HTTPStatus.BAD_REQUEST) filters = sent_filter_args(sent_filter_form()) manual_scan_sources() flash("Source rescan queued.", "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.route("/sent/") @login_required def sent_source_detail(source_uuid: uuid.UUID) -> ResponseReturnValue: """Display the sent Webmentions associated with a source. :param source_uuid: UUID of the source to display. :returns: Rendered source details page. """ filters = sent_filter_args(sent_filter_form()) source_page = request.args.get("source_page", 1, type=int) source = db.get_or_404(SourceDocument, source_uuid) webmentions = db.paginate( sa.select(SentWebmention) .where(SentWebmention.source_uuid == source.uuid) .order_by(SentWebmention.target, SentWebmention.uuid), 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(), ) @webmentions_bp.post("/sent///resend") @login_required def resend_webmention( source_uuid: uuid.UUID, webmention_uuid: uuid.UUID ) -> ResponseReturnValue: """Queue an outgoing Webmention to be sent again. The current desired source revision is reopened for processing so the sender task does not treat the Webmention as already completed. Historical successful-send fields are preserved, while result fields from the previous attempt are cleared. :param source_uuid: UUID of the source owning the Webmention. :param webmention_uuid: UUID of the sent Webmention to resend. :returns: Redirect response to the source details view. """ if not ConfirmActionForm().validate_on_submit(): abort(HTTPStatus.BAD_REQUEST) filters = sent_filter_args(sent_filter_form()) webmention = db.get_or_404(SentWebmention, webmention_uuid) if webmention.source_uuid != source_uuid: abort(HTTPStatus.NOT_FOUND) # Requeue the existing desired revision instead of inventing a new source # 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() send_webmention(webmention_uuid) flash(f"Webmention {webmention.uuid} queued for resend.", "success") 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, ) )