log-foundry 0.10.2.dev60__tar.gz → 0.10.2.dev61__tar.gz

{log_foundry-0.10.2.dev60 → log_foundry-0.10.2.dev61}/PKG-INFO

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

{log_foundry-0.10.2.dev60 → log_foundry-0.10.2.dev61}/pyproject.toml

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

{log_foundry-0.10.2.dev60 → log_foundry-0.10.2.dev61}/src/log_foundry/_lifecycle.py

@@ -24,7 +24,42 @@ _closers: list[threading.Thread] = []
 _closers_lock = threading.Lock()
 
 
-def close_detached(sink: Sink) -> threading.Thread | None:
+def release(sink: Sink, *, detached: bool = False) -> threading.Thread | None:
+    """Closes a sink on the library's behalf — the one path by which it ever does (SPEC-042 FR-002).
+
+    Eight sites closed a sink directly before this existed, and guarding only the three the
+    lifecycle owns was measurably insufficient: a forked child that wraps an **inherited** sink in
+    a ``MultiSink`` of its own reaches the inner sink through the wrapper, so the parent's
+    structural sink was closed twice with all three lifecycle sites guarded. Routing every
+    library closer through one function is what gives the ownership question one home.
+
+    **The guard moves here; the error handling does not.** This propagates whatever ``close()``
+    raises, because the callers do not agree today and must not be made to: four absorb, under
+    three distinct ``_diag`` texts naming the site (SPEC-029), ``MultiSink`` also increments its
+    ``failed`` counter, and ``FilteringSink``/``TransformSink``/``LogstashSink`` propagate under
+    a documented ``Raises:``. Folding the ``try/except`` in here would drop absorbed close
+    failures out of ``Health.sink.failed`` — a SPEC-026 regression — and falsify those three.
+
+    Args:
+      sink: The sink to close.
+      detached: Whether to close on a daemon thread rather than inline. Detached is for a sink
+        the caller has stopped delivering to and must not block on (SPEC-030 FR-003).
+
+    Returns:
+      The started closer thread for a detached release, or ``None`` — both when an inline close
+      completed and when the platform would not give the process another thread.
+
+    Raises:
+      Exception: Whatever an inline ``close()`` raised. A detached release raises nothing: the
+        thread body absorbs, since there is no caller left to hand it to.
+    """
+    if detached:
+        return _start_closer(sink)
+    sink.close()
+    return None
+
+
+def _start_closer(sink: Sink) -> threading.Thread | None:
     """Starts a daemon close of a sink no longer being delivered to (SPEC-030 FR-003).
 
     The thread is returned rather than joined, so a caller holding a lock can start under it and
@@ -79,7 +114,8 @@ def _close_guarded(sink: Sink) -> None:
     The guard is what makes the thread safe to leave unattended: an exception escaping here
     would reach CPython's thread bootstrap, which prints a full traceback carrying the
     exception's message — the user data arch §6 keeps out of anything the library says about
-    itself.
+    itself. It goes back through :func:`release` rather than calling ``close()`` itself, so the
+    thread body is one of the eight callers rather than a ninth close (SPEC-042 FR-002).
 
     Args:
       sink: The sink to close.
@@ -91,7 +127,7 @@ def _close_guarded(sink: Sink) -> None:
       None.
     """
     try:
-        sink.close()
+        release(sink)
     except Exception as exc:
         _diag.absorbed("closing a swapped-out sink", exc, "it may still hold its resources")
 

{log_foundry-0.10.2.dev60 → log_foundry-0.10.2.dev61}/src/log_foundry/decorator.py

@@ -504,7 +504,7 @@ def _close_orphan_sink() -> None:
         _orphan_sink = None
         _orphan_closed_sink = owed
     try:
-        owed.close()
+        _lifecycle.release(owed)
     except Exception as exc:
         _diag.absorbed("closing the sink", exc, "it may still hold its resources")
 
@@ -637,7 +637,7 @@ def _swap_sink(new_sink: Sink, timeout: float | None = DEFAULT_SWAP_TIMEOUT) ->
             _offer_orphan_signal(new_sink)
             if _worker is None or _worker.sink is not old:
                 _orphan_closed_sink = old
-                closer = _lifecycle.close_detached(old)
+                closer = _lifecycle.release(old, detached=True)
     if worker is not None:
         try:
             worker_holds_sink = worker.swap_sink(new_sink, timeout)

{log_foundry-0.10.2.dev60 → log_foundry-0.10.2.dev61}/src/log_foundry/sinks/filtering.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
-from log_foundry import _diag
+from log_foundry import _diag, _lifecycle
 from log_foundry.sinks.base import read_losses
 
 if TYPE_CHECKING:
@@ -172,6 +172,10 @@ class FilteringSink:
     def close(self) -> None:
         """Closes the inner sink (FR-003).
 
+        Routed through ``_lifecycle.release`` so a sink this process may not release is refused
+        here as it is at the lifecycle's own closers (SPEC-042 FR-002). The propagation is
+        unchanged: the helper re-raises, and this method's ``Raises:`` is the reason it does.
+
         Args:
           None.
 
@@ -181,4 +185,4 @@ class FilteringSink:
         Raises:
           Exception: Whatever the inner sink raises on close.
         """
-        self._inner.close()
+        _lifecycle.release(self._inner)

