log-foundry 0.10.2.dev103__tar.gz → 0.10.2.dev105__tar.gz

{log_foundry-0.10.2.dev103 → log_foundry-0.10.2.dev105}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: log-foundry
-Version: 0.10.2.dev103
+Version: 0.10.2.dev105
 Summary: Generate logs for your console and JSON events for downstream consumption.
 License-Expression: MIT
 License-File: LICENSE

{log_foundry-0.10.2.dev103 → log_foundry-0.10.2.dev105}/pyproject.toml

@@ -74,7 +74,7 @@ keywords = [
 # vulnerability-reporting channel. The repository is still named `log-forge` — the ORIGINAL name,
 # which PyPI rejected for the distribution — so these URLs deliberately do not match the package
 # name. See the note on `name` above before "correcting" them.
-version = "0.10.2.dev103"
+version = "0.10.2.dev105"
 
 [project.urls]
 Homepage = "https://github.com/agriffi10/log-forge"

{log_foundry-0.10.2.dev103 → log_foundry-0.10.2.dev105}/src/log_foundry/sinks/file.py

@@ -8,6 +8,7 @@ import threading
 import time
 from typing import TextIO
 
+from log_foundry import _diag
 from log_foundry.sinks.base import SinkDeliveryError
 
 __all__ = ["FileSink", "RotatingFileSink"]
@@ -267,6 +268,7 @@ class RotatingFileSink:
         self._stream: TextIO = open(path, "a", encoding=self._encoding)
         self._size = os.path.getsize(path) if os.path.exists(path) else 0
         self._next_rollover = self._schedule_next()
+        self._rotation_failing = False
         self._closed = False
         self._lock = threading.Lock()
 
@@ -278,6 +280,15 @@ class RotatingFileSink:
         ``_should_rotate`` check and the write that follows it must see the same stream, or a
         rotation between them sends the line to a closed handle.
 
+        **The batch is flushed before a rotation is attempted** (SPEC-048 FR-006). ``_rotate``
+        begins by closing the stream, which flushes it, while this loop otherwise flushes once at
+        the end — so under the canonical rotation failure, a full or read-only filesystem, it is
+        that flush that raises and the batch's buffered lines are gone before any rename is tried.
+        Flushing here means every event of the batch is on disk before the rotation can fail, at
+        every one of ``_rotate``'s raise sites rather than only at the renames. A flush that
+        raises *here* is deliberately not absorbed: nothing was written, so it is the
+        genuinely-total failure the worker's retry exists for.
+
         Args:
           batch: The events to write.
 
@@ -285,7 +296,9 @@ class RotatingFileSink:
           None.
 
         Raises:
-          OSError: If a write, flush or rotation fails.
+          OSError: If a write or a flush fails. A failed *rotation* no longer raises; see
+            :meth:`_rotate_or_continue`.
+          SinkDeliveryError: If the sink is closed.
         """
         if not batch:
             return
@@ -298,7 +311,8 @@ class RotatingFileSink:
                 line = json.dumps(event) + "\n"
                 data = len(line.encode(self._encoding))
                 if self._should_rotate(data):
-                    self._rotate()
+                    self._stream.flush()
+                    self._rotate_or_continue()
                 self._stream.write(line)
                 self._size += data
             self._stream.flush()
@@ -425,6 +439,68 @@ class RotatingFileSink:
             return True
         return self._next_rollover is not None and time.monotonic() >= self._next_rollover
 
+    def _rotate_or_continue(self) -> None:
+        """Rotates, or absorbs the failure and carries on writing to the un-rotated file.
+
+        A rotation that raised used to cost the batch twice. ``_rotate`` closes the active stream
+        first, so the events already written in this batch were on disk and the ``OSError``
+        propagated out of ``emit`` — the worker then re-sent the whole batch and wrote them again.
+        Measured: an 8-event batch failing after 3 were written put 11 lines on disk, 3 of them
+        duplicates. A persistent failure was worse: the sink kept a **closed** stream and every
+        later batch raised a raw ``PermissionError``, which is not a ``SinkDeliveryError`` and has
+        no ``losses()`` behind it.
+
+        Absorbing it costs nothing and duplicates nothing. The active file simply exceeds
+        ``max_bytes`` until a rotation succeeds, which is what happens anyway when rotation is
+        impossible — the trade SPEC-027 FR-004 already took, that a leaked resource beats a
+        corrupt write.
+
+        ``_next_rollover`` is re-armed as well as ``_size``: ``_rotate`` sets it on its last line,
+        so an absorbed failure would otherwise leave a **time** trigger permanently in the past.
+
+        **The re-arm does not damp the size trigger, and the diagnostic is what carries that.**
+        ``_size`` is re-seeded from a file that is now over ``max_bytes``, so ``_should_rotate``'s
+        size branch stays true and every subsequent event attempts a rotation again — measured at
+        598 attempts over 600 events. The attempts are cheap and lose nothing, but an unthrottled
+        stderr write per event is not: ``PostgresSink._reconnect_if_broken`` records the same rule
+        for the same reason, that a diagnostic which floods is one an operator stops reading. So
+        the failure is announced **once per outage** and the flag clears on the next successful
+        rotation. The remaining per-event attempt is recorded in ``architecture.md`` §12 rather
+        than fixed here, because damping it means deferring a rotation the caller asked for.
+
+        **The reopen can itself raise, and that is not absorbed.** It is the same
+        ``open(self._path, "a")`` call ``_rotate`` ends with, so whatever defeats it there —
+        a read-only mount, ``EMFILE``, a directory that lost write permission — defeats it here.
+        At that point this sink has no stream and cannot continue, so there is nothing to absorb
+        *into*; the ``OSError`` reaches ``emit`` and the worker retries the batch, duplicating the
+        prefix the pre-rotation flush had already written. That residue is recorded rather than
+        fixed: it is unchanged from before SPEC-048, the surviving events are on disk rather than
+        lost, and inventing a half-open state to avoid a duplicate would trade a visible
+        duplication for a silent loss.
+
+        Args:
+          None.
+
+        Returns:
+          None.
+
+        Raises:
+          OSError: If the *reopen* fails, per the paragraph above. A failed **rotation** is
+            absorbed and announced through ``_diag``; the batch continues, nothing is dropped, no
+            counter moves, and this class still has no ``losses()``.
+        """
+        try:
+            self._rotate()
+        except OSError as err:
+            self._stream = open(self._path, "a", encoding=self._encoding)
+            self._size = os.path.getsize(self._path) if os.path.exists(self._path) else 0
+            self._next_rollover = self._schedule_next()
+            if not self._rotation_failing:
+                self._rotation_failing = True
+                _diag.absorbed("rotating RotatingFileSink", err)
+            return
+        self._rotation_failing = False
+
     def _rotate(self) -> None:
         """Closes the active file, shifts and prunes backups, then opens a fresh active file.
 

{log_foundry-0.10.2.dev103 → log_foundry-0.10.2.dev105}/src/log_foundry/sinks/firehose.py

@@ -203,6 +203,22 @@ class FirehoseSink:
         this loop re-sends the records the destination flagged, and the canonical reason it flags
         them is throttling, which an immediate re-send makes worse.
 
+        **A client exception costs this chunk, never the batch** (SPEC-048 FR-002). It used to
+        propagate out of :meth:`emit`, so a failure on chunk N after chunks 1..N-1 had landed made
+        the worker re-send the whole batch and duplicate everything already delivered — the exit
+        drain, one large batch by construction, is exactly that shape. The guard sits around the
+        client call *inside* this loop rather than around ``_send`` in ``emit``, so only the
+        records still outstanding at the failing attempt are charged and the ones already accepted
+        still count toward the return.
+
+        A client exception is treated as **provable non-delivery** for the chunk, so a wholly
+        failed batch still raises and ``unknown`` is untouched: SPEC-018's "unadjudicable" is a
+        property of a *response*, and an exception is not a response. The cost is written down —
+        a read timeout means the request went out and the reply was lost, so a re-send may
+        duplicate — and taken because an unreachable endpoint is the common case and is exactly
+        what the worker's retry exists for, while suppressing the raise would lose every event of
+        every batch for a whole outage, silently.
+
         Args:
           records: One chunk's request entries.
 
@@ -214,13 +230,27 @@ class FirehoseSink:
           SPEC-018 settled must never be re-sent.
 
         Raises:
-          Exception: Whatever the client raises.
+          None. ``Exception`` is caught rather than ``BaseException``, so a ``KeyboardInterrupt``
+            or ``SystemExit`` still reaches the caller (SPEC-025 FR-004).
         """
         sent = len(records)
         for attempt in range(self.max_retries + 1):
-            response = self.client.put_record_batch(
-                DeliveryStreamName=self.delivery_stream, Records=records
-            )
+            try:
+                response = self.client.put_record_batch(
+                    DeliveryStreamName=self.delivery_stream, Records=records
+                )
+            except Exception as err:
+                if attempt < self.max_retries:
+                    wait(_BACKOFF_BASE * (2**attempt), self.log_foundry_stop_signal)
+                    continue
+                with self._counter_lock:
+                    self.failed += len(records)
+                _diag.lost(
+                    "record",
+                    len(records),
+                    f"FirehoseSink, {self.max_retries + 1} attempt(s), {type(err).__name__}",
+                )
+                return sent - len(records)
             if not response.get("FailedPutCount"):
                 return sent
             results = usable_results(response.get("RequestResponses"))

{log_foundry-0.10.2.dev103 → log_foundry-0.10.2.dev105}/src/log_foundry/sinks/http.py

@@ -125,6 +125,77 @@ inside a typical serverless timeout while leaving room for the request itself.
 """
 
 
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    """Declines every redirect, so a ``3xx`` reaches the sink as an ``HTTPError`` (SPEC-048).
+
+    ``urlopen``'s default opener follows ``301``, ``302`` and ``303`` on a ``POST`` by rewriting
+    the method to ``GET`` and dropping the body, while keeping every header — so a collector
+    behind a load balancer that redirects to ``https://`` silently discarded every batch and
+    forwarded the ``Authorization`` header to whatever host the redirect named, and the sink read
+    the redirect target's ``200`` as delivery. ``307`` and ``308`` were already refused for a
+    ``POST`` by the base class.
+    """
+
+    def redirect_request(
+        self,
+        req: urllib.request.Request,
+        fp: Any,
+        code: int,
+        msg: str,
+        headers: Any,
+        newurl: str,
+    ) -> None:
+        """Declines the redirect, leaving the default error handler to raise ``HTTPError``.
+
+        Returning ``None`` is ``urllib``'s documented "I cannot handle this, let another handler
+        try", and no other handler does, so ``HTTPDefaultErrorHandler`` raises — which
+        :meth:`HTTPSink._attempt` already unifies into a status, putting a ``3xx`` on the same
+        counted, announced path as a ``4xx``.
+
+        Args:
+          req: The request that was redirected.
+          fp: The response file object.
+          code: The ``3xx`` status.
+          msg: The status message.
+          headers: The response headers.
+          newurl: The redirect target, deliberately unused and never contacted.
+
+        Returns:
+          None, always — which is what declines the redirect. A bare ``return`` rather than
+          ``return None`` only because ``ruff``'s ``RET501`` refuses the explicit form; the value
+          urllib receives is the same.
+
+        Raises:
+          None.
+        """
+        return
+
+
+def _no_redirect_opener() -> Callable[..., Any]:
+    """Builds an opener that refuses redirects, for a sink the caller gave no ``opener=``.
+
+    Built per sink at construction rather than once at import, for two reasons. ``python.md`` §15
+    forbids a module doing real work at import time, which is why the ``StdoutSink`` default and
+    the worker are lazy too. And ``build_opener`` snapshots ``ProxyHandler``'s environment, so an
+    import-time opener would pin whatever ``http_proxy`` said when ``log_foundry`` was first
+    imported — a sink built after the application sets its proxy would silently ignore it, where
+    ``urlopen``'s lazily-built global opener would not. Construction time is when the caller is
+    standing there, so it is the honest moment to read the environment.
+
+    A sink is constructed once, so the cost is one object per sink and never per request.
+
+    Args:
+      None.
+
+    Returns:
+      A ``urlopen``-shaped callable that raises ``HTTPError`` on any ``3xx``.
+
+    Raises:
+      None.
+    """
+    return urllib.request.build_opener(_NoRedirect()).open
+
+
 def merge_headers(base: dict[str, str], http_kwargs: dict[str, object]) -> dict[str, str]:
     """Merges a platform sink's own headers with any caller-supplied ones, caller winning.
 
@@ -250,7 +321,9 @@ class HTTPSink:
           max_batch_bytes: Bytes one request's body may reach, or ``None`` for this class's
             :attr:`MAX_BATCH_BYTES`. Floored at one for the same reason.
           opener: A ``urlopen``-shaped callable, which a test can inject to assert on the
-            request without any network access.
+            request without any network access. Defaults to :func:`_no_redirect_opener` rather
+            than ``urlopen`` (SPEC-048 FR-001); an injected one is used exactly as given, since
+            it is the caller's object and the library does not reshape it.
 
         Returns:
           None.
@@ -274,7 +347,7 @@ class HTTPSink:
             max_batch_bytes if max_batch_bytes is not None else self.MAX_BATCH_BYTES, 1
         )
         self.log_foundry_stop_signal: threading.Event | None = None
-        self._opener = opener if opener is not None else urllib.request.urlopen
+        self._opener = opener if opener is not None else _no_redirect_opener()
         self.failed = 0
         self.dropped_oversized = 0
         self._counter_lock = threading.Lock()
@@ -796,7 +869,13 @@ class HTTPSink:
     ) -> tuple[dict[str, str], bytes]:
         """Builds the final header map and the optionally gzipped body.
 
-        Caller-provided headers override the sink's defaults (FR-002).
+        Caller-provided headers override the sink's defaults (FR-002), and that now includes
+        ``Content-Encoding``: ``gzip=True`` used to overwrite one the caller had set, which made
+        it the single header of theirs that did not win. A caller's own value both survives *and*
+        suppresses the compression, because a header saying ``identity`` over a gzipped body
+        makes the destination decode garbage. The test is against ``self._headers`` rather than
+        the merged map, so a per-request ``extra_headers`` value — which sits *beneath* the
+        caller's own — does not switch compression off (SPEC-048 FR-007).
 
         Args:
           body: The serialized batch.
@@ -814,7 +893,7 @@ class HTTPSink:
             headers.update(extra_headers)
         headers.update(self._headers)
         data = body
-        if self.gzip:
+        if self.gzip and "Content-Encoding" not in self._headers:
             data = _gzip.compress(body)
             headers["Content-Encoding"] = "gzip"
         self._apply_auth(headers)

{log_foundry-0.10.2.dev103 → log_foundry-0.10.2.dev105}/src/log_foundry/sinks/kinesis.py

@@ -180,17 +180,18 @@ class KinesisSink:
         records: list[dict[str, Any]] = []
         for event in batch:
             data = json.dumps(event).encode("utf-8")
-            if len(data) > self.MAX_RECORD_BYTES:
+            key = _partition_key(str(event.get(self.partition_key_field) or "log-foundry"))
+            charged = len(data) + len(key.encode("utf-8"))
+            if charged > self.MAX_RECORD_BYTES:
                 with self._counter_lock:
                     self.dropped_oversized += 1
                 _diag.lost(
                     "event",
                     1,
-                    f"KinesisSink, {len(data)} bytes exceeds the "
+                    f"KinesisSink, {charged} bytes with its partition key exceeds the "
                     f"{self.MAX_RECORD_BYTES}-byte per-record limit",
                 )
                 continue
-            key = str(event.get(self.partition_key_field) or "log-foundry")[:256]
             records.append({"Data": data, "PartitionKey": key})
         return records
 
@@ -201,6 +202,22 @@ class KinesisSink:
         this loop re-sends the records the destination flagged, and the canonical reason it flags
         them is throttling, which an immediate re-send makes worse.
 
+        **A client exception costs this chunk, never the batch** (SPEC-048 FR-002). It used to
+        propagate out of :meth:`emit`, so a failure on chunk N after chunks 1..N-1 had landed made
+        the worker re-send the whole batch and duplicate everything already delivered — the exit
+        drain, one large batch by construction, is exactly that shape. The guard sits around the
+        client call *inside* this loop rather than around ``_send`` in ``emit``, so only the
+        records still outstanding at the failing attempt are charged and the ones already accepted
+        still count toward the return.
+
+        A client exception is treated as **provable non-delivery** for the chunk, so a wholly
+        failed batch still raises and ``unknown`` is untouched: SPEC-018's "unadjudicable" is a
+        property of a *response*, and an exception is not a response. The cost is written down —
+        a read timeout means the request went out and the reply was lost, so a re-send may
+        duplicate — and taken because an unreachable endpoint is the common case and is exactly
+        what the worker's retry exists for, while suppressing the raise would lose every event of
+        every batch for a whole outage, silently.
+
         Args:
           records: One chunk's request entries.
 
@@ -212,11 +229,27 @@ class KinesisSink:
           SPEC-018 settled must never be re-sent.
 
         Raises:
-          Exception: Whatever the client raises.
+          None. ``Exception`` is caught rather than ``BaseException``, so a ``KeyboardInterrupt``
+            or ``SystemExit`` still reaches the caller (SPEC-025 FR-004).
         """
         sent = len(records)
         for attempt in range(self.max_retries + 1):
-            response = self.client.put_records(StreamName=self.stream_name, Records=records)
+            try:
+                response = self.client.put_records(
+                    StreamName=self.stream_name, Records=records
+                )
+            except Exception as err:
+                if attempt < self.max_retries:
+                    wait(_BACKOFF_BASE * (2**attempt), self.log_foundry_stop_signal)
+                    continue
+                with self._counter_lock:
+                    self.failed += len(records)
+                _diag.lost(
+                    "record",
+                    len(records),
+                    f"KinesisSink, {self.max_retries + 1} attempt(s), {type(err).__name__}",
+                )
+                return sent - len(records)
             if not response.get("FailedRecordCount"):
                 return sent
             results = usable_results(response.get("Records"))
@@ -248,6 +281,38 @@ class KinesisSink:
         return 0
 
 
+MAX_PARTITION_KEY_BYTES = 256
+"""The service's ceiling on a ``PutRecords`` partition key, in UTF-8 bytes."""
+
+
+def _partition_key(raw: str) -> str:
+    """Bounds a partition key to the service's 256 **bytes**, never 256 characters.
+
+    Both encodes carry an ``errors=`` and both are load-bearing. ``sanitize.coerce`` passes a lone
+    surrogate through unchanged, so a bare ``encode("utf-8")`` on a caller's ``trace_id`` raises
+    ``UnicodeEncodeError`` — a raw exception out of ``emit``, which is the failure SPEC-048 exists
+    to remove rather than introduce. ``errors="ignore"`` on the decode drops a character the byte
+    cut landed inside, so the result always decodes cleanly.
+
+    ``sanitize.truncate_str`` is the inventoried byte-bounded clipper and is deliberately **not**
+    reused: it appends a truncation marker, and a marker inside a partition key changes the shard
+    the record lands on.
+
+    Args:
+      raw: The derived key.
+
+    Returns:
+      The key, at most :data:`MAX_PARTITION_KEY_BYTES` UTF-8 bytes and always valid UTF-8.
+
+    Raises:
+      None.
+    """
+    encoded = raw.encode("utf-8", errors="replace")
+    if len(encoded) <= MAX_PARTITION_KEY_BYTES:
+        return encoded.decode("utf-8")
+    return encoded[:MAX_PARTITION_KEY_BYTES].decode("utf-8", errors="ignore")
+
+
 def _record_size(record: dict[str, Any]) -> int:
     """Measures one request entry, partition key included (SPEC-038 FR-009).
 
@@ -256,6 +321,10 @@ def _record_size(record: dict[str, Any]) -> int:
     service reject a chunk this sink believed was inside the budget. ``SQSSink`` charges its FIFO
     ids for the same reason and records the same rationale.
 
+    The charge is the key's **UTF-8 byte length**, not its character count (SPEC-048 FR-003): the
+    two differ for any non-ASCII key, and the service bills bytes. No ``errors=`` is needed here,
+    because :func:`_partition_key` already built this value and its output always encodes cleanly.
+
     This applies to Kinesis alone: a Firehose record is ``{"Data": data}`` and that API has no
     partition key, so there is nothing there to charge.
 
@@ -268,4 +337,4 @@ def _record_size(record: dict[str, Any]) -> int:
     Raises:
       None.
     """
-    return len(record["Data"]) + len(record["PartitionKey"])
+    return len(record["Data"]) + len(record["PartitionKey"].encode("utf-8"))

{log_foundry-0.10.2.dev103 → log_foundry-0.10.2.dev105}/src/log_foundry/sinks/pubsub.py

@@ -315,62 +315,172 @@ class GooglePubSubSink:
         """
         if not overflow:
             return
-        deadline = time.monotonic() + self.overflow_timeout
-        unresolved: list[Any] = []
-        for index, future in enumerate(overflow):
+        expired, unboundable = self._resolve_within(
+            overflow, time.monotonic() + self.overflow_timeout, heed_stop=True
+        )
+        unresolved = expired + unboundable
+        if not unresolved:
+            return
+        with self._futures_lock:
+            if not self._closed:
+                self._futures[:0] = unresolved
+                return
+        self._drain_pending(unresolved)
+
+    def _resolve_within(
+        self, pending: list[Any], deadline: float, *, heed_stop: bool
+    ) -> tuple[list[Any], list[Any]]:
+        """Waits on each future until the deadline, splitting what did not settle in two.
+
+        One deadline covers the whole list rather than a timeout per future: at the shipped
+        ``max_pending`` a per-future wait is not a bound at all (SPEC-038's rule that a bound
+        applied per item is ``n x timeout``). ``_futures_lock`` is never held across a
+        ``result()``, because ``emit`` takes it per event and an application thread on the orphan
+        path would block behind it.
+
+        Args:
+          pending: The futures to resolve, already removed from the pending list.
+          deadline: A ``time.monotonic()`` reading the pass must not run past.
+          heed_stop: Whether a set stop signal also ends the pass. **True only on the flush
+            path.** ``Worker.shutdown`` sets that event *before* closing the sink inline, so a
+            close that heeded it would abandon everything on every ordinary shutdown -- SPEC-038's
+            rule that a shutdown shortens a *wait* and must never skip *work*, and the exit drain
+            is the one path a serverless process has.
+
+        Returns:
+          The futures whose wait expired, and separately the ones that cannot be waited on within
+          a timeout at all. They are split because they mean opposite things: an expired future is
+          unconfirmed, while an *unboundable* one is a healthy publish this pass simply cannot
+          poll, and counting the second as loss invents it (SPEC-036 measured three of four
+          healthy publishes reported ``failed`` that way).
+
+        Raises:
+          None.
+        """
+        expired: list[Any] = []
+        unboundable: list[Any] = []
+        for index, future in enumerate(pending):
             settled = False
-            while not self._out_of_time(deadline):
+            unpollable = False
+            while not self._past(deadline, heed_stop=heed_stop):
                 began = time.monotonic()
                 slice_ = min(deadline - began, _POLL_INTERVAL)
                 try:
                     settled = self._resolve(future, slice_)
                 except _Unboundable:
+                    unpollable = True
                     break
                 if settled:
                     break
                 wait(slice_ - (time.monotonic() - began), self.log_foundry_stop_signal)
-            if settled:
-                continue
-            unresolved.append(future)
-            if self._out_of_time(deadline):
-                unresolved.extend(overflow[index + 1 :])
+            else:
+                self._classify_remainder(pending[index:], expired, unboundable)
                 break
-        if not unresolved:
-            return
-        with self._futures_lock:
-            if not self._closed:
-                self._futures[:0] = unresolved
-                return
-        for future in unresolved:
-            self._resolve(future)
+            if unpollable:
+                unboundable.append(future)
+        return expired, unboundable
+
+    def _classify_remainder(
+        self, remaining: list[Any], expired: list[Any], unboundable: list[Any]
+    ) -> None:
+        """Sorts the futures a deadline never reached into expired and unboundable.
 
-    def _out_of_time(self, deadline: float) -> bool:
-        """Reports whether the overflow pass must stop, on the deadline or on a shutdown.
+        The pass gives up on the whole remainder when its one deadline expires, and the two
+        outcomes must still be told apart: an expired future is unconfirmed and is counted, while
+        an **unboundable** one is a healthy publish that simply cannot be polled within a timeout,
+        and counting it invents loss. A blanket ``expired.extend(...)`` here charged three healthy
+        publishes as lost behind one stalled future, which is SPEC-036's measured defect
+        reintroduced by the fix that cites it.
 
-        The stop signal is read here rather than once before the loop: read once, a shutdown
-        arriving mid-pass was not noticed until every future had been waited on.
+        The probe is a zero-second wait, so it costs nothing against a deadline that has already
+        gone: a future whose ``result()`` takes no ``timeout`` raises ``_Unboundable`` on the way
+        in, and everything else either settles immediately or reports itself still in flight.
 
         Args:
-          deadline: The monotonic time the pass may not run past.
+          remaining: The futures the pass did not reach, the current one first.
+          expired: The unconfirmed list, appended to in place.
+          unboundable: The cannot-be-polled list, appended to in place.
 
         Returns:
-          True when no further waiting may happen.
+          None.
+
+        Raises:
+          None.
+        """
+        for future in remaining:
+            try:
+                if not self._resolve(future, 0):
+                    expired.append(future)
+            except _Unboundable:
+                unboundable.append(future)
+
+    def _past(self, deadline: float, *, heed_stop: bool) -> bool:
+        """Reports whether a resolution pass must stop.
+
+        Args:
+          deadline: A ``time.monotonic()`` reading.
+          heed_stop: Whether a set stop signal also ends the pass.
+
+        Returns:
+          True on the deadline, or on the stop signal when this caller heeds it.
 
         Raises:
           None.
         """
         if time.monotonic() >= deadline:
             return True
+        if not heed_stop:
+            return False
         stop = self.log_foundry_stop_signal
         return stop is not None and stop.is_set()
 
+    def _drain_pending(self, pending: list[Any]) -> None:
+        """Resolves a swapped-out list within the close bound, counting what it abandons.
+
+        The tail every close-race site shares: :meth:`close`, and the two branches where a close
+        lands while another pass is mid-flight. Each used to resolve its leftovers with
+        ``timeout=None``, which is the unbounded wait ``Worker.shutdown`` performs inline against
+        a client publish deadline of 600 s. ``_await_overflow``'s copy is the one that mattered
+        most: it runs on whichever thread called ``emit``, which on the orphan path is an
+        application thread.
+
+        Unboundable futures still get ``timeout=None``, because that is the only wait they accept
+        and :meth:`_resolve` counts whatever they resolve to.
+
+        Args:
+          pending: The futures this caller owns and nothing else will resolve.
+
+        Returns:
+          None.
+
+        Raises:
+          None.
+        """
+        expired, unboundable = self._resolve_within(
+            pending, time.monotonic() + self.overflow_timeout, heed_stop=False
+        )
+        for future in unboundable:
+            self._resolve(future)
+        if not expired:
+            return
+        with self._counter_lock:
+            self.failed += len(expired)
+        _diag.lost(
+            "event",
+            len(expired),
+            f"GooglePubSubSink, {len(expired)} publish(es) still in flight when the "
+            f"{self.overflow_timeout}s close bound expired",
+        )
+
     def _resolve(self, future: Any, timeout: float | None = None) -> bool:
         """Waits for one publish to settle, counting and announcing a failure.
 
         Args:
           future: The publish future to resolve.
-          timeout: Seconds to wait, or ``None`` to wait indefinitely — which is what ``close``
-            does, and what a shutdown defers this to.
+          timeout: Seconds to wait, or ``None`` to wait indefinitely. Since SPEC-048 FR-004 that
+            is what an *unboundable* future gets, not what ``close`` does: ``close`` bounds itself
+            on ``overflow_timeout`` through :meth:`_drain_pending`, because it runs inline inside
+            ``Worker.shutdown`` against a client publish deadline of 600 s.
 
         Returns:
           True when the future settled, False when a *bounded* wait expired with it still in
@@ -450,26 +560,10 @@ class GooglePubSubSink:
         if not pending:
             return
 
-        deadline = time.monotonic() + self.overflow_timeout
-        unresolved: list[Any] = []
-        for index, future in enumerate(pending):
-            settled = False
-            while not self._out_of_time(deadline):
-                began = time.monotonic()
-                slice_ = min(deadline - began, _POLL_INTERVAL)
-                try:
-                    settled = self._resolve(future, slice_)
-                except _Unboundable:
-                    break
-                if settled:
-                    break
-                wait(slice_ - (time.monotonic() - began), self.log_foundry_stop_signal)
-            if settled:
-                continue
-            unresolved.append(future)
-            if self._out_of_time(deadline):
-                unresolved.extend(pending[index + 1 :])
-                break
+        expired, unboundable = self._resolve_within(
+            pending, time.monotonic() + self.overflow_timeout, heed_stop=True
+        )
+        unresolved = expired + unboundable
 
         if not unresolved:
             return
@@ -478,14 +572,30 @@ class GooglePubSubSink:
             if not closed:
                 self._futures[:0] = unresolved
         if closed:
-            for future in unresolved:
-                self._resolve(future)
+            self._drain_pending(unresolved)
         raise SinkDeliveryError(
             f"GooglePubSubSink flushed with {len(unresolved)} publish(es) still in flight"
         )
 
     def close(self) -> None:
-        """Resolves all pending publish futures, counting and logging errors (FR-008).
+        """Resolves the pending publish futures within a bound, counting the rest (FR-008).
+
+        **Bounded since SPEC-048 FR-004.** It used to wait ``timeout=None`` per future, and
+        ``Worker.shutdown`` closes the live sink inline, so one unreachable destination held
+        process exit for the client's 600 s publish deadline per future. The bound is
+        ``overflow_timeout`` on the monotonic clock and deliberately **not** the stop signal;
+        :meth:`_resolve_within` records why.
+
+        **The bound does not cover a future that cannot be waited on within a timeout.** One whose
+        ``result()`` takes no ``timeout`` argument is resolved unbounded, because that is the only
+        wait it accepts and SPEC-036 measured that counting it instead invents loss on publishes
+        that were going to succeed. So a client handing out unboundable futures that also do not
+        settle still holds the close for its own deadline, once per future: measured at 27.0 s for
+        nine futures against a 3 s stand-in, where the bounded path took 2.0 s for sixty.
+        ``google-cloud-pubsub``'s own future accepts a timeout, so this is reachable only through
+        an injected ``client=`` that does not — but ``client=`` is a frozen public parameter, which
+        is why it is written down here rather than assumed away. Recorded in ``architecture.md``
+        §12; it is strictly better than before, where **every** future took this path.
 
         Idempotent. The pending list is swapped out under a lock rather than iterated and then
         cleared (SPEC-028 FR-002): ``emit`` appends to it from any thread, so the old
@@ -513,8 +623,7 @@ class GooglePubSubSink:
         with self._futures_lock:
             self._closed = True
             pending, self._futures = self._futures, []
-        for future in pending:
-            self._resolve(future)
+        self._drain_pending(pending)
 
 
 def _has_settled(future: Any) -> bool:

{log_foundry-0.10.2.dev103 → log_foundry-0.10.2.dev105}/src/log_foundry/sinks/sentry.py

@@ -252,7 +252,21 @@ class SentrySink:
             flush()
 
     def close(self) -> None:
-        """Forwards to the HTTP fallback, whose own close releases nothing (FR-012).
+        """Pushes the SDK transport, then forwards to the HTTP fallback (FR-012, SPEC-048 FR-005).
+
+        **The flush comes first, and without it a terminal ``shutdown()`` stranded everything.**
+        ``capture_event`` hands to the SDK's background transport and returns, so a process that
+        calls ``shutdown()`` and freezes — the whole of the serverless path, where the SDK's own
+        timer never fires again — left every captured event in the SDK's worker. :meth:`flush`
+        already pushes that queue; this method reached only the ``urllib`` fallback, which holds
+        nothing. Measured before the fix: 25 events captured, zero ``flush`` calls seen by the
+        client during ``close()``.
+
+        It is absorbed, because this is an isolation boundary and a failing flush must not stop
+        the release below it. And it is **not** suppressed on a repeat close: this sink adds no
+        post-close guard (SPEC-032 FR-003), so events can legitimately be captured between two
+        closes, and a flag suppressing the second flush would strand exactly what this exists to
+        un-strand. A repeat flush of a drained queue is a no-op.
 
         Idempotent, and it releases nothing — which is why the class docstring's post-close claim
         holds despite this method calling a ``close()``. ``HTTPSink.close`` is a documented no-op,
@@ -270,6 +284,10 @@ class SentrySink:
         Raises:
           None.
         """
+        try:
+            self.flush()
+        except Exception as err:
+            _diag.absorbed("closing SentrySink", err)
         if self._http is not None:
             _lifecycle.release(self._http, owner=self)
 

{log_foundry-0.10.2.dev103 → log_foundry-0.10.2.dev105}/src/log_foundry/sinks/sns.py

@@ -153,6 +153,21 @@ class SNSSink:
         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.
 
+        **A client exception costs this chunk, never the batch** (SPEC-048 FR-002). It used to
+        propagate out of :meth:`emit`, so a failure on chunk N after chunks 1..N-1 had landed made
+        the worker re-send the whole batch and duplicate everything already delivered — the exit
+        drain, one large batch by construction, is exactly that shape. The guard sits around the
+        client call *inside* this loop rather than around ``_send`` in ``emit``, so only the
+        messages still outstanding at the failing attempt are charged and the ones already accepted
+        still count toward the return.
+
+        A client exception is treated as **provable non-delivery** for the chunk, so a wholly
+        failed batch still raises. The cost is written down —
+        a read timeout means the request went out and the reply was lost, so a re-send may
+        duplicate — and taken because an unreachable endpoint is the common case and is exactly
+        what the worker's retry exists for, while suppressing the raise would lose every event of
+        every batch for a whole outage, silently.
+
         Args:
           bodies: One chunk's serialized events.
 
@@ -161,14 +176,28 @@ class SNSSink:
           success. A chunk whose entries all failed contributes zero.
 
         Raises:
-          Exception: Whatever the client raises.
+          None. ``Exception`` is caught rather than ``BaseException``, so a ``KeyboardInterrupt``
+            or ``SystemExit`` still reaches the caller (SPEC-025 FR-004).
         """
         sent = len(bodies)
         entries = [{"Id": str(i), "Message": body} for i, body in enumerate(bodies)]
         for attempt in range(self.max_retries + 1):
-            response = self.client.publish_batch(
-                TopicArn=self.topic_arn, PublishBatchRequestEntries=entries
-            )
+            try:
+                response = self.client.publish_batch(
+                    TopicArn=self.topic_arn, PublishBatchRequestEntries=entries
+                )
+            except Exception as err:
+                if attempt < self.max_retries:
+                    wait(_BACKOFF_BASE * (2**attempt), self.log_foundry_stop_signal)
+                    continue
+                with self._counter_lock:
+                    self.failed += len(entries)
+                _diag.lost(
+                    "message",
+                    len(entries),
+                    f"SNSSink, {self.max_retries + 1} attempt(s), {type(err).__name__}",
+                )
+                return sent - len(entries)
             failed = response.get("Failed", [])
             if not failed:
                 return sent

{log_foundry-0.10.2.dev103 → log_foundry-0.10.2.dev105}/src/log_foundry/sinks/sqs.py

@@ -337,6 +337,24 @@ class SQSSink:
         alone in re-sending immediately, while its own docstring named throttling as the
         retryable case, which is exactly what an instant retry makes worse.
 
+        **A client exception costs this chunk, never the batch** (SPEC-048 FR-002). It used to
+        propagate out of :meth:`emit`, so a failure on chunk N after chunks 1..N-1 had landed made
+        the worker re-send the whole batch and duplicate everything already in the queue — the
+        exit drain, one large batch by construction, is exactly that shape. The guard sits around
+        the client call *inside* this loop rather than around ``_send`` in ``emit``, because by
+        the time an exception is raised ``accepted`` may already be non-zero and ``entries``
+        narrowed to the retryable subset: charging the whole chunk outside would report a partial
+        success as "nothing delivered" and provoke the very retry this removes.
+
+        A client exception is treated as **provable non-delivery** for the chunk, so it feeds the
+        recoverable term and a wholly-failed batch still raises. That is not free — a read timeout
+        means the request went out and the *response* was lost, so entries may have landed and a
+        re-send duplicates them, which is SPEC-018's "cannot prove nothing landed". It is taken on
+        expected cost: an unreachable or refused endpoint is the common client exception and is
+        exactly what the worker's retry exists for, and suppressing the raise for it would lose
+        every event of every batch for the whole outage, silently. ``boto3``'s own ``max_attempts``
+        retry already carries the duplication property, so this does not introduce it.
+
         Args:
           prepared: One chunk's serialized, costed entries.
 
@@ -346,7 +364,8 @@ class SQSSink:
           recover. A chunk SQS rejected wholesale as invalid reports False there.
 
         Raises:
-          Exception: Whatever the client raises.
+          None. ``Exception`` is caught rather than ``BaseException``, so a ``KeyboardInterrupt``
+            or ``SystemExit`` still reaches the caller (SPEC-025 FR-004).
         """
         entries: list[dict[str, str]] = []
         for i, item in enumerate(prepared):
@@ -358,7 +377,22 @@ class SQSSink:
             entries.append(entry)
         accepted = 0
         for attempt in range(self.max_retries + 1):
-            response = self.client.send_message_batch(QueueUrl=self.queue_url, Entries=entries)
+            try:
+                response = self.client.send_message_batch(
+                    QueueUrl=self.queue_url, Entries=entries
+                )
+            except Exception as err:
+                if attempt < self.max_retries:
+                    wait(_BACKOFF_BASE * (2**attempt), self.log_foundry_stop_signal)
+                    continue
+                with self._counter_lock:
+                    self.failed += len(entries)
+                _diag.lost(
+                    "message",
+                    len(entries),
+                    f"SQSSink, {self.max_retries + 1} attempt(s), {type(err).__name__}",
+                )
+                return accepted, True
             failed = response.get("Failed", [])
             failed_ids = {item.get("Id") for item in failed}
             accepted += sum(1 for entry in entries if entry["Id"] not in failed_ids)