log-foundry 0.10.2.dev22__tar.gz → 0.10.2.dev23__tar.gz

{log_foundry-0.10.2.dev22 → log_foundry-0.10.2.dev23}/PKG-INFO

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

{log_foundry-0.10.2.dev22 → log_foundry-0.10.2.dev23}/pyproject.toml

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

{log_foundry-0.10.2.dev22 → log_foundry-0.10.2.dev23}/src/log_foundry/sinks/_socket.py

@@ -3,10 +3,7 @@
 from __future__ import annotations
 
 import socket
-from typing import TYPE_CHECKING
-
-if TYPE_CHECKING:
-    import threading
+import threading
 
 from log_foundry import _diag
 from log_foundry.sinks._retry import wait
@@ -64,6 +61,14 @@ class SocketTransport:
     100-message batch against a dead destination is roughly 70 s of backoff on the single drain
     thread at the defaults. The wait is interruptible, so ``shutdown()`` cuts it short.
 
+    Sends are serialized on a lock (SPEC-028 FR-002). One TCP connection is shared by every
+    caller, and ``sendall`` gives no atomicity against a concurrent one: two interleaved calls
+    splice their bytes into the stream, which turns octet-counted syslog framing into a sequence
+    the receiver cannot resynchronize — it reads the next frame's length from the middle of the
+    previous frame's payload and is lost for the life of the connection. That the lock is held
+    across the backoff waits is deliberate; they are interruptible, so a ``shutdown()`` releases
+    it promptly.
+
     Attributes:
       failed: Messages abandoned past the reconnect-retry bound.
     """
@@ -104,10 +109,15 @@ class SocketTransport:
         self._sock: socket.socket | None = None
         self.failed = 0
         self.stop_signal: threading.Event | None = None
+        self._lock = threading.Lock()
 
     def send_all(self, messages: list[bytes]) -> None:
         """Sends each pre-framed message, reconnecting on error (FR-005, FR-006).
 
+        The lock spans the whole call, not each message: it also guards ``_sock``, which a
+        reconnect rebinds, so releasing between messages would let another thread send on a
+        socket this one is about to reset (SPEC-028 FR-002).
+
         Args:
           messages: The exact bytes to put on the wire, one call per message.
 
@@ -121,10 +131,11 @@ class SocketTransport:
             would re-send the messages that already landed, and an empty call is a no-op rather
             than a total failure.
         """
-        delivered = 0
-        for message in messages:
-            if self._send_one(message):
-                delivered += 1
+        with self._lock:
+            delivered = 0
+            for message in messages:
+                if self._send_one(message):
+                    delivered += 1
         if messages and delivered == 0:
             raise SinkDeliveryError(
                 f"SocketTransport delivered none of {len(messages)} message(s)"
@@ -147,7 +158,10 @@ class SocketTransport:
     def close(self) -> None:
         """Closes the held socket, if any (FR-005, FR-012).
 
-        Idempotent.
+        Idempotent, and takes the send lock so it never closes the socket out from under an
+        in-flight ``send_all`` (SPEC-028 FR-002). ``_reset`` does not take the lock itself,
+        because ``_send_one`` calls it while ``send_all`` already holds one — the lock is
+        deliberately not re-entrant, so that path must stay the only unlocked caller.
 
         Args:
           None.
@@ -158,7 +172,8 @@ class SocketTransport:
         Raises:
           None.
         """
-        self._reset()
+        with self._lock:
+            self._reset()
 
     def _send_one(self, message: bytes) -> bool:
         """Sends one message within the retry bound.

{log_foundry-0.10.2.dev22 → log_foundry-0.10.2.dev23}/src/log_foundry/sinks/base.py

@@ -62,6 +62,18 @@ class Sink(Protocol):
     def emit(self, batch: list[dict[str, object]]) -> None:
         """Ships a batch of serialized event dicts.
 
+        **May be called concurrently from more than one thread, and must tolerate it**
+        (SPEC-028 FR-001). The background worker drains on its own thread, and a level call
+        made with no active span emits synchronously on the *caller's* thread (arch §12), which
+        may be any of the application's — an audit observed one sink object entered by two
+        application threads and the worker at once. An implementation holding mutable transport
+        state, such as a stream it rebinds, a reused socket or a connection with transaction
+        scope, must serialize access to it for the whole span of the operation that assumes
+        exclusivity. One that holds no such state need do nothing.
+
+        This is a requirement on implementations, not a promise the library serializes on their
+        behalf. It cannot: the orphan path runs on a thread the library does not own.
+
         Raise when the batch delivered nothing and it was non-empty — the worker's bounded
         retry and ``health().failed_batches`` depend on that signal, and a retry there cannot
         duplicate anything (SPEC-026 FR-001). Raise after the sink's own retries are spent, so
@@ -88,6 +100,13 @@ class Sink(Protocol):
     def close(self) -> None:
         """Flushes and releases any resources.
 
