aboutsummaryrefslogtreecommitdiff
path: root/webmentions_ssg/views/endpoint.py
blob: 36c46939d8c4fa0884a953fed0189b2aa0e13562 (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
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
# 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 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,
    ReceivedWebmentionStatus,
    ReceivedWebmentionStatusEvent,
)
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)
    webmention.status_events.append(
        ReceivedWebmentionStatusEvent(
            webmention_uuid=webmention.uuid,
            status=ReceivedWebmentionStatus.RECEIVED,
            action="Received submission",
            occurred_at=webmention.created_at,
        )
    )

    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)
    )
    if rows_affected(result) != 1:
        db.session.rollback()
        return False

    db.session.add(
        ReceivedWebmentionStatusEvent(
            webmention_uuid=webmention.uuid,
            status=ReceivedWebmentionStatus.RECEIVED,
            action="Resubmitted after cooldown",
            occurred_at=now,
        )
    )
    db.session.commit()
    return True


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