clientwright 0.1.0__py3-none-any.whl

clientwright/core/contracts/observability.py

@@ -0,0 +1,92 @@
+"""SDK-free observability seams.
+
+The kernel records everything through these protocols; concrete backends
+(Prometheus, OpenTelemetry) live in ``clientwright.adapters.observability``
+behind extras and are never imported by the core.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, MutableMapping
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class ClientMetricsProtocol(Protocol):
+    """Sink for the frozen ``http_client_*`` metric families.
+
+    Label semantics: ``outcome`` is ``"success"`` or a ``FailureKind`` value;
+    ``status`` is the HTTP status as a string or ``"none"`` when the call
+    produced no response; ``adapter``/``seam`` are per-adapter constants.
+    """
+
+    def record_call(
+        self,
+        *,
+        service: str,
+        adapter: str,
+        seam: str,
+        method: str,
+        origin: str,
+        route: str,
+        status: str,
+        outcome: str,
+        duration: float,
+    ) -> None: ...
+
+    def record_body_duration(
+        self,
+        *,
+        service: str,
+        adapter: str,
+        seam: str,
+        method: str,
+        origin: str,
+        route: str,
+        duration: float,
+    ) -> None: ...
+
+    def record_attempt(
+        self,
+        *,
+        service: str,
+        adapter: str,
+        seam: str,
+        method: str,
+        origin: str,
+        outcome: str,
+        duration: float,
+    ) -> None: ...
+
+    def inflight_delta(self, *, service: str, adapter: str, seam: str, origin: str, delta: int) -> None: ...
+
+    def record_circuit_state(self, *, service: str, adapter: str, key: str, state: str) -> None: ...
+
+    def record_redirect_hop(self, *, service: str, adapter: str, seam: str) -> None: ...
+
+    def record_retry_skipped(self, *, service: str, adapter: str, seam: str, reason: str) -> None: ...
+
+    def record_uninstrumented_call(self, *, service: str, adapter: str, seam: str) -> None: ...
+
+
+@runtime_checkable
+class SpanProtocol(Protocol):
+    """One client span; ended exactly once, in a finally block."""
+
+    def set_attribute(self, key: str, value: str | int | float | bool) -> None: ...
+
+    def record_failure(self, description: str) -> None: ...
+
+    def end(self) -> None: ...
+
+
+@runtime_checkable
+class TracerProtocol(Protocol):
+    """Opens client spans and injects propagation headers."""
+
+    def start_span(self, name: str, *, attributes: Mapping[str, str | int | float | bool]) -> SpanProtocol: ...
+
+    def inject_context(self, headers: MutableMapping[str, str]) -> None: ...
+
+
+__all__ = ["ClientMetricsProtocol", "SpanProtocol", "TracerProtocol"]

clientwright/core/contracts/settings.py

@@ -0,0 +1,140 @@
+"""Structural settings protocols for service integration.
+
+Services keep their own settings models (pydantic or otherwise); anything with
+these read-only properties satisfies the contract - the org convention set by
+grpc-client-kit. ``client_config_from_settings`` converts the structural shape
+into a ``ClientConfig``.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from ..config import (
+    CircuitBreakerConfig,
+    ClientConfig,
+    ObservabilityConfig,
+    PoolConfig,
+    RetryConfig,
+    TimeoutConfig,
+    TlsConfig,
+)
+
+
+@runtime_checkable
+class RetrySettingsProtocol(Protocol):
+    @property
+    def max_attempts(self) -> int: ...
+
+    @property
+    def initial_backoff(self) -> float: ...
+
+    @property
+    def max_backoff(self) -> float: ...
+
+    @property
+    def backoff_multiplier(self) -> float: ...
+
+
+@runtime_checkable
+class CircuitBreakerSettingsProtocol(Protocol):
+    @property
+    def fail_threshold(self) -> int: ...
+
+    @property
+    def recovery_timeout(self) -> float: ...
+
+    @property
+    def half_open_max_calls(self) -> int: ...
+
+
+@runtime_checkable
+class ClientSettingsProtocol(Protocol):
+    """Mirror of the legacy ``RestClientSettingsProtocol`` reachable surface."""
+
+    @property
+    def base_url(self) -> str: ...
+
+    @property
+    def timeout_seconds(self) -> float: ...
+
+    @property
+    def connect_timeout_seconds(self) -> float: ...
+
+    @property
+    def max_connections(self) -> int: ...
+
+    @property
+    def max_keepalive_connections(self) -> int: ...
+
+    @property
+    def enable_http2(self) -> bool: ...
+
+    @property
+    def verify(self) -> bool: ...
+
+    @property
+    def logging_enabled(self) -> bool: ...
+
+    @property
+    def metrics_enabled(self) -> bool: ...
+
+    @property
+    def tracing_enabled(self) -> bool: ...
+
+    @property
+    def retry(self) -> RetrySettingsProtocol | None: ...
+
+    @property
+    def circuit_breaker(self) -> CircuitBreakerSettingsProtocol | None: ...
+
+
+def client_config_from_settings(settings: ClientSettingsProtocol, service_name: str) -> ClientConfig:
+    """Build a ClientConfig from the structural settings shape used by services."""
+    retry_settings = settings.retry
+    retry = (
+        RetryConfig(
+            max_attempts=retry_settings.max_attempts,
+            initial_backoff=retry_settings.initial_backoff,
+            max_backoff=retry_settings.max_backoff,
+            multiplier=retry_settings.backoff_multiplier,
+        )
+        if retry_settings is not None
+        else None
+    )
+    breaker_settings = settings.circuit_breaker
+    circuit_breaker = (
+        CircuitBreakerConfig(
+            fail_threshold=breaker_settings.fail_threshold,
+            recovery_timeout=breaker_settings.recovery_timeout,
+            half_open_max_calls=breaker_settings.half_open_max_calls,
+        )
+        if breaker_settings is not None
+        else None
+    )
+    return ClientConfig(
+        service_name=service_name,
+        base_url=settings.base_url,
+        timeout=TimeoutConfig(total=settings.timeout_seconds, connect=settings.connect_timeout_seconds),
+        pool=PoolConfig(
+            max_connections=settings.max_connections,
+            max_keepalive=settings.max_keepalive_connections,
+            http2=settings.enable_http2,
+        ),
+        retry=retry,
+        circuit_breaker=circuit_breaker,
+        tls=TlsConfig(verify=settings.verify),
+        observability=ObservabilityConfig(
+            logging=settings.logging_enabled,
+            metrics=settings.metrics_enabled,
+            tracing=settings.tracing_enabled,
+        ),
+    )
+
+
+__all__ = [
+    "CircuitBreakerSettingsProtocol",
+    "ClientSettingsProtocol",
+    "RetrySettingsProtocol",
+    "client_config_from_settings",
+]

