log-foundry 0.7.2.dev2__tar.gz → 0.7.2.dev3__tar.gz

{log_foundry-0.7.2.dev2 → log_foundry-0.7.2.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: log-foundry
-Version: 0.7.2.dev2
+Version: 0.7.2.dev3
 Summary: Generate logs for your console and JSON events for downstream consumption.
 License-Expression: MIT
 License-File: LICENSE
@@ -783,6 +783,12 @@ the default configuration the interpreter's limit — not `max_value_bytes` —
 unlikely to meet it deliberately; `int.from_bytes(blob, "big")` over a couple of kilobytes gets
 there. Any ceiling firing sets `truncated: true` on the event.
 
+`max_value_bytes` therefore carries two units: **UTF-8 bytes** for a string, **rendered decimal
+length** (sign included) for an integer. They coincide for ASCII digits, and one ceiling for "how
+big may a single value get" was preferred to a second config key. Note that all four ceilings
+bound each *value* — an event of many bounded values can still be large; see
+[Known constraints](docs/architecture.md#known-constraints).
+
 ## Development
 
 ```bash

{log_foundry-0.7.2.dev2 → log_foundry-0.7.2.dev3}/README.md

@@ -747,6 +747,12 @@ the default configuration the interpreter's limit — not `max_value_bytes` —
 unlikely to meet it deliberately; `int.from_bytes(blob, "big")` over a couple of kilobytes gets
 there. Any ceiling firing sets `truncated: true` on the event.
 
+`max_value_bytes` therefore carries two units: **UTF-8 bytes** for a string, **rendered decimal
+length** (sign included) for an integer. They coincide for ASCII digits, and one ceiling for "how
+big may a single value get" was preferred to a second config key. Note that all four ceilings
+bound each *value* — an event of many bounded values can still be large; see
+[Known constraints](docs/architecture.md#known-constraints).
+
 ## Development
 
 ```bash

{log_foundry-0.7.2.dev2 → log_foundry-0.7.2.dev3}/pyproject.toml

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

{log_foundry-0.7.2.dev2 → log_foundry-0.7.2.dev3}/src/log_foundry/config.py

@@ -24,6 +24,15 @@ class Config:
     The four ``max_*`` ceilings bound every event payload (SPEC-017 FR-002). Defaults are set so
     that the overwhelming majority of events are untouched; they exist to stop *one* pathological
     value getting a whole event rejected by a sink's hard limit.
+
+    ``max_value_bytes`` carries **two units**, deliberately (SPEC-020, recorded by SPEC-021): a
+    string is measured in UTF-8 bytes, an integer in the decimal length it renders as, sign
+    included. They coincide for ASCII digits, and one ceiling covering "how big may a single
+    value get" beat a second config key for a distinction almost no one configures. An integer is
+    also bounded by ``sys.get_int_max_str_digits()`` whenever that is lower, since a longer one
+    cannot be rendered at all.
+
+    They bound each *value*, not the event as a whole — see arch §13 Known Constraints.
     """
 
     service: str = "unknown"
@@ -31,7 +40,7 @@ class Config:
     env: str = "dev"
     sink: Sink | None = None
     defaults: dict[str, object] = field(default_factory=dict)
-    max_value_bytes: int = 8192  # per str value, UTF-8 bytes
+    max_value_bytes: int = 8192  # per value: UTF-8 bytes for a str, rendered digits for an int
     max_stack_bytes: int = 32768  # error.stack only — legitimately long, and worth keeping
     max_keys: int = 256  # per mapping / sequence
     max_depth: int = 8  # nesting levels

{log_foundry-0.7.2.dev2 → log_foundry-0.7.2.dev3}/src/log_foundry/sanitize.py

@@ -55,6 +55,12 @@ _DEPTH_LIMIT = "<depth limit>"
 _LOG10_2_NUM = 30103
 _LOG10_2_DEN = 100000
 
+# ``int.__lt__`` bound once, for the sign test in :meth:`_Coercer.integer` (SPEC-021 FR-003). The
+# unbound slot cannot be diverted by an ``int`` subclass the way ``value < 0`` can, but reaching
+# it through ``int.__lt__`` costs a global plus an attribute lookup on a per-value hot path;
+# binding it here recovers about a third of that, the same idiom as the constants above.
+_INT_LT = int.__lt__
+
 # Exact-type membership, deliberately not ``isinstance``. ``IntEnum``/``StrEnum`` members *are*
 # ``int``/``str`` instances, so an isinstance check would pass the enum member itself through and
 # hand a sink an ``Enum`` where a plain value was promised. Exact typing lets them fall to the
@@ -74,6 +80,11 @@ def _int_digit_ceiling(max_value_bytes: int) -> int:
     raises ``ValueError``, which ``json.dumps`` inherits. A configured ceiling above that cannot be
     honoured — rendering such an integer is the very thing that raises — so the interpreter's limit
     wins whenever it is lower. A limit of ``0`` means the interpreter imposes none.
+
+    The caller measures a negative value's rendered length, sign included, against this; the
+    interpreter's own limit counts digits only. A negative integer sitting exactly on the
+    interpreter bound is therefore replaced rather than rendered — one value at the far edge, in
+    the direction this module always errs (SPEC-021 FR-003).
     """
     limit = sys.get_int_max_str_digits()
     return max_value_bytes if limit <= 0 else min(max_value_bytes, limit)
@@ -278,7 +289,11 @@ class _Coercer:
         The size test is ``bit_length()``, never ``len(str(value))``: converting an over-long
         integer to a string raises the very ``ValueError`` this bound exists to prevent, so the
         obvious check would move the crash rather than remove it (FR-002). ``bit_length()`` is
-        O(1), total, and ignores the sign, so ``n`` and ``-n`` are bounded identically.
+        O(1), total, and ignores the sign — so the minus sign is added back explicitly, since the
+        ceiling measures what the value *renders* as and ``-10**9`` renders as eleven bytes
+        (SPEC-021 FR-003). The placeholder still names the digit count: a sign is not a digit.
+        The sign is read through an *unbound* ``int.__lt__``, which an ``int`` subclass cannot
+        divert; ``bit_length()`` stays the one trusted call, as below.
 
         An over-long integer is *replaced*, not clipped. Dropping digits would silently change the
         value, and a wrong number is worse than a visibly elided one — so this reuses the
@@ -291,7 +306,13 @@ class _Coercer:
         ``type()`` check to catch only a value engineered to lie about itself.
         """
         digits = value.bit_length() * _LOG10_2_NUM // _LOG10_2_DEN + 1
-        if digits <= _int_digit_ceiling(self._cfg.max_value_bytes):
+        # ``_INT_LT`` (unbound ``int.__lt__``), never ``value < 0``: on an ``int`` *subclass* the
+        # operator dispatches to user code, which can raise — and a raise here is caught up in
+        # :meth:`value`, replacing the whole enclosing mapping and taking every sibling key with
+        # it, which is precisely what :meth:`key` was written to prevent. The unbound call reads
+        # the underlying integer and cannot be overridden.
+        rendered = digits + 1 if _INT_LT(value, 0) else digits
+        if rendered <= _int_digit_ceiling(self._cfg.max_value_bytes):
             return value
         self.truncated = True
         return f"<int: ~{digits} digits>"

{log_foundry-0.7.2.dev2 → log_foundry-0.7.2.dev3}/src/log_foundry/worker.py

@@ -308,14 +308,30 @@ class Worker:
         must not be able to ride on it. The exception's *type* is reported and its message is
         not — a sink's exception text can carry event data, and arch §6 keeps caller data out of
         places it was not asked for (the same rule behind ``sanitize``'s type-name placeholder).
+
+        The count reports what was *in hand* and what was still *queued behind it* (SPEC-021
+        FR-002). Held alone under-reads the loss: nothing will drain the queue either, so an
+        operator reading "1 undrained event-list(s)" could conclude far less was lost than was.
+
+        The queued figure is "items", not "event-lists", and says so: like ``Health.queued`` it is
+        read without stopping the world, so it counts any internal flush/shutdown marker sitting
+        alongside real submissions, and a producer thread can add to the queue between the death
+        and the read. It is a floor on what was lost, which is the useful direction.
         """
         name = type(exc).__name__
         with self._lock:
             self.stopped_reason = name
+        try:
+            # In its own guard, and after the record: ``qsize()`` is not guaranteed on every
+            # platform's queue, and a diagnostic must not be the reason the diagnosis is lost.
+            queued: object = self._queue.qsize()
+        except Exception:
+            queued = "?"
         try:
             sys.stderr.write(
                 f"log-foundry: worker thread stopped on {name}; {undrained} undrained "
-                f"event-list(s), nothing further will be delivered\n"
+                f"event-list(s) held and {queued} queued item(s) undelivered, nothing further "
+                f"will be delivered\n"
             )
         except Exception:  # best-effort: the record above is what an operator reads.
             pass