# 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 typing import Any, cast import sqlalchemy as sa import sqlalchemy.exc as sa_exc from flask import Response, abort, current_app, render_template, url_for from flask.typing import ResponseReturnValue from sqlalchemy.engine import CursorResult from .. import forms from ..extensions import csrf, db, limiter from ..models import ReceivedWebmention, received_url_digest from ..tasks.receiver import verify_webmention from .blueprint import root_page class UrlDigestCollisionError(Exception): """The URL digest already belongs to a different source/target pair.""" def find_webmention_by_digest(source: str, target: str) -> ReceivedWebmention | None: """Return the matching Webmention, or raise on a SHA-256 collision.""" webmention = db.session.execute( sa.select(ReceivedWebmention).where( ReceivedWebmention.url_digest == received_url_digest(source, target) ) ).scalar_one_or_none() if webmention is not None and (webmention.source, webmention.target) != ( source, target, ): raise UrlDigestCollisionError return webmention def insert_webmention(source: str, target: str) -> ReceivedWebmention | None: """Insert and return a Webmention, or None if another request won the race.""" 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_cooled_down(webmention: ReceivedWebmention) -> bool: """Atomically reopen an old Webmention and return whether it was reopened.""" now = datetime.now(UTC) cutoff = now - timedelta( seconds=current_app.config["ENDPOINT_REVERIFY_COOLDOWN_SECONDS"] ) result = cast( CursorResult[Any], db.session.execute( sa.update(ReceivedWebmention) .where( ReceivedWebmention.uuid == webmention.uuid, ReceivedWebmention.updated_at <= cutoff, ) .values(ReceivedWebmention.verification_reset_values(at=now)) .execution_options(synchronize_session=False) ), ) db.session.commit() return result.rowcount == 1 def submit_received(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. """ try: if (webmention := find_webmention_by_digest(source, target)) is None: if (webmention := insert_webmention(source, target)) is not None: return webmention.uuid, True # A concurrent insert won: look up its row after rolling back. if (webmention := find_webmention_by_digest(source, target)) is None: return None return webmention.uuid, reopen_if_cooled_down(webmention) except UrlDigestCollisionError: return None @root_page.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 endpoint() -> 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. :return: HTTP 201 response with the Webmention status URL in the ``Location`` header, or validation errors with HTTP 400. """ form = forms.EndpointForm(meta={"csrf": False}) if not form.validate_on_submit(): return form.errors, 400 source = cast(str, form.source.data) target = cast(str, form.target.data) result = submit_received(source, target) if result is None: return {"error": "Webmention URL fingerprint conflict"}, 409 identifier, should_verify = result if should_verify: verify_webmention(identifier) status_url = url_for("root.status", identifier=str(identifier), _external=True) return Response(status=201, headers={"Location": status_url}) @root_page.route("/status/") def status(identifier: uuid.UUID) -> ResponseReturnValue: """Display the verification status of a received Webmention. :param identifier: Identifier of the Webmention to display. :return: Rendered Webmention status page. """ webmention = db.session.get(ReceivedWebmention, identifier) if webmention is None: return abort(404) return render_template( "status.html", title="Webmention status", webmention=webmention )