aboutsummaryrefslogtreecommitdiff
path: root/webmentions_ssg/tasks/sender.py
diff options
context:
space:
mode:
authorDennis Fink2026-11-15 20:42:20 +0100
committerDennis Fink2026-11-15 20:42:20 +0100
commit509d93b2976e353d29441a7a7b7e78ca466dc4fd (patch)
tree753e637aefabd4293f808addbf9c310eaf0aa552 /webmentions_ssg/tasks/sender.py
parentc74feda222745ab7cca8993df83d9ea5f9d07e5b (diff)
downloadwebmentions-ssg-509d93b2976e353d29441a7a7b7e78ca466dc4fd.tar.gz
webmentions-ssg-509d93b2976e353d29441a7a7b7e78ca466dc4fd.zip
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.
Diffstat (limited to '')
-rw-r--r--webmentions_ssg/tasks/sender.py78
1 files changed, 40 insertions, 38 deletions
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,
)