diff options
Diffstat (limited to '')
| -rw-r--r-- | webmentions_ssg/views/admin.py | 19 | ||||
| -rw-r--r-- | webmentions_ssg/views/endpoint.py | 39 | ||||
| -rw-r--r-- | webmentions_ssg/views/session.py | 6 |
3 files changed, 47 insertions, 17 deletions
diff --git a/webmentions_ssg/views/admin.py b/webmentions_ssg/views/admin.py index f095de8..b9ab53e 100644 --- a/webmentions_ssg/views/admin.py +++ b/webmentions_ssg/views/admin.py @@ -22,7 +22,10 @@ from .blueprint import root_page def validate_admin_action() -> None: - """Reject invalid administrative action forms with HTTP 400.""" + """Reject invalid administrative action forms with HTTP 400. + + Abort the request when the posted form does not pass CSRF or other validation. + """ if not forms.AdminActionForm().validate_on_submit(): abort(400) @@ -32,7 +35,7 @@ def validate_admin_action() -> None: def received() -> ResponseReturnValue: """Display received Webmentions. - :return: Rendered page containing the paginated received Webmentions. + :returns: Rendered page containing the paginated received Webmentions. """ webmentions = db.paginate( sa.select(ReceivedWebmention).order_by(ReceivedWebmention.uuid.desc()), @@ -53,7 +56,7 @@ def delete_received_webmention(identifier: uuid.UUID) -> ResponseReturnValue: """Delete a received Webmention. :param identifier: Identifier of the Webmention to delete. - :return: Redirect response to the received Webmentions view. + :returns: Redirect response to the received Webmentions view. """ validate_admin_action() @@ -77,7 +80,7 @@ def reverify_received_webmention(identifier: uuid.UUID) -> ResponseReturnValue: The Webmention status is reset before a new verification task is queued. :param identifier: Identifier of the Webmention to reverify. - :return: Redirect response to the received Webmentions view. + :returns: Redirect response to the received Webmentions view. """ validate_admin_action() @@ -101,7 +104,7 @@ def reverify_received_webmention(identifier: uuid.UUID) -> ResponseReturnValue: def sent() -> ResponseReturnValue: """Display sources with sent Webmentions. - :return: Rendered page containing the paginated source list. + :returns: Rendered page containing the paginated source list. """ sources = db.paginate( sa.select(Source) @@ -122,7 +125,7 @@ def sent() -> ResponseReturnValue: def rescan_sent_sources() -> ResponseReturnValue: """Queue a manual scan of sent Webmention sources. - :return: Redirect response to the sent Webmentions view. + :returns: Redirect response to the sent Webmentions view. """ validate_admin_action() @@ -138,7 +141,7 @@ def sent_source(source_identifier: uuid.UUID) -> ResponseReturnValue: """Display the sent Webmentions associated with a source. :param source_identifier: Identifier of the source to display. - :return: Rendered source details page. + :returns: Rendered source details page. """ source = db.get_or_404(Source, source_identifier) @@ -172,7 +175,7 @@ def resend_sent_webmention( :param source_identifier: Identifier of the source owning the Webmention. :param webmention_identifier: Identifier of the sent Webmention to resend. - :return: Redirect response to the source details view. + :returns: Redirect response to the source details view. """ validate_admin_action() 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) diff --git a/webmentions_ssg/views/session.py b/webmentions_ssg/views/session.py index 870c967..371997d 100644 --- a/webmentions_ssg/views/session.py +++ b/webmentions_ssg/views/session.py @@ -21,7 +21,7 @@ from .blueprint import root_page def index() -> ResponseReturnValue: """Redirect to the received Webmentions view. - :return: Redirect response to the received Webmentions view. + :returns: Redirect response to the received Webmentions view. """ return redirect(url_for("root.received")) @@ -45,7 +45,7 @@ def login() -> ResponseReturnValue: successful login, the user is redirected to the requested local URL when provided. - :return: Rendered login page or redirect response. + :returns: Rendered login page or redirect response. """ if current_user.is_authenticated: return redirect(url_for("root.index")) @@ -77,7 +77,7 @@ def login() -> ResponseReturnValue: def logout() -> ResponseReturnValue: """End the current user's login session. - :return: Redirect response to the application index. + :returns: Redirect response to the application index. """ logout_user() return redirect(url_for("root.index")) |
