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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: log-foundry
-Version: 0.10.2.dev18
+Version: 0.10.2.dev20
 Summary: Generate logs for your console and JSON events for downstream consumption.
 License-Expression: MIT
 License-File: LICENSE
@@ -438,12 +438,16 @@ A few conventions hold across every sink below:
   The tables show the destination-defining arguments only; sinks that retry also take `max_retries`.
 - **Ownership.** A resource the sink opens itself is closed on `shutdown()`; an injected one is left
   open for you to manage.
-- **Never crashes the app.** A failing sink is retried with backoff and then counted (`.failed`,
-  `.dropped_oversized`, `.dropped_unadjudicated`, …) rather than raised — a broken destination
-  degrades logging, nothing more.
-  The one deliberate exception is a `MultiSink` whose children *all* failed: it re-raises so the
-  worker's retry engages, since nothing was delivered and there are no duplicates to risk. That
-  still doesn't reach your code — the worker is what catches it.
+- **Never crashes the app.** A broken destination degrades logging and nothing more. A sink that
+  delivered *part* of a batch counts what it lost (`.failed`, `.dropped_oversized`,
+  `.dropped_unadjudicated`, …) and returns, since retrying would re-deliver what already landed.
+  A sink that delivered **none** of it raises instead, so the worker's bounded retry engages and
+  `health().failed_batches` records the loss — there is nothing downstream to duplicate. Three
+  cases are excepted, each because a retry would be wrong rather than merely futile: an oversized
+  event (it can never fit), a response the sink could not adjudicate (it cannot prove nothing
+  landed), and an SQS sender fault (a byte-identical re-send can only fail again). Either way the
+  exception never reaches your code — inside a span the worker catches it, and on the orphan path
+  (`log_foundry.info(...)` outside any span, which emits synchronously) the emitter does.
 
 #### Built-in, zero-dependency
 
@@ -466,7 +470,7 @@ to a plain callable.
 
 | Sink | Import from | Configure |
 |---|---|---|
-| `MultiSink` | `log_foundry.sinks.multi` | `MultiSink(*sinks)` — forward each batch to every child; a failing child is isolated and counted on `.failed` |
+| `MultiSink` | `log_foundry.sinks.multi` | `MultiSink(*sinks)` — forward each batch to every child; a failing child is isolated and counted on `.failed`, unless *every* child failed, which re-raises |
 | `FilteringSink` | `log_foundry.sinks.filtering` | `FilteringSink(inner, *, predicate=None, min_level=None)` — forward only events passing `predicate` and/or at/above `min_level` |
 | `TransformSink` | `log_foundry.sinks.transform` | `TransformSink(inner, fn)` — map each event through `fn` before forwarding; return `None` to drop one |
 | `CallbackSink` | `log_foundry.sinks.callback` | `CallbackSink(fn, *, on_close=None)` — hand each batch to any callable |
