aboutsummaryrefslogtreecommitdiff
path: root/webmentions_ssg/views/endpoint.py
blob: 95e873147f5cb866bdd7938250d28a7949d7ebae (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
# SPDX-FileCopyrightText: 2026 Dennis Fink <me+coding@dennisfink.me>
#
# 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


def submit_received(source: str, target: str) -> tuple[uuid.UUID, bool] | None:
    """Upsert a submission atomically and return (identifier, enqueue flag).

    ``None`` means that the URL fingerprint matches a different source/target.
    No background task is enqueued until the transaction is committed.
    """
    url_digest = received_url_digest(source, target)
    webmention = db.session.execute(
        sa.select(ReceivedWebmention).where(ReceivedWebmention.url_digest == url_digest)
    ).scalar_one_or_none()

    # A SHA-256 collision must never cause an unrelated Webmention to be overwritten.
    if webmention is not None and (webmention.source, webmention.target) != (
        source,
        target,
    ):
        return None

    should_verify = False

    if webmention is None:
        identifier = uuid.uuid7()
        webmention = ReceivedWebmention(uuid=identifier, source=source, target=target)
        db.session.add(webmention)

        try:
            db.session.commit()
            should_verify = True
        except sa_exc.IntegrityError:
            db.session.rollback()

            # Another request may have inserted the same source/target pair
            # after our SELECT but before our COMMIT.
            webmention = db.session.execute(
                sa.select(ReceivedWebmention).where(
                    ReceivedWebmention.url_digest == url_digest
                )
            ).scalar_one_or_none()
            if webmention is None or (webmention.source, webmention.target) != (
                source,
                target,
            ):
                return None

    else:
        now = datetime.now(UTC)
        cutoff = now - timedelta(
            seconds=current_app.config["ENDPOINT_REVERIFY_COOLDOWN_SECONDS"]
        )

        # Atomic conditional update: only one concurrent request can reopen an expired verification.
        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)
            ),
        )
        should_verify = result.rowcount == 1
        db.session.commit()

    return webmention.uuid, should_verify


@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/<uuid:identifier>")
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
    )