# SPDX-FileCopyrightText: 2026 Dennis Fink # # SPDX-License-Identifier: BSD-3-Clause """Public Webmention endpoint and verification status view.""" import uuid from datetime import UTC, datetime, timedelta from http import HTTPStatus from typing import cast import sqlalchemy as sa import sqlalchemy.exc as sa_exc from flask import Response, current_app, render_template, url_for from flask.typing import ResponseReturnValue from ..db_helpers import rows_affected from ..extensions import csrf, db, limiter from ..forms.endpoint import WebmentionSubmissionForm from ..models.received import ReceivedWebmention from ..models.utils import source_target_digest from ..moderation_policy import rejection_reason from ..tasks.verification import verify_webmention from .blueprint import webmentions_bp class UrlDigestCollisionError(Exception): """The URL digest already belongs to a different source/target pair.""" def find_received_webmention(source: str, target: str) -> ReceivedWebmention | None: """Return the matching Webmention, or raise on a SHA-256 collision. :param source: Exact source URL to look up. :param target: Exact target URL to look up. :returns: Matching Webmention, or ``None`` if none is stored. :raises UrlDigestCollisionError: If the digest matches a different source/target pair. """ webmention = db.session.execute( sa.select(ReceivedWebmention).where( ReceivedWebmention.source_target_digest == source_target_digest(source, target) ) ).scalar_one_or_none() if webmention is not None and (webmention.source, webmention.target) != ( source, target, ): raise UrlDigestCollisionError return webmention def try_insert_received_webmention( source: str, target: str ) -> ReceivedWebmention | None: """Insert and return a Webmention, or None if another request won the race. Use an atomic insert and treat uniqueness conflicts as concurrent submissions. :param source: Source URL of the new Webmention. :param target: Target URL of the new Webmention. :returns: New Webmention, or ``None`` if a concurrent insert won. """ webmention = ReceivedWebmention(uuid=uuid.uuid7(), source=source, target=target) db.session.add(webmention) try: db.session.commit() except sa_exc.IntegrityError: db.session.rollback() return None return webmention def reopen_if_cooldown_elapsed(webmention: ReceivedWebmention) -> bool: """Atomically reopen an old Webmention and return whether it was reopened. Only a terminal Webmention beyond the cooldown interval can be reset. :param webmention: Existing Webmention to conditionally reopen. :returns: ``True`` when the Webmention was reopened for verification. """ now = datetime.now(UTC) cutoff = now - timedelta( seconds=current_app.config["ENDPOINT_REVERIFY_COOLDOWN_SECONDS"] ) result = db.session.execute( sa.update(ReceivedWebmention) .where( ReceivedWebmention.uuid == webmention.uuid, ReceivedWebmention.updated_at <= cutoff, ) .values(ReceivedWebmention.reopen_verification_values(at=now)) .execution_options(synchronize_session=False) ) db.session.commit() return rows_affected(result) == 1 def record_submission(source: str, target: str) -> tuple[uuid.UUID, bool] | None: """Return (identifier, enqueue flag), or None on a digest conflict. A new submission is committed before it can be queued for verification. Commit new submissions before returning whether a verification task should be queued. :param source: Submitted Webmention source URL. :param target: Submitted Webmention target URL. :returns: Webmention identifier and enqueue flag, or ``None`` on a digest collision. """ try: if (webmention := find_received_webmention(source, target)) is None: if ( webmention := try_insert_received_webmention(source, target) ) is not None: return webmention.uuid, True # A concurrent insert won: look up its row after rolling back. if (webmention := find_received_webmention(source, target)) is None: return None return webmention.uuid, reopen_if_cooldown_elapsed(webmention) except UrlDigestCollisionError: return None @webmentions_bp.post("/endpoint") @limiter.limit( lambda: current_app.config["ENDPOINT_GLOBAL_RATE_LIMIT"], key_func=lambda: "all-clients", ) @limiter.limit(lambda: current_app.config["ENDPOINT_RATE_LIMIT"]) @csrf.exempt def receive_webmention() -> ResponseReturnValue: """Receive and queue a Webmention for verification. Existing Webmentions with the same source and target are reset for reverification. Concurrent insertion of the same Webmention is handled by retrieving and updating the row created by the competing request. :returns: HTTP 201 response with the Webmention status URL in the ``Location`` header, or validation errors with HTTP 400. """ form = WebmentionSubmissionForm(meta={"csrf": False}) if not form.validate_on_submit(): return form.errors, HTTPStatus.BAD_REQUEST source = cast(str, form.source.data) target = cast(str, form.target.data) if reason := rejection_reason(source): return {"error": reason}, HTTPStatus.FORBIDDEN result = record_submission(source, target) if result is None: return {"error": "Webmention URL fingerprint conflict"}, HTTPStatus.CONFLICT identifier, should_verify = result if should_verify: verify_webmention(identifier) status_url = url_for( "webmentions.webmention_status", identifier=str(identifier), _external=True ) return Response(status=HTTPStatus.CREATED, headers={"Location": status_url}) @webmentions_bp.route("/status/") def webmention_status(identifier: uuid.UUID) -> ResponseReturnValue: """Display the verification status of a received Webmention. :param identifier: Identifier of the Webmention to display. :returns: Rendered Webmention status page. """ webmention = db.get_or_404(ReceivedWebmention, identifier) return render_template( "status.html", title="Webmention status", webmention=webmention )