log-foundry 0.10.2.dev19__tar.gz → 0.10.2.dev20__tar.gz

{log_foundry-0.10.2.dev19 → log_foundry-0.10.2.dev20}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: log-foundry
-Version: 0.10.2.dev19
+Version: 0.10.2.dev20
 Summary: Generate logs for your console and JSON events for downstream consumption.
 License-Expression: MIT
 License-File: LICENSE
@@ -780,9 +780,23 @@ which one you want depends on whether the process is about to end:
 import log_foundry as lf
 
 lf.flush()      # drain to the sink and keep going; returns True when everything landed
-lf.shutdown()   # drain, close the sink, and stop for good; blocks until drained
+lf.shutdown()   # drain, close the sink, and stop for good; blocks until drained (30s cap)
 ```
 
+Both are bounded, because both can be called somewhere with a deadline. `flush(timeout=5.0)`
+returns `False` if the drain did not complete; `shutdown(timeout=30.0)` returns having stopped
+what it could, and reports `health().stopped_reason == "ShutdownTimeout"`. Passing `None` to
+either waits indefinitely, which is unsafe in any environment with an execution deadline.
+
+**What a broken destination can cost you.** There is one drain thread, so a sink's backoff pauses
+*all* log delivery, and it spans `shutdown()`. At the defaults (`max_retries=3`) that is 0.7 s of
+backoff per batch for most sinks (per *message* for the socket-backed ones — ~70 s for a
+100-message batch against a dead syslog host), and up to 90 s for an HTTP sink whose destination
+is sending
+`Retry-After` — clamped to `max_retry_after=30.0` per wait, which you can lower. Every wait is cut
+short by a shutdown, and `shutdown()`'s own timeout bounds the total either way. Each sink's class
+docstring states its own worst case.
+
 | | `flush()` | `shutdown()` |
 |---|---|---|
 | Drains buffered events | yes | yes |

{log_foundry-0.10.2.dev19 → log_foundry-0.10.2.dev20}/README.md

@@ -744,9 +744,23 @@ which one you want depends on whether the process is about to end:
 import log_foundry as lf
 
 lf.flush()      # drain to the sink and keep going; returns True when everything landed
-lf.shutdown()   # drain, close the sink, and stop for good; blocks until drained
+lf.shutdown()   # drain, close the sink, and stop for good; blocks until drained (30s cap)
 ```
 
+Both are bounded, because both can be called somewhere with a deadline. `flush(timeout=5.0)`
+returns `False` if the drain did not complete; `shutdown(timeout=30.0)` returns having stopped
+what it could, and reports `health().stopped_reason == "ShutdownTimeout"`. Passing `None` to
+either waits indefinitely, which is unsafe in any environment with an execution deadline.
+
+**What a broken destination can cost you.** There is one drain thread, so a sink's backoff pauses
+*all* log delivery, and it spans `shutdown()`. At the defaults (`max_retries=3`) that is 0.7 s of
+backoff per batch for most sinks (per *message* for the socket-backed ones — ~70 s for a
+100-message batch against a dead syslog host), and up to 90 s for an HTTP sink whose destination
+is sending
+`Retry-After` — clamped to `max_retry_after=30.0` per wait, which you can lower. Every wait is cut
+short by a shutdown, and `shutdown()`'s own timeout bounds the total either way. Each sink's class
+docstring states its own worst case.
+
 | | `flush()` | `shutdown()` |
 |---|---|---|
 | Drains buffered events | yes | yes |

{log_foundry-0.10.2.dev19 → log_foundry-0.10.2.dev20}/pyproject.toml

@@ -20,7 +20,7 @@ dependencies = [
 ]
 
 # Optional features. Install with: pip install log-foundry[aws]
-version = "0.10.2.dev19"
+version = "0.10.2.dev20"
 
 [project.optional-dependencies]
 aws = ["boto3>=1.43.61"]              # SQSSink, SNSSink, KinesisSink, FirehoseSink

{log_foundry-0.10.2.dev19 → log_foundry-0.10.2.dev20}/src/log_foundry/__init__.py

