aboutsummaryrefslogtreecommitdiff
path: root/webmentions_ssg
diff options
context:
space:
mode:
authorDennis Fink2026-11-16 22:21:19 +0100
committerDennis Fink2026-11-16 22:21:19 +0100
commit354a5b449077478b141683bafbab47c9dc169d21 (patch)
treeb2d0be9cb848faf2f9944bb69a63f9fd9a857dbd /webmentions_ssg
parentf7d846b66ae4286518ecc20537ba19c5afadf7f4 (diff)
downloadwebmentions-ssg-354a5b449077478b141683bafbab47c9dc169d21.tar.gz
webmentions-ssg-354a5b449077478b141683bafbab47c9dc169d21.zip
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.
Diffstat (limited to '')
-rw-r--r--webmentions_ssg/config.py3
-rw-r--r--webmentions_ssg/forms.py53
-rw-r--r--webmentions_ssg/templates/received.html69
-rw-r--r--webmentions_ssg/views/admin.py113
4 files changed, 186 insertions, 52 deletions
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 %}
+ <th scope="col"
+ aria-sort="{{ ('ascending' if sort_order == 'asc' else 'descending') if active else 'none' }}">
+ <a href="{{ sort_urls[column] }}"
+ class="link-body-emphasis text-decoration-none">
+ {{ label }}
+ {% if active %}<span aria-hidden="true">{{ "↑" if sort_order == "asc" else "↓" }}</span>{% endif %}
+ </a>
+ </th>
+{% endmacro %}
+
{% block content %}
<div class="d-flex justify-content-between align-items-center mb-3">
<h1 class="mb-0">Received Webmentions</h1>
@@ -43,21 +55,52 @@ SPDX-License-Identifier: BSD-3-Clause
method="get"
class="row g-2 align-items-end mb-4"
role="search">
+ <input id="sort" name="sort" type="hidden" value="{{ sort_key }}">
+ <input id="order" name="order" type="hidden" value="{{ sort_order }}">
<div class="col-sm-6 col-lg">
- {{ filter_form.status.label(class="form-label") }}
- {{ filter_form.status(class="form-select") }}
+ <label class="form-label" for="status">Status</label>
+ <select class="form-select" id="status" name="status">
+ {% for value, label in status_choices.items() %}
+ <option value="{{ value }}"
+ {% if filters.get("status", "") == value %} selected{% endif %}>{{ label }}</option>
+ {% endfor %}
+ </select>
</div>
<div class="col-sm-6 col-lg">
- {{ filter_form.q.label(class="form-label") }}
- {{ filter_form.q(class="form-control", placeholder="Search URLs") }}
+ <label class="form-label" for="q">Source or target</label>
+ <input class="form-control"
+ id="q"
+ name="q"
+ type="search"
+ value="{{ filters.get('q', '') }}"
+ placeholder="Search URLs">
</div>
<div class="col-sm-6 col-lg">
- {{ filter_form.date_from.label(class="form-label") }}
- {{ filter_form.date_from(class="form-control") }}
+ <label class="form-label" for="date_from">Updated from (UTC)</label>
+ <input class="form-control"
+ id="date_from"
+ name="date_from"
+ type="date"
+ value="{{ filters.get('date_from', '') }}">
</div>
<div class="col-sm-6 col-lg">
- {{ filter_form.date_to.label(class="form-label") }}
- {{ filter_form.date_to(class="form-control") }}
+ <label class="form-label" for="date_to">Updated to (UTC)</label>
+ <input class="form-control"
+ id="date_to"
+ name="date_to"
+ type="date"
+ value="{{ filters.get('date_to', '') }}">
+ </div>
+ <div class="col-sm-6 col-lg-auto">
+ <label class="form-label" for="per_page">Rows per page</label>
+ <input class="form-control"
+ id="per_page"
+ name="per_page"
+ type="number"
+ value="{{ page_size }}"
+ min="1"
+ max="{{ max_received_page_size }}"
+ step="1">
</div>
<div class="col-auto d-flex gap-2 ms-auto">
<button type="submit" class="btn btn-primary">Filter</button>
@@ -69,11 +112,11 @@ SPDX-License-Identifier: BSD-3-Clause
<table class="table table-bordered table-striped table-hover align-middle">
<thead>
<tr>
- <th scope="col">Status</th>
- <th scope="col">Source</th>
- <th scope="col">Target</th>
- <th scope="col">Received</th>
- <th scope="col">Updated</th>
+ {{ sortable_header('Status', 'status') }}
+ {{ sortable_header('Source', 'source') }}
+ {{ sortable_header('Target', 'target') }}
+ {{ sortable_header('Received', 'received') }}
+ {{ sortable_header('Updated', 'updated') }}
<th scope="col">Reason</th>
<th scope="col">Actions</th>
</tr>
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,
)
)