{log_foundry-0.10.2.dev60 → log_foundry-0.10.2.dev61}/src/log_foundry/sinks/logstash.py

@@ -8,6 +8,7 @@ from typing import TYPE_CHECKING
 if TYPE_CHECKING:
     import threading
 
+from log_foundry import _lifecycle
 from log_foundry.sinks._socket import DEFAULT_MAX_DATAGRAM_BYTES, SocketTransport
 from log_foundry.sinks.base import SinkLosses
 from log_foundry.sinks.http import HTTPSink
@@ -124,6 +125,11 @@ class LogstashSink:
     def close(self) -> None:
         """Closes whichever backend is held (FR-005).
 
+        The two branches are deliberately not symmetric. The HTTP backend is a ``Sink`` and goes
+        through ``_lifecycle.release``, so a forked child cannot release one it inherited
+        (SPEC-042 FR-002); the socket is a ``SocketTransport`` this sink built and owns
+        outright, which no sink-ownership record describes.
+
         Args:
           None.
 
@@ -134,7 +140,7 @@ class LogstashSink:
           Exception: Whatever the backend raises on close.
         """
         if self._http is not None:
-            self._http.close()
+            _lifecycle.release(self._http)
         elif self._socket is not None:
             self._socket.close()
 

{log_foundry-0.10.2.dev60 → log_foundry-0.10.2.dev61}/src/log_foundry/sinks/multi.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import threading
 from typing import TYPE_CHECKING
 
-from log_foundry import _diag
+from log_foundry import _diag, _lifecycle
 from log_foundry.sinks.base import SinkLosses, read_losses
 
 if TYPE_CHECKING:
@@ -178,7 +178,11 @@ class MultiSink:
         """Closes every child, isolating a failing one so the rest still close (FR-002).
 
         Unlike :meth:`emit` this keeps the unconditional isolate-and-continue behaviour even on
-        total failure, because a failed close has nothing to retry.
+        total failure, because a failed close has nothing to retry. Each child goes through
+        ``_lifecycle.release`` rather than being closed here, so a child this process may not
+        release is refused by the same guard the lifecycle's own closers consult (SPEC-042
+        FR-002) — the wrapper route is how a forked child reached a parent's sink with all three
+        lifecycle sites already guarded.
 
         Args:
           None.
@@ -191,7 +195,7 @@ class MultiSink:
         """
         for sink in self._sinks:
             try:
-                sink.close()
+                _lifecycle.release(sink)
             except Exception as err:
                 with self._counter_lock:
                     self.failed += 1

{log_foundry-0.10.2.dev60 → log_foundry-0.10.2.dev61}/src/log_foundry/sinks/sentry.py

@@ -8,7 +8,7 @@ import uuid
 from typing import Any
 from urllib.parse import urlparse
 
-from log_foundry import _diag
+from log_foundry import _diag, _lifecycle
 from log_foundry.sinks.base import SinkDeliveryError, SinkLosses
 from log_foundry.sinks.http import HTTPSink
 
@@ -128,7 +128,9 @@ class SentrySink:
         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,
         since ``urllib`` builds a fresh connection per request; the forward exists so a future
-        ``HTTPSink`` that *did* hold a pool would be released here rather than leaked.
+        ``HTTPSink`` that *did* hold a pool would be released here rather than leaked. It goes
+        through ``_lifecycle.release`` for that same future: the day the forward releases
+        something is the day a forked child must not perform it (SPEC-042 FR-002).
 
         Args:
           None.
@@ -140,7 +142,7 @@ class SentrySink:
           None.
         """
         if self._http is not None:
-            self._http.close()
+            _lifecycle.release(self._http)
 
     @property
     def log_foundry_stop_signal(self) -> threading.Event | None:

{log_foundry-0.10.2.dev60 → log_foundry-0.10.2.dev61}/src/log_foundry/sinks/transform.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
-from log_foundry import _diag
+from log_foundry import _diag, _lifecycle
 from log_foundry.sinks.base import read_losses
 
 if TYPE_CHECKING:
@@ -140,6 +140,10 @@ class TransformSink:
     def close(self) -> None:
         """Closes the inner sink (FR-004).
 
+        Routed through ``_lifecycle.release`` so a sink this process may not release is refused
+        here as it is at the lifecycle's own closers (SPEC-042 FR-002). The propagation is
+        unchanged: the helper re-raises, and this method's ``Raises:`` is the reason it does.
+
         Args:
           None.
 
@@ -149,4 +153,4 @@ class TransformSink:
         Raises:
           Exception: Whatever the inner sink raises on close.
         """
-        self._inner.close()
+        _lifecycle.release(self._inner)

{log_foundry-0.10.2.dev60 → log_foundry-0.10.2.dev61}/src/log_foundry/worker.py

@@ -790,7 +790,7 @@ class Worker:
             wait this method exists to remove, in the one situation where the process is
             already under resource pressure.
         """
-        closer = _lifecycle.close_detached(sink)
+        closer = _lifecycle.release(sink, detached=True)
         if closer is not None:
             closer.join(timeout)
 
@@ -1009,7 +1009,7 @@ class Worker:
           None.
         """
         try:
-            self.sink.close()
+            _lifecycle.release(self.sink)
         except Exception as exc:
             _diag.absorbed("closing the sink", exc, "it may still hold its resources")