From 8ec35babe87ff8139ec23cc10b858b7481f132db Mon Sep 17 00:00:00 2001 From: Dennis Fink Date: Thu, 19 Nov 2026 18:15:34 +0100 Subject: refactor(sender)!: align sent Webmention terminology Rename source-list forms, views, helpers, and tests around the Sent Webmentions UI while keeping source documents as the grouping model. BREAKING CHANGE: authenticated outgoing routes move from `/sources` to `/sent`, with corresponding blueprint endpoint and Python module renames. --- webmentions_ssg/views/__init__.py | 4 +- webmentions_ssg/views/sent.py | 277 ++++++++++++++++++++++++++++++++++++++ webmentions_ssg/views/sources.py | 277 -------------------------------------- 3 files changed, 279 insertions(+), 279 deletions(-) create mode 100644 webmentions_ssg/views/sent.py delete mode 100644 webmentions_ssg/views/sources.py (limited to 'webmentions_ssg/views') diff --git a/webmentions_ssg/views/__init__.py b/webmentions_ssg/views/__init__.py index 5abaa14..1701838 100644 --- a/webmentions_ssg/views/__init__.py +++ b/webmentions_ssg/views/__init__.py @@ -4,7 +4,7 @@ """Collect and expose the routes for the blueprint.""" -from . import dashboard, endpoint, moderation, received, session, sources, user +from . import dashboard, endpoint, moderation, received, session, sent, user from .blueprint import webmentions_bp __all__ = [ @@ -13,7 +13,7 @@ __all__ = [ "moderation", "received", "session", - "sources", + "sent", "user", "webmentions_bp", ] diff --git a/webmentions_ssg/views/sent.py b/webmentions_ssg/views/sent.py new file mode 100644 index 0000000..27dffb3 --- /dev/null +++ b/webmentions_ssg/views/sent.py @@ -0,0 +1,277 @@ +# 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 ..extensions import db +from ..forms.admin import ConfirmActionForm +from ..forms.sent import ( + SENT_STATUS_CHOICES, + SentFilterForm, + default_sent_page_size, +) +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 + + +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, + ) + + return render_template( + "sent_source.html", + title="Sent Webmention Source", + source=source, + webmentions=webmentions, + 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() + + 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) + return redirect( + url_for( + "webmentions.sent_source_detail", + source_uuid=source_uuid, + page=page if page > 1 else None, + source_page=source_page if source_page > 1 else None, + **filters, + ) + ) diff --git a/webmentions_ssg/views/sources.py b/webmentions_ssg/views/sources.py deleted file mode 100644 index 22cabb6..0000000 --- a/webmentions_ssg/views/sources.py +++ /dev/null @@ -1,277 +0,0 @@ -# SPDX-FileCopyrightText: 2026 Dennis Fink -# -# SPDX-License-Identifier: BSD-3-Clause - -"""Authenticated source document and sent Webmention views.""" - -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 ..extensions import db -from ..forms.admin import ConfirmActionForm -from ..forms.sources import ( - SOURCE_STATUS_CHOICES, - SourceFilterForm, - default_source_page_size, -) -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 - - -class SourceFilterArgs(TypedDict, total=False): - """Validated source-list 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 source_filter_form() -> SourceFilterForm: - """Validate GET filters without requiring CSRF on the search form.""" - form = SourceFilterForm(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 source_filter_args(form: SourceFilterForm) -> SourceFilterArgs: - """Serialize non-default values for pagination, sorting, and navigation.""" - values: dict[str, str] = {} - for name in SourceFilterArgs.__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(SourceFilterArgs, values) - - -@webmentions_bp.route("/sources") -@login_required -def source_list() -> ResponseReturnValue: - """Display source documents with filters for outgoing delivery problems.""" - filter_form = source_filter_form() - filters = source_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_source_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: SourceFilterArgs = {**filters, "sort": key, "order": next_order} - sort_urls[key] = url_for("webmentions.source_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=SOURCE_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("/sources/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 = source_filter_args(source_filter_form()) - manual_scan_sources() - flash("Source rescan queued.", "success") - - page = request.args.get("page", 1, type=int) - return redirect( - url_for("webmentions.source_list", page=page if page > 1 else None, **filters) - ) - - -@webmentions_bp.route("/sources/") -@login_required -def 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 = source_filter_args(source_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, - ) - - return render_template( - "sent_source.html", - title="Sent Webmentions", - source=source, - webmentions=webmentions, - filters=filters, - source_page=source_page, - action_form=ConfirmActionForm(), - ) - - -@webmentions_bp.post("/sources///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 = source_filter_args(source_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() - - 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) - return redirect( - url_for( - "webmentions.source_detail", - source_uuid=source_uuid, - page=page if page > 1 else None, - source_page=source_page if source_page > 1 else None, - **filters, - ) - ) -- cgit v1.3.1