@@ -21,7 +21,7 @@ from log_foundry.context import (
 )
 from log_foundry.decorator import continue_trace, trace
 from log_foundry.sinks.base import SinkDeliveryError, SinkLosses
-from log_foundry.worker import Health
+from log_foundry.worker import DEFAULT_SHUTDOWN_TIMEOUT, Health
 
 try:
     # Distribution name ("log-foundry") differs from the import name ("log_foundry").
@@ -92,7 +92,7 @@ def health() -> Health:
     return _worker_health()
 
 
-def shutdown() -> None:
+def shutdown(timeout: float | None = DEFAULT_SHUTDOWN_TIMEOUT) -> None:
     """Flush buffered events and close the sink, blocking until drained. Idempotent.
 
     Also registered via ``atexit``; call it explicitly before a fast process exit when you
@@ -101,13 +101,21 @@ def shutdown() -> None:
     This is **terminal** — the worker does not come back. Do not call it per-invocation in a
     serverless handler: the first invocation on a warm container would log and every later one
     would silently log nothing. Use :func:`flush` there, which drains and keeps the worker.
+
+    ``timeout`` bounds the wait for the background thread (SPEC-027 FR-004). ``None`` waits
+    indefinitely, which is what this did unconditionally before and is still available on
+    request — but it is unsafe anywhere with an execution deadline, and ``atexit`` is one such
+    place: a sink blocked in a network call would hold the process open. An expired shutdown
+    reports ``health().stopped_reason == "ShutdownTimeout"`` and leaves the sink **open**, since
+    the drain thread may still be inside ``emit``. Never raises.
     """
     from log_foundry.decorator import _shutdown_worker
 
