diff options
Diffstat (limited to 'webmentions_ssg/views/endpoint.py')
| -rw-r--r-- | webmentions_ssg/views/endpoint.py | 39 |
1 files changed, 33 insertions, 6 deletions
diff --git a/webmentions_ssg/views/endpoint.py b/webmentions_ssg/views/endpoint.py index a7badfd..85ec398 100644 --- a/webmentions_ssg/views/endpoint.py +++ b/webmentions_ssg/views/endpoint.py @@ -26,7 +26,14 @@ class UrlDigestCollisionError(Exception): def find_webmention_by_digest(source: str, target: str) -> ReceivedWebmention | None: - """Return the matching Webmention, or raise on a SHA-256 collision.""" + """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.url_digest == received_url_digest(source, target) @@ -43,7 +50,14 @@ def find_webmention_by_digest(source: str, target: str) -> ReceivedWebmention | def insert_webmention(source: str, target: str) -> ReceivedWebmention | None: - """Insert and return a Webmention, or None if another request won the race.""" + """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) @@ -57,7 +71,13 @@ def insert_webmention(source: str, target: str) -> ReceivedWebmention | None: def reopen_if_cooled_down(webmention: ReceivedWebmention) -> bool: - """Atomically reopen an old Webmention and return whether it was reopened.""" + """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"] @@ -80,6 +100,13 @@ 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. + + 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_webmention_by_digest(source, target)) is None: @@ -108,8 +135,8 @@ def endpoint() -> ResponseReturnValue: 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. + :returns: HTTP 201 response with the Webmention status URL in the ``Location`` + header, or validation errors with HTTP 400. """ form = forms.EndpointForm(meta={"csrf": False}) @@ -139,7 +166,7 @@ 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. + :returns: Rendered Webmention status page. """ webmention = db.get_or_404(ReceivedWebmention, identifier) |