clientwright/core/engine/__init__.py

@@ -0,0 +1 @@
+"""Attempt engines: the only retry/redirect/deadline loops in the library."""

clientwright/core/engine/aio.py

@@ -0,0 +1,246 @@
+"""The single asynchronous attempt loop of the whole library.
+
+Order is baked in and not configurable:
+deadline -> headers -> per-origin slot -> circuit check (outside retry)
+-> [hop loop -> attempt loop] -> circuit record (one signal) -> telemetry end.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Awaitable, Callable
+from contextlib import AsyncExitStack
+from typing import Any
+
+from ..contracts.adapter import AdapterDeps
+from ..contracts.message import AsyncNormalizer, RequestView, ResponseView
+from ..errors import CallError, CircuitOpenError, DeadlineExceededError, TooManyRedirectsError
+from ..model import Attempt, FailureKind, Outcome
+from ..plan import CallPlan, ClientRuntime
+from ..policy.budget import Deadline
+from ..telemetry.emitter import CallObservation, ClientTelemetry
+from .base import SKIP_REASONS, deadline_header_value, inject_static_headers
+from .redirects import apply_redirect, plan_redirect
+
+type AsyncSend = Callable[[RequestView], Awaitable[Any]]
+type ErrorTranslator = Callable[[CallError], BaseException]
+
+logger = logging.getLogger("clientwright.engine")
+
+
+class AsyncAttemptEngine:
+    """Runs one logical call: retries, owned redirects, deadline, telemetry."""
+
+    def __init__(
+        self,
+        *,
+        plan: CallPlan,
+        runtime: ClientRuntime,
+        telemetry: ClientTelemetry,
+        normalizer: AsyncNormalizer,
+        deps: AdapterDeps,
+        translate: ErrorTranslator,
+    ) -> None:
+        self._plan = plan
+        self._runtime = runtime
+        self._telemetry = telemetry
+        self._norm = normalizer
+        self._deps = deps
+        self._translate = translate
+
+    async def run(self, native_request: Any, send: AsyncSend) -> Any:
+        clock = self._runtime.clock
+        request = self._norm.wrap_request(native_request)
+        info = request.info
+        started = clock()
+        observation = self._telemetry.call_start(info, started)
+        final_outcome = Outcome(kind=FailureKind.UNKNOWN)
+        response: ResponseView | None = None
+        try:
+            response, final_outcome = await self._admitted(request, send, observation)
+        except CallError as error:
+            final_outcome = self._call_error_outcome(error)
+            raise self._translate(error) from error
+        except BaseException as error:
+            if final_outcome.exception is not error:
+                final_outcome = Outcome(kind=self._norm.classify_error(error), exception=error)
+            raise
+        finally:
+            self._telemetry.call_end(observation, info, final_outcome, clock() - started)
+        if final_outcome.exception is not None:
+            raise final_outcome.exception
+        assert response is not None  # a call without exception always has a response
+        self._wrap_stream(response, info)
+        return response.native
+
+    def _call_error_outcome(self, error: CallError) -> Outcome:
+        if isinstance(error, CircuitOpenError):
+            return Outcome(kind=FailureKind.CIRCUIT_OPEN, exception=error)
+        if isinstance(error, DeadlineExceededError):
+            return Outcome(kind=FailureKind.TOTAL_TIMEOUT, exception=error)
+        return Outcome(kind=FailureKind.UNKNOWN, exception=error)
+
+    def _wrap_stream(self, response: ResponseView, info: Any) -> None:
+        def on_done(outcome: Outcome, duration: float) -> None:
+            self._telemetry.record_body_duration(info, duration)
+
+        self._norm.wrap_stream(response, on_done)
+
+    def _inject_headers(self, request: RequestView) -> None:
+        headers = request.headers
+        inject_static_headers(headers, dict(self._plan.config.headers))
+        for provider in self._deps.header_providers:
+            try:
+                inject_static_headers(headers, dict(provider()))
+            except Exception:
+                logger.debug("Header provider %r failed", provider, exc_info=True)
+                continue
+        self._telemetry.tracer.inject_context(headers)
+
+    def _deadline(self, request: RequestView) -> Deadline:
+        ambient = self._deps.deadline_source.remaining() if self._deps.deadline_source is not None else None
+        return Deadline.intersect(self._runtime.clock, self._plan.config.timeout.total, ambient)
+
+    async def _admitted(
+        self, request: RequestView, send: AsyncSend, observation: CallObservation
+    ) -> tuple[ResponseView | None, Outcome]:
+        plan = self._plan
+        runtime = self._runtime
+        info = request.info
+        deadline = self._deadline(request)
+        self._inject_headers(request)
+        circuit_key: str | None = None
+        async with AsyncExitStack() as stack:
+            if plan.use_origin_limiter and runtime.async_limiter is not None:
+                await stack.enter_async_context(runtime.async_limiter.acquire(info.origin))
+            if runtime.circuits is not None and plan.config.circuit_breaker is not None:
+                circuit_key = info.circuit_key(plan.config.circuit_breaker.key)
+                runtime.circuits.check(circuit_key)
+            if runtime.retry_budgets is not None:
+                runtime.retry_budgets.earn(info.origin)
+            outcome = Outcome(kind=FailureKind.UNKNOWN)
+            aborted = False
+            try:
+                response, outcome = await self._hops(request, send, deadline, observation)
+            except CallError as error:
+                outcome = self._call_error_outcome(error)
+                raise
+            except BaseException:
+                # Cancellation or an adapter fault: no classified outcome, so it
+                # must be neither a success nor a failure signal for the breaker.
+                aborted = True
+                raise
+            else:
+                return response, outcome
+            finally:
+                if circuit_key is not None and runtime.circuits is not None:
+                    if aborted:
+                        runtime.circuits.record_aborted(circuit_key)
+                    else:
+                        runtime.circuits.record(circuit_key, outcome)
+        raise AssertionError("unreachable")  # pragma: no cover - AsyncExitStack never swallows
+
+    async def _hops(
+        self, request: RequestView, send: AsyncSend, deadline: Deadline, observation: CallObservation
+    ) -> tuple[ResponseView | None, Outcome]:
+        plan = self._plan
+        replayable = await self._freeze_if_needed(request)
+        history: list[Attempt] = []
+        while True:
+            response, outcome = await self._attempts(request, send, deadline, observation, history, replayable)
+            if response is None or outcome.exception is not None:
+                return response, outcome
+            if plan.config.redirects.value != "owned":
+                return response, outcome
+            step = plan_redirect(response, request)
+            if step is None:
+                return response, outcome
+            if observation.hops >= plan.config.max_redirects:
+                raise TooManyRedirectsError(plan.config.max_redirects)
+            if step.needs_body_replay and not replayable:
+                return response, outcome
+            await self._norm.discard(response)
+            apply_redirect(request, step)
+            self._telemetry.redirect_hop(observation)
+
+    async def _freeze_if_needed(self, request: RequestView) -> bool:
+        plan = self._plan
+        needs_replay = plan.retry_policy is not None or plan.config.redirects.value == "owned"
+        if not needs_replay:
+            return True
+        return await self._norm.freeze(request)
+
+    async def _attempts(
+        self,
+        request: RequestView,
+        send: AsyncSend,
+        deadline: Deadline,
+        observation: CallObservation,
+        history: list[Attempt],
+        replayable: bool,
+    ) -> tuple[ResponseView | None, Outcome]:
+        plan = self._plan
+        runtime = self._runtime
+        info = request.info
+        caller = request.caller_timeouts()
+        while True:
+            remaining = deadline.remaining()
+            if remaining is not None and remaining <= 0:
+                raise DeadlineExceededError(deadline.total or 0.0)
+            timeouts = plan.planner.plan(remaining=remaining, caller=caller)
+            request.apply_timeouts(timeouts)
+            if plan.config.deadline_header is not None and remaining is not None:
+                request.headers[plan.config.deadline_header] = deadline_header_value(remaining)
+            attempt_started = runtime.clock()
+            observation.attempts += 1
+            response: ResponseView | None = None
+            try:
+                async with asyncio.timeout(timeouts.attempt):
+                    native_response = await send(request)
+                response = self._norm.wrap_response(native_response)
+                outcome = self._norm.classify_response(response)
+            except CallError:
+                raise
+            except asyncio.CancelledError:
+                raise
+            except TimeoutError as error:
+                outcome = Outcome(kind=FailureKind.TOTAL_TIMEOUT, exception=error)
+            except Exception as error:
+                outcome = Outcome(kind=self._norm.classify_error(error), exception=error)
+            attempt = Attempt(
+                index=len(history) + 1,
+                started=attempt_started,
+                duration=runtime.clock() - attempt_started,
+                outcome=outcome,
+                hop=observation.hops,
+            )
+            history.append(attempt)
+            if plan.emit_attempt_metrics:
+                self._telemetry.attempt_end(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:
+                return response, outcome
+            decision = plan.retry_policy.decide(
+                info=info,
+                history=history,
+                remaining=deadline.remaining(),
+                replayable=replayable,
+                rng=runtime.rng,
+            )
+            if not decision.retry:
+                if decision.reason in SKIP_REASONS:
+                    self._telemetry.retry_skipped(decision.reason)
+                return response, outcome
+            if runtime.retry_budgets is not None and not runtime.retry_budgets.try_spend(info.origin):
+                self._telemetry.retry_skipped("budget")
+                return response, outcome
+            if response is not None:
+                await self._norm.discard(response)
+            await self._norm.rewind(request)
+            if decision.delay > 0:
+                await asyncio.sleep(decision.delay)
+
+
+__all__ = ["AsyncAttemptEngine", "AsyncSend", "ErrorTranslator"]

clientwright/core/engine/base.py

@@ -0,0 +1,65 @@
+"""Pure helpers shared by the sync and async engines."""
+
+from __future__ import annotations
+
+import datetime
+import email.utils
+from collections.abc import MutableMapping
+
+from ..contracts.message import ResponseView
+from ..model import FailureKind, Outcome
+
+# Statuses that commonly carry Retry-After.
+_RETRY_AFTER_STATUSES = frozenset({413, 429, 503})
+
+# Reasons worth a retry_skipped sentinel: the policy WANTED to retry but could not.
+SKIP_REASONS = frozenset({"method", "non_replayable", "deadline", "budget"})
+
+
+def parse_retry_after(value: str | None) -> float | None:
+    """Seconds from a Retry-After header: integer form or HTTP-date form."""
+    if not value:
+        return None
+    text = value.strip()
+    if text.isdigit():
+        return float(text)
+    try:
+        when = email.utils.parsedate_to_datetime(text)
+    except (TypeError, ValueError):
+        return None
+    if when.tzinfo is None:
+        when = when.replace(tzinfo=datetime.UTC)
+    delta = (when - datetime.datetime.now(datetime.UTC)).total_seconds()
+    return max(delta, 0.0)
+
+
+def default_response_outcome(response: ResponseView) -> Outcome:
+    """Default classification: a received response is a failure only when 5xx.
+
+    Retry-After is captured for throttling and unavailability statuses so the
+    retry policy can honor it.
+    """
+    status = response.status_code
+    retry_after = parse_retry_after(response.header("retry-after")) if status in _RETRY_AFTER_STATUSES else None
+    kind = FailureKind.STATUS if status >= 500 else None
+    return Outcome(kind=kind, status_code=status, retry_after=retry_after)
+
+
+def inject_static_headers(headers: MutableMapping[str, str], extra: dict[str, str]) -> None:
+    """setdefault semantics: caller-set headers always win."""
+    for name, value in extra.items():
+        if name not in headers:
+            headers[name] = value
+
+
+def deadline_header_value(remaining: float) -> str:
+    return str(max(int(remaining * 1000), 0))
+
+
+__all__ = [
+    "SKIP_REASONS",
+    "deadline_header_value",
+    "default_response_outcome",
+    "inject_static_headers",
+    "parse_retry_after",
+]

clientwright/core/engine/redirects.py

@@ -0,0 +1,64 @@
+"""Owned redirects: the engine follows hops, native following stays disabled.
+
+One logical call therefore has ONE deadline, ONE retry budget and ONE circuit
+signal regardless of hop count - on every adapter.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from urllib.parse import urljoin
+
+from ..contracts.message import RequestView, ResponseView
+from ..model import origin_of
+
+REDIRECT_STATUSES = frozenset({301, 302, 303, 307, 308})
+
+# Stripped when a redirect crosses origins, mirroring urllib3's
+# remove_headers_on_redirect and browser behavior.
+CROSS_ORIGIN_STRIP = ("authorization", "proxy-authorization", "cookie")
+
+
+@dataclass(frozen=True, slots=True)
+class RedirectStep:
+    url: str
+    method: str | None
+    drop_body: bool
+    cross_origin: bool
+
+    @property
+    def needs_body_replay(self) -> bool:
+        return not self.drop_body
+
+
+def plan_redirect(response: ResponseView, request: RequestView) -> RedirectStep | None:
+    """The next hop, or None when the response is not a followable redirect."""
+    if response.status_code not in REDIRECT_STATUSES:
+        return None
+    location = response.location
+    if not location:
+        return None
+    info = request.info
+    url = urljoin(info.url, location)
+    method: str | None = None
+    drop_body = False
+    if response.status_code == 303 or (response.status_code in (301, 302) and info.method == "POST"):
+        if info.method != "HEAD":
+            method = "GET"
+        drop_body = True
+    return RedirectStep(
+        url=url,
+        method=method,
+        drop_body=drop_body,
+        cross_origin=origin_of(url) != info.origin,
+    )
+
+
+def apply_redirect(request: RequestView, step: RedirectStep) -> None:
+    if step.cross_origin:
+        for name in CROSS_ORIGIN_STRIP:
+            request.headers.pop(name, None)
+    request.retarget(step.url, method=step.method, drop_body=step.drop_body)
+
+
+__all__ = ["CROSS_ORIGIN_STRIP", "REDIRECT_STATUSES", "RedirectStep", "apply_redirect", "plan_redirect"]

clientwright/core/engine/suppress.py

@@ -0,0 +1,30 @@
+"""ContextVar suppression against double accounting.
+
+When one instrumented client physically sits on top of another (requests over
+urllib3) or a seam recurses into itself, the inner layer must stay silent: the
+outer layer owns instrumentation.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Generator
+from contextlib import contextmanager
+from contextvars import ContextVar
+
+_DEPTH: ContextVar[int] = ContextVar("clientwright_suppress_depth", default=0)
+
+
+def is_suppressed() -> bool:
+    return _DEPTH.get() > 0
+
+
+@contextmanager
+def suppressed() -> Generator[None]:
+    token = _DEPTH.set(_DEPTH.get() + 1)
+    try:
+        yield
+    finally:
+        _DEPTH.reset(token)
+
+
+__all__ = ["is_suppressed", "suppressed"]