xakki-log-python 0.4.0__py3-none-any.whl

log_python/manager.py

@@ -0,0 +1,394 @@
+"""Core record-enrichment orchestration, ported from `LogManager::appendContext()`
+(reference `src/LogManager.php`, spec `docs/LoggingRules.md` / `docs/ContextFieldNaming.md`,
+both re-verified 2026-08-13). This is the single behavioural hook every other phase feeds
+into: `LogManager.append_context()` takes a level/message/context triple and returns an
+enriched context dict plus the (possibly truncated) message, ready for a formatter
+to render onto the wire. Handler/formatter wiring lives in `log_python.setup()`; this
+module remains framework-agnostic.
+
+## Operation order (verified against `LogManager::appendContext()`, line-by-line)
+
+1. Extract the `LOGGER_SKIP_TRACE` ('skipTrace') marker, cast it through the SAME
+   bool-truthiness convention as every other bool-shaped context field
+   (`context.py`'s `_cast_bool()` / `CONTEXT_FALSE_VALUES`, wired via
+   `trace.should_skip_trace()`), and POP the marker key so it never reaches the wire —
+   this mirrors a fix landed concurrently on the PHP side (uncommitted as of this port,
+   `LogManager::appendContext()` using `contextCastBool()`); see `mapping.md`.
+2. Extract `context['exception']` when it is a real exception instance (and only then —
+   a non-exception value under that key is left alone, exactly like the reference's
+   `instanceof \\Throwable` guard).
+3. `log_type` classification: only when the caller did not already supply one — `logger`
+   by default, promoted to `exception` when an exception is present and the ambient
+   `LogType.current()` origin is still the default.
+4. Context type-coercion (`ContextTypeCorrector`) THEN key-based redaction
+   (`Redactor.should_redact_key`) — in that order, and ONLY in that order. Reference
+   `contextTypeCorrector()` checks `shouldRedactKey()` BEFORE casting a given key, so a
+   sensitive key is masked outright and never cast; running redaction first and coercion
+   second here would be a no-op for THAT ordering, but running coercion first, redaction
+   AFTER (this port's approach), and never re-coercing the masked `"***"` string produces
+   the identical final result — because coercion and (key-based) redaction are mutually
+   exclusive per key, "coerce every key, then overwrite the sensitive ones with the mask"
+   equals "check-then-branch per key". The one order that is WRONG is masking a value
+   BEFORE coercion could see it: `contextCastBool("***")` on a `password_bool` key would
+   come out `True` — a masked value turned back into a coerced one, a real type-stability
+   break the tests in `test_manager.py` pin explicitly (a key that is both sensitive AND
+   suffix-typed must serialize as the string `"***"`, never a cast value).
+5. Exception-derived fields, added to the ALREADY-coerced-and-redacted dict — so these
+   fields bypass coercion and (key-based) redaction entirely, exactly like the reference
+   (`appendContext()` populates them AFTER its own `contextTypeCorrector()` call). See
+   "Exception chain wire shape" below for the field list.
+6. `message_len` — the length of the ORIGINAL, untruncated message. Order matters: the
+   reference computes this BEFORE the message is ever truncated (truncation only happens
+   at the very end, on the RETURNED string, never stored back into `context`).
+7. Caller `file:line` (+ conditionally, call-site `trace`) — ONLY when `'file'` is not
+   already set (i.e., no exception path ran, or it left `'file'` falsy). Delegates to
+   `TraceCapture.capture()`, which already embeds the "no trace below WARNING" cutoff.
+8. Memory fields, only when `allow_memory` is on.
+9. `request_id` — always (re)stamped, unconditionally, from the ambient context var.
+10. Return `(message[:message_limit], enriched_context)`.
+
+## Public-API divergence from the reference (documented, not an oversight)
+
+PHP's `appendContext(Level $level, string|Stringable $message, array &$context): string`
+mutates `$context` by reference and returns only the truncated message. This port instead
+returns `(message, new_context)` — the SAME "never mutate the input, return a new dict"
+convention `ContextTypeCorrector.correct()` and `Redactor.redact()` already established in
+phases 2/3, kept consistent rather than reintroducing PHP's by-reference out-param pattern
+into idiomatic Python.
+"""
+
+from __future__ import annotations
+
+import contextvars
+import math
+import sys
+import tracemalloc
+import uuid
+from collections.abc import Mapping
+from typing import Final
+
+from log_python.config import PylogConfig
+from log_python.const import LOGGER_MEMORY, LOGGER_MEMORY_PEAK, LOGGER_SKIP_TRACE
+from log_python.context import ContextTypeCorrector
+from log_python.logtype import LogType
+from log_python.redactor import Redactor
+from log_python.trace import TraceCapture, exception_class_name, exception_origin, should_skip_trace
+
+# The full `__cause__`/`__context__` chain, coalesced into ONE string field by
+# `TraceCapture.format_exception_chain()` (phase 4) — satisfies spec §6.1's stated intent
+# ("full chain via getPrevious()") alongside the flat, ONE-level `exception_prev*` fields
+# below, which reproduce the reference's ACTUAL (narrower) behaviour 1:1. Deliberately not
+# a `LOGGER_*` constant in `const.py`: that module's contract is "byte-for-byte identical to
+# the PHP reference" (its own docstring, and `test_const.py` asserts each entry against
+# `src/const.php` verbatim) — there is nothing in the PHP source for this field to match,
+# since it has no PHP counterpart at all. Chosen not to collide with any of the seven
+# PHP-defined exception field names.
+EXCEPTION_CHAIN_FIELD: Final[str] = "exception_chain"
+
+_REQUEST_ID: Final[contextvars.ContextVar[str | None]] = contextvars.ContextVar("pylog_request_id", default=None)
+
+
+def get_or_create_request_id() -> str:
+    """Return the current context's request id, generating one on first use.
+
+    Reference `LogManager::getOrCreateRequestId()`: a UUID (or an incoming
+    `X-Request-ID`), pinned to string in the type-coercion table because it may be
+    all-digits and must never flip to int (see `context.py::_RESERVED_RULES`).
+
+    Format: `str(uuid.uuid4())` — a standard RFC 4122 v4 UUID string (lowercase,
+    hyphenated), the same textual shape as Laravel's `Str::uuid()`. This port does not
+    read an inbound `X-Request-ID` header itself (there is no framework-agnostic Python
+    equivalent of PHP's `$_SERVER` superglobal to read from) — a web/worker integration
+    calls `set_request_id()` explicitly instead, e.g. from middleware.
+
+    Scoping divergence (deliberate): the reference's id lives in `$_SERVER`, a single
+    process-global value — correct for PHP-FPM's one-request-per-process model, but a
+    Python process may serve many concurrent requests/tasks on the SAME process (threads,
+    asyncio). A bare global here would leak one request's id into another's log lines
+    running concurrently. `contextvars.ContextVar` gives each thread/async-task context
+    its own value instead, which is a closer match to the spec's own description of
+    `request_id` as "stable within one request" than a literal process-global port would
+    have been.
+    """
+    current = _REQUEST_ID.get()
+    if current:
+        return current
+    new_id = str(uuid.uuid4())
+    _REQUEST_ID.set(new_id)
+    return new_id
+
+
+def set_request_id(request_id: str) -> None:
+    """Seed the current context's request id explicitly — e.g. from an inbound
+    `X-Request-ID` header in a web middleware. No PHP method maps onto this directly;
+    the reference reads `$_SERVER['HTTP_X_REQUEST_ID']` inline inside
+    `getOrCreateRequestId()`, which has no framework-agnostic Python equivalent — this is
+    the explicit seam a caller uses instead.
+    """
+    _REQUEST_ID.set(request_id)
+
+
+def reset_request_id() -> None:
+    """Clear the current context's request id so the next unit of work gets a fresh one.
+
+    Reference `LogManager::resetRequestId()` — the Laravel `JobProcessing` listener
+    (`LaraLogServiceProvider`) becomes this explicit function, which a worker calls
+    between jobs so a long-running process doesn't stamp every job with the same id.
+    """
+    _REQUEST_ID.set(None)
+
+
+def _safe_str(value: object) -> str:
+    """Best-effort `str()`, never raising — used for the log `message` itself, which the
+    public API accepts as `object` specifically so a hostile value (broken `__str__`)
+    degrades to a placeholder rather than blowing up the logging path.
+    """
+    if isinstance(value, str):
+        return value
+    try:
+        return str(value)
+    except Exception:
+        return "<unrenderable message>"
+
+
+def _safe_copy_context(context: Mapping[str, object] | None) -> dict[str, object]:
+    """Shallow-copy the caller's context into a fresh dict this function owns — never
+    mutates the caller's mapping. Wrapped because a hostile custom `Mapping` (broken
+    `__iter__`/`.items()`) must not be able to raise out of the logging path.
+    """
+    if context is None:
+        return {}
+    try:
+        return dict(context)
+    except Exception:
+        return {}
+
+
+def _exception_code(exc: BaseException) -> int:
+    """Python-side derivation of PHP's `(int) $e->getCode()`. Every PHP `Throwable` has a
+    `getCode()` (default `0`); Python's `BaseException` has no universal numeric-code
+    attribute. This reads an optional `.code` attribute (several stdlib exceptions —
+    `SystemExit`, some driver exceptions — already use that name) and coerces it the same
+    tolerant way the reference's `(int)` cast would, falling back to `0` for anything
+    absent, non-numeric, or a raising property.
+    """
+    try:
+        code = getattr(exc, "code", None)
+    except Exception:
+        return 0
+    if isinstance(code, bool):
+        return int(code)
+    if isinstance(code, int):
+        return code
+    if isinstance(code, float):
+        return int(code) if math.isfinite(code) else 0
+    if isinstance(code, str):
+        try:
+            return int(code.strip())
+        except ValueError:
+            return 0
+    return 0
+
+
+def _previous_exception(exc: BaseException) -> BaseException | None:
+    """The exception this port treats as PHP's `$e->getPrevious()` — owner decision:
+    `__cause__` (explicit `raise X from Y`) takes priority over `__context__` (implicit
+    chaining), and an explicit `raise X from None` (`__suppress_context__`) means no
+    previous exception at all, matching Python's own traceback-printing rule and
+    `TraceCapture.format_exception_chain()`'s identical priority (phase 4, `trace.py`).
+    Wrapped because reading dunder attributes off a hostile custom exception subclass
+    (e.g. `__cause__`/`__suppress_context__` as raising properties) must not raise out of
+    the logging path.
+    """
+    try:
+        cause = exc.__cause__
+        if cause is not None:
+            return cause
+        context = exc.__context__
+        if context is not None and not exc.__suppress_context__:
+            return context
+    except Exception:
+        return None
+    return None
+
+
+def _peak_memory_bytes() -> int | None:
+    """Process-wide peak resident set size, in bytes — the closest POSIX analogue of PHP's
+    `memory_get_peak_usage()`, but NOT the same quantity: PHP's figure is the Zend engine's
+    own allocator peak (userland PHP object/array memory), while `ru_maxrss` is the OS's
+    peak RSS for the whole process (interpreter, C extensions, everything). Same field
+    name (`LOGGER_MEMORY_PEAK`), same JSON type (int), genuinely different semantics —
+    documented here and in `mapping.md`, not papered over.
+
+    `resource` is POSIX-only (no Windows build) and imported lazily, inside the `try`,
+    specifically so there is nothing to reassign in an `except` branch — the
+    strict no-suppression rule in `AGENTS.md` rules out the usual conditional
+    import plus assignment-suppression shape,
+    and this local-import form needs no such fallback assignment at all.
+
+    `ru_maxrss` unit differs by platform: kibibytes on Linux, bytes on macOS (`darwin`) —
+    normalized to bytes here so the field means the same thing regardless of host OS,
+    matching the PHP fleet's byte-denominated field.
+    """
+    try:
+        import resource
+    except ImportError:
+        return None
+    try:
+        peak = resource.getrusage(resource.RUSAGE_SELF).ru_maxrss
+    except Exception:
+        return None
+    if sys.platform == "darwin":
+        return int(peak)
+    return int(peak) * 1024
+
+
+def _current_traced_memory_bytes() -> int | None:
+    """Current Python-allocated memory, in bytes, from `tracemalloc` — ONLY when tracing
+    is already active. This library never calls `tracemalloc.start()` itself (a real,
+    measurable hot-path tax for every allocation in the process); when tracing is off the
+    `LOGGER_MEMORY` field is simply omitted from the record rather than emitted as a
+    placeholder, which is fine for the field-type-stability contract (an ABSENT key is not
+    a second JSON type for the same key, only a present-with-wrong-type value would be).
+    """
+    if not tracemalloc.is_tracing():
+        return None
+    try:
+        current, _peak = tracemalloc.get_traced_memory()
+    except Exception:
+        return None
+    return current
+
+
+class LogManager:
+    """Precompiled, reusable enrichment orchestrator (mirrors `Redactor` /
+    `ContextTypeCorrector` / `TraceCapture` — build once per process from a `PylogConfig`,
+    reuse for its lifetime; no per-call recompilation or env re-reads on the hot path).
+
+    `append_context()` is the single public entry point, faithfully porting
+    `LogManager::appendContext()` — see the module docstring for the verified operation
+    order. This class does not touch handler/formatter wiring or install process
+    hooks; it is a pure enrichment function.
+    """
+
+    __slots__ = ("_allow_memory", "_corrector", "_message_limit", "_redactor", "_trace")
+
+    def __init__(self, config: PylogConfig) -> None:
+        self._redactor = Redactor.from_config(config)
+        self._corrector = ContextTypeCorrector.from_config(config)
+        self._trace = TraceCapture.from_config(config, self._redactor)
+        self._message_limit = config.message_limit
+        self._allow_memory = config.allow_memory
+
+    def append_context(self, level: int, message: object, context: Mapping[str, object] | None = None) -> tuple[str, dict[str, object]]:
+        """Enrich `context` for a record at `level` (a stdlib `logging` level int) with
+        `message`. Returns `(message_truncated_to_message_limit, enriched_context)` — see
+        the module docstring for exactly what gets added and in what order.
+
+        Must never raise: `message` and `context` are both treated as untrusted input
+        (hostile `__str__`/`__repr__`, a `Mapping` whose `.items()` raises, a broken
+        exception object, ...). Every raise-prone step ported into this method is wrapped
+        individually (see the private helpers above); this is the one OUTER last-resort
+        net for anything those miss — it still returns a well-formed, minimally-enriched
+        result rather than letting an exception escape the logging path.
+        """
+        safe_message = _safe_str(message)
+        try:
+            return self._append_context(level, safe_message, context)
+        except Exception:
+            return safe_message[: self._message_limit], {
+                "log_type": LogType.LOGGER,
+                "request_id": get_or_create_request_id(),
+            }
+
+    def _append_context(self, level: int, message: str, context: Mapping[str, object] | None) -> tuple[str, dict[str, object]]:
+        working = _safe_copy_context(context)
+
+        # 1. LOGGER_SKIP_TRACE: read, bool-cast, then POP so the marker key never reaches
+        # coercion/redaction/the wire — mirrors the reference's `unset()` of the same key.
+        skip_trace = should_skip_trace(working)
+        working.pop(LOGGER_SKIP_TRACE, None)
+
+        # 2. Extract a real exception only — a non-Throwable-shaped value under
+        # 'exception' is left in place, exactly like `isset(...) && ... instanceof`.
+        raw_exc = working.get("exception")
+        exc: BaseException | None = raw_exc if isinstance(raw_exc, BaseException) else None
+        if exc is not None:
+            del working["exception"]
+
+        # 3. log_type classification — only when the caller did not already supply one.
+        if working.get("log_type") is None:
+            log_type = LogType.current()
+            if exc is not None and log_type == LogType.LOGGER:
+                log_type = LogType.EXCEPTION
+            working["log_type"] = log_type
+
+        # 4. Coercion, THEN key-based redaction — see the module docstring for why this
+        # order (and not the reverse) is the one that matches the reference.
+        enriched = self._coerce_and_redact(working)
+
+        # 5. Exception-derived fields, added AFTER coercion/redaction — bypass both,
+        # exactly like the reference (these are library-computed, already-typed values).
+        if exc is not None:
+            enriched["exception"] = exception_class_name(exc)
+            enriched["exception_message"] = self._redactor.redact_value(_safe_str(exc))
+            enriched["exception_code"] = _exception_code(exc)
+            enriched["file"] = exception_origin(exc)
+            if not skip_trace:
+                enriched["trace"] = self._trace.render_exception_trace(exc)
+                enriched[EXCEPTION_CHAIN_FIELD] = self._trace.format_exception_chain(exc)
+            prev = _previous_exception(exc)
+            if prev is not None:
+                enriched["exception_prev"] = exception_class_name(prev)
+                # Owner-flagged content divergence from the reference: PHP writes
+                # `$e->getPrevious()->getMessage()` verbatim, unredacted. Spec §6.1 itself
+                # calls the exception message "suspect" (PII/log-injection) and offers
+                # "apply the same redactor as for the request body" as an option; this
+                # port takes that option (value-shape `redact_value()`, best-effort, same
+                # mechanism `_render_arg()` already applies to trace arguments) rather
+                # than reproducing the unredacted PHP behaviour. Field NAME and TYPE stay
+                # 1:1 with PHP (still a plain string) — only string CONTENT can differ,
+                # and only when the message happens to match a Bearer/JWT/URL-credential/
+                # key=value shape. Reported to the team-lead as vetoable.
+                enriched["exception_prev_message"] = self._redactor.redact_value(_safe_str(prev))
+                enriched["exception_prev_file"] = exception_origin(prev)
+                enriched["exception_prev_code"] = _exception_code(prev)
+                if not skip_trace:
+                    enriched["exception_prev_trace"] = self._trace.render_exception_trace(prev)
+
+        # 6. message_len: the length of the message BEFORE truncation — computed here,
+        # truncation happens only in the tuple this method returns, at the very end.
+        enriched["message_len"] = len(message)
+
+        # 7. Caller file:line (+ conditionally, call-site trace) — only when 'file' is not
+        # already set (exception path already set it above, when exc is not None).
+        if not enriched.get("file"):
+            captured = self._trace.capture(level)
+            enriched["file"] = captured.file
+            if not skip_trace and not enriched.get("trace") and captured.trace is not None:
+                enriched["trace"] = captured.trace
+
+        # 8. Memory fields, opt-in only.
+        if self._allow_memory:
+            peak = _peak_memory_bytes()
+            if peak is not None:
+                enriched[LOGGER_MEMORY_PEAK] = peak
+            current = _current_traced_memory_bytes()
+            if current is not None:
+                enriched[LOGGER_MEMORY] = current
+
+        # 9. request_id — always (re)stamped, unconditionally.
+        enriched["request_id"] = get_or_create_request_id()
+
+        # 10. Truncate the RETURNED message only; message_len above already reflects the
+        # untruncated length.
+        return message[: self._message_limit], enriched
+
+    def _coerce_and_redact(self, context: Mapping[str, object]) -> dict[str, object]:
+        """`ContextTypeCorrector.correct()` THEN a key-based redaction overlay. See the
+        module docstring's point 4 for why "coerce everything, then overwrite sensitive
+        keys with the mask" is equivalent to (and not "backwards" from) the reference's
+        per-key "check redaction before casting" order.
+        """
+        coerced = self._corrector.correct(context)
+        return {key: (Redactor.MASK if self._redactor.should_redact_key(key) else value) for key, value in coerced.items()}

