log-foundry 0.7.1.dev1__tar.gz → 0.7.1.dev2__tar.gz

{log_foundry-0.7.1.dev1 → log_foundry-0.7.1.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: log-foundry
-Version: 0.7.1.dev1
+Version: 0.7.1.dev2
 Summary: Generate logs for your console and JSON events for downstream consumption.
 License-Expression: MIT
 License-File: LICENSE
@@ -743,10 +743,28 @@ Every event is the same shape (arch §6). Boundary events add a few fields:
 | `duration_ms` | span.end | wall time from a monotonic delta |
 | `status` | span.end | `"ok"` or `"error"` |
 | `error` | on failure | `{"type": ..., "stack": ...}` |
+| `truncated` | when a ceiling fired | `true`; absent otherwise, never `false` |
 
 IDs are [W3C Trace Context](https://www.w3.org/TR/trace-context/)-compatible by design, so the
 logs can later correlate with distributed traces cheaply.
 
+### Field values are coerced and bounded
+
+Every value you pass is made JSON-safe and given a size ceiling once, when the event is assembled
+— so no sink can be handed a payload JSON refuses, and no single field can grow without limit.
+Strings are clipped to `max_value_bytes` (8192 by default), mappings and sequences to `max_keys`
+entries and `max_depth` levels. `datetime`, `UUID`, `Decimal`, `bytes` and friends render as
+strings; anything with no JSON form becomes `<unserializable: TypeName>` — the type name only,
+never a `repr`, so coercion can never leak a value the library was careful not to capture.
+
+Integers are the one case worth knowing about. They are passed through unchanged — an ID or an
+amount stays a number, at full precision — but an integer too long to *render* is replaced by
+`<int: ~N digits>`. CPython refuses to convert an integer past `sys.get_int_max_str_digits()`
+decimal digits (**4300** by default) and raises, and `json.dumps` inherits that refusal, so with
+the default configuration the interpreter's limit — not `max_value_bytes` — is what binds. You are
+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.
+
 ## Development
 
 ```bash

{log_foundry-0.7.1.dev1 → log_foundry-0.7.1.dev2}/README.md

@@ -707,10 +707,28 @@ Every event is the same shape (arch §6). Boundary events add a few fields:
 | `duration_ms` | span.end | wall time from a monotonic delta |
 | `status` | span.end | `"ok"` or `"error"` |
 | `error` | on failure | `{"type": ..., "stack": ...}` |
+| `truncated` | when a ceiling fired | `true`; absent otherwise, never `false` |
 
 IDs are [W3C Trace Context](https://www.w3.org/TR/trace-context/)-compatible by design, so the
 logs can later correlate with distributed traces cheaply.
 
+### Field values are coerced and bounded
+
+Every value you pass is made JSON-safe and given a size ceiling once, when the event is assembled
+— so no sink can be handed a payload JSON refuses, and no single field can grow without limit.
+Strings are clipped to `max_value_bytes` (8192 by default), mappings and sequences to `max_keys`
+entries and `max_depth` levels. `datetime`, `UUID`, `Decimal`, `bytes` and friends render as
+strings; anything with no JSON form becomes `<unserializable: TypeName>` — the type name only,
+never a `repr`, so coercion can never leak a value the library was careful not to capture.
+
+Integers are the one case worth knowing about. They are passed through unchanged — an ID or an
+amount stays a number, at full precision — but an integer too long to *render* is replaced by
+`<int: ~N digits>`. CPython refuses to convert an integer past `sys.get_int_max_str_digits()`
+decimal digits (**4300** by default) and raises, and `json.dumps` inherits that refusal, so with
+the default configuration the interpreter's limit — not `max_value_bytes` — is what binds. You are
+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.
+
 ## Development
 
 ```bash

{log_foundry-0.7.1.dev1 → log_foundry-0.7.1.dev2}/pyproject.toml

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

{log_foundry-0.7.1.dev1 → log_foundry-0.7.1.dev2}/src/log_foundry/sanitize.py

@@ -27,6 +27,7 @@ dropped without disclosing it.
 
 from __future__ import annotations
 
+import sys
 from collections.abc import Iterable, Mapping, Sequence
 from datetime import date, datetime, time
 from decimal import Decimal
@@ -47,6 +48,13 @@ _MARKER_BYTES = len(TRUNCATION_MARKER.encode("utf-8"))
 _CIRCULAR = "<circular>"
 _DEPTH_LIMIT = "<depth limit>"
 
+# ``log10(2)`` as an integer ratio, rounded *up*: ``|n| < 2**b``, so ``n`` has at most
+# ``b * _LOG10_2_NUM // _LOG10_2_DEN + 1`` decimal digits. Rounding the ratio up makes that an
+# over-estimate, which is the safe direction — it can replace an integer marginally short of the
+# ceiling, but never admit one past it (SPEC-020 FR-002).
+_LOG10_2_NUM = 30103
+_LOG10_2_DEN = 100000
+
 # 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
@@ -59,6 +67,18 @@ _PLAIN_SCALARS: frozenset[type] = frozenset({int, float, bool})
 _TEXTLIKE: tuple[type, ...] = (str, bytes, bytearray, memoryview)
 
 
+def _int_digit_ceiling(max_value_bytes: int) -> int:
+    """The largest decimal length an integer may have and still be rendered (SPEC-020 FR-001).
+
+    CPython 3.11+ refuses to convert an integer past ``sys.get_int_max_str_digits()`` digits and
+    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.
+    """
+    limit = sys.get_int_max_str_digits()
+    return max_value_bytes if limit <= 0 else min(max_value_bytes, limit)
+
+
 def _measured(value: str) -> bytes:
     """UTF-8 bytes of ``value``, tolerating lone surrogates.
 
@@ -152,7 +172,9 @@ class _Coercer:
         kind = type(value)
         if kind is str:
             return self.text(value)  # type: ignore[arg-type]
-        if kind in _PLAIN_SCALARS:
+        if kind is int:  # before _PLAIN_SCALARS: `int` is the one scalar with no natural ceiling.
+            return self.integer(value)  # type: ignore[arg-type]
+        if kind in _PLAIN_SCALARS:  # float (IEEE-754-bounded) and bool
             return value
         if kind is dict:
             return self.mapping(value, depth)  # type: ignore[arg-type]
@@ -161,6 +183,8 @@ class _Coercer:
 
         if isinstance(value, Enum):
             member = value.value
+            if type(member) is int:  # an IntEnum member is as unbounded as a bare int.
+                return self.integer(member)
             if type(member) in _PLAIN_SCALARS or member is None:
                 return member
             if isinstance(member, str):
@@ -170,7 +194,9 @@ class _Coercer:
             return self.text(str(value))
         if isinstance(value, bool):  # bool before int: it is an int subclass.
             return value
-        if isinstance(value, (int, float)):  # int/float *subclasses* land here.
+        if isinstance(value, int):  # int *subclasses* — bounded like the exact type above.
+            return self.integer(value)
+        if isinstance(value, float):  # float *subclasses*.
             return value
         if isinstance(value, (datetime, date, time)):
             return self.text(value.isoformat())
@@ -231,9 +257,44 @@ class _Coercer:
             self._parents.pop()
 
     def key(self, key: object) -> str:
-        """Coerce a mapping key to a bounded ``str`` — JSON object keys are always strings."""
-        text = key if isinstance(key, str) else str(key)
-        return self.text(text)
+        """Coerce a mapping key to a bounded ``str`` — JSON object keys are always strings.
+
+        An integer key goes through :meth:`integer` first. A bare ``str()`` here would raise on an
+        over-long one — the very ``ValueError`` this module exists to keep away from a sink — and
+        the failure would be caught up in :meth:`value`, replacing the *whole mapping* with a
+        placeholder. One hostile key would take every sibling key with it, unmarked. ``bool`` is
+        excluded because ``True`` must render as the key ``"True"``, not ``"1"``.
+        """
+        if isinstance(key, str):
+            return self.text(key)
+        if isinstance(key, int) and not isinstance(key, bool):
+            rendered = self.integer(key)
+            return self.text(rendered if isinstance(rendered, str) else str(rendered))
+        return self.text(str(key))
+
+    def integer(self, value: int) -> object:
+        """Return ``value`` unchanged, or a placeholder when it is too long to render (FR-001).
+
+        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.
+
+        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
+        type-naming shape of :meth:`_placeholder` rather than inventing a second elision style.
+
+        The bound trusts ``bit_length()``. An ``int`` subclass that overrides it to understate its
+        own magnitude defeats this, and nothing here can tell — the call does not raise, so the
+        totality guard in :meth:`value` never engages either. That is the same trust every coercion
+        rule extends to a subclass's dunders, and narrowing it would cost the common path a
+        ``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):
+            return value
+        self.truncated = True
+        return f"<int: ~{digits} digits>"
 
     def text(self, value: str) -> str:
         """Apply ``max_value_bytes``, recording whether it fired."""