+        **May be called while an ``emit`` is in flight on another thread** (SPEC-028 FR-001).
+        It must therefore either wait for that emit or become a no-op, and must never release a
+        resource a concurrent ``emit`` is about to use — a half-released transport is worse than
+        an unreleased one, because the emit then fails against a closed handle instead of
+        succeeding. Taking the same lock ``emit`` takes satisfies this; so does an idempotent
+        guard checked under that lock.
+
         Args:
           None.
 

{log_foundry-0.10.2.dev22 → log_foundry-0.10.2.dev23}/src/log_foundry/sinks/file.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import json
 import os
+import threading
 import time
 from typing import TextIO
 
@@ -22,8 +23,12 @@ class FileSink:
 
     Not every deployment ships to a cloud queue; local dev, debugging, air-gapped hosts and
     simple archival just want events on the local disk. Writes are synchronous stdlib calls
-    only, and a single-process, single-worker-thread writer is assumed (arch §9) — cross-process
-    coordination is out of scope.
+    only.
+
+    Writers within the process are serialized on a lock, because ``emit`` may be called
+    concurrently (SPEC-028 FR-002) — this module claimed a single worker thread until that spec
+    measured the orphan path emitting on application threads at the same time. Cross-*process*
+    coordination remains out of scope: two processes appending to one path are on their own.
     """
 
     def __init__(self, path: str, *, encoding: str = "utf-8") -> None:
@@ -47,10 +52,16 @@ class FileSink:
         self._encoding = encoding
         self._stream: TextIO = open(path, "a", encoding=encoding)
         self._closed = False
+        self._lock = threading.Lock()
 
     def emit(self, batch: list[dict[str, object]]) -> None:
         """Writes every event as one newline-terminated ``json.dumps`` line, then flushes.
 
+        The lock covers the whole batch rather than each line (SPEC-028 FR-002). A text stream
+        does not promise that one ``write`` is atomic against another, so per-line locking could
+        still interleave two events' bytes; batch-wide locking also keeps a batch contiguous in
+        the file, which is what makes the output readable.
+
         Args:
           batch: The events to write.
 
@@ -60,13 +71,17 @@ class FileSink:
         Raises:
           OSError: If the write or flush fails (FR-001).
         """
-        for event in batch:
-            self._stream.write(json.dumps(event) + "\n")
-        self._stream.flush()
+        with self._lock:
+            for event in batch:
+                self._stream.write(json.dumps(event) + "\n")
+            self._stream.flush()
 
     def close(self) -> None:
         """Flushes and closes the file handle, with a second call a no-op (FR-001).
 
+        Taking the same lock ``emit`` takes means a close waits for an in-flight write rather
+        than pulling the stream out from under it (SPEC-028 FR-002).
+
         Args:
           None.
 
