clientwright 0.1.0__tar.gz → 0.2.1__tar.gz

clientwright-0.2.1/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+## [0.2.1](https://github.com/bedrock-python/clientwright/compare/clientwright-v0.2.0...clientwright-v0.2.1) (2026-09-06)
+
+
+### Bug Fixes
+
+* retry gating, native override reporting and connection metrics ([#21](https://github.com/bedrock-python/clientwright/issues/21)) ([b82e2dd](https://github.com/bedrock-python/clientwright/commit/b82e2dd886fd049f1f5d4ae8c169bdabe599d585))
+
+## [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)
+
+
+### Features
+
+* initial release ([14d4ee6](https://github.com/bedrock-python/clientwright/commit/14d4ee6eba85e6bfb5445b75393891f45cd9878d))
+
+## Changelog
+
+All notable changes to this project are documented in this file.
+
+This file is generated by [Release Please](https://github.com/googleapis/release-please)
+from [Conventional Commits](https://www.conventionalcommits.org/) — do not edit it by hand.
+The project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html); while the
+version is `0.x`, minor releases may contain breaking changes.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: clientwright
-Version: 0.1.0
+Version: 0.2.1
 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/
@@ -95,6 +95,15 @@ handle = inspect(client)  # what actually got applied
 print(handle.report.dropped)  # config the adapter could not express
 ```
 
+> [!TIP]
+> **Building this with an AI assistant?** Hand it
+> **[one page](https://bedrock-python.github.io/clientwright/agents/)** instead of the
+> whole site: the whole public API with its real defaults, where the boundary between the
+> core engine and an adapter runs, the rules that break code when they are broken, the
+> mistakes models actually make with this API, and a map of which page to fetch for the
+> rest. Every docs page is also served as raw Markdown at its own URL, and a **Copy page**
+> button at the top of each one hands it straight to a chat window.
+
 ## Why
 
 - **Instrumentation under the public API.** The seam sits in the transport

{clientwright-0.1.0 → clientwright-0.2.1}/README.md

@@ -38,6 +38,15 @@ handle = inspect(client)  # what actually got applied
 print(handle.report.dropped)  # config the adapter could not express
 ```
 
+> [!TIP]
+> **Building this with an AI assistant?** Hand it
+> **[one page](https://bedrock-python.github.io/clientwright/agents/)** instead of the
+> whole site: the whole public API with its real defaults, where the boundary between the
+> core engine and an adapter runs, the rules that break code when they are broken, the
+> mistakes models actually make with this API, and a map of which page to fetch for the
+> rest. Every docs page is also served as raw Markdown at its own URL, and a **Copy page**
+> button at the top of each one hands it straight to a chat window.
+
 ## Why
 
 - **Instrumentation under the public API.** The seam sits in the transport

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

@@ -52,6 +52,7 @@ from .core.contracts import (
     ClientSettingsProtocol,
     DeadlineSource,
     HeaderProvider,
+    MaskerProtocol,
     RetrySettingsProtocol,
     SpanProtocol,
     TracerProtocol,
@@ -73,6 +74,7 @@ from .core.model import IDEMPOTENT_METHODS, CircuitKey, FailureKind, Outcome, Re
 from .core.options import CallOptions, call_options, current_call_options
 from .core.plan import ClientHandle, ClientRuntime, inspect_client
 from .core.registry import register_adapter, registered_adapters, resolve_adapter
+from .core.telemetry.redaction import redact_headers
 
 # The builders are typed ``Any`` deliberately. The whole product is "you get the
 # REAL native client", and the core cannot name ``httpx.AsyncClient`` without
@@ -136,6 +138,7 @@ __all__ = [
     "DurationBoundary",
     "FailureKind",
     "HeaderProvider",
+    "MaskerProtocol",
     "Maybe",
     "NativeConfigError",
     "NativeOptions",
@@ -173,6 +176,7 @@ __all__ = [
     "inspect",
     "inspect_client",
     "is_set",
+    "redact_headers",
     "register_adapter",
     "registered_adapters",
     "resolve_adapter",

clientwright-0.2.1/clientwright/__version__.py

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

{clientwright-0.1.0 → clientwright-0.2.1}/clientwright/adapters/_httpx_shared.py

@@ -30,7 +30,7 @@ from ..core.engine.aio import AsyncAttemptEngine
 from ..core.engine.sync import SyncAttemptEngine
 from ..core.errors import CallError, CircuitOpenError, DeadlineExceededError, TooManyRedirectsError
 from ..core.model import IDEMPOTENT_METHODS, ConnMetrics, FailureKind, Outcome, RequestInfo, ResolvedTimeouts, origin_of
-from ..core.native import validate_native
+from ..core.native import accepted_overrides, validate_native
 from ..core.plan import CallPlan, ClientHandle, ClientRuntime, compile_plan, register_handle
 from ..core.policy.timeout import base_timeouts
 from ..core.telemetry.emitter import ClientTelemetry
@@ -622,7 +622,7 @@ class FamilyAdapter:
             config_conflicts={},
         )
 
-    def _compile(self, config: ClientConfig, *, sync: bool) -> CallPlan:
+    def _compile(self, config: ClientConfig, native: Mapping[str, Mapping[str, Any]], *, sync: bool) -> CallPlan:
         applied = {
             Capability.TIMEOUT_CONNECT,
             Capability.TIMEOUT_READ,
@@ -657,6 +657,7 @@ class FamilyAdapter:
             applied_natively=frozenset(applied),
             emulated=frozenset(emulated),
             dropped=dropped,
+            native_overrides=accepted_overrides(native),
         )
         plan.report.enforce(config.on_unsupported)
         return plan
@@ -699,7 +700,7 @@ class FamilyAdapter:
         runtime = deps.runtime or ClientRuntime.for_config(
             config, clock=deps.clock, circuit_listener=telemetry.circuit_state_changed
         )
-        plan = self._compile(config, sync=False)
+        plan = self._compile(config, native, sync=False)
         base = base_timeouts(config.timeout, NATIVE_TIMEOUT_DEFAULTS)
         engine = AsyncAttemptEngine(
             plan=plan,
@@ -756,7 +757,7 @@ class FamilyAdapter:
         runtime = deps.runtime or ClientRuntime.for_config(
             config, clock=deps.clock, circuit_listener=telemetry.circuit_state_changed
         )
-        plan = self._compile(config, sync=True)
+        plan = self._compile(config, native, sync=True)
         base = base_timeouts(config.timeout, NATIVE_TIMEOUT_DEFAULTS)
         engine = SyncAttemptEngine(
             plan=plan,

{clientwright-0.1.0 → clientwright-0.2.1}/clientwright/adapters/aiohttp/adapter.py

@@ -24,7 +24,7 @@ from ...core.contracts.adapter import AdapterDeps
 from ...core.engine.aio import AsyncAttemptEngine
 from ...core.errors import UnsupportedCapabilityError
 from ...core.model import ResolvedTimeouts
-from ...core.native import validate_native
+from ...core.native import accepted_overrides, validate_native
 from ...core.plan import CallPlan, ClientHandle, ClientRuntime, compile_plan, register_handle
 from ...core.policy.timeout import base_timeouts
 from ...core.telemetry.emitter import ClientTelemetry
@@ -116,7 +116,7 @@ class AiohttpAdapter:
             config_conflicts={},
         )
 
-    def _compile(self, config: ClientConfig) -> CallPlan:
+    def _compile(self, config: ClientConfig, native: Mapping[str, Mapping[str, Any]]) -> CallPlan:
         applied = {
             Capability.TIMEOUT_CONNECT,
             Capability.TIMEOUT_READ,
@@ -146,6 +146,7 @@ class AiohttpAdapter:
             applied_natively=frozenset(applied),
             emulated=frozenset(emulated),
             dropped=dropped,
+            native_overrides=accepted_overrides(native),
         )
         plan.report.enforce(config.on_unsupported)
         return plan
@@ -179,7 +180,7 @@ class AiohttpAdapter:
         runtime = deps.runtime or ClientRuntime.for_config(
             config, clock=deps.clock, circuit_listener=telemetry.circuit_state_changed
         )
-        plan = self._compile(config)
+        plan = self._compile(config, native)
         base = base_timeouts(config.timeout, _NATIVE_TIMEOUT_DEFAULTS)
         engine = AsyncAttemptEngine(
             plan=plan,

{clientwright-0.1.0 → clientwright-0.2.1}/clientwright/adapters/requests/adapter.py

@@ -25,7 +25,7 @@ from ...core.engine.suppress import is_suppressed, suppressed
 from ...core.engine.sync import SyncAttemptEngine
 from ...core.errors import UnsupportedCapabilityError
 from ...core.model import ResolvedTimeouts
-from ...core.native import validate_native
+from ...core.native import accepted_overrides, validate_native
 from ...core.plan import CallPlan, ClientHandle, ClientRuntime, compile_plan, register_handle
 from ...core.telemetry.emitter import ClientTelemetry
 from ._imports import HTTPAdapter, requests, urllib3
@@ -111,7 +111,7 @@ class RequestsAdapter:
             config_conflicts={},
         )
 
-    def _compile(self, config: ClientConfig) -> CallPlan:
+    def _compile(self, config: ClientConfig, native: Mapping[str, Mapping[str, Any]]) -> CallPlan:
         applied = {Capability.TIMEOUT_CONNECT, Capability.TIMEOUT_READ, Capability.REDIRECTS_OWNABLE}
         if resolve(config.pool.max_connections_per_host, None) is not None:
             applied.add(Capability.POOL_LIMIT_PER_HOST)
@@ -136,6 +136,7 @@ class RequestsAdapter:
             applied_natively=frozenset(applied),
             emulated=frozenset(emulated),
             dropped=dropped,
+            native_overrides=accepted_overrides(native),
         )
         plan.report.enforce(config.on_unsupported)
         return plan
@@ -155,7 +156,7 @@ class RequestsAdapter:
         runtime = deps.runtime or ClientRuntime.for_config(
             config, clock=deps.clock, circuit_listener=telemetry.circuit_state_changed
         )
-        plan = self._compile(config)
+        plan = self._compile(config, native)
         engine = SyncAttemptEngine(
             plan=plan,
             runtime=runtime,

{clientwright-0.1.0 → clientwright-0.2.1}/clientwright/adapters/urllib3/adapter.py

@@ -24,7 +24,7 @@ from ...core.engine.suppress import is_suppressed, suppressed
 from ...core.engine.sync import SyncAttemptEngine
 from ...core.errors import UnsupportedCapabilityError
 from ...core.model import ResolvedTimeouts
-from ...core.native import validate_native
+from ...core.native import accepted_overrides, validate_native
 from ...core.plan import CallPlan, ClientHandle, ClientRuntime, compile_plan, register_handle
 from ...core.policy.timeout import base_timeouts
 from ...core.telemetry.emitter import ClientTelemetry
@@ -141,7 +141,7 @@ class Urllib3Adapter:
             config_conflicts={},
         )
 
-    def _compile(self, config: ClientConfig) -> CallPlan:
+    def _compile(self, config: ClientConfig, native: Mapping[str, Mapping[str, Any]]) -> CallPlan:
         per_host = resolve(config.pool.max_connections_per_host, None)
         applied = {Capability.TIMEOUT_CONNECT, Capability.TIMEOUT_READ, Capability.REDIRECTS_OWNABLE}
         if per_host is not None:
@@ -172,6 +172,7 @@ class Urllib3Adapter:
             applied_natively=frozenset(applied),
             emulated=frozenset(emulated),
             dropped=dropped,
+            native_overrides=accepted_overrides(native),
         )
         plan.report.enforce(config.on_unsupported)
         return plan
@@ -215,7 +216,7 @@ class Urllib3Adapter:
         runtime = deps.runtime or ClientRuntime.for_config(
             config, clock=deps.clock, circuit_listener=telemetry.circuit_state_changed
         )
-        plan = self._compile(config)
+        plan = self._compile(config, native)
         engine = SyncAttemptEngine(
             plan=plan,
             runtime=runtime,

{clientwright-0.1.0 → clientwright-0.2.1}/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.1}/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.1}/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.1}/clientwright/core/engine/aio.py

@@ -214,10 +214,11 @@ class AsyncAttemptEngine:
                 duration=runtime.clock() - attempt_started,
                 outcome=outcome,
                 hop=observation.hops,
+                conn=self._norm.conn_metrics(response) if response is not None else None,
             )
             history.append(attempt)
             if plan.emit_attempt_metrics:
-                self._telemetry.attempt_end(info, attempt)
+                self._telemetry.attempt_end(observation, info, attempt)
             if outcome.kind is FailureKind.TOTAL_TIMEOUT and deadline.expired:
                 raise DeadlineExceededError(deadline.total or 0.0) from outcome.exception
             if plan.retry_policy is None:

{clientwright-0.1.0 → clientwright-0.2.1}/clientwright/core/engine/sync.py

@@ -209,10 +209,11 @@ class SyncAttemptEngine:
                 duration=runtime.clock() - attempt_started,
                 outcome=outcome,
                 hop=observation.hops,
+                conn=self._norm.conn_metrics(response) if response is not None else None,
             )
             history.append(attempt)
             if plan.emit_attempt_metrics:
-                self._telemetry.attempt_end(info, attempt)
+                self._telemetry.attempt_end(observation, info, attempt)
             if outcome.kind is FailureKind.TOTAL_TIMEOUT and deadline.expired:
                 raise DeadlineExceededError(deadline.total or 0.0) from outcome.exception
             if plan.retry_policy is None:

{clientwright-0.1.0 → clientwright-0.2.1}/clientwright/core/errors.py

@@ -93,7 +93,15 @@ class TooManyRedirectsError(CallError):
 
 
 class NotReplayableError(CallError):
-    """The request body cannot be replayed, so the required repeat is impossible."""
+    """A body that cannot be replayed made a required repeat impossible.
+
+    The engine never raises this. A non-replayable body ends the call with the
+    response it already has plus a ``retry_skipped{reason="non_replayable"}``
+    counter, so ``except NotReplayableError`` around a call never fires. It is
+    part of the public ``CallError`` family for adapters and callers that choose
+    to make that refusal fatal themselves; the adapter translators pass it
+    through unchanged rather than dressing it in an SDK error class.
+    """
 
 
 __all__ = [

{clientwright-0.1.0 → clientwright-0.2.1}/clientwright/core/native.py

@@ -81,4 +81,9 @@ def validate_native(
     return validated
 
 
-__all__ = ["validate_native"]
+def accepted_overrides(validated: Mapping[str, Mapping[str, object]]) -> dict[str, tuple[str, ...]]:
+    """Report shape of validated passthrough: slot -> the keys that survived validation."""
+    return {slot: tuple(sorted(values)) for slot, values in validated.items() if values}
+
+
+__all__ = ["accepted_overrides", "validate_native"]

{clientwright-0.1.0 → clientwright-0.2.1}/clientwright/core/policy/retry.py

@@ -11,7 +11,7 @@ from dataclasses import dataclass
 from random import Random
 
 from ..config import RetryConfig
-from ..model import Attempt, FailureKind, RequestInfo
+from ..model import IDEMPOTENT_METHODS, Attempt, FailureKind, RequestInfo
 
 # A retry whose backoff would land this close to the deadline is pointless.
 _DEADLINE_SLACK = 0.001
@@ -40,6 +40,20 @@ class DefaultRetryPolicy:
             return f"kind_{kind.value}"
         return None
 
+    def _method_allows_retry(self, info: RequestInfo) -> bool:
+        """Two vetoes on repeating this method, either of which is enough.
+
+        ``RequestInfo.idempotent`` restates the method's RFC default unless the
+        CALL SITE overrode it, so a flag disagreeing with ``IDEMPOTENT_METHODS``
+        is the call site talking and decides on its own - that is what makes
+        ``idempotent=True`` unlock a POST and ``idempotent=False`` veto a GET.
+        A flag that only restates the default leaves the decision with the
+        operator's ``retry.methods``.
+        """
+        if info.idempotent != (info.method in IDEMPOTENT_METHODS):
+            return info.idempotent
+        return info.method in self._config.methods
+
     def _backoff(self, attempt_index: int, retry_after: float | None, rng: Random) -> float:
         config = self._config
         if config.respect_retry_after and retry_after is not None:
@@ -67,7 +81,7 @@ class DefaultRetryPolicy:
             return RetryDecision(retry=False, reason="final")
         if len(history) >= config.max_attempts:
             return RetryDecision(retry=False, reason="attempts")
-        if info.method not in config.methods and not info.idempotent:
+        if not self._method_allows_retry(info):
             return RetryDecision(retry=False, reason="method")
         if config.require_replayable_body and not replayable:
             return RetryDecision(retry=False, reason="non_replayable")

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

@@ -12,10 +12,10 @@ from dataclasses import dataclass
 
 from ..config import ObservabilityConfig
 from ..contracts.observability import ClientMetricsProtocol, SpanProtocol, TracerProtocol
-from ..model import Attempt, Outcome, RequestInfo
+from ..model import Attempt, ConnMetrics, 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(
@@ -84,7 +97,7 @@ class ClientTelemetry:
             )
         return CallObservation(span=span, started=started)
 
-    def attempt_end(self, info: RequestInfo, attempt: Attempt) -> None:
+    def attempt_end(self, observation: CallObservation, info: RequestInfo, attempt: Attempt) -> None:
         self._metrics.record_attempt(
             service=self._service,
             adapter=self._adapter,
@@ -94,6 +107,25 @@ class ClientTelemetry:
             outcome=outcome_label(attempt.outcome),
             duration=attempt.duration,
         )
+        if attempt.conn is not None:
+            self._record_conn(observation.span, attempt.conn)
+
+    def _record_conn(self, span: SpanProtocol, conn: ConnMetrics) -> None:
+        """Connection timings onto the call span; the last attempt that saw them wins.
+
+        The metric families are a frozen contract with no room for them, so the
+        span is where an adapter that can observe them surfaces them.
+        """
+        for key, value in (
+            ("http.connection.dns_duration", conn.dns),
+            ("http.connection.connect_duration", conn.connect),
+            ("http.connection.tls_duration", conn.tls),
+            ("http.connection.pool_wait_duration", conn.pool_wait),
+            ("http.connection.reused", conn.reused),
+            ("network.protocol.version", conn.http_version),
+        ):
+            if value is not None:
+                span.set_attribute(key, value)
 
     def redirect_hop(self, observation: CallObservation) -> None:
         observation.hops += 1

{clientwright-0.1.0 → clientwright-0.2.1}/tests/helpers/engine.py

@@ -22,10 +22,11 @@ from clientwright.core.capabilities import (
 )
 from clientwright.core.config import ClientConfig, RetryConfig
 from clientwright.core.contracts.adapter import AdapterDeps
+from clientwright.core.contracts.observability import TracerProtocol
 from clientwright.core.engine.aio import AsyncAttemptEngine
 from clientwright.core.engine.base import default_response_outcome
 from clientwright.core.engine.sync import SyncAttemptEngine
-from clientwright.core.model import FailureKind, Outcome, RequestInfo, ResolvedTimeouts, origin_of
+from clientwright.core.model import ConnMetrics, FailureKind, Outcome, RequestInfo, ResolvedTimeouts, origin_of
 from clientwright.core.plan import ClientRuntime, compile_plan
 from clientwright.core.telemetry.emitter import ClientTelemetry
 from clientwright.core.testing import RecordingMetrics
@@ -182,12 +183,13 @@ def as_async_send(script: ScriptedSend) -> Callable[[EngineRequest], Any]:
 class FakeNormalizer:
     """Both normalizer flavors in one object; the request/response ARE the views."""
 
-    def __init__(self, *, freeze_ok: bool = True) -> None:
+    def __init__(self, *, freeze_ok: bool = True, conn: ConnMetrics | None = None) -> None:
         self.freeze_ok = freeze_ok
         self.freezes = 0
         self.rewinds = 0
         self.discards = 0
         self.wrapped_streams = 0
+        self.conn = conn
 
     def wrap_request(self, native: Any) -> EngineRequest:
         assert isinstance(native, EngineRequest)
@@ -212,8 +214,8 @@ class FakeNormalizer:
     def wrap_stream(self, response: FakeResponse, on_done: Callable[[Outcome, float], None]) -> None:
         self.wrapped_streams += 1
 
-    def conn_metrics(self, response: FakeResponse) -> None:
-        return None
+    def conn_metrics(self, response: FakeResponse) -> ConnMetrics | None:
+        return self.conn
 
     # -- sync flavor -------------------------------------------------------
 
@@ -261,6 +263,8 @@ class Harness:
         freeze_ok: bool = True,
         sync: bool = False,
         clock: Callable[[], float] | None = None,
+        tracer: TracerProtocol | None = None,
+        conn: ConnMetrics | None = None,
     ) -> None:
         self.config = config
         self.metrics = RecordingMetrics()
@@ -273,11 +277,11 @@ class Harness:
             seam="test",
             config=config.observability,
             metrics=self.metrics,
-            tracer=None,
+            tracer=tracer,
         )
         self.normalizer: FakeSyncNormalizer | FakeAsyncNormalizer
         if sync:
-            self.normalizer = FakeSyncNormalizer(freeze_ok=freeze_ok)
+            self.normalizer = FakeSyncNormalizer(freeze_ok=freeze_ok, conn=conn)
             self.engine: Any = SyncAttemptEngine(
                 plan=self.plan,
                 runtime=self.runtime,
@@ -287,7 +291,7 @@ class Harness:
                 translate=lambda error: error,
             )
         else:
-            self.normalizer = FakeAsyncNormalizer(freeze_ok=freeze_ok)
+            self.normalizer = FakeAsyncNormalizer(freeze_ok=freeze_ok, conn=conn)
             self.engine = AsyncAttemptEngine(
                 plan=self.plan,
                 runtime=self.runtime,

clientwright-0.2.1/tests/helpers/telemetry.py

@@ -0,0 +1,41 @@
+"""Telemetry doubles: a tracer that keeps every span it opened."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, MutableMapping
+from dataclasses import dataclass, field
+
+
+@dataclass(slots=True)
+class RecordingSpan:
+    """SpanProtocol double keeping every attribute the emitter sets."""
+
+    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:
+    """TracerProtocol double; one RecordingSpan per logical call."""
+
+    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: MutableMapping[str, str]) -> None:
+        return
+
+
+__all__ = ["RecordingSpan", "RecordingTracer"]