-    _shutdown_worker()
+    _shutdown_worker(timeout)
 
 
 __all__ = [
+    "DEFAULT_SHUTDOWN_TIMEOUT",
     "Health",
     "SinkDeliveryError",
     "SinkLosses",

{log_foundry-0.10.2.dev19 → log_foundry-0.10.2.dev20}/src/log_foundry/decorator.py

@@ -39,7 +39,7 @@ from log_foundry.ids import (
     parse_traceparent,
 )
 from log_foundry.model import Span, backfill_baggage, end_event, start_event
-from log_foundry.worker import Health, Worker
+from log_foundry.worker import DEFAULT_SHUTDOWN_TIMEOUT, Health, Worker
 
 if TYPE_CHECKING:
     import contextvars
@@ -209,10 +209,15 @@ def _get_worker() -> Worker:
     return _worker
 
 
-def _shutdown_worker() -> None:
-    """Drain + close the process worker if one was created (idempotent). Backs ``shutdown()``."""
+def _shutdown_worker(timeout: float | None = DEFAULT_SHUTDOWN_TIMEOUT) -> None:
+    """Drain + close the process worker if one was created (idempotent). Backs ``shutdown()``.
+
+    The ``atexit`` registration binds this function, so the exit path gets the bounded form and
+    its default (SPEC-027 FR-004) — an unbounded join in an ``atexit`` handler is a process that
+    will not exit.
+    """
     if _worker is not None:
-        _worker.shutdown()
+        _worker.shutdown(timeout)
 
 
 def _flush_worker(timeout: float | None = 5.0) -> bool:

log_foundry-0.10.2.dev20/src/log_foundry/sinks/_retry.py

@@ -0,0 +1,103 @@
+"""Shared retry waiting for the sinks (SPEC-027).
+
+Every sink that retries does so by sleeping the one thread that delivers anything. The worker
+owns a single drain thread by design (arch §9), so a sink's backoff is not a local decision — it
+is a global pause on log delivery, and it is held across ``shutdown()``, which joins that thread.
+
+Two rules follow, and this module is where both are applied once rather than at fifteen call
+sites:
+
+* **A wait is interruptible.** Sinks wait on an ``Event`` rather than calling ``time.sleep``, so a
+  shutdown cuts an in-progress backoff short instead of holding the drain thread for its full
+  delay. The worker's own backoff already did this (``worker.py``'s ``_stop.wait``); the sinks had
+  no access to the signal.
+* **A server-supplied delay is advice, not an instruction.** ``Retry-After`` arrives from the
+  destination and went straight to ``time.sleep`` with no ceiling and no sign check: a measured
+  ``Retry-After: 8`` with the default ``max_retries=3`` blocked ``shutdown()`` for 22 seconds, a
+  header of ``86400`` would stall logging for a day, and a negative one makes ``time.sleep``
+  raise — absorbed inside a span, but reaching the caller on the orphan path.
+
+This module imports nothing from its own package (``_diag``'s rule, for the same reason: it sits
+below everything that might want it).
+"""
+
+from __future__ import annotations
+
+import math
+import time
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import threading
+
+__all__ = ["MAX_WAIT", "clamp_server_delay", "wait"]
+
+MAX_WAIT = 86_400.0
+"""Hard ceiling on any single wait, in seconds — a day.
+
+Not a policy, a totality guard. ``time.sleep`` and ``Event.wait`` both raise ``OverflowError``
+past the platform's ``time_t``, so ``wait(1e18)`` — reachable from a large ``max_retry_after``, or
+from ``0.1 * 2**63`` on an absurd ``max_retries`` — would raise on the drain thread, which is the
+one thing this module exists to prevent. Nothing legitimate waits longer than this, and a caller
+who genuinely wants to is better served by not logging.
+"""
+
+
+def wait(delay: float, stop: threading.Event | None = None) -> None:
+    """Wait ``delay`` seconds, returning early if ``stop`` is set (SPEC-027 FR-002).
+
+    Total. A non-positive or non-finite delay returns immediately rather than raising, so a
+    caller that computed one from arithmetic — or from a destination's header — cannot turn a
+    backoff into an exception on the drain thread.
+
+    ``stop`` is the worker's shutdown event when the sink was given one, and ``None`` for a sink
+    used standalone, which then waits exactly as it did before this spec. ``Event.wait`` is used
+    rather than ``time.sleep`` in both cases: with no event there is nothing to wait on, so the
+    ``None`` path falls back to ``time.sleep``.
+
+    A finite delay larger than :data:`MAX_WAIT` is capped rather than passed through: both
+    ``time.sleep`` and ``Event.wait`` raise ``OverflowError`` past the platform's ``time_t``, and
+    "total" has to mean total.
+
+    It does **not** abort an in-flight network call — only the pause between attempts. Cancelling
+    a socket mid-write is not something this library attempts.
+    """
+    if not (delay > 0) or math.isinf(delay):
+        return
+    delay = min(delay, MAX_WAIT)
+    if stop is None:
+        time.sleep(delay)
+        return
+    stop.wait(delay)
+
+
+def clamp_server_delay(value: float | None, ceiling: float) -> float | None:
+    """Bound a server-supplied delay; ``None`` means "fall back to exponential backoff".
+
+    ``None`` in and ``None`` out is the ordinary case: no ``Retry-After``, or one in HTTP-date
+    form that the parser declined. Everything else is validated against what a *delay* can be —
+    finite, positive, and no longer than the caller's ceiling.
+
+    Zero is rejected rather than honoured as "retry now". A destination that is rate-limiting has
+    asked us to slow down, and a header saying "wait zero seconds" is far more likely a broken or
+    truncated value than a real instruction to hammer it; the exponential backoff is the safer
+    reading. ``NaN`` falls out of the same comparison that rejects a negative: every comparison
+    against ``NaN`` is ``False``, which is why the test is written ``not (value > 0)`` rather than
+    ``value <= 0`` — the latter reads ``False`` for ``NaN``, letting it through to ``min()``,
+    which returns it.
+
+    The ceiling is the caller's, not a constant: a platform that legitimately asks for a
+    two-minute pause should be allowed one, and a caller with an execution deadline should be able
+    to lower it below the default.
+    """
+    if value is None or not (value > 0) or math.isinf(value):
+        return None
+    if not (ceiling > 0):
+        # An unusable ceiling is a misconfiguration, not an instruction to stop waiting. Left
+        # unchecked, ``min(value, 0)`` returns ``0.0`` — which is *not* ``None``, so the caller
+        # reads it as an honoured delay and retries with no backoff at all, and ``min(value,
+        # nan)`` returns ``value``, so the ceiling silently vanishes and the header is honoured
+        # in full. Both defeat this function in the direction it exists to prevent. Falling back
+        # to the sink's own backoff is the same answer a missing header gets.
+        return None
+    return min(value, ceiling)

{log_foundry-0.10.2.dev19 → log_foundry-0.10.2.dev20}/src/log_foundry/sinks/_socket.py

@@ -12,9 +12,13 @@ substitute a fake socket without any network access.
 from __future__ import annotations
 
 import socket
-import time
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import threading
 
 from log_foundry import _diag
+from log_foundry.sinks._retry import wait
 from log_foundry.sinks.base import SinkDeliveryError, SinkLosses
 
 __all__ = ["SocketTransport"]
@@ -35,6 +39,11 @@ def _make_udp() -> socket.socket:
 class SocketTransport:
     """Send pre-framed messages over a TCP or UDP socket, reconnecting on error within a bound.
 
+    **Worst-case delay** (SPEC-027 FR-005): ``max_retries`` waits of ``0.1 * 2**n`` *per
+    message* — 0.7 s per message at the default 3, so a 100-message batch against a dead
+    destination is ~70 s of backoff on the single drain thread. The wait is interruptible, so
+    ``shutdown()`` cuts it short.
+
     Attributes:
         failed: Messages abandoned past the reconnect-retry bound.
     """
@@ -59,6 +68,8 @@ class SocketTransport:
         self._max_retries = max(max_retries, 0)
         self._sock: socket.socket | None = None
         self.failed = 0
+        # Set by the worker through the owning sink (SPEC-027 FR-002).
+        self.stop_signal: threading.Event | None = None
 
     def send_all(self, messages: list[bytes]) -> None:
         """Send each pre-framed message, reconnecting on error (FR-005, FR-006).
@@ -102,7 +113,7 @@ class SocketTransport:
             except OSError as err:
                 self._reset()  # force a fresh connection on the next attempt
                 if attempt < self._max_retries:
-                    time.sleep(_BACKOFF_BASE * (2**attempt))
+                    wait(_BACKOFF_BASE * (2**attempt), self.stop_signal)
                     continue
                 self.failed += 1
                 # Guarded now (SPEC-029 FR-003): this runs on the worker thread, and the bare

{log_foundry-0.10.2.dev19 → log_foundry-0.10.2.dev20}/src/log_foundry/sinks/clickhouse.py

@@ -9,11 +9,14 @@ idempotent ``MergeTree`` ``create_table`` convenience is off by default. Write-o
 from __future__ import annotations
 
 import json
-import time
-from typing import Any
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    import threading
 
 from log_foundry import _diag
 from log_foundry.sinks._chunk import chunk_list, valid_identifier
+from log_foundry.sinks._retry import wait
 from log_foundry.sinks.base import SinkDeliveryError, SinkLosses
 
 __all__ = ["ClickHouseSink"]
@@ -41,7 +44,11 @@ _COLUMN_TYPES = {
 
 
 class ClickHouseSink:
-    """A :class:`~log_foundry.sinks.base.Sink` that batch-inserts events into a ClickHouse table."""
+    """A :class:`~log_foundry.sinks.base.Sink` that batch-inserts events into a ClickHouse table.
+
+    **Worst-case delay** (SPEC-027 FR-005): ``max_retries`` waits of ``0.1 * 2**n`` per chunk —
+    0.7 s at the default 3. The waits are interruptible, so ``shutdown()`` cuts one short.
+    """
 
     def __init__(
         self,
@@ -58,6 +65,8 @@ class ClickHouseSink:
         # Floored as ``Worker._emit`` floors its own (SPEC-021): a negative value returned
         # from ``_insert`` having attempted nothing, and reported success.
         self.max_retries = max(max_retries, 0)
+        # Set by the worker when this sink is the configured one (SPEC-027 FR-002).
+        self.stop_signal: threading.Event | None = None
         self.failed = 0
         self._closed = False
         self._owns_client = client is None
@@ -110,7 +119,7 @@ class ClickHouseSink:
                 return 1
             except Exception as err:  # isolation boundary: never crash the worker (FR-006)
                 if attempt < self.max_retries:
-                    time.sleep(_BACKOFF_BASE * (2**attempt))
+                    wait(_BACKOFF_BASE * (2**attempt), self.stop_signal)
                     continue
                 self.failed += len(rows)
                 _diag.lost(

{log_foundry-0.10.2.dev19 → log_foundry-0.10.2.dev20}/src/log_foundry/sinks/eventhubs.py

@@ -10,10 +10,13 @@ send errors are retried within a bound. ``close()`` closes the producer.
 from __future__ import annotations
 
 import json
-import time
-from typing import Any
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    import threading
 
 from log_foundry import _diag
+from log_foundry.sinks._retry import wait
 from log_foundry.sinks.base import SinkDeliveryError, SinkLosses
 
 __all__ = ["AzureEventHubsSink"]
@@ -22,7 +25,11 @@ _BACKOFF_BASE = 0.1
 
 
 class AzureEventHubsSink:
-    """A :class:`~log_foundry.sinks.base.Sink` that sends events to an Azure Event Hub."""
+    """A :class:`~log_foundry.sinks.base.Sink` that sends events to an Azure Event Hub.
+
+    **Worst-case delay** (SPEC-027 FR-005): ``max_retries`` waits of ``0.1 * 2**n`` per EventDataBatch —
+    0.7 s at the default 3. The waits are interruptible, so ``shutdown()`` cuts one short.
+    """
 
     def __init__(
         self,
@@ -48,6 +55,8 @@ class AzureEventHubsSink:
         # Floored as ``Worker._emit`` floors its own (SPEC-021): a negative value returned
         # from ``_send`` having attempted nothing, and reported success.
         self.max_retries = max(max_retries, 0)
+        # Set by the worker when this sink is the configured one (SPEC-027 FR-002).
+        self.stop_signal: threading.Event | None = None
         self.failed = 0
         self.dropped_oversized = 0
 
@@ -112,7 +121,7 @@ class AzureEventHubsSink:
                 return 1
             except Exception as err:  # isolation boundary: never crash the worker (FR-011)
                 if attempt < self.max_retries:
-                    time.sleep(_BACKOFF_BASE * (2**attempt))
+                    wait(_BACKOFF_BASE * (2**attempt), self.stop_signal)
                     continue
                 self.failed += len(event_batch)
                 _diag.lost(

{log_foundry-0.10.2.dev19 → log_foundry-0.10.2.dev20}/src/log_foundry/sinks/filtering.py

@@ -10,9 +10,11 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
+from log_foundry import _diag
 from log_foundry.sinks.base import read_losses
 
 if TYPE_CHECKING:
+    import threading
     from collections.abc import Callable
 
     from log_foundry.sinks.base import Sink, SinkLosses
@@ -43,6 +45,7 @@ class FilteringSink:
         min_level: str | None = None,
     ) -> None:
         self._inner = inner
+        self._stop_signal: threading.Event | None = None
         self._predicate = predicate
         self._min_rank: int | None = None
         if min_level is not None:
@@ -71,6 +74,29 @@ class FilteringSink:
                 return False
         return True
 
+    @property
+    def stop_signal(self) -> threading.Event | None:
+        """The worker's shutdown event, forwarded to whatever actually holds the retry loop.
+
+        The worker sets this on the *configured* sink (SPEC-027 FR-002), and a wrapper is not
+        where the waiting happens. Without the forward the attribute is set on an object that
+        never waits, and the backoff one level down stays uninterruptible — which is the whole
+        defect, moved rather than fixed.
+        """
+        return self._stop_signal
+
+    @stop_signal.setter
+    def stop_signal(self, signal: threading.Event | None) -> None:
+        self._stop_signal = signal
+        try:
+            self._inner.stop_signal = signal  # type: ignore[attr-defined]
+        except Exception as err:
+            _diag.absorbed(
+                "handing the inner sink its stop signal",
+                err,
+                f"{type(self._inner).__name__} stays uninterruptible",
+            )
+
     def losses(self) -> SinkLosses | None:
         """Report the inner sink's losses (SPEC-026 FR-002). Never raises.
 

{log_foundry-0.10.2.dev19 → log_foundry-0.10.2.dev20}/src/log_foundry/sinks/firehose.py

@@ -9,19 +9,28 @@ retried within a bounded count.
 from __future__ import annotations
 
 import json
-from typing import Any
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    import threading
 
 from log_foundry import _diag
 from log_foundry.sinks._batch import adjudicate_positional, usable_results
 from log_foundry.sinks._chunk import chunk_items
+from log_foundry.sinks._retry import wait
 from log_foundry.sinks.base import SinkDeliveryError, SinkLosses
 
 __all__ = ["FirehoseSink"]
 
+_BACKOFF_BASE = 0.1  # seconds; delay before retry attempt n is _BACKOFF_BASE * 2**n
+
 
 class FirehoseSink:
     """A :class:`~log_foundry.sinks.base.Sink` that writes events to a Firehose delivery stream.
 
+    **Worst-case delay** (SPEC-027 FR-005): ``max_retries`` waits of ``0.1 * 2**n`` per chunk —
+    0.7 s at the default 3. The waits are interruptible, so ``shutdown()`` cuts one short.
+
     Three counters report what was not delivered: ``failed`` (the delivery stream told us these
     failed, and they still failed after ``max_retries``), ``dropped_oversized`` (too large for the
     per-record limit to ever accept), and ``dropped_unadjudicated`` (a ``put_record_batch`` response
@@ -45,6 +54,8 @@ class FirehoseSink:
         # Floored as ``Worker._emit`` floors its own (SPEC-021): a negative value returned
         # from ``_send`` having sent nothing, and reported success.
         self.max_retries = max(max_retries, 0)
+        # Set by the worker when this sink is the configured one (SPEC-027 FR-002).
+        self.stop_signal: threading.Event | None = None
         self.failed = 0
         self.dropped_oversized = 0
         self.dropped_unadjudicated = 0
@@ -153,6 +164,11 @@ class FirehoseSink:
             records = verdict.retry
             if not records:
                 return sent
+            if attempt < self.max_retries:
+                # Before the next attempt, never before abandoning (SPEC-027 FR-003). This loop
+                # re-sends the entries the destination flagged, and the canonical reason it
+                # flags them is throttling — which an immediate re-send makes worse.
+                wait(_BACKOFF_BASE * (2**attempt), self.stop_signal)
             if attempt >= self.max_retries:
                 self.failed += len(records)
                 _diag.lost(

{log_foundry-0.10.2.dev19 → log_foundry-0.10.2.dev20}/src/log_foundry/sinks/http.py

@@ -15,22 +15,32 @@ from __future__ import annotations
 
 import gzip as _gzip
 import json
-import time
 import urllib.error
 import urllib.request
 from base64 import b64encode
 from typing import TYPE_CHECKING, Any, NoReturn
 
 from log_foundry import _diag
+from log_foundry.sinks._retry import clamp_server_delay, wait
 from log_foundry.sinks.base import SinkDeliveryError, SinkLosses
 
 if TYPE_CHECKING:
+    import threading
     from collections.abc import Callable
 
 __all__ = ["HTTPSink", "merge_headers"]
 
 _BACKOFF_BASE = 0.1  # seconds; delay for retry attempt n is _BACKOFF_BASE * 2**n
 
+DEFAULT_MAX_RETRY_AFTER = 30.0
+"""Ceiling on a server-supplied ``Retry-After``, in seconds (SPEC-027 FR-001).
+
+Thirty rather than something smaller because a rate-limited platform asking for half a minute is
+making a reasonable request, and rather than something larger because the *total* is what a caller
+with an execution deadline pays: with the default ``max_retries=3`` the worst case is three waits,
+90 s, which stays inside a typical serverless timeout while leaving room for the request itself.
+"""
+
 
 def merge_headers(base: dict[str, str], http_kwargs: dict[str, object]) -> dict[str, str]:
     """Merge a platform sink's own headers with any caller-supplied ``headers`` (caller wins).
@@ -52,6 +62,12 @@ class HTTPSink:
     requires ``https://`` — over a plaintext endpoint a bearer token, and a basic-auth pair (which
     is base64, not encryption), travel in the clear. Use ``https://`` for anything off the host.
 
