clientwright 0.1.0__py3-none-any.whl

clientwright/core/registry.py

@@ -0,0 +1,75 @@
+"""Adapter registry: string names to lazy import paths.
+
+``import clientwright`` pays nothing: adapter modules load only when resolved,
+at which point the adapter's ``_imports`` guard raises a friendly install hint
+if the matching extra is absent. Capability modules are zero-dependency and
+always importable. Dynamic string imports keep the core->adapters import-linter
+contract intact by construction.
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING, Any
+
+from .errors import UnknownAdapterError
+
+if TYPE_CHECKING:
+    from .capabilities import AdapterCapabilities
+
+_ADAPTERS: dict[str, str] = {
+    "httpx": "clientwright.adapters.httpx.adapter:HttpxAdapter",
+    "httpx2": "clientwright.adapters.httpx2.adapter:HttpxAdapter",
+    "aiohttp": "clientwright.adapters.aiohttp.adapter:AiohttpAdapter",
+    "requests": "clientwright.adapters.requests.adapter:RequestsAdapter",
+    "urllib3": "clientwright.adapters.urllib3.adapter:Urllib3Adapter",
+}
+
+_CAPABILITIES: dict[str, str] = {
+    "httpx": "clientwright.adapters.httpx.capabilities:CAPABILITIES",
+    "httpx2": "clientwright.adapters.httpx2.capabilities:CAPABILITIES",
+    "aiohttp": "clientwright.adapters.aiohttp.capabilities:CAPABILITIES",
+    "requests": "clientwright.adapters.requests.capabilities:CAPABILITIES",
+    "urllib3": "clientwright.adapters.urllib3.capabilities:CAPABILITIES",
+}
+
+
+def _load(target: str) -> Any:
+    module_path, _, attribute = target.partition(":")
+    module = importlib.import_module(module_path)
+    return getattr(module, attribute)
+
+
+def register_adapter(name: str, adapter_target: str, capabilities_target: str) -> None:
+    """Register a third-party adapter: ``"module.path:Class"`` strings, lazily loaded."""
+    for label, target in (("adapter", adapter_target), ("capabilities", capabilities_target)):
+        if ":" not in target:
+            raise ValueError(f"{label} target must look like 'module.path:Attribute', got {target!r}")
+    _ADAPTERS[name] = adapter_target
+    _CAPABILITIES[name] = capabilities_target
+
+
+def registered_adapters() -> tuple[str, ...]:
+    return tuple(sorted(_ADAPTERS))
+
+
+def resolve_adapter(name: str) -> Any:
+    """Load and return the adapter class registered under ``name``."""
+    try:
+        target = _ADAPTERS[name]
+    except KeyError:
+        raise UnknownAdapterError(name, registered_adapters()) from None
+    return _load(target)
+
+
+def capability_records() -> dict[str, AdapterCapabilities]:
+    """Capability record of every registered adapter; importable without extras."""
+    return {name: _load(target) for name, target in sorted(_CAPABILITIES.items())}
+
+
+__all__ = [
+    "capability_records",
+    "register_adapter",
+    "registered_adapters",
+    "resolve_adapter",
+]

clientwright/core/telemetry/__init__.py

@@ -0,0 +1,6 @@
+"""Single telemetry implementation for the whole library.
+
+Adapters never write a metric or a log line: they call ``send`` and the engine
+drives the one ``ClientTelemetry`` emitter, so the schema physically cannot
+diverge between backends.
+"""

clientwright/core/telemetry/emitter.py

@@ -0,0 +1,163 @@
+"""ClientTelemetry - the single emitter driving logs, metrics and spans.
+
+Observability closes in ``finally`` for every path: an attempt that dies with
+an exception still decrements in-flight, ends its span and records metrics -
+the legacy kit's event hooks lost every exception outcome.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+
+from ..config import ObservabilityConfig
+from ..contracts.observability import ClientMetricsProtocol, SpanProtocol, TracerProtocol
+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
+
+
+def outcome_label(outcome: Outcome) -> str:
+    return OUTCOME_SUCCESS if outcome.kind is None else outcome.kind.value
+
+
+def status_label(outcome: Outcome) -> str:
+    return STATUS_NONE if outcome.status_code is None else str(outcome.status_code)
+
+
+@dataclass(slots=True)
+class CallObservation:
+    """Mutable per-call observation state carried through the engine."""
+
+    span: SpanProtocol
+    started: float
+    hops: int = 0
+    attempts: int = 0
+
+
+class ClientTelemetry:
+    """One instance per built client; adapter/seam are burned in as constants."""
+
+    def __init__(
+        self,
+        *,
+        service: str,
+        adapter: str,
+        seam: str,
+        config: ObservabilityConfig,
+        metrics: ClientMetricsProtocol | None,
+        tracer: TracerProtocol | None,
+    ) -> None:
+        self._service = service
+        self._adapter = adapter
+        self._seam = seam
+        self._config = config
+        self._metrics: ClientMetricsProtocol = metrics if (metrics and config.metrics) else NullMetrics()
+        self._tracer: TracerProtocol = tracer if (tracer and config.tracing) else NullTracer()
+        self._logger = logging.getLogger(f"clientwright.client.{service}")
+        self._log_enabled = config.logging
+
+    @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)
+
+    def call_start(self, info: RequestInfo, started: float) -> CallObservation:
+        span = self._tracer.start_span(
+            f"HTTP {info.method}",
+            attributes={
+                "http.request.method": info.method,
+                "server.origin": info.origin,
+                "url.full": self._safe_url(info),
+            },
+        )
+        self._metrics.inflight_delta(
+            service=self._service, adapter=self._adapter, seam=self._seam, origin=info.origin, delta=1
+        )
+        if self._log_enabled:
+            self._logger.debug(
+                "HTTP call started",
+                extra={"method": info.method, "url": self._safe_url(info), "origin": info.origin},
+            )
+        return CallObservation(span=span, started=started)
+
+    def attempt_end(self, info: RequestInfo, attempt: Attempt) -> None:
+        self._metrics.record_attempt(
+            service=self._service,
+            adapter=self._adapter,
+            seam=self._seam,
+            method=info.method,
+            origin=info.origin,
+            outcome=outcome_label(attempt.outcome),
+            duration=attempt.duration,
+        )
+
+    def redirect_hop(self, observation: CallObservation) -> None:
+        observation.hops += 1
+        self._metrics.record_redirect_hop(service=self._service, adapter=self._adapter, seam=self._seam)
+
+    def retry_skipped(self, reason: str) -> None:
+        self._metrics.record_retry_skipped(service=self._service, adapter=self._adapter, seam=self._seam, reason=reason)
+
+    def circuit_state_changed(self, key: str, state: str) -> None:
+        self._metrics.record_circuit_state(service=self._service, adapter=self._adapter, key=key, state=state)
+
+    def uninstrumented_call(self) -> None:
+        """A call bypassed the instrumentation seam (e.g. aiohttp middlewares=())."""
+        self._metrics.record_uninstrumented_call(service=self._service, adapter=self._adapter, seam=self._seam)
+
+    def call_end(self, observation: CallObservation, info: RequestInfo, outcome: Outcome, duration: float) -> None:
+        route = info.route or ROUTE_UNKNOWN
+        try:
+            self._metrics.record_call(
+                service=self._service,
+                adapter=self._adapter,
+                seam=self._seam,
+                method=info.method,
+                origin=info.origin,
+                route=route,
+                status=status_label(outcome),
+                outcome=outcome_label(outcome),
+                duration=duration,
+            )
+            self._metrics.inflight_delta(
+                service=self._service, adapter=self._adapter, seam=self._seam, origin=info.origin, delta=-1
+            )
+            if self._log_enabled:
+                extra = {
+                    "method": info.method,
+                    "url": self._safe_url(info),
+                    "origin": info.origin,
+                    "outcome": outcome_label(outcome),
+                    "status": status_label(outcome),
+                    "duration": round(duration, 6),
+                    "attempts": observation.attempts,
+                    "hops": observation.hops,
+                }
+                if outcome.kind is None:
+                    self._logger.log(self._config.success_log_level, "HTTP call finished", extra=extra)
+                else:
+                    self._logger.warning("HTTP call failed", extra=extra)
+        finally:
+            if outcome.status_code is not None:
+                observation.span.set_attribute("http.response.status_code", outcome.status_code)
+            if outcome.kind is not None:
+                observation.span.record_failure(outcome_label(outcome))
+            observation.span.end()
+
+    def record_body_duration(self, info: RequestInfo, duration: float) -> None:
+        self._metrics.record_body_duration(
+            service=self._service,
+            adapter=self._adapter,
+            seam=self._seam,
+            method=info.method,
+            origin=info.origin,
+            route=info.route or ROUTE_UNKNOWN,
+            duration=duration,
+        )
+
+
+__all__ = ["CallObservation", "ClientTelemetry", "outcome_label", "status_label"]

