log-foundry 0.10.2.dev53__tar.gz → 0.10.2.dev54__tar.gz

{log_foundry-0.10.2.dev53 → log_foundry-0.10.2.dev54}/PKG-INFO

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

{log_foundry-0.10.2.dev53 → log_foundry-0.10.2.dev54}/pyproject.toml

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

{log_foundry-0.10.2.dev53 → log_foundry-0.10.2.dev54}/src/log_foundry/_fork.py

@@ -7,10 +7,13 @@ import os
 import sys
 import threading
 import types
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from log_foundry import _diag
 
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
 _PACKAGE = __name__.rpartition(".")[0]
 """This package's import name, derived rather than written.
 
@@ -25,6 +28,15 @@ _LOCK_TYPES: tuple[type, ...] = (type(threading.Lock()), _RLOCK_TYPE)
 
 _CONTAINER_TYPES: tuple[type, ...] = (list, tuple, set, frozenset, dict, collections.deque)
 
+_child_handlers: list[Callable[[], None]] = []
+"""What runs in the child once its locks are its own again, in registration order.
+
+**An inverted registry, and that is what keeps the dependency arrow pointing one way**
+(FR-006). The work a child needs done belongs to ``decorator``, ``_lifecycle`` and the sinks,
+and all three would have to import this module for it to reach them; instead they register with
+it, so this module imports nothing that imports it and there is no cycle to break later.
+"""
+
 _installed = False
 """Whether :func:`install` has already registered the child handler in this process.
 
@@ -367,12 +379,46 @@ def _reinit_primitives() -> None:
                 stack.append(value)
 
 
+def register_child_handler(fn: Callable[[], None]) -> None:
+    """Adds work to be done in a forked child, after its locks have been re-initialised.
+
+    A handler may take any of the library's locks, which is what the ordering in
+    :func:`_reinit_after_fork` buys it and why registering is the only way in. What it must not
+    assume is that it is alone: handlers run in registration order and an earlier one may have
+    started a thread — ``decorator``'s rebuild does exactly that — so only the *first* runs in a
+    genuinely single-threaded child. None of them may block, since nothing has returned from
+    ``fork`` yet.
+
+    Registering the same function twice is a no-op, compared by **identity**: ``in`` would ask
+    a registered object's ``__eq__``, which is not this function's to trust and would raise into
+    a caller documented as raising nothing. The exposure is the one :data:`_installed` records
+    for the fork registration itself: a reload of a module whose body registers here would
+    otherwise stack a second handler, and for the worker rebuild that means two drain threads,
+    the first bound to a queue nothing writes to.
+
+    Args:
+      fn: Called with no arguments in the child. A failure is absorbed and announced, and the
+        remaining handlers still run.
+
+    Returns:
+      None.
+
+    Raises:
+      None.
+    """
+    if not any(handler is fn for handler in _child_handlers):
+        _child_handlers.append(fn)
+
+
 def _reinit_after_fork() -> None:
     """Repairs the library in a child that has just returned from ``fork``.
 
-    **The order of work here is the contract** (FR-001 AC-2): locks and events first, because
-    anything running afterwards may take one, and a lock re-initialised after a handler that
-    takes it is a handler that hangs.
+    **The order of work here is the contract** (FR-001 AC-2): locks and events first, then the
+    registered handlers. A lock re-initialised *after* a handler that takes it is a handler
+    that hangs, and it hangs on the child's only thread with nothing to interrupt it. Work that
+    must happen before *any* handler belongs inline between the two steps rather than registered
+    — the buffer discard FR-004 adds is the case, and registering it would put it after
+    ``decorator``'s rebuild, which has started a live drain thread by then.
 
     Args:
       None.
@@ -383,12 +429,22 @@ def _reinit_after_fork() -> None:
     Raises:
       None. A fork handler that raises has its exception printed by CPython with a full
         traceback, carrying the message arch §6 keeps out of anything the library says about
-        itself — and it would leave the rest of the repair undone.
+        itself — and it would leave the rest of the repair undone. One handler's failure is
+        absorbed separately from the rest for the same reason: a child that cannot rebuild its
+        worker should still have working locks. The list is iterated live rather than copied,
+        which is safe because CPython's list iterator is index-based, so a handler that
+        registers another simply causes it to run — and :func:`register_child_handler` is the
+        only writer, appending only.
     """
     try:
         _reinit_primitives()
     except Exception as exc:
         _diag.absorbed("repairing the library after a fork", exc, "this child may block or lose")