+    **Worst-case delay** (SPEC-027 FR-005): ``max_retries`` waits, each at most
+    ``max_retry_after`` when the server sends a ``Retry-After`` and ``0.1 * 2**n`` otherwise —
+    so 90 s at the defaults (3 × 30 s), plus the request timeouts themselves. That delay pauses
+    the single drain thread, so it is a pause on *all* log delivery, not just this sink's.
+    ``shutdown()``'s own timeout bounds the total (SPEC-027 FR-004).
+
     Attributes:
         failed: Requests abandoned past the retry bound.
         dropped_oversized: Events dropped for exceeding a destination's hard size limit (used by
@@ -69,6 +85,7 @@ class HTTPSink:
         timeout: float = 5.0,
         gzip: bool = False,
         max_retries: int = 3,
+        max_retry_after: float = DEFAULT_MAX_RETRY_AFTER,
         opener: Callable[..., Any] | None = None,
     ) -> None:
         self.url = url
@@ -82,6 +99,13 @@ class HTTPSink:
         # skipped the loop entirely, so the request was abandoned with no attempt made and no
         # counter moved — reachable only by misconfiguration, but reachable.
         self.max_retries = max(max_retries, 0)
+        # Not floored or rejected here: ``clamp_server_delay`` refuses an unusable ceiling and
+        # falls back to exponential backoff, which keeps the validation in one place (SPEC-027
+        # FR-001). Stored as given so a caller can read back what they passed.
+        self.max_retry_after = max_retry_after
+        # Set by the worker when this sink is the configured one (SPEC-027 FR-002); ``None``
+        # standalone, which backs off uninterruptibly exactly as before.
+        self.stop_signal: threading.Event | None = None
         self._opener = opener if opener is not None else urllib.request.urlopen
         self.failed = 0
         self.dropped_oversized = 0
