diff options
Diffstat (limited to '')
| -rw-r--r-- | contrib/webmentions-ssg.example.cfg | 6 | ||||
| -rw-r--r-- | tests/tasks/test_notifications.py | 169 | ||||
| -rw-r--r-- | tests/test_config.py | 33 | ||||
| -rw-r--r-- | webmentions_ssg/config.py | 10 | ||||
| -rw-r--r-- | webmentions_ssg/tasks/notifications.py | 43 | ||||
| -rw-r--r-- | webmentions_ssg/templates/emails/verified_digest.txt | 20 |
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 |
