log-foundry 0.10.2.dev29__tar.gz → 0.10.2.dev30__tar.gz

{log_foundry-0.10.2.dev29 → log_foundry-0.10.2.dev30}/PKG-INFO

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

{log_foundry-0.10.2.dev29 → log_foundry-0.10.2.dev30}/pyproject.toml

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

{log_foundry-0.10.2.dev29 → log_foundry-0.10.2.dev30}/src/log_foundry/api.py

@@ -30,6 +30,12 @@ def _log(level: str, message: str, echo: bool, fields: dict[str, object]) -> Non
     the sink resolved through ``_ensure_sink`` so a zero-config orphan log falls back to
     ``StdoutSink`` rather than crashing.
 
+    That direct handoff is **settled, not pending**: SPEC-004's worker took over the traced
+    path and this branch was deliberately left synchronous, so a level call outside a span is
+    never silently dropped for want of a worker (``architecture.md`` §12 Resolved, "Orphan
+    logs"). It carried a comment saying the worker "will later" own it long after the
+    decision was made (SPEC-031 FR-003).
+
     The orphan branch is the one that reaches the sink on the caller's own thread, with no
     worker between them to absorb a failure, so the whole branch is guarded (SPEC-025
     FR-003) — ``_ensure_sink`` constructs the sink on first use, so a sink that fails to

{log_foundry-0.10.2.dev29 → log_foundry-0.10.2.dev30}/src/log_foundry/console.py

@@ -16,13 +16,24 @@ class ConsoleWriter:
     operator sees it without waiting for the async flush. It is deliberately dumb, rendering
     an already-built event dict and knowing nothing about spans, and echo is additive — an
     echoed event still rides the normal pipeline to the sink.
+
+    The default stream is **stderr**, not stdout (SPEC-031 FR-003, which corrected two
+    documents that said otherwise). It is the twelve-factor convention ``StderrSink`` already
+    cites — logs on stderr, the application's own output on stdout — so an echo cannot corrupt
+    a program whose stdout is a data stream someone pipes.
     """
 
     def __init__(self, stream: TextIO | None = None) -> None:
-        """Binds the writer to an output stream.
+        """Binds the writer to an output stream, once, at construction.
+
+        The binding is deliberate and permanent for the life of the writer: a later
+        ``contextlib.redirect_stderr`` or a test's capture of ``sys.stderr`` is not honoured,
+        because the attribute was resolved here. ``api._console`` is built at import, so in
+        practice a process's echo stream is fixed before any test runs. Passing ``stream=``
+        explicitly is how a caller — a test above all — captures the output (SPEC-031 FR-003).
 
         Args:
-          stream: The stream to write to, defaulting to ``sys.stderr``.
+          stream: The stream to write to, defaulting to ``sys.stderr`` as resolved now.
 
         Returns:
           None.

{log_foundry-0.10.2.dev29 → log_foundry-0.10.2.dev30}/src/log_foundry/model.py

@@ -8,6 +8,8 @@ from dataclasses import dataclass, field
 from datetime import UTC, datetime
 from typing import TYPE_CHECKING
 
+from log_foundry.config import get_config
+from log_foundry.ids import new_log_id
 from log_foundry.sanitize import sanitize_fields, truncate_str, truncate_tail
 
 if TYPE_CHECKING:
@@ -72,6 +74,12 @@ def build_event(
     bounded too, since both are caller-supplied text and leaving either out would keep
     ``info(huge_string)`` unbounded.
 
+    ``get_config`` and ``new_log_id`` are imported at module scope (SPEC-031 FR-004). They were
+    function-local to avoid a cycle, but there is none to avoid: neither ``config`` nor ``ids``
+    imports this module, and ``config``'s own back-references to ``decorator`` stay local for
+    the reason its docstrings give. This is the hottest path in the library, so resolving them
+    once at import is what ``sanitize`` already does with its one-time bindings.
+
     Args:
       span: The span the event belongs to, supplying identity and defaults.
       level: The severity label, such as ``"INFO"``.
@@ -85,9 +93,6 @@ def build_event(
     Raises:
       None.
     """
-    from log_foundry.config import get_config
-    from log_foundry.ids import new_log_id
-
     cfg = get_config()
     merged: dict[str, object] = {**cfg.defaults, **span.defaults, **baggage, **fields}
     safe, clipped = sanitize_fields(merged, cfg=cfg)
@@ -226,8 +231,6 @@ def end_event(
     Raises:
       None.
     """
-    from log_foundry.config import get_config
-
     level = "INFO" if status == "ok" else "ERROR"
     event = build_event(span, level, _END_MESSAGE, fields={}, baggage={})
     event["duration_ms"] = (time.monotonic() - span.start_ts) * 1000.0
@@ -266,8 +269,6 @@ def backfill_baggage(span: Span, baggage: dict[str, object]) -> None:
     """
     if not baggage:
         return
-    from log_foundry.config import get_config
-
     safe, clipped = sanitize_fields(baggage, cfg=get_config())
     for event in span.events:
         if event.get("message") in (_START_MESSAGE, _END_MESSAGE):

{log_foundry-0.10.2.dev29 → log_foundry-0.10.2.dev30}/src/log_foundry/sanitize.py

@@ -142,7 +142,7 @@ class _Coercer:
     ``build_event`` already allocates per event, it is noise.
     """
 
-    __slots__ = ("_cfg", "_parents", "truncated")
+    __slots__ = ("_cfg", "_int_ceiling", "_parents", "truncated")
 
     def __init__(self, cfg: Config) -> None:
         """Starts a pass with the configured ceilings and an empty ancestor chain.
@@ -152,6 +152,11 @@ class _Coercer:
         recursion for the whole descent, so its ``id()`` cannot be recycled underneath us, and
         two siblings referencing the same object are not a cycle and must both render.
 
+        The integer ceiling is resolved here, once per pass rather than once per integer
+        (SPEC-031 FR-004): it reads ``sys.get_int_max_str_digits()``, which cannot change
+        during a coercion pass, and the alternative sat four lines below an ``int.__lt__``
+        binding justified by this being a per-value hot path.
+
         Args:
           cfg: The config supplying ``max_value_bytes``, ``max_keys`` and ``max_depth``.
 
@@ -162,6 +167,7 @@ class _Coercer:
           None.
         """
         self._cfg = cfg
+        self._int_ceiling = _int_digit_ceiling(cfg.max_value_bytes)
         self.truncated = False
         self._parents: list[int] = []
 
@@ -368,7 +374,7 @@ class _Coercer:
         """
         digits = value.bit_length() * _LOG10_2_NUM // _LOG10_2_DEN + 1
         rendered = digits + 1 if _INT_LT(value, 0) else digits
-        if rendered <= _int_digit_ceiling(self._cfg.max_value_bytes):
+        if rendered <= self._int_ceiling:
             return value
         self.truncated = True
         return f"<int: ~{digits} digits>"

{log_foundry-0.10.2.dev29 → log_foundry-0.10.2.dev30}/src/log_foundry/sinks/_socket.py

@@ -33,21 +33,45 @@ def _make_tcp(host: str, port: int, timeout: float) -> socket.socket:
     return socket.create_connection((host, port), timeout=timeout)
 
 
-def _make_udp() -> socket.socket:
-    """Opens an unconnected UDP socket.
+def _make_udp(host: str) -> socket.socket:
+    """Opens an unconnected UDP socket in an address family the host resolves to (SPEC-031).
+
+    The family is resolved rather than assumed: a hardcoded ``AF_INET`` made every ``sendto``
+    to an IPv6 destination fail, silently, until the retry bound abandoned the message. TCP
+    never had the defect because ``socket.create_connection`` resolves for itself.
+
+    **IPv4 wins when the host offers it**, and taking the first result instead was measured
+    losing logs. ``getaddrinfo`` sorts by RFC 6724, which puts AAAA first, so a dual-stack
+    name like ``localhost`` would move from IPv4 — where every deployment of this library has
+    sent — to IPv6, and a collector bound to ``0.0.0.0:514`` would never see the datagram. UDP
+    is unconnected, so that failure is *silent*: ``sendto`` succeeds locally, ``emit`` returns,
+    and no counter moves. FR-002 AC-2 requires delivery to a hostname to be unchanged, and
+    this is what makes it so while AC-1 still holds. It is a fixed preference, not
+    happy-eyeballs, address caching, or a setting — none of which this FR builds.
 
     This is a module-level seam so tests can substitute a fake socket without network access.
 
     Args:
-      None.
+      host: The destination host, resolved to choose the family.
 
     Returns:
       The socket.
 
     Raises:
-      OSError: If the socket cannot be created.
+      OSError: If the host resolves to nothing, or the socket cannot be created. Both reach
+        ``_send_one``'s handler, which counts and announces rather than raising — a
+        ``gaierror`` is an ``OSError``, so an unresolvable host fails exactly as an
+        unreachable one already did. The empty-result case is raised as one explicitly: CPython
+        raises rather than returning ``[]``, but indexing it would produce an ``IndexError``,
+        which is *not* an ``OSError`` and would escape that handler into the caller — the one
+        thing SPEC-025 says this library may never do.
     """
-    return socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    families = [entry[0] for entry in socket.getaddrinfo(host, None, type=socket.SOCK_DGRAM)]
+    if not families:
+        raise socket.gaierror(socket.EAI_NONAME, "resolution returned no address family")
+    return socket.socket(
+        socket.AF_INET if socket.AF_INET in families else families[0], socket.SOCK_DGRAM
+    )
 
 
 class SocketTransport:
@@ -235,6 +259,10 @@ class SocketTransport:
     def _socket(self) -> socket.socket:
         """Returns the held socket, opening one if none is held.
 
+        The UDP address family is resolved here rather than per message, because this is the
+        only place a socket is created and the socket outlives every send made through it
+        (SPEC-031 FR-002).
+
         Args:
           None.
 
@@ -242,11 +270,11 @@ class SocketTransport:
           The socket.
 
         Raises:
-          OSError: If the socket cannot be created or connected.
+          OSError: If the socket cannot be created, resolved or connected.
         """
         if self._sock is None:
             self._sock = (
-                _make_udp() if self._transport == "udp" else _make_tcp(
+                _make_udp(self._host) if self._transport == "udp" else _make_tcp(
                     self._host, self._port, self._timeout
                 )
             )

{log_foundry-0.10.2.dev29 → log_foundry-0.10.2.dev30}/src/log_foundry/sinks/file.py

@@ -113,12 +113,16 @@ class RotatingFileSink:
     Two independent triggers may be enabled, either or both. With a positive ``max_bytes`` it
     rotates before the write that would push the active file past that size, so the file never
     grows unbounded; with a ``when`` unit code and an interval it rotates on the first emit after
-    that period has elapsed since the last rotation.
+    that period has elapsed since the last rotation. That period is measured on the monotonic
+    clock (SPEC-031 FR-001), so a wall-clock step in either direction neither defers a rotation
+    nor forces an early one.
 
     Rotation renames the active file through numbered backups, prunes any beyond the backup
     count, and opens a fresh active file — a backup count of zero keeps none, simply replacing
-    the active file. No event is lost across a rotation, because the rotate happens before the
-    pending event is written and the event lands in the fresh file.
+    the active file. Backups are numbered rather than timestamped, so no filename derives from
+    a clock at all and the monotonic deadline has no naming consequence. No event is lost across
+    a rotation, because the rotate happens before the pending event is written and the event
+    lands in the fresh file.
 
     A rotation rebinds the active stream, so it is the sink where concurrent writers did real
     damage: a second thread mid-``emit`` could write to the handle rotation had just closed, or
@@ -249,24 +253,34 @@ class RotatingFileSink:
         return unit * interval
 
     def _schedule_next(self) -> float | None:
-        """Returns the wall-clock time of the next time-based rotation.
+        """Returns the monotonic-clock deadline for the next time-based rotation (SPEC-031).
+
+        Monotonic rather than wall-clock for the reason ``Span.start_ts`` is: a backward step —
+        an NTP correction, a container clock sync — larger than the interval would otherwise
+        defer every time-based rotation until wall-clock caught up, silently defeating this
+        class's promise to bound on-disk growth. Nothing here is a timestamp anyone reads; it is
+        only ever compared against another reading of the same clock.
 
         Args:
           None.
 
         Returns:
-          The absolute time, or ``None`` when there is no time trigger.
+          The deadline as a ``time.monotonic()`` reading, or ``None`` when there is no time
+          trigger.
 
         Raises:
           None.
         """
         if self._interval_seconds is None:
             return None
-        return time.time() + self._interval_seconds
+        return time.monotonic() + self._interval_seconds
 
     def _should_rotate(self, incoming: int) -> bool:
         """Decides whether to rotate before writing the next event.
 
+        The time trigger reads ``time.monotonic()``, the same clock :meth:`_schedule_next`
+        wrote the deadline on; comparing the two clocks is what the SPEC-031 fix removes.
+
         Args:
           incoming: The byte cost of the event about to be written.
 
@@ -282,7 +296,7 @@ class RotatingFileSink:
             and self._size + incoming > self._max_bytes
         ):
             return True
-        return self._next_rollover is not None and time.time() >= self._next_rollover
+        return self._next_rollover is not None and time.monotonic() >= self._next_rollover
 
     def _rotate(self) -> None:
         """Closes the active file, shifts and prunes backups, then opens a fresh active file.

{log_foundry-0.10.2.dev29 → log_foundry-0.10.2.dev30}/src/log_foundry/sinks/logstash.py

@@ -24,6 +24,18 @@ class LogstashSink:
     :class:`~log_foundry.sinks._socket.SocketTransport`. Either backend handles its own bounded
     retry and raises on total failure of its own accord, so ``emit`` needs no rule of its own.
 
+    In socket mode both IPv4 and IPv6 destinations are supported, over either transport
+    (SPEC-031 FR-002): the UDP socket's address family is resolved from ``host`` rather than
+    assumed, which is what an unconditional ``AF_INET`` used to make impossible.
+
+    **A hostname that resolves to both families goes to IPv4**, because that is where every
+    release before this one sent and moving it silently would strand a collector bound to
+    ``0.0.0.0``. The consequence is the mirror case, stated because nothing else states it: a
+    dual-stack *name* whose collector listens on IPv6 only will not be reached over UDP, and
+    since UDP is unconnected that failure is silent — no exception, no counter. Give the IPv6
+    literal, or a name with no ``A`` record, to select IPv6 for such a destination. TCP is
+    unaffected either way; ``create_connection`` tries each candidate in turn.
+
     It takes **no** transport lock (SPEC-028 FR-002) of its own: whichever backend it built owns
     that decision — ``SocketTransport`` locks its sends, ``HTTPSink`` holds no transport to
     guard. The post-close rule follows the same split (SPEC-032 FR-004), and the two modes

{log_foundry-0.10.2.dev29 → log_foundry-0.10.2.dev30}/src/log_foundry/sinks/stdout.py

@@ -29,10 +29,15 @@ class StdoutSink:
     """
 
     def __init__(self, stream: TextIO | None = None) -> None:
-        """Binds the sink to an output stream.
+        """Binds the sink to an output stream, once, at construction.
+
+        The binding is deliberate and permanent for the life of the sink: a later
+        ``contextlib.redirect_stdout`` or a test's capture of ``sys.stdout`` is not honoured,
+        because the attribute was resolved here. Passing ``stream=`` explicitly is how a caller
+        — a test above all — captures the output (SPEC-031 FR-003).
 
         Args:
-          stream: The stream to write to, defaulting to ``sys.stdout``.
+          stream: The stream to write to, defaulting to ``sys.stdout`` as resolved now.
 
         Returns:
           None.

{log_foundry-0.10.2.dev29 → log_foundry-0.10.2.dev30}/src/log_foundry/sinks/syslog.py

@@ -34,6 +34,18 @@ class SyslogSink:
     and a severity mapped from the event's level. UDP sends one datagram per event, TCP uses
     octet-counted framing (RFC 6587), and the whole sink is dependency-free.
 
+    Both IPv4 and IPv6 destinations are supported, on either transport (SPEC-031 FR-002): the
+    UDP socket's address family is resolved from ``host`` rather than assumed, which is what an
+    unconditional ``AF_INET`` used to make impossible.
+
+    **A hostname that resolves to both families goes to IPv4**, because that is where every
+    release before this one sent and moving it silently would strand a collector bound to
+    ``0.0.0.0``. The consequence is the mirror case, stated because nothing else states it: a
+    dual-stack *name* whose collector listens on IPv6 only will not be reached over UDP, and
+    since UDP is unconnected that failure is silent — no exception, no counter. Give the IPv6
+    literal, or a name with no ``A`` record, to select IPv6 for such a destination. TCP is
+    unaffected either way; ``create_connection`` tries each candidate in turn.
+
     It takes **no** transport lock (SPEC-028 FR-002) of its own: the socket it holds is a
     :class:`~log_foundry.sinks._socket.SocketTransport`, which locks its own sends. Its
     post-close refusal comes from there too (SPEC-032 FR-004) — a batch emitted after

{log_foundry-0.10.2.dev29 → log_foundry-0.10.2.dev30}/src/log_foundry/sinks/util.py

@@ -20,11 +20,16 @@ class StderrSink(StdoutSink):
     """
 
     def __init__(self, stream: TextIO | None = None) -> None:
-        """Binds the sink to an output stream.
+        """Binds the sink to an output stream, once, at construction.
+
+        The binding is resolved here and not re-read per write, so a later
+        ``contextlib.redirect_stderr`` is not honoured — the same property
+        :class:`~log_foundry.sinks.stdout.StdoutSink` documents (SPEC-031 FR-003), restated
+        because this override means none of that docstring is inherited.
 
         Args:
-          stream: The stream to write to, defaulting to ``sys.stderr``. An explicit one, such
-            as a ``StringIO``, can be injected for capture.
+          stream: The stream to write to, defaulting to ``sys.stderr`` as resolved now. An
+            explicit one, such as a ``StringIO``, can be injected for capture.
 
         Returns:
           None.

{log_foundry-0.10.2.dev29 → log_foundry-0.10.2.dev30}/src/log_foundry/worker.py

@@ -854,6 +854,12 @@ class Worker:
         this sweep, and that one waits out its timeout — then returns False, which is correct
         either way.
 
+        The reliance on ``queue.Queue``'s private ``mutex`` and ``queue`` is deliberate and is
+        recorded in ``architecture.md`` §13 Known Constraints (SPEC-031 FR-005): there is no
+        public "inspect without consuming", and the draining alternative would destroy the
+        evidence the terminal-failure line reports. A CPython change would surface as the test
+        that exercises this against a mixed queue, rather than as waiters silently timing out.
+
         Args:
           None.