@@ -76,11 +91,12 @@ class FileSink:
         Raises:
           OSError: If the flush or close fails.
         """
-        if self._closed:
-            return
-        self._stream.flush()
-        self._stream.close()
-        self._closed = True
+        with self._lock:
+            if self._closed:
+                return
+            self._stream.flush()
+            self._stream.close()
+            self._closed = True
 
 
 class RotatingFileSink:
@@ -95,6 +111,11 @@ class RotatingFileSink:
     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.
+
+    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
+    to the pre-rotation file it had already renamed away. Both are serialized on a lock
+    (SPEC-028 FR-002).
     """
 
     def __init__(
@@ -136,10 +157,16 @@ class RotatingFileSink:
         self._size = os.path.getsize(path) if os.path.exists(path) else 0
         self._next_rollover = self._schedule_next()
         self._closed = False
+        self._lock = threading.Lock()
 
     def emit(self, batch: list[dict[str, object]]) -> None:
         """Appends each event, rotating first whenever a size or time trigger fires (FR-002).
 
+        The lock spans the whole batch, so the decide-rotate-write-account sequence is
+        indivisible (SPEC-028 FR-002). Guarding only ``_rotate`` would not be enough: the
+        ``_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.
+
         Args:
           batch: The events to write.
 
@@ -149,18 +176,23 @@ class RotatingFileSink:
         Raises:
           OSError: If a write, flush or rotation fails.
         """
-        for event in batch:
-            line = json.dumps(event) + "\n"
-            data = len(line.encode(self._encoding))
-            if self._should_rotate(data):
-                self._rotate()
-            self._stream.write(line)
-            self._size += data
-        self._stream.flush()
+        with self._lock:
+            for event in batch:
+                line = json.dumps(event) + "\n"
+                data = len(line.encode(self._encoding))
+                if self._should_rotate(data):
+                    self._rotate()
+                self._stream.write(line)
+                self._size += data
+            self._stream.flush()
 
     def close(self) -> None:
         """Flushes and closes the active handle, with a second call a no-op (FR-002).
 
+        Taking the same lock ``emit`` takes means a close waits for an in-flight write, and in
+        particular never lands between a rotation and the write it was making room for
+        (SPEC-028 FR-002).
+
         Args:
           None.
 
@@ -170,11 +202,12 @@ class RotatingFileSink:
         Raises:
           OSError: If the flush or close fails.
         """
-        if self._closed:
-            return
-        self._stream.flush()
-        self._stream.close()
-        self._closed = True
+        with self._lock:
+            if self._closed:
+                return
+            self._stream.flush()
+            self._stream.close()
+            self._closed = True
 
     @staticmethod
     def _rollover_seconds(when: str | None, interval: int) -> float | None:

{log_foundry-0.10.2.dev22 → log_foundry-0.10.2.dev23}/src/log_foundry/sinks/sqlite.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import json
 import sqlite3
+import threading
 
 from log_foundry.sinks._chunk import valid_identifier
 
@@ -18,8 +19,14 @@ class SQLiteSink:
     For local dev, debugging, air-gapped hosts or simple archival, an embedded SQLite file is a
     durable sink you can open later and query with plain SQL. Each event is stored as its full
     JSON — the source of truth — plus a few columns projected out for cheap filtering, which are
-    ``NULL`` when absent. Standard library only, and a single-process, single-worker-thread
-    writer is assumed (arch §9).
+    ``NULL`` when absent. Standard library only.
+
+    The driver requirement satisfied (SPEC-028 FR-002): ``check_same_thread=False`` switches off
+    ``sqlite3``'s own same-thread guard, and ``with connection`` is a transaction scope on the
+    shared connection rather than a per-caller one — two threads inside it at once share a single
+    implicit transaction, so one thread's rollback discards rows the other had already inserted.
+    A lock restores the one-writer-at-a-time the guard used to enforce. Cross-*process* writers
+    to one database file remain out of scope.
     """
 
     def __init__(
@@ -33,8 +40,9 @@ class SQLiteSink:
         """Connects to the database and, by default, provisions the schema.
 
         The connection is opened with ``check_same_thread=False``: the background worker is a
-        different thread from the one that ran ``configure()`` and is the sole writer, so
-        SQLite's same-thread guard would only get in the way.
+        different thread from the one that ran ``configure()``, so SQLite's same-thread guard
+        would reject every insert. It is not the sole writer — the orphan path emits on the
+        caller's thread (SPEC-028) — which is why the lock below replaces what the guard gave up.
 
         Args:
           database: The database file to open, ignored when a connection is injected.
@@ -61,6 +69,7 @@ class SQLiteSink:
             else sqlite3.connect(database, check_same_thread=False)
         )
         self._closed = False
+        self._lock = threading.Lock()
         if create_table:
             self._ensure_schema()
 
@@ -68,7 +77,9 @@ class SQLiteSink:
         """Inserts every event in one transaction (FR-003).
 
         ``with connection`` opens a transaction and commits on success or rolls back on error,
-        so the whole batch lands atomically.
+        so the whole batch lands atomically. The lock holds that transaction to one thread
+        (SPEC-028 FR-002); the row-building above it needs no protection, but sits inside for
+        simplicity and costs nothing an uncontended lock does not.
 
         Args:
           batch: The events to insert.
@@ -84,7 +95,7 @@ class SQLiteSink:
         ]
         placeholders = ", ".join("?" * (len(_COLUMNS) + 1))
         columns = ", ".join((*_COLUMNS, "event"))
-        with self._conn:
+        with self._lock, self._conn:
             self._conn.executemany(
                 f'INSERT INTO "{self._table}" ({columns}) VALUES ({placeholders})', rows
             )
@@ -92,7 +103,8 @@ class SQLiteSink:
     def close(self) -> None:
         """Commits pending work and closes only a connection the sink owns (FR-003).
 
-        Idempotent.
+        Idempotent, and takes the emit lock so it never closes the connection out from under an
+        in-flight transaction (SPEC-028 FR-002).
 
         Args:
           None.
@@ -103,12 +115,13 @@ class SQLiteSink:
         Raises:
           sqlite3.Error: If the commit or close fails.
         """
-        if self._closed:
-            return
-        self._conn.commit()
-        if self._owns_connection:
-            self._conn.close()
-        self._closed = True
+        with self._lock:
+            if self._closed:
+                return
+            self._conn.commit()
+            if self._owns_connection:
+                self._conn.close()
+            self._closed = True
 
     def _ensure_schema(self) -> None:
         """Idempotently creates the target table.