+    for handler in _child_handlers:
+        try:
+            handler()
+        except Exception as exc:
+            _diag.absorbed("running a fork handler", exc, "this child may not deliver")
 
 
 def install() -> None:

{log_foundry-0.10.2.dev53 → log_foundry-0.10.2.dev54}/src/log_foundry/decorator.py

@@ -11,7 +11,7 @@ from dataclasses import replace
 from time import monotonic
 from typing import TYPE_CHECKING, Any, TypeVar, cast, overload
 
-from log_foundry import _diag, _lifecycle, context
+from log_foundry import _diag, _fork, _lifecycle, context
 from log_foundry.config import _ensure_sink
 from log_foundry.ids import (
     is_valid_span_id,
@@ -332,6 +332,43 @@ def _note_orphan_emit(sink: Sink) -> None:
         _orphan_sink = sink
 
 
+def _rebuild_worker_after_fork() -> None:
+    """Gives a forked child a drain thread of its own, or a retired worker (SPEC-039 FR-002).
+
+    Registered with ``_fork`` at import rather than reached for by it, which is what keeps that
+    module free of an import of this one (FR-006). It runs on the child's only thread, after the
+    locks are its own again, so it may take them.
+
+    The predicate is deliberately **not** ``_live_worker()``, even though the two agree today.
+    What is being asked is whether to start a thread, and the answer must survive a later
+    reading of ``retired`` — so it is hoisted into ``resume`` and passed, where the roster files
+    it as its own decision rather than as a call whose category a reader has to chase.
+
+    ``_worker_lock`` is deliberately **not** taken. There is one thread here by construction,
+    and the lock was re-initialised moments ago: a child that took it would be taking a lock no
+    other thread can contend for, at the one moment in the process's life when that is provably
+    true.
+
+    Args:
+      None.
+
+    Returns:
+      None.
+
+    Raises:
+      None. ``_fork`` absorbs and announces a handler's failure, so a child whose worker cannot
+        be rebuilt still has working locks.
+    """
+    worker = _worker
+    if worker is None:
+        return
+    resume = not worker.retired
+    worker._reinit_after_fork(resume=resume)
+
+
+_fork.register_child_handler(_rebuild_worker_after_fork)
+
+
 def _live_worker() -> Worker | None:
     """Returns the process worker only while it is still delivering (SPEC-033 FR-002).
 

{log_foundry-0.10.2.dev53 → log_foundry-0.10.2.dev54}/src/log_foundry/worker.py

@@ -81,7 +81,10 @@ class Health:
         report. Non-``None`` is categorically worse than the two counters above: they measure
         loss the worker absorbed and kept running through, this one means the worker is gone
         (SPEC-019 FR-003). Also ``"ShutdownTimeout"`` when a bounded :meth:`Worker.shutdown`
-        expired before the drain finished (SPEC-027 FR-004), the same thing to a reader.
+        expired before the drain finished (SPEC-027 FR-004), and the type name of whatever
+        stopped a forked child's rebuild from starting a thread at all (SPEC-039 FR-002) — a
+        case where the drain thread never ran rather than died. All three are the same thing to
+        a reader, which is why they share the field: nothing is delivering.
       sink: The configured sink's own loss counters, or ``None`` when there is no worker or
         the sink reports nothing (SPEC-026 FR-003). Nested rather than folded into the
         integers above because they count different things: ``dropped`` here is backpressure
@@ -229,6 +232,7 @@ class Worker:
         self.stopped_reason: str | None = None
         self.submitted_after_shutdown = 0
         self.incomplete_swaps = 0
+        self._max_queue = max_queue
         self._queue: queue.Queue[object] = queue.Queue(maxsize=max_queue)
         self._stop = threading.Event()
         self._drain_finished = threading.Event()
@@ -242,6 +246,101 @@ class Worker:
         )
         self._thread.start()
 
+    def _reinit_after_fork(self, *, resume: bool) -> None:
+        """Rebuilds this worker **in place** for a child that has just forked (SPEC-039 FR-002).
+
+        The child inherits a ``Worker`` whose thread does not exist, so ``submit`` goes on
+        enqueueing and nothing drains: measured, six events never delivered, ``atexit`` closing
+        the sink without a drain, and ``health()`` reading ``queued=2`` with every other field
+        clean — the documented alert idiom blind. Rebuilding rather than retiring is the design:
+        a prefork server's child is a working process, and a child that silently stops logging
+        is the failure this arc exists to remove.
+
+        **In place, never a new object** (FR-002 AC-5). The ownership guards keyed on
+        ``_worker.sink is X`` and ``_lifecycle``'s registry are identity comparisons, so
+        replacing the worker would leave every one of them answering about something else.
+
+        **The queue is replaced, not drained.** Emptying it would keep ``queue.Queue``'s own
+        mutex and its three ``Condition``s, which the fork walk cannot reach — it enters no
+        standard-library container — and a fork landing inside that mutex leaves the child's
+        very next ``submit`` blocked on the application's thread. That is why the replacement
+        happens even when nothing is resumed: a retired worker still *accepts* submissions
+        (SPEC-030 FR-001), so a retired child would block on the same mutex. Starting empty is
+        also what stops the parent's undelivered backlog being sent twice (AC-2).
+
+        ``stopped_reason`` is cleared rather than set to ``"Forked"`` (AC-6). SPEC-019 defines
+        that field as "the drain thread died", and this child's drain thread is about to be
+        running — the alternative reads as the more honest one and is not.
+
+        The two drain events are **set or cleared to match what this child will actually do**,
+        never simply inherited. Resuming clears them, so ``draining`` and ``flush``'s gate
+        describe the thread starting here rather than the one that did not survive the fork;
+        retiring **sets** them, because no thread will ever set them and a child forked while a
+        ``shutdown()`` was mid-join otherwise inherits them unset with nothing to settle them.
+        Two consequences, both measured: that child paid the whole 30 s budget at exit and with
+        ``shutdown(timeout=None)`` would never exit at all, and — reaching further —
+        ``_offer_orphan_signal`` reads it as still draining and skips, leaving the sink holding
+        a **set** stop event, so every later backoff returns instantly against a destination
+        that is already refusing (SPEC-033 FR-004). ``_drain_finished`` has no reader on a
+        retired worker and is set for the invariant rather than for an observable: settled with
+        finished clear is what :attr:`draining` defines as an *abandoned* drain, and a child
+        reporting no ``stopped_reason`` must not read that way. The stop signal is re-offered for
+        the sink the fork walk cannot reach: a **third-party** sink is outside its ownership
+        boundary, so it would keep pointing at the pre-fork event while this worker sets a new
+        one — SPEC-027's guarantee broken by the repair meant to preserve it.
+
+        **The new thread is only installed once it has started**, which ``__init__`` never had
+        to consider: a constructor whose ``start`` raises lets no ``Worker`` escape, while here
+        the worker is already the process's. Assigning first would leave an unstarted ``Thread``
+        on a live worker reading ``draining`` forever, and the next ``shutdown()`` would take a
+        ``RuntimeError`` from ``join`` straight out of a public call documented to raise nothing.
+        The inherited thread object is kept instead, which is safe because CPython repairs it
+        across the fork — measured, it reports dead and both a bounded and an unbounded ``join``
+        return in 0.0000 s — and the failure is recorded as a ``stopped_reason``, which is
+        exactly SPEC-019's vocabulary for "nothing is delivering". Setting both drain events is
+        what keeps :meth:`shutdown` from queueing a sentinel into a queue no thread will read.
+
+        The success path assigns ``self._thread`` *after* the start, so for an instant a live
+        drain thread coexists with the inherited dead one in that attribute. That is safe only
+        because the drain thread never reads it — ``_run``, ``_drain``, ``_terminal_failure``
+        and ``_release_waiters`` do not, and the three readers are all on caller threads — which
+        is an invariant this note states rather than one anything enforces.
+
+        Args:
+          resume: Whether to start a drain thread. ``False`` for a retired parent, which forks
+            a retired child (AC-4): a fork does not undo a ``shutdown()``, and reviving a worker
+            the caller terminated would be the library overruling them.
+
+        Returns:
+          None.
+
+        Raises:
+          None.
+        """
+        self._queue = queue.Queue(maxsize=self._max_queue)
+        self.dropped = 0
+        self.failed_batches = 0
+        self.submitted_after_shutdown = 0
+        self.incomplete_swaps = 0
+        self.stopped_reason = None
+        if not resume:
+            self._drain_finished.set()
+            self._drain_settled.set()
+            return
+        self._drain_finished.clear()
+        self._drain_settled.clear()
+        self._offer_stop_signal()
+        thread = threading.Thread(target=self._run, name="log-foundry-worker", daemon=True)
+        try:
+            thread.start()
+        except Exception as exc:
+            self.stopped_reason = type(exc).__name__
+            self._drain_finished.set()
+            self._drain_settled.set()
+            _diag.absorbed("starting this child's drain thread", exc, "it will deliver nothing")
+            return
+        self._thread = thread
+
     def _offer_stop_signal(self) -> None:
         """Gives the sink this worker's shutdown event, if it advertises somewhere to put it.