@@ -219,9 +243,18 @@ class HTTPSink:
         return int(status), payload, _parse_retry_after(getattr(response, "headers", None))
 
     def _sleep_backoff(self, attempt: int, retry_after: float | None) -> None:
-        """Sleep before the next attempt: ``Retry-After`` if the server gave one, else backoff."""
-        delay = retry_after if retry_after is not None else _BACKOFF_BASE * (2**attempt)
-        time.sleep(delay)
+        """Wait before the next attempt: ``Retry-After`` if usable, else exponential backoff.
+
+        The server's value is clamped and sign-checked first (SPEC-027 FR-001) — it is advice
+        from the destination, not an instruction the application must obey. Unbounded, a measured
+        ``Retry-After: 8`` held ``shutdown()`` for 22 s and a header of ``86400`` would have held
+        it for a day; a negative one made ``time.sleep`` raise, which the orphan path handed to
+        the caller. Anything rejected falls back to this sink's own backoff, which is what the
+        destination would have got had it sent no header at all.
+        """
+        server = clamp_server_delay(retry_after, self.max_retry_after)
+        delay = server if server is not None else _BACKOFF_BASE * (2**attempt)
+        wait(delay, self.stop_signal)
 
     def _abandon(self, reason: str) -> NoReturn:
         """Count, log, then raise for a request abandoned past the retry bound (FR-012).

{log_foundry-0.10.2.dev19 → log_foundry-0.10.2.dev20}/src/log_foundry/sinks/kinesis.py

@@ -10,19 +10,28 @@ unless a sink is built without an injected client. Each incoming batch is re-chu
 from __future__ import annotations
 
 import json
-from typing import Any
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    import threading
 
 from log_foundry import _diag
 from log_foundry.sinks._batch import adjudicate_positional, usable_results
 from log_foundry.sinks._chunk import chunk_items
+from log_foundry.sinks._retry import wait
 from log_foundry.sinks.base import SinkDeliveryError, SinkLosses
 
 __all__ = ["KinesisSink"]
 
+_BACKOFF_BASE = 0.1  # seconds; delay before retry attempt n is _BACKOFF_BASE * 2**n
+
 
 class KinesisSink:
     """A :class:`~log_foundry.sinks.base.Sink` that writes events to a Kinesis Data Stream.
 
