# SPDX-FileCopyrightText: 2026 Dennis Fink # # SPDX-License-Identifier: BSD-3-Clause """Claim, send, and persist outgoing Webmention attempts.""" import uuid from datetime import UTC, datetime, timedelta import httpx import sqlalchemy as sa from flask import current_app from huey.exceptions import TaskLockedException from ..db_helpers import rows_affected from ..extensions import db, huey from ..models import SentWebmention, SentWebmentionStatus from ..net import ( AddressResolutionError, UnsafeAddressError, build_client, is_http_url, is_temporary_status, ) from ..version import APP_NAME, VERSION from .discovery import ( PermanentSenderError, TemporarySenderError, discover_webmention_endpoint, post_webmention, ) def attempt_is_current(webmention: SentWebmention, revision: int) -> bool: """Check whether a send attempt still represents the desired revision. The Webmention is refreshed from the database before comparing its desired and processed revisions. :param webmention: Sent Webmention being processed. :param revision: Source revision represented by the current attempt. :return: Whether the attempt is still current and requires processing. """ db.session.refresh(webmention) return webmention.desired_revision == revision and webmention.pending def retry_delay(attempt: int) -> timedelta: """Calculate the capped exponential delay after a numbered send attempt.""" base = max(1, int(current_app.config["SEND_RETRY_BASE_SECONDS"])) maximum = max(base, int(current_app.config["SEND_RETRY_MAX_SECONDS"])) return timedelta(seconds=min(base * 2 ** (attempt - 1), maximum)) @huey.task() def send_webmention(webmention_uuid: uuid.UUID) -> None: """Discover a receiver endpoint and send a Webmention. The result of the attempt is stored on the corresponding sent Webmention. Temporary failures are recorded with an exponential retry deadline. The scanner requeues them when due; Huey does not retry them independently. The retry budget is per desired source revision. :param webmention_uuid: Identifier of the sent Webmention to process. """ # Huey locks have static names when used as decorators. Acquire one keyed by # UUID inside the task so different Webmentions can still send in parallel. # The pending/retry checks must happen *under* this lock. try: with huey.lock_task(f"send-webmention-{webmention_uuid}"): _send_locked(webmention_uuid) except TaskLockedException: # Another worker is already sending this Webmention. The active worker # owns its result; a later scan will requeue it if it remains pending. return def _send_locked(webmention_uuid: uuid.UUID) -> None: """Process a Webmention while holding its per-UUID task lock.""" webmention = db.session.get(SentWebmention, webmention_uuid) if webmention is None: current_app.logger.warning( "Cannot send unknown SentWebmention %s", webmention_uuid ) return if not webmention.pending: return revision = webmention.desired_revision source = webmention.source.url target = webmention.target now = datetime.now(UTC) deadline = webmention.next_retry_at if deadline is not None: aware_deadline = deadline if deadline.tzinfo else deadline.replace(tzinfo=UTC) if aware_deadline > now: return max_attempts = max(1, int(current_app.config["SEND_MAX_ATTEMPTS"])) if webmention.attempt_count >= max_attempts: # Recover records whose worker died during the final attempt, without # touching a newer revision that may have been queued in the meantime. db.session.execute( sa.update(SentWebmention) .where( SentWebmention.uuid == webmention_uuid, SentWebmention.desired_revision == revision, SentWebmention.attempt_count >= max_attempts, SentWebmention.pending, sa.or_( SentWebmention.next_retry_at.is_(None), SentWebmention.next_retry_at <= now, ), ) .values( processed_revision=revision, next_retry_at=None, status=SentWebmentionStatus.FAILED, failure_reason=( webmention.failure_reason or f"Retry limit reached ({max_attempts} attempts)" ), ) .execution_options(synchronize_session=False) ) db.session.commit() return attempt = webmention.attempt_count + 1 next_retry_at = now + retry_delay(attempt) # Claim the attempt atomically: duplicate queued tasks must not send the # same revision concurrently or bypass its retry deadline. claim = db.session.execute( sa.update(SentWebmention) .where( SentWebmention.uuid == webmention_uuid, SentWebmention.desired_revision == revision, SentWebmention.attempt_count == attempt - 1, SentWebmention.pending, sa.or_( SentWebmention.next_retry_at.is_(None), SentWebmention.next_retry_at <= now, ), ) .values( attempt_count=attempt, last_attempted_at=now, next_retry_at=next_retry_at, endpoint=None, response_status=None, status_url=None, ) .execution_options(synchronize_session=False) ) db.session.commit() if rows_affected(claim) != 1: return db.session.refresh(webmention) endpoint: str | None = None response_status: int | None = None status_url: str | None = None reason: str | None = None terminal = True temporary_failure = False try: if not is_http_url(target): raise PermanentSenderError(f"Invalid target URL: {target!r}") with build_client(f"{APP_NAME}/{VERSION} SentWebmention") as client: endpoint = discover_webmention_endpoint(client, target) if endpoint is None: outcome = SentWebmentionStatus.UNSUPPORTED reason = "No Webmention endpoint discovered" else: response_status, status_url = post_webmention( client, endpoint=endpoint, source=source, target=target ) if not 200 <= response_status <= 299: message = f"Webmention endpoint returned HTTP {response_status}" if is_temporary_status(response_status): raise TemporarySenderError(message) raise PermanentSenderError(message) outcome = SentWebmentionStatus.SENT except ( PermanentSenderError, UnsafeAddressError, httpx.InvalidURL, httpx.UnsupportedProtocol, httpx.LocalProtocolError, ) as exc: # Known permanent failures cannot improve with retries. outcome = SentWebmentionStatus.FAILED reason = str(exc) or type(exc).__name__ except (TemporarySenderError, AddressResolutionError, httpx.RequestError) as exc: outcome = SentWebmentionStatus.FAILED reason = str(exc) or "Webmention request failed" terminal = attempt >= max_attempts temporary_failure = True except Exception as exc: # Unexpected errors must not disappear into a generic permanent-failure # handler without a traceback (including programming ValueErrors). current_app.logger.exception( "Unexpected error sending SentWebmention %s", webmention_uuid ) outcome = SentWebmentionStatus.FAILED reason = str(exc) or type(exc).__name__ # A scanner may have reopened or superseded the revision during I/O. # Refresh only once, and persist one outcome atomically with its metadata. if not attempt_is_current(webmention, revision): return webmention.status = outcome webmention.failure_reason = reason webmention.endpoint = endpoint webmention.response_status = response_status if terminal: webmention.processed_revision = revision webmention.next_retry_at = None if outcome == SentWebmentionStatus.SENT: webmention.sent_revision = revision webmention.status_url = ( status_url if status_url is not None and is_http_url(status_url) else None ) webmention.last_sent_at = datetime.now(UTC) db.session.commit() if temporary_failure and not terminal: # Huey does not retry: scanner requeues after next_retry_at. current_app.logger.info( "Webmention %s send attempt %d failed; will retry", webmention_uuid, attempt ) elif temporary_failure and terminal: current_app.logger.warning( "Webmention %s exhausted %d send attempts: %s", webmention_uuid, attempt, reason, )