clientwright 0.1.0__tar.gz → 0.2.0__tar.gz

{clientwright-0.1.0 → clientwright-0.2.0}/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [0.2.0](https://github.com/bedrock-python/clientwright/compare/clientwright-v0.1.0...clientwright-v0.2.0) (2026-08-14)
+
+
+### ⚠ BREAKING CHANGES
+
+* add url_masker seam for value-level PII masking, drop dead sensitive_headers knob
+
+### Features
+
+* add url_masker seam for value-level PII masking, drop dead sensitive_headers knob ([90f74fb](https://github.com/bedrock-python/clientwright/commit/90f74fbecaafb77b2405c4d06804e3d7dad91b34))
+
 ## 0.1.0 (2026-08-14)
 
 

{clientwright-0.1.0 → clientwright-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: clientwright
-Version: 0.1.0
+Version: 0.2.0
 Summary: HTTP client platform: one resilience and observability core with adapters for httpx, aiohttp, requests, urllib3 and friends
 Project-URL: Repository, https://github.com/bedrock-python/clientwright
 Project-URL: Documentation, https://bedrock-python.github.io/clientwright/

{clientwright-0.1.0 → clientwright-0.2.0}/clientwright/__init__.py

@@ -52,6 +52,7 @@ from .core.contracts import (
     ClientSettingsProtocol,
     DeadlineSource,
     HeaderProvider,
+    MaskerProtocol,
     RetrySettingsProtocol,
     SpanProtocol,
     TracerProtocol,
@@ -136,6 +137,7 @@ __all__ = [
     "DurationBoundary",
     "FailureKind",
     "HeaderProvider",
+    "MaskerProtocol",
     "Maybe",
     "NativeConfigError",
     "NativeOptions",

clientwright-0.2.0/clientwright/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"  # x-release-please-version

{clientwright-0.1.0 → clientwright-0.2.0}/clientwright/core/config.py

@@ -15,10 +15,13 @@ import logging
 from collections.abc import Mapping
 from dataclasses import dataclass, field
 from enum import StrEnum
-from typing import Final
+from typing import TYPE_CHECKING, Final
 
 from .model import IDEMPOTENT_METHODS, CircuitKey, FailureKind
 
+if TYPE_CHECKING:
+    from .contracts.observability import MaskerProtocol
+
 
 class _Unset:
     """Singleton sentinel distinguishing "user set this" from "default applies"."""
@@ -106,6 +109,9 @@ DEFAULT_TRIP_KINDS: Final = frozenset(
     }
 )
 
+# Not a config knob: clientwright never emits headers into logs or spans, so
+# there is nothing for a header list to protect. Kept as a public default for
+# services that log headers themselves via ``redact_headers``.
 DEFAULT_SENSITIVE_HEADERS: Final = frozenset(
     {
         "authorization",
@@ -261,14 +267,26 @@ _INFO_LEVEL: Final = logging.INFO
 
 @dataclass(frozen=True, slots=True)
 class ObservabilityConfig:
-    """Which telemetry channels are active; only knobs that actually work exist here."""
+    """Which telemetry channels are active; only knobs that actually work exist here.
+
+    Two-stage URL scrubbing before anything reaches a log line or a span:
+    ``sensitive_query_params`` redacts by parameter *name*, then ``url_masker``
+    (if set) sees the whole redacted URL and may scrub PII by *value* - the
+    email in a path segment that no name list can catch. See
+    :class:`~clientwright.core.contracts.observability.MaskerProtocol` for the
+    failure contract.
+    """
 
     logging: bool = True
     metrics: bool = True
     tracing: bool = True
     success_log_level: int = _INFO_LEVEL
-    sensitive_headers: frozenset[str] = DEFAULT_SENSITIVE_HEADERS
     sensitive_query_params: frozenset[str] = DEFAULT_SENSITIVE_QUERY_PARAMS
+    url_masker: MaskerProtocol | None = None
+
+    def __post_init__(self) -> None:
+        if self.url_masker is not None and not callable(self.url_masker):
+            raise ValueError(f"observability.url_masker must be callable or None, got {self.url_masker!r}")
 
 
 @dataclass(frozen=True, slots=True)

{clientwright-0.1.0 → clientwright-0.2.0}/clientwright/core/contracts/__init__.py

@@ -9,6 +9,7 @@ from .message import RequestView as RequestView
 from .message import ResponseView as ResponseView
 from .message import SyncNormalizer as SyncNormalizer
 from .observability import ClientMetricsProtocol as ClientMetricsProtocol
+from .observability import MaskerProtocol as MaskerProtocol
 from .observability import SpanProtocol as SpanProtocol
 from .observability import TracerProtocol as TracerProtocol
 from .settings import CircuitBreakerSettingsProtocol as CircuitBreakerSettingsProtocol
@@ -24,6 +25,7 @@ __all__ = [
     "ClientSettingsProtocol",
     "DeadlineSource",
     "HeaderProvider",
+    "MaskerProtocol",
     "RequestView",
     "ResponseView",
     "RetrySettingsProtocol",

{clientwright-0.1.0 → clientwright-0.2.0}/clientwright/core/contracts/observability.py

@@ -69,6 +69,24 @@ class ClientMetricsProtocol(Protocol):
     def record_uninstrumented_call(self, *, service: str, adapter: str, seam: str) -> None: ...
 
 
+@runtime_checkable
+class MaskerProtocol(Protocol):
+    """Value-level masker applied to telemetry strings before they are emitted.
+
+    The key-based redaction (``sensitive_query_params``) runs first; the masker
+    then sees the whole string and may scrub PII that key lists cannot reach -
+    an email in a path segment, a card number in a free-form value. Any
+    ``(str) -> str`` callable qualifies: a regex substitution, a
+    format-preserving masker, a locally hosted NER model.
+
+    Contract: synchronous, and cheap enough to run 2-3 times per HTTP call.
+    A raising masker never breaks the request - the emitter replaces the whole
+    value with ``[redacted]`` (fail closed) and warns once per client.
+    """
+
+    def __call__(self, value: str) -> str: ...
+
+
 @runtime_checkable
 class SpanProtocol(Protocol):
     """One client span; ended exactly once, in a finally block."""
@@ -89,4 +107,4 @@ class TracerProtocol(Protocol):
     def inject_context(self, headers: MutableMapping[str, str]) -> None: ...
 
 
-__all__ = ["ClientMetricsProtocol", "SpanProtocol", "TracerProtocol"]
+__all__ = ["ClientMetricsProtocol", "MaskerProtocol", "SpanProtocol", "TracerProtocol"]

{clientwright-0.1.0 → clientwright-0.2.0}/clientwright/core/telemetry/emitter.py

@@ -15,7 +15,7 @@ from ..contracts.observability import ClientMetricsProtocol, SpanProtocol, Trace
 from ..model import Attempt, Outcome, RequestInfo
 from .names import OUTCOME_SUCCESS, ROUTE_UNKNOWN, STATUS_NONE
 from .null import NullMetrics, NullTracer
-from .redaction import redact_url
+from .redaction import REDACTED, redact_url
 
 
 def outcome_label(outcome: Outcome) -> str:
@@ -57,13 +57,26 @@ class ClientTelemetry:
         self._tracer: TracerProtocol = tracer if (tracer and config.tracing) else NullTracer()
         self._logger = logging.getLogger(f"clientwright.client.{service}")
         self._log_enabled = config.logging
+        self._masker_warned = False
 
     @property
     def tracer(self) -> TracerProtocol:
         return self._tracer
 
     def _safe_url(self, info: RequestInfo) -> str:
-        return redact_url(info.url, self._config.sensitive_query_params)
+        url = redact_url(info.url, self._config.sensitive_query_params)
+        masker = self._config.url_masker
+        if masker is None:
+            return url
+        # Fail closed: a broken masker must not publish the raw URL, and must
+        # not break the request either. Warn once per client, not per call.
+        try:
+            return masker(url)
+        except Exception:
+            if not self._masker_warned:
+                self._masker_warned = True
+                self._logger.warning("url_masker raised; emitting [redacted] instead of the URL", exc_info=True)
+            return REDACTED
 
     def call_start(self, info: RequestInfo, started: float) -> CallObservation:
         span = self._tracer.start_span(

clientwright-0.2.0/tests/unit/core/telemetry/test_masking.py

@@ -0,0 +1,140 @@
+"""Value-level URL masking: the MaskerProtocol seam in the emitter."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+from urllib.parse import quote_plus
+
+import pytest
+
+from clientwright.core.config import ObservabilityConfig
+from clientwright.core.model import Outcome, RequestInfo
+from clientwright.core.telemetry.emitter import ClientTelemetry
+from clientwright.core.telemetry.redaction import REDACTED
+
+# redact_url reassembles the query with urlencode, so the marker comes out
+# percent-encoded inside URLs.
+REDACTED_IN_URL = quote_plus(REDACTED)
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+INFO = RequestInfo(
+    method="GET",
+    origin="https://a:443",
+    url="https://a/users/alex@example.com/orders?token=x",
+    route="/users/{id}/orders",
+)
+
+
+@dataclass(slots=True)
+class RecordingSpan:
+    attributes: dict[str, object] = field(default_factory=dict)
+    ended: bool = False
+
+    def set_attribute(self, key: str, value: str | int | float | bool) -> None:
+        self.attributes[key] = value
+
+    def record_failure(self, description: str) -> None:
+        self.attributes["failure"] = description
+
+    def end(self) -> None:
+        self.ended = True
+
+
+@dataclass(slots=True)
+class RecordingTracer:
+    spans: list[RecordingSpan] = field(default_factory=list)
+
+    def start_span(self, name: str, *, attributes: Mapping[str, str | int | float | bool]) -> RecordingSpan:
+        span = RecordingSpan(attributes=dict(attributes))
+        self.spans.append(span)
+        return span
+
+    def inject_context(self, headers: dict[str, str]) -> None:  # pragma: no cover - unused
+        return
+
+
+def telemetry(config: ObservabilityConfig, tracer: RecordingTracer | None = None) -> ClientTelemetry:
+    return ClientTelemetry(service="svc", adapter="fake", seam="test", config=config, metrics=None, tracer=tracer)
+
+
+# --- masker applied ---
+
+
+def test__masker__runs_after_query_redaction_and_reaches_span_and_log(caplog: pytest.LogCaptureFixture) -> None:
+    seen: list[str] = []
+
+    def masker(value: str) -> str:
+        seen.append(value)
+        return value.replace("alex@example.com", "***")
+
+    tracer = RecordingTracer()
+    config = ObservabilityConfig(sensitive_query_params=frozenset({"token"}), url_masker=masker)
+    emitter = telemetry(config, tracer)
+
+    with caplog.at_level(logging.DEBUG, logger="clientwright.client.svc"):
+        observation = emitter.call_start(INFO, started=0.0)
+        emitter.call_end(observation, INFO, Outcome(kind=None, status_code=200), duration=0.1)
+
+    # The masker saw the query already redacted by name - never the raw token.
+    assert seen and all("token=x" not in value for value in seen)
+    assert all(f"token={REDACTED_IN_URL}" in value for value in seen)
+    # PII in the path segment is gone from the span and from every log record.
+    masked = f"https://a/users/***/orders?token={REDACTED_IN_URL}"
+    assert tracer.spans[0].attributes["url.full"] == masked
+    urls = [record.url for record in caplog.records if hasattr(record, "url")]
+    assert urls and all(url == masked for url in urls)
+
+
+def test__masker_none__url_unchanged_beyond_query_redaction() -> None:
+    tracer = RecordingTracer()
+    config = ObservabilityConfig(sensitive_query_params=frozenset({"token"}))
+    emitter = telemetry(config, tracer)
+    observation = emitter.call_start(INFO, started=0.0)
+    emitter.call_end(observation, INFO, Outcome(kind=None, status_code=200), duration=0.1)
+    assert tracer.spans[0].attributes["url.full"] == f"https://a/users/alex@example.com/orders?token={REDACTED_IN_URL}"
+
+
+# --- fail closed ---
+
+
+def test__masker_raises__emits_redacted_and_never_breaks_the_call(caplog: pytest.LogCaptureFixture) -> None:
+    def broken(value: str) -> str:
+        raise RuntimeError("model not loaded")
+
+    tracer = RecordingTracer()
+    emitter = telemetry(ObservabilityConfig(url_masker=broken), tracer)
+
+    with caplog.at_level(logging.DEBUG, logger="clientwright.client.svc"):
+        observation = emitter.call_start(INFO, started=0.0)
+        emitter.call_end(observation, INFO, Outcome(kind=None, status_code=200), duration=0.1)
+
+    # Fail closed: the raw URL is not published anywhere.
+    assert tracer.spans[0].attributes["url.full"] == REDACTED
+    assert all("alex@example.com" not in str(getattr(record, "url", "")) for record in caplog.records)
+    assert tracer.spans[0].ended
+
+
+def test__masker_raises__warns_once_per_client_not_per_call(caplog: pytest.LogCaptureFixture) -> None:
+    def broken(value: str) -> str:
+        raise RuntimeError("boom")
+
+    emitter = telemetry(ObservabilityConfig(url_masker=broken))
+    with caplog.at_level(logging.WARNING, logger="clientwright.client.svc"):
+        for _ in range(3):
+            observation = emitter.call_start(INFO, started=0.0)
+            emitter.call_end(observation, INFO, Outcome(kind=None, status_code=200), duration=0.1)
+    warnings = [record for record in caplog.records if record.levelno == logging.WARNING]
+    assert len(warnings) == 1
+    assert "url_masker" in warnings[0].getMessage()
+
+
+# --- config validation ---
+
+
+def test__url_masker_not_callable__rejected_at_config_time() -> None:
+    with pytest.raises(ValueError, match="url_masker must be callable"):
+        ObservabilityConfig(url_masker="not-a-callable")  # type: ignore[arg-type]

clientwright-0.1.0/clientwright/__version__.py

@@ -1 +0,0 @@
-__version__ = "0.1.0"  # x-release-please-version