From 509d93b2976e353d29441a7a7b7e78ca466dc4fd Mon Sep 17 00:00:00 2001 From: Dennis Fink Date: Sun, 15 Nov 2026 20:42:20 +0100 Subject: refactor(core)!: standardize application terminology Rename configuration keys, task helpers, forms, network utilities, and view endpoints to make their responsibilities and domains more explicit. Align source-management routes and templates with the new terminology and rename the target-matching module and related task abstractions consistently. BREAKING CHANGE: configuration keys have been renamed and sent-source routes move from `/sent` to `/sources`, with corresponding blueprint endpoint changes. --- webmentions_ssg/tasks/sender.py | 78 +++++++++++++++++++++-------------------- 1 file changed, 40 insertions(+), 38 deletions(-) (limited to 'webmentions_ssg/tasks/sender.py') diff --git a/webmentions_ssg/tasks/sender.py b/webmentions_ssg/tasks/sender.py index cf8ab9d..c33cf06 100644 --- a/webmentions_ssg/tasks/sender.py +++ b/webmentions_ssg/tasks/sender.py @@ -19,20 +19,20 @@ from ..models import SentWebmention, SentWebmentionStatus from ..net import ( AddressResolutionError, UnsafeAddressError, - build_client, + build_public_http_client, is_http_url, - is_temporary_status, + is_retryable_status, ) from ..version import APP_NAME, VERSION from .discovery import ( - PermanentSenderError, - TemporarySenderError, + PermanentDeliveryError, + RetryableDeliveryError, discover_webmention_endpoint, post_webmention, ) -def attempt_is_current(webmention: SentWebmention, revision: int) -> bool: +def revision_still_pending(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 @@ -47,7 +47,7 @@ def attempt_is_current(webmention: SentWebmention, revision: int) -> bool: return webmention.desired_revision == revision and webmention.pending -def retry_delay(attempt: int) -> timedelta: +def backoff_delay(attempt: int) -> timedelta: """Calculate the capped exponential delay after a numbered send attempt. :param attempt: One-based send attempt number. @@ -76,7 +76,7 @@ def send_webmention(webmention_uuid: uuid.UUID) -> None: # The pending/retry checks must happen *under* this lock. try: with huey.lock_task(f"send-webmention-{webmention_uuid}"): - _send_locked(webmention_uuid) + _process_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. @@ -84,12 +84,12 @@ def send_webmention(webmention_uuid: uuid.UUID) -> None: @dataclass(frozen=True) -class SendAttempt: +class ClaimedSendAttempt: """Claimed source revision and retry budget for one send.""" - identifier: uuid.UUID + webmention_uuid: uuid.UUID revision: int - number: int + attempt_number: int max_attempts: int source: str target: str @@ -112,7 +112,7 @@ class DeliveryResult: temporary_failure: bool = False -def is_due(webmention: SentWebmention, now: datetime) -> bool: +def is_ready_to_send(webmention: SentWebmention, now: datetime) -> bool: """Return whether an unprocessed Webmention has reached its retry deadline. :param webmention: Outgoing Webmention whose retry eligibility is checked. @@ -130,7 +130,9 @@ def is_due(webmention: SentWebmention, now: datetime) -> bool: return aware_deadline <= now -def claim_attempt(webmention: SentWebmention, now: datetime) -> SendAttempt | None: +def reserve_send_attempt( + webmention: SentWebmention, now: datetime +) -> ClaimedSendAttempt | None: """Atomically reserve one send attempt, or finish an exhausted revision. An attempt's next retry deadline is persisted *before* the HTTP request so @@ -172,10 +174,10 @@ def claim_attempt(webmention: SentWebmention, now: datetime) -> SendAttempt | No db.session.commit() return None - attempt = SendAttempt( - identifier=webmention.uuid, + attempt = ClaimedSendAttempt( + webmention_uuid=webmention.uuid, revision=revision, - number=webmention.attempt_count + 1, + attempt_number=webmention.attempt_count + 1, max_attempts=max_attempts, source=webmention.source.url, target=webmention.target, @@ -183,9 +185,9 @@ def claim_attempt(webmention: SentWebmention, now: datetime) -> SendAttempt | No changed = db.session.execute( sa.update(SentWebmention) .where( - SentWebmention.uuid == attempt.identifier, + SentWebmention.uuid == attempt.webmention_uuid, SentWebmention.desired_revision == revision, - SentWebmention.attempt_count == attempt.number - 1, + SentWebmention.attempt_count == attempt.attempt_number - 1, SentWebmention.pending, sa.or_( SentWebmention.next_retry_at.is_(None), @@ -193,9 +195,9 @@ def claim_attempt(webmention: SentWebmention, now: datetime) -> SendAttempt | No ), ) .values( - attempt_count=attempt.number, + attempt_count=attempt.attempt_number, last_attempted_at=now, - next_retry_at=now + retry_delay(attempt.number), + next_retry_at=now + backoff_delay(attempt.attempt_number), endpoint=None, response_status=None, status_url=None, @@ -211,7 +213,7 @@ def claim_attempt(webmention: SentWebmention, now: datetime) -> SendAttempt | No return attempt -def deliver_webmention( +def attempt_delivery( source: str, target: str, *, webmention_uuid: uuid.UUID ) -> DeliveryResult: """Discover and POST a Webmention, returning an outcome without DB writes. @@ -227,9 +229,9 @@ def deliver_webmention( try: if not is_http_url(target): - raise PermanentSenderError(f"Invalid target URL: {target!r}") + raise PermanentDeliveryError(f"Invalid target URL: {target!r}") - with build_client(f"{APP_NAME}/{VERSION} SentWebmention") as client: + with build_public_http_client(f"{APP_NAME}/{VERSION} SentWebmention") as client: endpoint = discover_webmention_endpoint(client, target) if endpoint is None: @@ -243,9 +245,9 @@ def deliver_webmention( ) 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) + if is_retryable_status(response_status): + raise RetryableDeliveryError(message) + raise PermanentDeliveryError(message) return DeliveryResult( status=SentWebmentionStatus.SENT, @@ -254,7 +256,7 @@ def deliver_webmention( status_url=status_url, ) except ( - PermanentSenderError, + PermanentDeliveryError, UnsafeAddressError, httpx.InvalidURL, httpx.UnsupportedProtocol, @@ -267,7 +269,7 @@ def deliver_webmention( endpoint=endpoint, response_status=response_status, ) - except (TemporarySenderError, AddressResolutionError, httpx.RequestError) as exc: + except (RetryableDeliveryError, AddressResolutionError, httpx.RequestError) as exc: return DeliveryResult( status=SentWebmentionStatus.FAILED, reason=str(exc) or "Webmention request failed", @@ -289,9 +291,9 @@ def deliver_webmention( ) -def record_outcome( +def record_delivery_outcome( webmention: SentWebmention, - attempt: SendAttempt, + attempt: ClaimedSendAttempt, result: DeliveryResult, *, terminal: bool, @@ -305,7 +307,7 @@ def record_outcome( :returns: ``True`` if the outcome was recorded for the current revision. """ # A scanner may have reopened or superseded the revision during I/O. - if not attempt_is_current(webmention, attempt.revision): + if not revision_still_pending(webmention, attempt.revision): return False webmention.status = result.status @@ -330,7 +332,7 @@ def record_outcome( return True -def _send_locked(webmention_uuid: uuid.UUID) -> bool: +def _process_send_locked(webmention_uuid: uuid.UUID) -> bool: """Process a due Webmention while holding its per-UUID task lock. :param webmention_uuid: Identifier of the outgoing Webmention being processed. @@ -344,18 +346,18 @@ def _send_locked(webmention_uuid: uuid.UUID) -> bool: return False now = datetime.now(UTC) - if not is_due(webmention, now): + if not is_ready_to_send(webmention, now): return False - if (attempt := claim_attempt(webmention, now)) is None: + if (attempt := reserve_send_attempt(webmention, now)) is None: return False - result = deliver_webmention( + result = attempt_delivery( attempt.source, attempt.target, webmention_uuid=webmention_uuid ) - terminal = result.terminal or attempt.number >= attempt.max_attempts + terminal = result.terminal or attempt.attempt_number >= attempt.max_attempts - if not record_outcome(webmention, attempt, result, terminal=terminal): + if not record_delivery_outcome(webmention, attempt, result, terminal=terminal): return False if result.temporary_failure and not terminal: @@ -363,13 +365,13 @@ def _send_locked(webmention_uuid: uuid.UUID) -> bool: current_app.logger.info( "Webmention %s send attempt %d failed; will retry", webmention_uuid, - attempt.number, + attempt.attempt_number, ) elif result.temporary_failure: current_app.logger.warning( "Webmention %s exhausted %d send attempts: %s", webmention_uuid, - attempt.number, + attempt.attempt_number, result.reason, ) -- cgit v1.3.1