From 354a5b449077478b141683bafbab47c9dc169d21 Mon Sep 17 00:00:00 2001
From: Dennis Fink
Date: Mon, 16 Nov 2026 22:21:19 +0100
Subject: feat(receiver): add sorting and page size controls
Allow received Webmentions to be sorted by status, source, target,
received time, or updated time with stable pagination and accessible
sortable headers.
Add configurable per-page sizing and preserve sorting, filters, and page
size across pagination and administrative actions.
---
webmentions_ssg/config.py | 3 +
webmentions_ssg/forms.py | 53 +++++++++++----
webmentions_ssg/templates/received.html | 69 +++++++++++++++----
webmentions_ssg/views/admin.py | 113 ++++++++++++++++++++++++--------
4 files changed, 186 insertions(+), 52 deletions(-)
(limited to 'webmentions_ssg')
diff --git a/webmentions_ssg/config.py b/webmentions_ssg/config.py
index 2110a62..1419b82 100644
--- a/webmentions_ssg/config.py
+++ b/webmentions_ssg/config.py
@@ -64,6 +64,8 @@ class DefaultConfig:
VERIFICATION_RECOVERY_SCHEDULE = "*/5 * * * *"
# Purge terminal failed/source-removed received Webmentions after 30 days.
RECEIVED_RETENTION_DAYS = 30
+ # Maximum rows that an admin can request per received Webmentions page.
+ RECEIVED_MAX_PAGE_SIZE = 100
RECEIVED_RETENTION_SCHEDULE = "0 3 * * *"
# Scanner
@@ -224,6 +226,7 @@ def validated_config_overrides(
"MAX_CONTENT_LENGTH",
"MAX_WEBMENTION_URL_BYTES",
"RECEIVED_RETENTION_DAYS",
+ "RECEIVED_MAX_PAGE_SIZE",
):
value = config[key]
if type(value) is not int or value <= 0:
diff --git a/webmentions_ssg/forms.py b/webmentions_ssg/forms.py
index d97cc69..ae969b3 100644
--- a/webmentions_ssg/forms.py
+++ b/webmentions_ssg/forms.py
@@ -12,6 +12,8 @@ from flask_wtf import FlaskForm
from wtforms import (
DateField,
Field,
+ HiddenField,
+ IntegerField,
PasswordField,
SearchField,
SelectField,
@@ -20,11 +22,25 @@ from wtforms import (
ValidationError,
)
from wtforms.form import BaseForm
-from wtforms.validators import InputRequired, Optional, StopValidation
+from wtforms.validators import (
+ AnyOf,
+ InputRequired,
+ NumberRange,
+ Optional,
+ StopValidation,
+)
from .net import is_public_address, normalized_hostname
from .validation import is_control_character
+RECEIVED_STATUS_CHOICES = {
+ "": "All statuses",
+ "pending": "Pending",
+ "verifying": "Verifying",
+ "verified": "Verified",
+ "declined": "Declined",
+}
+
class MaxURLBytes:
"""Check the UTF-8 byte length of a submitted URL using the current config."""
@@ -186,25 +202,38 @@ class CanonicalDate:
raise ValidationError(field.gettext("Invalid date."))
+def default_received_page_size() -> int:
+ """Use 25 rows unless the configured maximum is lower."""
+ return min(25, current_app.config["RECEIVED_MAX_PAGE_SIZE"])
+
+
class ReceivedWebmentionFilterForm(FlaskForm):
"""GET filters for the received Webmention list."""
- status = SelectField(
- "Status",
- choices={
- "": "All statuses",
- "pending": "Pending",
- "verifying": "Verifying",
- "verified": "Verified",
- "declined": "Declined",
- },
- default="",
- )
+ status = SelectField("Status", choices=RECEIVED_STATUS_CHOICES, default="")
q = SearchField("Source or target")
date_from = DateField(
"Updated from (UTC)", validators=[Optional(), CanonicalDate()]
)
date_to = DateField("Updated to (UTC)", validators=[Optional(), CanonicalDate()])
+ sort = HiddenField(
+ default="received",
+ validators=[AnyOf(("received", "updated", "status", "source", "target"))],
+ )
+ order = HiddenField(default="desc", validators=[AnyOf(("asc", "desc"))])
+ per_page = IntegerField(
+ "Rows per page",
+ default=default_received_page_size,
+ validators=[NumberRange(min=1)],
+ )
+
+ def validate_per_page(self, field: IntegerField) -> None:
+ """Enforce the deployment's maximum received-list page size."""
+ if (
+ field.data is not None
+ and field.data > current_app.config["RECEIVED_MAX_PAGE_SIZE"]
+ ):
+ raise ValidationError("Rows per page exceeds the configured maximum.")
def validate_date_to(self, field: DateField) -> None:
"""Require the end date to be on or after the start date."""
diff --git a/webmentions_ssg/templates/received.html b/webmentions_ssg/templates/received.html
index 9034ca8..8cd952c 100644
--- a/webmentions_ssg/templates/received.html
+++ b/webmentions_ssg/templates/received.html
@@ -34,6 +34,18 @@ SPDX-License-Identifier: BSD-3-Clause
}
} %}
+{% macro sortable_header(label, column) %}
+ {% set active = sort_key == column %}
+
+
+ {{ label }}
+ {% if active %}{{ "↑" if sort_order == "asc" else "↓" }}{% endif %}
+
+ |
+{% endmacro %}
+
{% block content %}
Received Webmentions
@@ -43,21 +55,52 @@ SPDX-License-Identifier: BSD-3-Clause
method="get"
class="row g-2 align-items-end mb-4"
role="search">
+
+
- {{ filter_form.status.label(class="form-label") }}
- {{ filter_form.status(class="form-select") }}
+
+
- {{ filter_form.q.label(class="form-label") }}
- {{ filter_form.q(class="form-control", placeholder="Search URLs") }}
+
+
- {{ filter_form.date_from.label(class="form-label") }}
- {{ filter_form.date_from(class="form-control") }}
+
+
- {{ filter_form.date_to.label(class="form-label") }}
- {{ filter_form.date_to(class="form-control") }}
+
+
+
+
+
+
@@ -69,11 +112,11 @@ SPDX-License-Identifier: BSD-3-Clause
- | Status |
- Source |
- Target |
- Received |
- Updated |
+ {{ sortable_header('Status', 'status') }}
+ {{ sortable_header('Source', 'source') }}
+ {{ sortable_header('Target', 'target') }}
+ {{ sortable_header('Received', 'received') }}
+ {{ sortable_header('Updated', 'updated') }}
Reason |
Actions |
diff --git a/webmentions_ssg/views/admin.py b/webmentions_ssg/views/admin.py
index 5246d3a..9bbc596 100644
--- a/webmentions_ssg/views/admin.py
+++ b/webmentions_ssg/views/admin.py
@@ -5,11 +5,12 @@
"""Authenticated incoming and outgoing Webmention management."""
import uuid
-from datetime import UTC, datetime, time
+from datetime import UTC, date, datetime, time
from http import HTTPStatus
+from typing import TypedDict, cast
import sqlalchemy as sa
-from flask import abort, flash, redirect, render_template, request, url_for
+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
@@ -38,6 +39,18 @@ RECEIVED_STATUS_FILTERS = {
}
+class ReceivedFilterArgs(TypedDict, total=False):
+ """Validated received-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 received_filter_form() -> forms.ReceivedWebmentionFilterForm:
"""Validate query-string filters without requiring CSRF on the GET form."""
form = forms.ReceivedWebmentionFilterForm(
@@ -49,15 +62,20 @@ def received_filter_form() -> forms.ReceivedWebmentionFilterForm:
return form
-def received_filter_args(form: forms.ReceivedWebmentionFilterForm) -> dict[str, str]:
- """Return validated, nonempty filters for pagination and redirects."""
- values = {
- "status": form.status.data,
- "q": form.q.data,
- "date_from": form.date_from.data.isoformat() if form.date_from.data else "",
- "date_to": form.date_to.data.isoformat() if form.date_to.data else "",
- }
- return {key: value for key, value in values.items() if value}
+def received_filter_args(
+ form: forms.ReceivedWebmentionFilterForm,
+) -> ReceivedFilterArgs:
+ """Serialize non-default form fields registered in ``ReceivedFilterArgs``."""
+ values: dict[str, str] = {}
+ for name in ReceivedFilterArgs.__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)
+ # TypedDict keys are dynamic because this function iterates its annotations.
+ return cast(ReceivedFilterArgs, values)
@webmentions_bp.route("/received")
@@ -72,12 +90,12 @@ def received_list() -> ResponseReturnValue:
query = sa.select(ReceivedWebmention)
- if status := filter_form.status.data:
+ if status := filters.get("status"):
query = query.where(
ReceivedWebmention.status.in_(RECEIVED_STATUS_FILTERS[status])
)
- if text := filter_form.q.data:
+ if text := filters.get("q"):
query = query.where(
sa.or_(
ReceivedWebmention.source.icontains(text, autoescape=True),
@@ -85,26 +103,73 @@ def received_list() -> ResponseReturnValue:
)
)
- if (start := filter_form.date_from.data) is not None:
+ if start := filters.get("date_from"):
query = query.where(
- ReceivedWebmention.updated_at >= datetime.combine(start, time.min, UTC)
+ ReceivedWebmention.updated_at
+ >= datetime.combine(date.fromisoformat(start), time.min, UTC)
)
- if (end := filter_form.date_to.data) is not None:
+ if end := filters.get("date_to"):
query = query.where(
- ReceivedWebmention.updated_at <= datetime.combine(end, time.max, UTC)
+ ReceivedWebmention.updated_at
+ <= datetime.combine(date.fromisoformat(end), time.max, UTC)
)
+ # Keep both declined lifecycle states together when sorting by status.
+ # UUID is a unique tie-breaker for stable pagination.
+ status_rank = sa.case(
+ (ReceivedWebmention.status == ReceivedWebmentionStatus.RECEIVED, 0),
+ (ReceivedWebmention.status == ReceivedWebmentionStatus.VERIFYING, 1),
+ (ReceivedWebmention.status == ReceivedWebmentionStatus.VERIFIED, 2),
+ else_=3,
+ )
+ sort_columns = {
+ "received": ReceivedWebmention.uuid,
+ "updated": ReceivedWebmention.updated_at,
+ "status": status_rank,
+ "source": ReceivedWebmention.source,
+ "target": ReceivedWebmention.target,
+ }
+
+ sort_key = filters.get("sort", "received")
+ sort_order = filters.get("order", "desc")
+
+ column = sort_columns[sort_key]
+ ordering = column.asc() if sort_order == "asc" else column.desc()
+
+ query = query.order_by(ordering)
+
+ if sort_key != "received":
+ query = query.order_by(ReceivedWebmention.uuid.desc())
+
+ page_size = int(filters.get("per_page", forms.default_received_page_size()))
webmentions = db.paginate(
- query.order_by(ReceivedWebmention.uuid.desc()), per_page=25
+ query,
+ per_page=page_size,
+ max_per_page=current_app.config["RECEIVED_MAX_PAGE_SIZE"],
)
+ 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 ("status", "source", "target") else "desc"
+
+ sort_filters: ReceivedFilterArgs = {**filters, "sort": key, "order": next_order}
+ sort_urls[key] = url_for("webmentions.received_list", **sort_filters)
+
return render_template(
"received.html",
title="Received Webmentions",
webmentions=webmentions,
filters=filters,
- filter_form=filter_form,
+ sort_key=sort_key,
+ sort_order=sort_order,
+ status_choices=forms.RECEIVED_STATUS_CHOICES,
+ page_size=page_size,
+ sort_urls=sort_urls,
+ max_received_page_size=current_app.config["RECEIVED_MAX_PAGE_SIZE"],
action_form=forms.ConfirmActionForm(),
)
@@ -132,10 +197,7 @@ def delete_received_webmention(webmention_uuid: uuid.UUID) -> ResponseReturnValu
url_for(
"webmentions.received_list",
page=request.args.get("page", 1, type=int),
- status=filters.get("status"),
- q=filters.get("q"),
- date_from=filters.get("date_from"),
- date_to=filters.get("date_to"),
+ **filters,
)
)
@@ -168,10 +230,7 @@ def reverify_received_webmention(webmention_uuid: uuid.UUID) -> ResponseReturnVa
url_for(
"webmentions.received_list",
page=request.args.get("page", 1, type=int),
- status=filters.get("status"),
- q=filters.get("q"),
- date_from=filters.get("date_from"),
- date_to=filters.get("date_to"),
+ **filters,
)
)
--
cgit v1.3.1