log_python/redactor.py

@@ -0,0 +1,261 @@
+"""Credential / secret redaction at the process boundary.
+
+Python port of the reference `src/Redactor.php` (xakki/laralog, spec
+`docs/LoggingRules.md` §2 / §2.1). Two complementary modes:
+
+- **by key**: for keyed data (context fields, dict entries) — match the FIELD
+  NAME against a needle list, case-insensitive substring.
+- **by value**: for positional / free-form data (stack-trace arguments,
+  exception args, log messages) where no field name is available — match the
+  VALUE itself against Bearer/Basic-auth headers, JWTs, and
+  ``key=value``/``key: value`` assignments whose key looks sensitive.
+
+Built-in needles are always active; extra needles (e.g. from
+``PylogConfig.redact``) are merged ON TOP of them and never replace them.
+
+This module has zero third-party dependencies (stdlib ``re`` only), per the
+project's zero-runtime-dependency contract for the core.
+
+Deliberate divergences from ``Redactor.php`` (the reference has neither):
+
+- ``redact_value`` also matches a needle key wrapped in a quote (``"key":
+  "value"`` JSON, ``'key' => 'value'`` PHP-array-style) — logging a raw
+  request/response body is routine, so leaving quoted values unredacted was a
+  live gap worth closing in the port even though the reference doesn't.
+- ``redact_value`` also masks the password component of a
+  ``scheme://user:password@host`` URL (host and user are left intact — they
+  are diagnostically useful and not secret).
+
+Known, accepted limitation (same in both languages, not a bug to "discover"
+later): a bare token with no key and no Bearer/Basic/JWT shape — e.g.
+``["Authorization", "Bearer", raw_token]`` split across list elements — is
+never redacted. Catching that would need heuristics over unrelated sibling
+values with unacceptable false-positive risk.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable, Mapping
+from typing import ClassVar, Final
+
+from log_python.config import PylogConfig
+
+MASK: Final[str] = "***"
+
+# High-signal needles only — substring match, so overly-broad tokens (`auth`, `card`,
+# `pin`, `session`) are deliberately excluded to avoid masking legit fields like
+# `cardinality` / `shipping` / `author`. Add narrow project needles via
+# `PylogConfig.redact`. Ported 1:1 from `Redactor.php::BUILTIN` (14 needles,
+# verified against the reference 2026-08-13).
+BUILTIN_NEEDLES: Final[tuple[str, ...]] = (
+    "password",
+    "passwd",
+    "secret",
+    "token",
+    "authorization",
+    "api_key",
+    "apikey",
+    "access_key",
+    "private_key",
+    "credential",
+    "cookie",
+    "cvv",
+    "card_number",
+    "cardnumber",
+)
+
+# Bearer / Basic auth header values. PHP: `/\b(bearer|basic)\s+[A-Za-z0-9._\-\/+=]{8,}/i`.
+# The token-body quantifier is bounded (PHP's `{8,}` is not) as a defensive cap against
+# pathological input sizes. This is safe specifically because it is a TRAILING atom with
+# nothing after it in the pattern: a bound here can only shorten what gets matched for the
+# `.search()` boolean check, never prevent the match outright (as long as >=8 eligible chars
+# exist anywhere, some prefix of them up to the cap still matches). And since a match masks
+# the WHOLE value (see `redact_value` below), a truncated match still fully masks the value
+# — there is no truncation-leak and no false-non-match. Verified 2026-08-13.
+_BEARER_RE: Final[re.Pattern[str]] = re.compile(r"\b(?:bearer|basic)\s+[A-Za-z0-9._\-/+=]{8,4096}", re.IGNORECASE)
+
+# JWT: three base64url segments. PHP: `/\beyJ[A-Za-z0-9_\-]+\.[A-Za-z0-9_\-]+\.[A-Za-z0-9_\-]+/`.
+# Unlike _BEARER_RE, each segment quantifier here is immediately followed by a required
+# literal ('.' or end of string) — so a bound is NOT safe: a payload segment longer than the
+# bound (real JWTs can carry many claims/roles well past 4096 chars) has no position within
+# the bound where the next char is the required '.', so the WHOLE regex silently fails to
+# match — a false non-match that leaks the entire token, worse than any truncation. Verified
+# 2026-08-13 (a >4096-char payload segment was confirmed to defeat the bounded version).
+# Restored unbounded to match the PHP reference exactly.
+_JWT_RE: Final[re.Pattern[str]] = re.compile(r"\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+")
+
+# URL-embedded credentials: `scheme://user:password@host`. Not present in Redactor.php (see
+# module docstring). Only the password is masked; scheme/user/host stay intact for
+# diagnostics.
+_URL_CREDENTIALS_RE: Final[re.Pattern[str]] = re.compile(r"(?P<scheme>[A-Za-z][A-Za-z0-9+.-]*://)(?P<user>[^:/?#\s@]+):(?P<password>[^@/?#\s]+)@")
+
+# Recursion guard for Redactor.redact(). No realistic log payload is this deep; hitting the
+# limit means either a pathological or self-referential structure, so we fail safe (mask)
+# rather than risk leaking an un-inspected branch.
+_MAX_DEPTH: Final[int] = 50
+_CIRCULAR_PLACEHOLDER: Final[str] = "<circular>"
+
+# Hot-path guard for Redactor._redact(): these four types can never carry a secret, so the
+# generic str()-scan fallback is skipped for them entirely. Deliberately a small explicit
+# allow-list (not "isinstance of a numeric ABC" or similar) — Decimal/complex/etc. are NOT
+# listed here on purpose and still go through the str() scan, per project instruction.
+_SKIP_STR_SCAN_TYPES: Final[tuple[type, ...]] = (type(None), bool, int, float)
+
+
+class Redactor:
+    """Precompiled, reusable redaction helper.
+
+    Construct once (needle list + value-pattern regexes are compiled at
+    construction, not per call — this sits on the hot logging path) and reuse
+    for the process lifetime.
+    """
+
+    MASK: ClassVar[str] = MASK
+
+    __slots__ = ("_kv_sub_re", "_needles")
+
+    def __init__(self, needles: Iterable[str] = ()) -> None:
+        """Build the merged, deduplicated, lowercased needle list and precompile regexes.
+
+        Built-in needles always win a place; ``needles`` (e.g. config-supplied
+        extras) are merged ON TOP, never replacing them.
+        """
+        merged: list[str] = []
+        seen: set[str] = set()
+        for needle in (*BUILTIN_NEEDLES, *needles):
+            lowered = needle.strip().lower()
+            if lowered and lowered not in seen:
+                seen.add(lowered)
+                merged.append(lowered)
+        self._needles: tuple[str, ...] = tuple(merged)
+
+        # key=value / key: value / key=>value where key is one of the needles (built-in or
+        # config-supplied). PHP: match `/(needles)\s*[=:]\s*\S+/i` then replace
+        # `/((?:needles)\s*[=:]\s*)\S+/i` with `$1***`. Python `re.sub` already no-ops when
+        # there is no match, so a single substitution call covers both PHP steps.
+        #
+        # The trailing value atom is intentionally UNBOUNDED (`\S+`, not `\S{1,N}`): it is a
+        # simple greedy atom at the end of the pattern with nothing after it to fail on, so it
+        # cannot backtrack catastrophically — a bound here only truncated the capture, leaving
+        # the tail of any secret longer than the bound as literal, unmasked characters right
+        # after the mask (a real leak, not just a theoretical one — verified 2026-08-13).
+        #
+        # Divergence from Redactor.php (documented in the module docstring): an optional quote
+        # right after the needle (closing quote of a JSON/PHP-array key, e.g. `"password":` /
+        # `'token' =>`) and an optional opening quote at the start of the value are both
+        # tolerated, and a quoted value is matched — and replaced, together with its closing
+        # quote — as a single unit, so no dangling quote is ever left behind.
+        alternation = "|".join(re.escape(needle) for needle in self._needles)
+        self._kv_sub_re: re.Pattern[str] = re.compile(
+            rf"((?:{alternation})[\"']?\s*(?:=>|[=:])\s*)(?:\"[^\"]*\"|'[^']*'|\S+)",
+            re.IGNORECASE,
+        )
+
+    @classmethod
+    def from_config(cls, config: PylogConfig) -> Redactor:
+        """Build a Redactor whose extra needles come from `PylogConfig.redact`."""
+        return cls(config.redact)
+
+    @property
+    def needles(self) -> tuple[str, ...]:
+        """The merged, deduplicated, lowercased needle list (built-ins + config extras)."""
+        return self._needles
+
+    def should_redact_key(self, key: str) -> bool:
+        """True if `key` (case-insensitive substring match) contains any needle."""
+        lowered = key.lower()
+        return any(needle in lowered for needle in self._needles)
+
+    def redact_value(self, value: str) -> str:
+        """Best-effort redaction of a positional (key-less) string value.
+
+        Masks the whole value when it looks like a Bearer/Basic auth header or a JWT;
+        otherwise masks the password component of any `scheme://user:password@host` URL
+        (Python-only addition, see module docstring) and the value part of any
+        `needle=...`/`needle: ...`/`needle=>...` assignment (optionally quoted) found
+        inside it, leaving the rest of the string untouched.
+        """
+        if _BEARER_RE.search(value):
+            return MASK
+        if _JWT_RE.search(value):
+            return MASK
+        value = _URL_CREDENTIALS_RE.sub(rf"\g<scheme>\g<user>:{MASK}@", value)
+        return self._kv_sub_re.sub(r"\1" + MASK, value)
+
+    def redact_pair(self, key: str, value: object) -> object:
+        """Redact a single key/value pair: mask outright on a sensitive key, else walk the value."""
+        if self.should_redact_key(key):
+            return MASK
+        return self.redact(value)
+
+    def redact(self, value: object) -> object:
+        """Recursively redact a nested structure (dict/list/tuple/set/scalar/arbitrary object).
+
+        - Mapping: keys matching a needle are masked outright; other values recurse.
+        - list/tuple: every element recurses (list stays a list, tuple stays a tuple).
+        - set/frozenset: every element recurses (type preserved); redacted elements stay
+          hashable (str/tuple/frozenset), so this can never raise.
+        - str: scanned with `redact_value` (Bearer/JWT/URL-credentials/key=value patterns).
+        - bytes/bytearray: decoded (`errors="replace"`, never raises) and scanned the same
+          way; returned as the redacted `str` if anything changed, else as the original
+          object unchanged (callers keep their type when there was nothing to redact).
+        - None/bool/int/float: returned unchanged — these can never carry a secret, so the
+          `str()` scan below is skipped for them as a hot-path guard.
+        - anything else (dataclass, exception, custom class, ...): `str(obj)` is scanned the
+          same way; the redacted **string** is returned only if redaction actually changed
+          it, otherwise the original object is returned unchanged so structure/type survive
+          the overwhelmingly common non-secret case. `str(obj)` is allowed to raise (a
+          broken `__str__`) — caught and failed safe to MASK, since a logging library must
+          never raise from the logging path.
+
+        Guards against unbounded recursion (depth cap, fails safe to MASK) and
+        self-referential containers (identity-tracked, fails safe to a circular marker).
+        """
+        return self._redact(value, seen=frozenset(), depth=0)
+
+    def _redact(self, value: object, *, seen: frozenset[int], depth: int) -> object:
+        if depth >= _MAX_DEPTH:
+            return MASK
+        if isinstance(value, str):
+            return self.redact_value(value)
+        if isinstance(value, bytes | bytearray):
+            decoded = value.decode("utf-8", errors="replace")
+            redacted_text = self.redact_value(decoded)
+            return redacted_text if redacted_text != decoded else value
+        if isinstance(value, Mapping):
+            obj_id = id(value)
+            if obj_id in seen:
+                return _CIRCULAR_PLACEHOLDER
+            next_seen = seen | {obj_id}
+            return {
+                key: (MASK if isinstance(key, str) and self.should_redact_key(key) else self._redact(item, seen=next_seen, depth=depth + 1))
+                for key, item in value.items()
+            }
+        if isinstance(value, list | tuple):
+            obj_id = id(value)
+            if obj_id in seen:
+                return _CIRCULAR_PLACEHOLDER
+            next_seen = seen | {obj_id}
+            items = [self._redact(item, seen=next_seen, depth=depth + 1) for item in value]
+            return items if isinstance(value, list) else tuple(items)
+        if isinstance(value, set | frozenset):
+            obj_id = id(value)
+            if obj_id in seen:
+                return _CIRCULAR_PLACEHOLDER
+            next_seen = seen | {obj_id}
+            # Elements of a set/frozenset are already hashable by construction, and every
+            # branch above returns a hashable type (str, tuple, frozenset, scalar) for a
+            # hashable input, so the rebuilt set/frozenset can never raise TypeError here.
+            redacted_items = {self._redact(item, seen=next_seen, depth=depth + 1) for item in value}
+            return redacted_items if isinstance(value, set) else frozenset(redacted_items)
+        if isinstance(value, _SKIP_STR_SCAN_TYPES):
+            return value
+        try:
+            text = str(value)
+        except Exception:
+            # A logging library must not raise from the logging path just because some
+            # object's __str__ is broken — fail safe to MASK rather than propagate.
+            return MASK
+        redacted_text = self.redact_value(text)
+        return redacted_text if redacted_text != text else value