From a231913ab273f427697f2d27d615b495f6e160bb Mon Sep 17 00:00:00 2001 From: Dennis Fink Date: Sun, 25 Oct 2026 20:47:14 +0100 Subject: feat(receiver): add email notifications for new webmentions Send an email after a newly received Webmention is successfully verified, with SMTP delivery configurable through Flask-Mail. Avoid notifications for resubmissions and manual reverification, and keep the persisted verification result unchanged if notification enqueueing fails. --- webmentions_ssg/__init__.py | 3 +++ webmentions_ssg/config.py | 10 ++++++++++ webmentions_ssg/tasks/consumer.py | 2 +- webmentions_ssg/tasks/notifications.py | 36 ++++++++++++++++++++++++++++++++++ webmentions_ssg/tasks/receiver.py | 16 ++++++++++++++- webmentions_ssg/views.py | 8 ++++++-- 6 files changed, 71 insertions(+), 4 deletions(-) create mode 100644 webmentions_ssg/tasks/notifications.py (limited to 'webmentions_ssg') diff --git a/webmentions_ssg/__init__.py b/webmentions_ssg/__init__.py index ad77667..1797a4d 100644 --- a/webmentions_ssg/__init__.py +++ b/webmentions_ssg/__init__.py @@ -13,6 +13,7 @@ import sqlalchemy as sa from flask import Flask from flask.cli import AppGroup from flask_bootstrap import Bootstrap5 +from flask_mail import Mail from flask_migrate import Migrate, upgrade from flask_sqlalchemy import SQLAlchemy from flask_wtf.csrf import CSRFProtect @@ -35,6 +36,7 @@ BOOTSTRAP = Bootstrap5() DATABASE = SQLAlchemy(model_class=Base) MIGRATE = Migrate() HUEY = Huey() +MAIL = Mail() USERS_CLI = AppGroup("users", help="Handle users") DB_CLI = AppGroup("db", help="Handle database") @@ -106,6 +108,7 @@ def create_app(config_class: type[DefaultConfig] | None = None) -> Flask: DATABASE.init_app(app) MIGRATE.init_app(app, db=DATABASE) CSRF.init_app(app) + MAIL.init_app(app) from .auth import AUTH diff --git a/webmentions_ssg/config.py b/webmentions_ssg/config.py index 72842c4..afe7126 100644 --- a/webmentions_ssg/config.py +++ b/webmentions_ssg/config.py @@ -18,9 +18,19 @@ class DefaultConfig: LOGFILE_MAX_BYTES = 20_000_000 LOGFILE_BACKUP_COUNT = 10 SQLALCHEMY_DATABASE_URI = "sqlite:///webmentions-ssg.db" + WEBMENTIONS_SSG_SOURCE_DIRECTORY = None WEBMENTIONS_SSG_SOURCE_BASE_URL = None WEBMENTIONS_SSG_SCANNER_SCHEDULE = "0 * * * *" + WEBMENTIONS_SSG_NOTIFICATION_EMAIL = None + + MAIL_SERVER = "localhost" + MAIL_PORT = 25 + MAIL_USE_TLS = False + MAIL_USE_SSL = False + MAIL_USERNAME = None + MAIL_PASSWORD = None + MAIL_DEFAULT_SENDER = None class DevelopmentConfig(DefaultConfig): diff --git a/webmentions_ssg/tasks/consumer.py b/webmentions_ssg/tasks/consumer.py index 0f73529..d71f2fa 100644 --- a/webmentions_ssg/tasks/consumer.py +++ b/webmentions_ssg/tasks/consumer.py @@ -19,7 +19,7 @@ def create_consumer() -> Huey: """ app = create_app() - from . import receiver, scanner, sender # noqa: F401 + from . import notifications, receiver, scanner, sender # noqa: F401 schedule = crontab( *app.config["WEBMENTIONS_SSG_SCANNER_SCHEDULE"].split(), strict=True diff --git a/webmentions_ssg/tasks/notifications.py b/webmentions_ssg/tasks/notifications.py new file mode 100644 index 0000000..473216b --- /dev/null +++ b/webmentions_ssg/tasks/notifications.py @@ -0,0 +1,36 @@ +# SPDX-FileCopyrightText: 2026 Dennis Fink +# +# SPDX-License-Identifier: BSD-3-Clause + +import uuid + +from flask import current_app +from flask_mail import Message + +from .. import DATABASE as db +from .. import HUEY as huey +from .. import MAIL as mail +from ..models import ReceivedWebmention + + +@huey.task(retries=2, retry_delay=60) +def send_webmention_notification(webmention_uuid: uuid.UUID) -> None: + """Send an email when a received webmention has been verified.""" + recipient = current_app.config.get("WEBMENTIONS_SSG_NOTIFICATION_EMAIL") + if not recipient: + return + + webmention = db.session.get(ReceivedWebmention, webmention_uuid) + if webmention is None or webmention.status != "verified": + return + + message = Message( + subject="New verified webmention", + recipients=[recipient], + body=( + "A received webmention has been verified.\n\n" + f"Source: {webmention.source}\n" + f"Target: {webmention.target}\n" + ), + ) + mail.send(message) diff --git a/webmentions_ssg/tasks/receiver.py b/webmentions_ssg/tasks/receiver.py index c33f517..e99eea3 100644 --- a/webmentions_ssg/tasks/receiver.py +++ b/webmentions_ssg/tasks/receiver.py @@ -15,6 +15,7 @@ from .. import DATABASE as db from .. import HUEY as huey from ..models import ReceivedWebmention from ..url_security import AddressResolutionError, is_public_url +from .notifications import send_webmention_notification class VerificationError(Exception): @@ -218,7 +219,9 @@ def source_mentions_target(source_url: str, target_url: str) -> bool: @huey.task(retries=2, retry_delay=50) -def verify_webmention(webmention_uuid: uuid.UUID) -> None: +def verify_webmention( + webmention_uuid: uuid.UUID, send_notification: bool = True +) -> None: """ Verify a received webmention and store its verification status. @@ -226,6 +229,8 @@ def verify_webmention(webmention_uuid: uuid.UUID) -> None: retry the task. :param webmention_uuid: Identifier of the received webmention to verify. + :param send_notification: Whether to enqueue an email notification after + successful verification. :raises TemporaryFetchError: If fetching the source fails temporarily. :raises httpx.RequestError: If an HTTP request error occurs while fetching the source. @@ -267,3 +272,12 @@ def verify_webmention(webmention_uuid: uuid.UUID) -> None: webmention.failure_reason = "Source does not mention target" db.session.commit() + + if send_notification: + try: + send_webmention_notification(webmention_uuid) + except Exception: + # Notification delivery must not change the persisted verification status. + current_app.logger.exception( + "Could not enqueue webmention notification for %s", webmention_uuid + ) diff --git a/webmentions_ssg/views.py b/webmentions_ssg/views.py index b19d832..b2f7e7e 100644 --- a/webmentions_ssg/views.py +++ b/webmentions_ssg/views.py @@ -164,7 +164,7 @@ def reverify_received_webmention(identifier: uuid.UUID) -> ResponseReturnValue: db.session.commit() - verify_webmention(identifier) + verify_webmention(identifier, send_notification=False) flash(f"Webmention {webmention.uuid} queued for reverification.", "success") @@ -315,6 +315,9 @@ def endpoint() -> ResponseReturnValue: ) ).scalar_one_or_none() + # Only notify about new webmentions, not resubmissions of existing ones. + send_notification = webmention is None + if webmention is None: identifier = uuid.uuid7() @@ -326,6 +329,7 @@ def endpoint() -> ResponseReturnValue: db.session.commit() except sa_exc.IntegrityError: db.session.rollback() + send_notification = False # Another request may have inserted the same source/target pair # after our SELECT but before our COMMIT. @@ -351,7 +355,7 @@ def endpoint() -> ResponseReturnValue: db.session.commit() - verify_webmention(webmention.uuid) + verify_webmention(webmention.uuid, send_notification=send_notification) status_url = url_for("root.status", identifier=str(identifier), _external=True) -- cgit v1.3.1