@@ -659,8 +663,56 @@ Write-only inserts (querying is the downstream tool's job); each needs its own e
 `PostgresSink` / `ClickHouseSink` default `create_table=False` (you own the schema and indexes); set
 it `True` for an idempotent `CREATE TABLE IF NOT EXISTS` convenience.
 
-Prefer a destination not listed here? Implement the two-method `Sink` protocol yourself, or wrap any
-callable in `CallbackSink`.
+Prefer a destination not listed here? Implement the `Sink` protocol yourself, or wrap any callable
+in `CallbackSink`.
+
+#### Writing your own sink
+
+`Sink` is two required methods, `emit(batch)` and `close()`, plus two rules about *how* `emit`
+fails. They are not stylistic — the library's whole loss-reporting apparatus is built on them:
+
+- **Raise when you delivered none of the batch**, after your own retries are spent. That is the
+  signal the worker's bounded retry and `health().failed_batches` depend on, and the one case where
+  a retry cannot duplicate anything: nothing landed downstream. Raise `SinkDeliveryError` (from
+  `log_foundry.sinks.base`) or any exception of your own — the contract is that *something*
+  propagates.
+- **Do not raise when you delivered some of it.** The worker retries whole batches, so raising on a
+  partial success re-delivers the records that already arrived, and duplicates downstream are worse
+  than a counted loss.
+
+A sink that absorbs a total failure and returns normally is a sink the worker believes: the retry
+never engages, `failed_batches` stays at zero, and `flush()` returns `True` while every event is
+lost.
+
+Optionally add `losses()` to report what you absorbed. It must never raise and must be safe to call
+while `emit` is running (`health()` is a poll):
+
+```python
+from log_foundry.sinks.base import SinkDeliveryError, SinkLosses
+
+class MySink:
+    def __init__(self) -> None:
+        self._dropped = self._failed = 0
+
+    def emit(self, batch: list[dict[str, object]]) -> None:
+        delivered = 0
+        for chunk in self._chunks(batch):
+            if self._send(chunk):          # your own bounded retry
+                delivered += len(chunk)
+            else:
+                self._failed += len(chunk)
+        if batch and not delivered:
+            raise SinkDeliveryError(f"MySink delivered none of {len(batch)} event(s)")
+
+    def losses(self) -> SinkLosses:
+        return SinkLosses(dropped=self._dropped, failed=self._failed)
+
+    def close(self) -> None: ...
+```
+
+`losses()` is optional and probed by name, so a sink written before it existed keeps working and
+simply contributes nothing to `health().sink`. `emit([])` must be a no-op: an empty batch has not
+failed to deliver.
 
 ### Flushing and shutdown
 
@@ -676,17 +728,33 @@ returns a snapshot of the worker's counters:
 
 ```python
 h = log_foundry.health()
-if h.dropped or h.failed_batches or h.stopped_reason:
+if h.dropped or h.failed_batches or h.stopped_reason or (h.sink and (h.sink.dropped or h.sink.failed)):
     ...  # logs were silently lost — worth an alert
 ```
 
-The three tell you different things, and they want different responses:
+They tell you different things, and they want different responses:
 
 | Field | Means | What to do |
 |---|---|---|
 | `dropped` | The queue filled — the destination is not keeping up. Delivery continues. | Tune `batch_size`/`flush_interval`, or scale the sink. |
 | `failed_batches` | A sink stayed broken through the whole retry budget. Delivery continues. | Fix the destination. |
 | `stopped_reason` | The background thread **died** on that exception type. Nothing further will be delivered, ever. | Restart the process; investigate the named exception. |
+| `sink.dropped` | The sink discarded events **before** attempting delivery — an oversized record, or one the client refused outright. | Read the stderr line: it names the cause. An oversized record means shrink what you log; a refused local produce/publish (Kafka, Pub/Sub) points at the client — a saturated buffer, a bad topic, a credential. |
+| `sink.failed` | The sink attempted delivery and could not confirm it — abandoned requests, partially-failed batches, responses it could not adjudicate. | Fix the destination. |
+
+`h.sink` is a `SinkLosses(dropped, failed)` or `None` — `None` when no worker exists yet, or when
+the configured sink reports nothing (`losses()` is optional). Note the two `dropped` fields count
+different things: the worker's is backpressure at *its* queue, the sink's is an event that never
+reached the wire. They are separate because the remedies do not overlap — and `sink.dropped` is
+itself two causes, which is why the diagnostic line matters. Most sinks drop only what can never
+fit; `KafkaSink` and `GooglePubSubSink` also count what their client refused outright, which may
+be backpressure one layer further out than the worker's, or may be a misconfiguration. The stderr
+line carries the exception type that distinguishes them.
+
+`sink.failed` is an **upper bound** on loss, not a count of it. A sink that raises on total failure
+counts the attempt *and* hands the batch back to the worker, whose retry may then deliver it — so a
+transient outage leaves it non-zero with nothing actually lost. `failed_batches` is the record of a
+batch given up on for good.
 
 `stopped_reason` is a type name (e.g. `"SystemExit"`), never the exception's message — a sink's
 error text can carry event data. It reads `None` for a healthy worker, for a process that has never
@@ -694,9 +762,10 @@ logged, and after a clean `shutdown()`, so a plain truthiness check is safe. Wit
 thread showed up only indirectly, as `dropped` climbing once the queue filled — the wrong signal,
 pointing at the wrong fix.
 
-Read a snapshot by attribute (`h.dropped`), as above. `Health` is a `NamedTuple` and gained a
-fourth field in `v0.7.0`, so unpacking it whole — `queued, dropped, failed = health()` — raises
-`ValueError` from that version on.
+Read a snapshot by attribute (`h.dropped`), as above. `Health` is a `NamedTuple` and has gained
+fields over time — a fourth (`stopped_reason`) in `v0.7.0` and a fifth (`sink`) not yet in a tagged
+release — so unpacking it whole (`queued, dropped, failed = health()`) raises `ValueError`. Every
+field keeps its position when a new one is appended, so attribute and index access stay stable.
 
 `dropped` counts submissions discarded because the queue filled; `failed_batches` counts batches
 abandoned after the retry budget was spent. Overflow also warns on stderr — on the first drop and
@@ -711,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.dev18 → log_foundry-0.10.2.dev20}/README.md

