aboutsummaryrefslogtreecommitdiff
path: root/webmentions_ssg/views
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--webmentions_ssg/views/admin.py19
-rw-r--r--webmentions_ssg/views/endpoint.py39
-rw-r--r--webmentions_ssg/views/session.py6
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"))