clientwright/core/telemetry/names.py

@@ -0,0 +1,61 @@
+"""FROZEN metric names and label sets - a wire contract with dashboards.
+
+Changing anything here is a breaking change of the observability contract and
+requires a dashboard migration plan; see docs/advanced/migration.md for the
+mapping principles from legacy ``rest_client_*``-style names.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+REQUESTS_TOTAL: Final = "http_client_requests_total"
+REQUEST_DURATION: Final = "http_client_request_duration_seconds"
+BODY_DURATION: Final = "http_client_body_duration_seconds"
+ATTEMPTS_TOTAL: Final = "http_client_attempts_total"
+ATTEMPT_DURATION: Final = "http_client_attempt_duration_seconds"
+INFLIGHT: Final = "http_client_inflight"
+CIRCUIT_STATE: Final = "http_client_circuit_state"
+REDIRECT_HOPS_TOTAL: Final = "http_client_redirect_hops_total"
+RETRY_SKIPPED_TOTAL: Final = "http_client_retry_skipped_total"
+UNINSTRUMENTED_CALLS_TOTAL: Final = "http_client_uninstrumented_calls_total"
+
+LABELS_CALL: Final = ("service", "adapter", "seam", "method", "origin", "route", "status", "outcome")
+LABELS_DURATION: Final = ("service", "adapter", "seam", "method", "origin", "route")
+LABELS_ATTEMPT: Final = ("service", "adapter", "seam", "method", "origin", "outcome")
+LABELS_INFLIGHT: Final = ("service", "adapter", "seam", "origin")
+LABELS_CIRCUIT: Final = ("service", "adapter", "key")
+LABELS_SEAM: Final = ("service", "adapter", "seam")
+LABELS_RETRY_SKIPPED: Final = ("service", "adapter", "seam", "reason")
+
+OUTCOME_SUCCESS: Final = "success"
+STATUS_NONE: Final = "none"
+ROUTE_UNKNOWN: Final = "unknown"
+
+# Inherited verbatim from service-observability's DEFAULT_REST_BUCKETS: tuned
+# for REST latencies and already burned into existing dashboards.
+DEFAULT_BUCKETS: Final = (0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0)
+
+__all__ = [
+    "ATTEMPTS_TOTAL",
+    "ATTEMPT_DURATION",
+    "BODY_DURATION",
+    "CIRCUIT_STATE",
+    "DEFAULT_BUCKETS",
+    "INFLIGHT",
+    "LABELS_ATTEMPT",
+    "LABELS_CALL",
+    "LABELS_CIRCUIT",
+    "LABELS_DURATION",
+    "LABELS_INFLIGHT",
+    "LABELS_RETRY_SKIPPED",
+    "LABELS_SEAM",
+    "OUTCOME_SUCCESS",
+    "REDIRECT_HOPS_TOTAL",
+    "REQUESTS_TOTAL",
+    "REQUEST_DURATION",
+    "RETRY_SKIPPED_TOTAL",
+    "ROUTE_UNKNOWN",
+    "STATUS_NONE",
+    "UNINSTRUMENTED_CALLS_TOTAL",
+]

clientwright/core/telemetry/null.py

@@ -0,0 +1,89 @@
+"""Null observability backends: emitters never branch on ``is None``."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, MutableMapping
+
+
+class NullMetrics:
+    """Accepts every record and does nothing."""
+
+    def record_call(
+        self,
+        *,
+        service: str,
+        adapter: str,
+        seam: str,
+        method: str,
+        origin: str,
+        route: str,
+        status: str,
+        outcome: str,
+        duration: float,
+    ) -> None:
+        return None
+
+    def record_body_duration(
+        self,
+        *,
+        service: str,
+        adapter: str,
+        seam: str,
+        method: str,
+        origin: str,
+        route: str,
+        duration: float,
+    ) -> None:
+        return None
+
+    def record_attempt(
+        self,
+        *,
+        service: str,
+        adapter: str,
+        seam: str,
+        method: str,
+        origin: str,
+        outcome: str,
+        duration: float,
+    ) -> None:
+        return None
+
+    def inflight_delta(self, *, service: str, adapter: str, seam: str, origin: str, delta: int) -> None:
+        return None
+
+    def record_circuit_state(self, *, service: str, adapter: str, key: str, state: str) -> None:
+        return None
+
+    def record_redirect_hop(self, *, service: str, adapter: str, seam: str) -> None:
+        return None
+
+    def record_retry_skipped(self, *, service: str, adapter: str, seam: str, reason: str) -> None:
+        return None
+
+    def record_uninstrumented_call(self, *, service: str, adapter: str, seam: str) -> None:
+        return None
+
+
+class NullSpan:
+    def set_attribute(self, key: str, value: str | int | float | bool) -> None:
+        return None
+
+    def record_failure(self, description: str) -> None:
+        return None
+
+    def end(self) -> None:
+        return None
+
+
+class NullTracer:
+    _SPAN = NullSpan()
+
+    def start_span(self, name: str, *, attributes: Mapping[str, str | int | float | bool]) -> NullSpan:
+        return self._SPAN
+
+    def inject_context(self, headers: MutableMapping[str, str]) -> None:
+        return None
+
+
+__all__ = ["NullMetrics", "NullSpan", "NullTracer"]