+    **Worst-case delay** (SPEC-027 FR-005): ``max_retries`` waits of ``0.1 * 2**n`` per chunk —
+    0.7 s at the default 3. The waits are interruptible, so ``shutdown()`` cuts one short.
+
     Three counters report what was not delivered: ``failed`` (the stream told us these failed, and
     they still failed after ``max_retries``), ``dropped_oversized`` (too large for the per-record
     limit to ever accept), and ``dropped_unadjudicated`` (a ``put_records`` response whose results
@@ -53,6 +62,8 @@ class KinesisSink:
         # Floored as ``Worker._emit`` floors its own (SPEC-021): a negative value returned
         # from ``_send`` having sent nothing, and reported success.
         self.max_retries = max(max_retries, 0)
+        # Set by the worker when this sink is the configured one (SPEC-027 FR-002).
+        self.stop_signal: threading.Event | None = None
         self.failed = 0
         self.dropped_oversized = 0
         self.dropped_unadjudicated = 0
@@ -158,6 +169,11 @@ class KinesisSink:
             records = verdict.retry
             if not records:
                 return sent
+            if attempt < self.max_retries:
+                # Before the next attempt, never before abandoning (SPEC-027 FR-003). This loop
+                # re-sends the entries the destination flagged, and the canonical reason it
+                # flags them is throttling — which an immediate re-send makes worse.
+                wait(_BACKOFF_BASE * (2**attempt), self.stop_signal)
             if attempt >= self.max_retries:
                 self.failed += len(records)
                 _diag.lost(

{log_foundry-0.10.2.dev19 → log_foundry-0.10.2.dev20}/src/log_foundry/sinks/logstash.py

@@ -12,6 +12,10 @@ Either backend handles its own bounded retry; ``close()`` releases whichever it
 from __future__ import annotations
 
 import json
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import threading
 
 from log_foundry.sinks._socket import SocketTransport
 from log_foundry.sinks.base import SinkLosses
@@ -47,6 +51,7 @@ class LogstashSink:
             )
         else:
             raise ValueError("LogstashSink requires either url= (HTTP) or host= + port= (socket)")
+        self._stop_signal: threading.Event | None = None
 
     def emit(self, batch: list[dict[str, object]]) -> None:
         """Send the batch over the configured backend (FR-005)."""
@@ -68,6 +73,25 @@ class LogstashSink:
         elif self._socket is not None:
             self._socket.close()
 
+    @property
+    def stop_signal(self) -> threading.Event | None:
+        """The worker's shutdown event, forwarded to whatever actually holds the retry loop.
+
+        The worker sets this on the *configured* sink (SPEC-027 FR-002), and a wrapper is not
+        where the waiting happens. Without the forward the attribute is set on an object that
+        never waits, and the backoff one level down stays uninterruptible — which is the whole
+        defect, moved rather than fixed.
+        """
+        return self._stop_signal
+
+    @stop_signal.setter
+    def stop_signal(self, signal: threading.Event | None) -> None:
+        self._stop_signal = signal
+        if self._http is not None:
+            self._http.stop_signal = signal
+        elif self._socket is not None:
+            self._socket.stop_signal = signal
+
     @property
     def failed(self) -> int:
         """Requests/messages abandoned past the retry bound, from the active backend."""