@@ -402,12 +402,16 @@ A few conventions hold across every sink below:
   The tables show the destination-defining arguments only; sinks that retry also take `max_retries`.
 - **Ownership.** A resource the sink opens itself is closed on `shutdown()`; an injected one is left
   open for you to manage.
-- **Never crashes the app.** A failing sink is retried with backoff and then counted (`.failed`,
-  `.dropped_oversized`, `.dropped_unadjudicated`, …) rather than raised — a broken destination
-  degrades logging, nothing more.
-  The one deliberate exception is a `MultiSink` whose children *all* failed: it re-raises so the
-  worker's retry engages, since nothing was delivered and there are no duplicates to risk. That
-  still doesn't reach your code — the worker is what catches it.
+- **Never crashes the app.** A broken destination degrades logging and nothing more. A sink that
+  delivered *part* of a batch counts what it lost (`.failed`, `.dropped_oversized`,
+  `.dropped_unadjudicated`, …) and returns, since retrying would re-deliver what already landed.
+  A sink that delivered **none** of it raises instead, so the worker's bounded retry engages and
+  `health().failed_batches` records the loss — there is nothing downstream to duplicate. Three
+  cases are excepted, each because a retry would be wrong rather than merely futile: an oversized
+  event (it can never fit), a response the sink could not adjudicate (it cannot prove nothing
+  landed), and an SQS sender fault (a byte-identical re-send can only fail again). Either way the
+  exception never reaches your code — inside a span the worker catches it, and on the orphan path
+  (`log_foundry.info(...)` outside any span, which emits synchronously) the emitter does.
 
 #### Built-in, zero-dependency
 
@@ -430,7 +434,7 @@ to a plain callable.
 
 | Sink | Import from | Configure |
 |---|---|---|
-| `MultiSink` | `log_foundry.sinks.multi` | `MultiSink(*sinks)` — forward each batch to every child; a failing child is isolated and counted on `.failed` |
+| `MultiSink` | `log_foundry.sinks.multi` | `MultiSink(*sinks)` — forward each batch to every child; a failing child is isolated and counted on `.failed`, unless *every* child failed, which re-raises |
 | `FilteringSink` | `log_foundry.sinks.filtering` | `FilteringSink(inner, *, predicate=None, min_level=None)` — forward only events passing `predicate` and/or at/above `min_level` |
 | `TransformSink` | `log_foundry.sinks.transform` | `TransformSink(inner, fn)` — map each event through `fn` before forwarding; return `None` to drop one |
 | `CallbackSink` | `log_foundry.sinks.callback` | `CallbackSink(fn, *, on_close=None)` — hand each batch to any callable |