clientwright/core/telemetry/redaction.py

@@ -0,0 +1,24 @@
+"""Secret redaction for logs and spans."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
+
+REDACTED = "[redacted]"
+
+
+def redact_headers(headers: Mapping[str, str], sensitive: frozenset[str]) -> dict[str, str]:
+    return {name: (REDACTED if name.lower() in sensitive else value) for name, value in headers.items()}
+
+
+def redact_url(url: str, sensitive_params: frozenset[str]) -> str:
+    parts = urlsplit(url)
+    if not parts.query:
+        return url
+    pairs = parse_qsl(parts.query, keep_blank_values=True)
+    cleaned = [(name, REDACTED if name.lower() in sensitive_params else value) for name, value in pairs]
+    return urlunsplit(parts._replace(query=urlencode(cleaned)))
+
+
+__all__ = ["REDACTED", "redact_headers", "redact_url"]

clientwright/core/testing/__init__.py

@@ -0,0 +1,7 @@
+"""Test doubles and a fault-injecting origin server, stdlib only."""
+
+from .doubles import ManualClock as ManualClock
+from .doubles import RecordingMetrics as RecordingMetrics
+from .origin import OriginServer as OriginServer
+
+__all__ = ["ManualClock", "OriginServer", "RecordingMetrics"]

clientwright/core/testing/doubles.py

@@ -0,0 +1,107 @@
+"""Deterministic doubles for engine and telemetry tests."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+class ManualClock:
+    """Monotonic clock advanced by hand."""
+
+    def __init__(self, start: float = 0.0) -> None:
+        self._now = start
+
+    def __call__(self) -> float:
+        return self._now
+
+    def advance(self, seconds: float) -> None:
+        self._now += seconds
+
+
+@dataclass(slots=True)
+class RecordingMetrics:
+    """ClientMetricsProtocol implementation that remembers every record."""
+
+    calls: list[dict[str, object]] = field(default_factory=list)
+    attempts: list[dict[str, object]] = field(default_factory=list)
+    body_durations: list[dict[str, object]] = field(default_factory=list)
+    inflight: list[dict[str, object]] = field(default_factory=list)
+    circuit_states: list[dict[str, object]] = field(default_factory=list)
+    redirect_hops: list[dict[str, object]] = field(default_factory=list)
+    retry_skips: list[dict[str, object]] = field(default_factory=list)
+    uninstrumented: list[dict[str, object]] = field(default_factory=list)
+
+    def record_call(
+        self,
+        *,
+        service: str,
+        adapter: str,
+        seam: str,
+        method: str,
+        origin: str,
+        route: str,
+        status: str,
+        outcome: str,
+        duration: float,
+    ) -> None:
+        self.calls.append(
+            {
+                "service": service,
+                "adapter": adapter,
+                "seam": seam,
+                "method": method,
+                "origin": origin,
+                "route": route,
+                "status": status,
+                "outcome": outcome,
+                "duration": duration,
+            }
+        )
+
+    def record_body_duration(
+        self,
+        *,
+        service: str,
+        adapter: str,
+        seam: str,
+        method: str,
+        origin: str,
+        route: str,
+        duration: float,
+    ) -> None:
+        self.body_durations.append({"method": method, "origin": origin, "route": route, "duration": duration})
+
+    def record_attempt(
+        self,
+        *,
+        service: str,
+        adapter: str,
+        seam: str,
+        method: str,
+        origin: str,
+        outcome: str,
+        duration: float,
+    ) -> None:
+        self.attempts.append({"method": method, "origin": origin, "outcome": outcome, "duration": duration})
+
+    def inflight_delta(self, *, service: str, adapter: str, seam: str, origin: str, delta: int) -> None:
+        self.inflight.append({"origin": origin, "delta": delta})
+
+    def record_circuit_state(self, *, service: str, adapter: str, key: str, state: str) -> None:
+        self.circuit_states.append({"key": key, "state": state})
+
+    def record_redirect_hop(self, *, service: str, adapter: str, seam: str) -> None:
+        self.redirect_hops.append({"adapter": adapter})
+
+    def record_retry_skipped(self, *, service: str, adapter: str, seam: str, reason: str) -> None:
+        self.retry_skips.append({"reason": reason})
+
+    def record_uninstrumented_call(self, *, service: str, adapter: str, seam: str) -> None:
+        self.uninstrumented.append({"adapter": adapter})
+
+    @property
+    def inflight_balance(self) -> int:
+        return sum(int(record["delta"]) for record in self.inflight)  # type: ignore[call-overload]
+
+
+__all__ = ["ManualClock", "RecordingMetrics"]