aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDennis Fink2026-11-22 11:11:23 +0100
committerDennis Fink2026-11-22 11:11:23 +0100
commit779d10051556242ba1e70b70f6c6e8f1158e861d (patch)
tree284d8228491f0a7ee9422a2100149adebad5aaa7
parentef90dc381322122ecfb9af039cf790de92807514 (diff)
downloadwebmentions-ssg-main.tar.gz
webmentions-ssg-main.zip
feat(receiver)!: enrich digest notification emailsHEADmain
Render plain-text digests with source, target, per-Webmention detail links, and a filtered dashboard link while preserving singular and plural wording. Freeze the notified rows before sending so mentions arriving during delivery are left for the next digest. BREAKING CHANGE: enabling `DIGEST_EMAIL` now requires `SERVER_NAME` so background workers can generate absolute administration URLs.
-rw-r--r--contrib/webmentions-ssg.example.cfg6
-rw-r--r--tests/tasks/test_notifications.py169
-rw-r--r--tests/test_config.py33
-rw-r--r--webmentions_ssg/config.py10
-rw-r--r--webmentions_ssg/tasks/notifications.py43
-rw-r--r--webmentions_ssg/templates/emails/verified_digest.txt20
6 files changed, 261 insertions, 20 deletions
diff --git a/contrib/webmentions-ssg.example.cfg b/contrib/webmentions-ssg.example.cfg
index 6393b3f..3f3703e 100644
--- a/contrib/webmentions-ssg.example.cfg
+++ b/contrib/webmentions-ssg.example.cfg
@@ -222,6 +222,12 @@ LOGIN_USERNAME_RATE_LIMIT = "20/minute;100/hour"
DIGEST_EMAIL = "admin@example.com"
# Daily notification digest at 08:00 UTC (Huey defaults to UTC).
DIGEST_SCHEDULE = "0 8 * * *"
+# Required when DIGEST_EMAIL is set: the public hostname of the Webmentions SSG
+# *admin interface* (not your static site's SITE_BASE_URL). Flask's url_for
+# builds the digest's absolute dashboard and details links outside a request.
+SERVER_NAME = "webmentions.example.com"
+PREFERRED_URL_SCHEME = "https"
+# APPLICATION_ROOT = "/manage" # If the admin is hosted under a path prefix.
# ---------------------------------------------------------------------------
# Mail (SMTP)
diff --git a/tests/tasks/test_notifications.py b/tests/tasks/test_notifications.py
index dadec3e..1b1c1f1 100644
--- a/tests/tasks/test_notifications.py
+++ b/tests/tasks/test_notifications.py
@@ -18,6 +18,10 @@ from webmentions_ssg.models.received import ReceivedWebmention
@pytest.fixture
def notifications(app: Flask) -> ModuleType:
+ # Digest URLs are generated without a request context. Keep the public
+ # hostname local to these tests instead of changing all Flask test clients.
+ app.config.update(SERVER_NAME="mentions.example.com", PREFERRED_URL_SCHEME="https")
+
from webmentions_ssg.tasks import notifications
return notifications
@@ -56,8 +60,19 @@ def test_digest_sends_one_email_for_multiple_verified_mentions(
message = send.call_args.args[0]
assert message.recipients == ["owner@example.com"]
- assert "2 new Webmentions" in message.body
- assert "source.example" not in message.body
+ assert message.subject == "2 new verified webmentions on your site"
+ assert "2 new verified webmentions" in message.body
+ assert message.html is None
+ assert message.body.count("Mentioned by:") == 2
+ for identifier in (first, second):
+ source_url = f"https://source.example/{identifier}"
+ assert source_url in message.body
+ detail_url = f"https://mentions.example.com/received/{identifier}"
+ assert f"View details: {detail_url}" in message.body
+ assert message.body.count("https://dennisfink.me/post") == 2
+ assert str(unverified) not in message.body
+ dashboard_url = "https://mentions.example.com/received?status=verified"
+ assert dashboard_url in message.body
first_mention = db.session.get(ReceivedWebmention, first)
second_mention = db.session.get(ReceivedWebmention, second)
@@ -72,6 +87,156 @@ def test_digest_sends_one_email_for_multiple_verified_mentions(
assert unverified_mention.notification_sent_at is None
+def test_digest_uses_singular_wording_for_one_verified_mention(
+ notifications: ModuleType, app: Flask
+) -> None:
+ app.config["DIGEST_EMAIL"] = "owner@example.com"
+ identifier = create_mention(app)
+
+ with app.app_context():
+ with patch("webmentions_ssg.tasks.notifications.mail.send") as send:
+ notifications.email_verified_digest()
+
+ message = send.call_args.args[0]
+ assert message.subject == "1 new verified webmention on your site"
+ assert "1 new verified webmention!" in message.body
+ assert message.html is None
+ assert f"https://source.example/{identifier}" in message.body
+ assert f"https://mentions.example.com/received/{identifier}" in message.body
+
+
+def test_digest_links_handle_admin_url_path_prefix(
+ notifications: ModuleType, app: Flask
+) -> None:
+ app.config["DIGEST_EMAIL"] = "owner@example.com"
+ app.config.update(APPLICATION_ROOT="/manage")
+ identifier = create_mention(app)
+
+ with app.app_context():
+ with patch("webmentions_ssg.tasks.notifications.mail.send") as send:
+ notifications.email_verified_digest()
+
+ message = send.call_args.args[0]
+ detail_url = f"https://mentions.example.com/manage/received/{identifier}"
+ dashboard_url = "https://mentions.example.com/manage/received?status=verified"
+ assert detail_url in message.body
+ assert message.html is None
+ assert dashboard_url in message.body
+
+
+def test_digest_uses_server_name_with_port(
+ notifications: ModuleType, app: Flask
+) -> None:
+ app.config.update(
+ DIGEST_EMAIL="owner@example.com",
+ SERVER_NAME="mentions.example.com:8443",
+ PREFERRED_URL_SCHEME="https",
+ )
+ identifier = create_mention(app)
+
+ with app.app_context():
+ with patch("webmentions_ssg.tasks.notifications.mail.send") as send:
+ notifications.email_verified_digest()
+
+ message = send.call_args.args[0]
+ detail_url = f"https://mentions.example.com:8443/received/{identifier}"
+ dashboard_url = "https://mentions.example.com:8443/received?status=verified"
+ assert f"View details: {detail_url}" in message.body
+ assert message.html is None
+ assert dashboard_url in message.body
+
+
+def test_digest_server_name_respects_application_root(
+ notifications: ModuleType, app: Flask
+) -> None:
+ app.config.update(
+ DIGEST_EMAIL="owner@example.com",
+ SERVER_NAME="mentions.example.com",
+ PREFERRED_URL_SCHEME="https",
+ APPLICATION_ROOT="/manage",
+ )
+ identifier = create_mention(app)
+
+ with app.app_context():
+ with patch("webmentions_ssg.tasks.notifications.mail.send") as send:
+ notifications.email_verified_digest()
+
+ message = send.call_args.args[0]
+ detail_url = f"https://mentions.example.com/manage/received/{identifier}"
+ dashboard_url = "https://mentions.example.com/manage/received?status=verified"
+ assert detail_url in message.body
+ assert message.html is None
+ assert dashboard_url in message.body
+
+
+def test_digest_without_server_name_does_not_send_or_mark_mentions(
+ notifications: ModuleType, app: Flask
+) -> None:
+ app.config.update(DIGEST_EMAIL="owner@example.com", SERVER_NAME=None)
+ identifier = create_mention(app)
+
+ with app.app_context():
+ with (
+ patch("webmentions_ssg.tasks.notifications.mail.send") as send,
+ pytest.raises(RuntimeError, match="SERVER_NAME"),
+ ):
+ notifications.email_verified_digest()
+
+ send.assert_not_called()
+ mention = db.session.get(ReceivedWebmention, identifier)
+ assert mention is not None and mention.notification_sent_at is None
+
+
+def test_digest_preserves_urls_in_plain_text_without_html(
+ notifications: ModuleType, app: Flask
+) -> None:
+ app.config["DIGEST_EMAIL"] = "owner@example.com"
+ identifier = create_mention(app)
+ source = 'https://source.example/post?tag="onmouseover="alert(1)&x=<script>'
+ target = 'https://dennisfink.me/post?tag=<strong>&other="test"'
+
+ with app.app_context():
+ mention = db.session.get(ReceivedWebmention, identifier)
+ assert mention is not None
+ mention.source = source
+ mention.target = target
+ db.session.commit()
+
+ with patch("webmentions_ssg.tasks.notifications.mail.send") as send:
+ notifications.email_verified_digest()
+
+ message = send.call_args.args[0]
+ assert source in message.body
+ assert target in message.body
+ assert message.html is None
+
+
+def test_digest_only_marks_mentions_in_the_sent_message(
+ notifications: ModuleType, app: Flask
+) -> None:
+ app.config["DIGEST_EMAIL"] = "owner@example.com"
+ first = create_mention(app)
+ new_arrival: list[uuid.UUID] = []
+
+ def receive_during_send(message) -> None:
+ assert str(first) in message.body
+ new_arrival.append(create_mention(app))
+
+ with app.app_context():
+ with patch(
+ "webmentions_ssg.tasks.notifications.mail.send",
+ side_effect=receive_during_send,
+ ):
+ notifications.email_verified_digest()
+
+ first_mention = db.session.get(ReceivedWebmention, first)
+ later_mention = db.session.get(ReceivedWebmention, new_arrival[0])
+ assert first_mention is not None
+ assert later_mention is not None
+ assert first_mention.notification_sent_at is not None
+ assert later_mention.notification_sent_at is None
+
+
def test_digest_skips_when_notifications_disabled(
notifications: ModuleType, app: Flask
) -> None:
diff --git a/tests/test_config.py b/tests/test_config.py
index 43c29ab..fedd7ce 100644
--- a/tests/test_config.py
+++ b/tests/test_config.py
@@ -39,6 +39,39 @@ def test_session_cookie_defaults(
assert config_class.SESSION_COOKIE_SAMESITE == "Lax"
+def test_testing_config_preserves_default_request_host() -> None:
+ app = create_app(TestingConfig)
+ assert app.config["SERVER_NAME"] is None
+ assert app.config["PREFERRED_URL_SCHEME"] == "http"
+
+
+def test_digest_requires_server_name_at_app_startup() -> None:
+ class MissingServerNameConfig(TestingConfig):
+ DIGEST_EMAIL = "owner@example.com"
+ SERVER_NAME = None
+
+ with pytest.raises(RuntimeError, match="Configure SERVER_NAME"):
+ create_app(MissingServerNameConfig)
+
+
+def test_digest_rejects_blank_server_name() -> None:
+ class BlankServerNameConfig(TestingConfig):
+ DIGEST_EMAIL = "owner@example.com"
+ SERVER_NAME = " "
+
+ with pytest.raises(RuntimeError, match="Configure SERVER_NAME"):
+ create_app(BlankServerNameConfig)
+
+
+def test_server_name_optional_when_digest_disabled() -> None:
+ class NoDigestConfig(TestingConfig):
+ DIGEST_EMAIL = None
+ SERVER_NAME = None
+
+ app = create_app(NoDigestConfig)
+ assert app.config["SERVER_NAME"] is None
+
+
def test_source_allowlist_mode_requires_boolean_configuration(tmp_path: Path) -> None:
class BadSourceModeConfig(TestingConfig):
LOG_FILE = str(tmp_path / "mode-test.log")
diff --git a/webmentions_ssg/config.py b/webmentions_ssg/config.py
index 3d05e5d..514432a 100644
--- a/webmentions_ssg/config.py
+++ b/webmentions_ssg/config.py
@@ -236,6 +236,16 @@ def validated_config_overrides(
except (TypeError, ValueError) as exc:
raise type(exc)(f"{key}: {exc}") from exc
+ # Digests are rendered from a background worker without a request host.
+ # Require a public hostname at startup instead of silently omitting links.
+ if config.get("DIGEST_EMAIL") and not (
+ isinstance(config.get("SERVER_NAME"), str) and config["SERVER_NAME"].strip()
+ ):
+ raise RuntimeError(
+ "Configure SERVER_NAME for the Webmentions SSG admin interface "
+ "when DIGEST_EMAIL is enabled."
+ )
+
if type(config["ALLOWLIST_ENABLED"]) is not bool:
raise ValueError("ALLOWLIST_ENABLED must be a boolean.")
diff --git a/webmentions_ssg/tasks/notifications.py b/webmentions_ssg/tasks/notifications.py
index 6a0e6b9..9871349 100644
--- a/webmentions_ssg/tasks/notifications.py
+++ b/webmentions_ssg/tasks/notifications.py
@@ -7,7 +7,7 @@
from datetime import UTC, datetime
import sqlalchemy as sa
-from flask import current_app
+from flask import current_app, render_template
from flask_mail import Message
from ..extensions import db, huey, mail
@@ -17,8 +17,8 @@ from ..models.received import ReceivedWebmention, ReceivedWebmentionStatus
def email_verified_digest() -> None:
"""Send one digest of verified, previously unreported Webmentions.
- Acquire the digest lock before notifying recipients about previously unreported
- verified mentions.
+ Acquire the digest lock before notifying recipients about previously
+ unreported verified mentions.
"""
# Resolve the lock against the current Huey backend, not the import-time one.
with huey.lock_task("send-webmention-digest"):
@@ -28,8 +28,8 @@ def email_verified_digest() -> None:
def _send_digest_locked() -> None:
"""Do the work while the current backend's digest lock is held.
- Collect verified mentions, send the configured message, and persist notification
- timestamps.
+ Collect verified mentions, send the configured message, and persist
+ notification timestamps.
"""
recipient = current_app.config.get("DIGEST_EMAIL")
if not recipient:
@@ -43,24 +43,28 @@ def _send_digest_locked() -> None:
ReceivedWebmention.updated_at <= cutoff,
)
- count = (
- db.session.scalar(
- sa.select(sa.func.count())
- .select_from(ReceivedWebmention)
- .where(*conditions)
+ # Freeze the list before sending. Only rows represented in this email may
+ # be marked as notified, even if new verified mentions arrive meanwhile.
+ mentions = db.session.execute(
+ sa.select(
+ ReceivedWebmention.uuid,
+ ReceivedWebmention.source,
+ ReceivedWebmention.target,
)
- or 0
- )
+ .where(*conditions)
+ .order_by(ReceivedWebmention.updated_at, ReceivedWebmention.uuid)
+ ).all()
- if count == 0:
+ if not mentions:
return
+ count = len(mentions)
+ subject = f"{count} new verified webmention{'s' if count != 1 else ''} on your site"
message = Message(
- subject=f"Webmention digest: {count} new verified",
+ subject=subject,
recipients=[recipient],
- body=(
- f"{count} new Webmentions have been verified.\n\n"
- "Visit your Webmentions administration page to review them.\n"
+ body=render_template(
+ "emails/verified_digest.txt", count=count, mentions=mentions
),
)
@@ -68,7 +72,10 @@ def _send_digest_locked() -> None:
db.session.execute(
sa.update(ReceivedWebmention)
- .where(*conditions)
+ .where(
+ ReceivedWebmention.uuid.in_([mention.uuid for mention in mentions]),
+ *conditions,
+ )
.values(notification_sent_at=cutoff)
.execution_options(synchronize_session="fetch")
)
diff --git a/webmentions_ssg/templates/emails/verified_digest.txt b/webmentions_ssg/templates/emails/verified_digest.txt
new file mode 100644
index 0000000..959a1cf
--- /dev/null
+++ b/webmentions_ssg/templates/emails/verified_digest.txt
@@ -0,0 +1,20 @@
+{# SPDX-FileCopyrightText: 2026 Dennis Fink <me+coding@dennisfink.me> #}
+{# SPDX-License-Identifier: BSD-3-Clause #}
+Hey,
+
+Your site has {{ count }} new verified webmention{{ "s" if count != 1 else "" }}!
+
+{{ "A page on another site links to your content, and we've verified it." if count == 1 else "Other sites are linking to your content, and we've verified the links." }}
+
+YOUR NEW WEBMENTIONS
+--------------------
+{% for mention in mentions %}
+{{ loop.index }}. Mentioned by: {{ mention.source }}
+ Links to: {{ mention.target }}
+ View details: {{ url_for('webmentions.received_detail', webmention_uuid=mention.uuid, _external=True) }}
+
+{% endfor %}
+See all verified webmentions in your dashboard:
+{{ url_for('webmentions.received_list', status='verified', _external=True) }}
+
+— Webmentions SSG