@@ -623,8 +627,56 @@ Write-only inserts (querying is the downstream tool's job); each needs its own e
 `PostgresSink` / `ClickHouseSink` default `create_table=False` (you own the schema and indexes); set
 it `True` for an idempotent `CREATE TABLE IF NOT EXISTS` convenience.
 
-Prefer a destination not listed here? Implement the two-method `Sink` protocol yourself, or wrap any
-callable in `CallbackSink`.
+Prefer a destination not listed here? Implement the `Sink` protocol yourself, or wrap any callable
+in `CallbackSink`.
+
+#### Writing your own sink
+
+`Sink` is two required methods, `emit(batch)` and `close()`, plus two rules about *how* `emit`
+fails. They are not stylistic — the library's whole loss-reporting apparatus is built on them:
+
+- **Raise when you delivered none of the batch**, after your own retries are spent. That is the
+  signal the worker's bounded retry and `health().failed_batches` depend on, and the one case where
+  a retry cannot duplicate anything: nothing landed downstream. Raise `SinkDeliveryError` (from
+  `log_foundry.sinks.base`) or any exception of your own — the contract is that *something*
+  propagates.
+- **Do not raise when you delivered some of it.** The worker retries whole batches, so raising on a
+  partial success re-delivers the records that already arrived, and duplicates downstream are worse
+  than a counted loss.
+
+A sink that absorbs a total failure and returns normally is a sink the worker believes: the retry
+never engages, `failed_batches` stays at zero, and `flush()` returns `True` while every event is
+lost.
+
+Optionally add `losses()` to report what you absorbed. It must never raise and must be safe to call
+while `emit` is running (`health()` is a poll):
+
+```python
+from log_foundry.sinks.base import SinkDeliveryError, SinkLosses
+
+class MySink:
+    def __init__(self) -> None:
+        self._dropped = self._failed = 0
+
+    def emit(self, batch: list[dict[str, object]]) -> None:
+        delivered = 0
+        for chunk in self._chunks(batch):
+            if self._send(chunk):          # your own bounded retry
+                delivered += len(chunk)
+            else:
+                self._failed += len(chunk)
+        if batch and not delivered:
+            raise SinkDeliveryError(f"MySink delivered none of {len(batch)} event(s)")
+
+    def losses(self) -> SinkLosses:
+        return SinkLosses(dropped=self._dropped, failed=self._failed)
+
+    def close(self) -> None: ...
+```
+
+`losses()` is optional and probed by name, so a sink written before it existed keeps working and
+simply contributes nothing to `health().sink`. `emit([])` must be a no-op: an empty batch has not
+failed to deliver.
 
 ### Flushing and shutdown
 
@@ -640,17 +692,33 @@ returns a snapshot of the worker's counters:
 
 ```python
 h = log_foundry.health()
-if h.dropped or h.failed_batches or h.stopped_reason:
+if h.dropped or h.failed_batches or h.stopped_reason or (h.sink and (h.sink.dropped or h.sink.failed)):
     ...  # logs were silently lost — worth an alert
 ```
 
-The three tell you different things, and they want different responses:
+They tell you different things, and they want different responses:
 
 | Field | Means | What to do |
 |---|---|---|
 | `dropped` | The queue filled — the destination is not keeping up. Delivery continues. | Tune `batch_size`/`flush_interval`, or scale the sink. |
 | `failed_batches` | A sink stayed broken through the whole retry budget. Delivery continues. | Fix the destination. |
 | `stopped_reason` | The background thread **died** on that exception type. Nothing further will be delivered, ever. | Restart the process; investigate the named exception. |
+| `sink.dropped` | The sink discarded events **before** attempting delivery — an oversized record, or one the client refused outright. | Read the stderr line: it names the cause. An oversized record means shrink what you log; a refused local produce/publish (Kafka, Pub/Sub) points at the client — a saturated buffer, a bad topic, a credential. |
+| `sink.failed` | The sink attempted delivery and could not confirm it — abandoned requests, partially-failed batches, responses it could not adjudicate. | Fix the destination. |
+
+`h.sink` is a `SinkLosses(dropped, failed)` or `None` — `None` when no worker exists yet, or when
+the configured sink reports nothing (`losses()` is optional). Note the two `dropped` fields count
+different things: the worker's is backpressure at *its* queue, the sink's is an event that never
+reached the wire. They are separate because the remedies do not overlap — and `sink.dropped` is
+itself two causes, which is why the diagnostic line matters. Most sinks drop only what can never
+fit; `KafkaSink` and `GooglePubSubSink` also count what their client refused outright, which may
+be backpressure one layer further out than the worker's, or may be a misconfiguration. The stderr
+line carries the exception type that distinguishes them.
+
+`sink.failed` is an **upper bound** on loss, not a count of it. A sink that raises on total failure
+counts the attempt *and* hands the batch back to the worker, whose retry may then deliver it — so a
+transient outage leaves it non-zero with nothing actually lost. `failed_batches` is the record of a
+batch given up on for good.
 
 `stopped_reason` is a type name (e.g. `"SystemExit"`), never the exception's message — a sink's
 error text can carry event data. It reads `None` for a healthy worker, for a process that has never
@@ -658,9 +726,10 @@ logged, and after a clean `shutdown()`, so a plain truthiness check is safe. Wit
 thread showed up only indirectly, as `dropped` climbing once the queue filled — the wrong signal,
 pointing at the wrong fix.
 
-Read a snapshot by attribute (`h.dropped`), as above. `Health` is a `NamedTuple` and gained a
-fourth field in `v0.7.0`, so unpacking it whole — `queued, dropped, failed = health()` — raises
-`ValueError` from that version on.
+Read a snapshot by attribute (`h.dropped`), as above. `Health` is a `NamedTuple` and has gained
+fields over time — a fourth (`stopped_reason`) in `v0.7.0` and a fifth (`sink`) not yet in a tagged
+release — so unpacking it whole (`queued, dropped, failed = health()`) raises `ValueError`. Every
+field keeps its position when a new one is appended, so attribute and index access stay stable.
 
 `dropped` counts submissions discarded because the queue filled; `failed_batches` counts batches
 abandoned after the retry budget was spent. Overflow also warns on stderr — on the first drop and
@@ -675,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.dev18 → 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.dev18"
+version = "0.10.2.dev20"
 
 [project.optional-dependencies]
 aws = ["boto3>=1.43.61"]              # SQSSink, SNSSink, KinesisSink, FirehoseSink

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

@@ -20,7 +20,8 @@ from log_foundry.context import (
     reset_context,
 )
 from log_foundry.decorator import continue_trace, trace
-from log_foundry.worker import Health
+from log_foundry.sinks.base import SinkDeliveryError, SinkLosses
+from log_foundry.worker import DEFAULT_SHUTDOWN_TIMEOUT, Health
 
 try:
     # Distribution name ("log-foundry") differs from the import name ("log_foundry").
@@ -59,17 +60,29 @@ def flush(timeout: float | None = 5.0) -> bool:
 def health() -> Health:
     """Snapshot the background worker's delivery counters (SPEC-017 FR-005). Never raises.
 
-    Returns ``queued`` / ``dropped`` / ``failed_batches`` / ``stopped_reason``. A non-zero
-    ``dropped`` means the queue filled and submissions were discarded to keep your code
+    Returns ``queued`` / ``dropped`` / ``failed_batches`` / ``stopped_reason`` / ``sink``. A
+    non-zero ``dropped`` means the queue filled and submissions were discarded to keep your code
     non-blocking; a non-zero ``failed_batches`` means a sink stayed broken through the whole
     retry budget. Both are losses the library absorbs on purpose, and this is how you notice
     them. A non-``None`` ``stopped_reason`` is worse than either: the background thread died
     on that exception type, so nothing further will be delivered at all (SPEC-019)::
 
         h = log_foundry.health()
-        if h.dropped or h.failed_batches or h.stopped_reason:
+        if h.dropped or h.failed_batches or h.stopped_reason or (
+            h.sink and (h.sink.dropped or h.sink.failed)
+        ):
             ...  # raise an alert; logs were silently lost
 
+    ``sink`` is the configured sink's own :class:`~log_foundry.sinks.base.SinkLosses` — loss the
+    *sink* absorbed rather than the worker, which the worker's counters cannot see (SPEC-026).
+    It is ``None`` when no worker exists and when the sink reports nothing, since ``losses()`` is
+    optional. Its ``dropped`` is not the worker's: the worker's is backpressure at the queue, the
+    sink's is an event that never reached the wire — usually one too large to ever fit, and for the
+    sinks whose client owns a local buffer (Kafka, Pub/Sub) also what that buffer refused. The
+    stderr line names which. Its ``failed`` is an upper bound on loss, not a count of it: a sink
+    that raises on total failure counts the attempt *and* hands the batch back, and the worker's
+    retry may then deliver it.
+
     A process that has never logged has no worker, and asking after its health does not create
     one — the snapshot is simply zeroed. Valid after :func:`shutdown`, which leaves the final
     counters readable.
@@ -79,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
@@ -88,14 +101,24 @@ 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",
     "__version__",
     "configure",
     "continue_trace",

{log_foundry-0.10.2.dev18 → 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.dev18 → 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.dev18 → log_foundry-0.10.2.dev20}/src/log_foundry/sinks/base.py

@@ -41,10 +41,12 @@ class SinkDeliveryError(Exception):
 class SinkLosses(NamedTuple):
     """What a sink discarded or could not confirm, cumulative for its lifetime (SPEC-026 FR-002).
 
-    Two fields rather than one because the remedies differ: ``dropped`` means the destination
-    could never have accepted the event as built (an oversized record), so the fix is upstream in
-    what the application logs; ``failed`` means delivery was attempted and the destination did not
-    confirm it, so the fix is the destination or the network.
+    Two fields rather than one because the remedies differ. ``dropped`` is an event the sink
+    discarded *before* attempting delivery — usually one the destination could never have accepted
+    as built (an oversized record), so the fix is upstream in what the application logs; for a sink
+    whose client owns a local buffer it also covers what that buffer refused, which is
+    backpressure. The stderr line names which. ``failed`` means delivery was attempted and the
+    destination did not confirm it, so the fix is the destination or the network.
 
     ``failed`` is an **upper bound** on loss, not a count of it. A sink that also raises on total
     failure counts the attempt here *and* hands the batch back to the worker, whose retry may