clientwright 0.1.0__py3-none-any.whl

clientwright/core/engine/sync.py

@@ -0,0 +1,241 @@
+"""The single synchronous attempt loop; mirrors AsyncAttemptEngine.
+
+Sync runtimes cannot cancel a blocked socket call, so the total deadline is
+SOFT here: per-attempt phases are clamped by the remaining budget and the
+deadline is re-checked at attempt boundaries. Adapters declare this as
+``DEADLINE_HARD: ABSENT``.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from collections.abc import Callable
+from contextlib import ExitStack
+from typing import Any
+
+from ..contracts.adapter import AdapterDeps
+from ..contracts.message import RequestView, ResponseView, SyncNormalizer
+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 SyncSend = Callable[[RequestView], Any]
+type ErrorTranslator = Callable[[CallError], BaseException]
+
+logger = logging.getLogger("clientwright.engine")
+
+
+class SyncAttemptEngine:
+    def __init__(
+        self,
+        *,
+        plan: CallPlan,
+        runtime: ClientRuntime,
+        telemetry: ClientTelemetry,
+        normalizer: SyncNormalizer,
+        deps: AdapterDeps,
+        translate: ErrorTranslator,
+    ) -> None:
+        self._plan = plan
+        self._runtime = runtime
+        self._telemetry = telemetry
+        self._norm = normalizer
+        self._deps = deps
+        self._translate = translate
+
+    def run(self, native_request: Any, send: SyncSend) -> 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 = 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
+        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) -> 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)
+
+    def _admitted(
+        self, request: RequestView, send: SyncSend, observation: CallObservation
+    ) -> tuple[ResponseView | None, Outcome]:
+        plan = self._plan
+        runtime = self._runtime
+        info = request.info
+        deadline = self._deadline()
+        self._inject_headers(request)
+        circuit_key: str | None = None
+        with ExitStack() as stack:
+            if plan.use_origin_limiter and runtime.sync_limiter is not None:
+                stack.enter_context(runtime.sync_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 = self._hops(request, send, deadline, observation)
+            except CallError as error:
+                outcome = self._call_error_outcome(error)
+                raise
+            except BaseException:
+                # No classified outcome: neither success nor failure 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 - ExitStack never swallows
+
+    def _hops(
+        self, request: RequestView, send: SyncSend, deadline: Deadline, observation: CallObservation
+    ) -> tuple[ResponseView | None, Outcome]:
+        plan = self._plan
+        replayable = self._freeze_if_needed(request)
+        history: list[Attempt] = []
+        while True:
+            response, outcome = 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
+            self._norm.discard(response)
+            apply_redirect(request, step)
+            self._telemetry.redirect_hop(observation)
+
+    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 self._norm.freeze(request)
+
+    def _attempts(
+        self,
+        request: RequestView,
+        send: SyncSend,
+        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:
+                native_response = send(request)
+                response = self._norm.wrap_response(native_response)
+                outcome = self._norm.classify_response(response)
+            except CallError:
+                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:
+                self._norm.discard(response)
+            self._norm.rewind(request)
+            if decision.delay > 0:
+                time.sleep(decision.delay)
+
+
+__all__ = ["SyncAttemptEngine", "SyncSend"]

clientwright/core/errors.py

@@ -0,0 +1,113 @@
+"""Kernel error hierarchy.
+
+Errors raised on the call path (``CallError`` subclasses) are translated by each
+adapter into classes that ALSO inherit the native client's error family, so a
+user's ``except httpx.HTTPError`` keeps working. Errors raised at build time are
+plain kernel errors.
+"""
+
+from __future__ import annotations
+
+
+class ClientwrightError(Exception):
+    """Base class for everything clientwright raises on its own authority."""
+
+
+class UnknownAdapterError(ClientwrightError):
+    """Requested adapter name is not registered."""
+
+    def __init__(self, name: str, known: tuple[str, ...]) -> None:
+        super().__init__(f"Unknown adapter {name!r}; registered adapters: {', '.join(known) or '<none>'}")
+        self.name = name
+        self.known = known
+
+
+class UnsupportedCapabilityError(ClientwrightError):
+    """Config asks for something the chosen adapter cannot express (STRICT mode)."""
+
+
+class NativeConfigError(ClientwrightError):
+    """Base for invalid native passthrough configuration."""
+
+
+class UnknownNativeSlotError(NativeConfigError):
+    def __init__(self, slot: str, known: tuple[str, ...]) -> None:
+        super().__init__(f"Unknown native slot {slot!r}; adapter slots: {', '.join(known)}")
+        self.slot = slot
+        self.known = known
+
+
+class ReservedNativeKeyError(NativeConfigError):
+    def __init__(self, slot: str, key: str, hint: str) -> None:
+        super().__init__(f"Native key {key!r} in slot {slot!r} is owned by clientwright: {hint}")
+        self.slot = slot
+        self.key = key
+
+
+class UnknownNativeKeyError(NativeConfigError):
+    def __init__(self, slot: str, key: str, suggestion: str | None = None) -> None:
+        hint = f"; did you mean {suggestion!r}?" if suggestion else ""
+        super().__init__(f"Native slot {slot!r} accepts no parameter {key!r}{hint}")
+        self.slot = slot
+        self.key = key
+        self.suggestion = suggestion
+
+
+class NativeConfigConflictError(NativeConfigError):
+    def __init__(self, slot: str, key: str, config_field: str) -> None:
+        super().__init__(
+            f"Native key {key!r} in slot {slot!r} conflicts with explicitly set config field {config_field!r}; "
+            f"set it in exactly one place"
+        )
+        self.slot = slot
+        self.key = key
+        self.config_field = config_field
+
+
+class CallError(ClientwrightError):
+    """Base for errors raised while executing a call; adapters dual-inherit these."""
+
+
+class CircuitOpenError(CallError):
+    """Local refusal: the circuit for this key is open."""
+
+    def __init__(self, key: str, retry_after: float | None = None) -> None:
+        suffix = f" (retry in ~{retry_after:.1f}s)" if retry_after is not None else ""
+        super().__init__(f"Circuit open for {key!r}{suffix}")
+        self.key = key
+        self.retry_after = retry_after
+
+
+class DeadlineExceededError(CallError):
+    """The total deadline of the logical call was exhausted."""
+
+    def __init__(self, total: float) -> None:
+        super().__init__(f"Deadline of {total:.3f}s exhausted")
+        self.total = total
+
+
+class TooManyRedirectsError(CallError):
+    def __init__(self, hops: int) -> None:
+        super().__init__(f"Exceeded {hops} redirect hops")
+        self.hops = hops
+
+
+class NotReplayableError(CallError):
+    """The request body cannot be replayed, so the required repeat is impossible."""
+
+
+__all__ = [
+    "CallError",
+    "CircuitOpenError",
+    "ClientwrightError",
+    "DeadlineExceededError",
+    "NativeConfigConflictError",
+    "NativeConfigError",
+    "NotReplayableError",
+    "ReservedNativeKeyError",
+    "TooManyRedirectsError",
+    "UnknownAdapterError",
+    "UnknownNativeKeyError",
+    "UnknownNativeSlotError",
+    "UnsupportedCapabilityError",
+]

clientwright/core/model.py

@@ -0,0 +1,138 @@
+"""Transport-neutral data model shared by engines, policies and adapters."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from urllib.parse import urlsplit
+
+_DEFAULT_PORTS = {"http": 80, "https": 443}
+
+# Methods whose semantics make a repeat safe without an idempotency key (RFC 9110).
+IDEMPOTENT_METHODS = frozenset({"GET", "HEAD", "PUT", "DELETE", "OPTIONS", "TRACE"})
+
+
+class FailureKind(StrEnum):
+    """Shared alphabet of call outcomes.
+
+    An alphabet, not a shared partition: each adapter declares which kinds it
+    can actually emit (``AdapterCapabilities.emits``) and which finer kinds
+    collapse into coarser ones (``AdapterCapabilities.collapses``).
+    """
+
+    CONNECT_TIMEOUT = "connect_timeout"
+    READ_TIMEOUT = "read_timeout"
+    WRITE_TIMEOUT = "write_timeout"
+    POOL_TIMEOUT = "pool_timeout"
+    TOTAL_TIMEOUT = "total_timeout"
+    CONNECT_ERROR = "connect_error"
+    DNS_ERROR = "dns_error"
+    TLS_ERROR = "tls_error"
+    PROTOCOL_ERROR = "protocol_error"
+    DISCONNECTED = "disconnected"
+    BODY_ERROR = "body_error"
+    STATUS = "status"
+    CANCELLED = "cancelled"
+    CIRCUIT_OPEN = "circuit_open"
+    UNKNOWN = "unknown"
+
+
+class CircuitKey(StrEnum):
+    """Granularity of the circuit-breaker key."""
+
+    ORIGIN = "origin"
+    ORIGIN_ROUTE = "origin_route"
+    ORIGIN_METHOD = "origin_method"
+
+
+@dataclass(frozen=True, slots=True)
+class Outcome:
+    """Result of a single attempt. ``kind is None`` means success."""
+
+    kind: FailureKind | None
+    status_code: int | None = None
+    retry_after: float | None = None
+    exception: BaseException | None = None
+
+    @property
+    def ok(self) -> bool:
+        return self.kind is None
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedTimeouts:
+    """Per-attempt timeout plan handed to the adapter before each send.
+
+    ``attempt`` is the hard ceiling of the whole attempt; async engines enforce
+    it with task cancellation, sync engines can only clamp the phases below.
+    """
+
+    connect: float | None = None
+    read: float | None = None
+    write: float | None = None
+    pool_acquire: float | None = None
+    attempt: float | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ConnMetrics:
+    """Optional per-connection timings; ``None`` fields mean the adapter cannot see them."""
+
+    dns: float | None = None
+    connect: float | None = None
+    tls: float | None = None
+    pool_wait: float | None = None
+    reused: bool | None = None
+    http_version: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class Attempt:
+    """One physical attempt inside a logical call."""
+
+    index: int
+    started: float
+    duration: float
+    outcome: Outcome
+    hop: int = 0
+    conn: ConnMetrics | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class RequestInfo:
+    """Low-cardinality identity of a logical call."""
+
+    method: str
+    origin: str
+    url: str
+    route: str | None = None
+    idempotent: bool = True
+
+    def circuit_key(self, mode: CircuitKey) -> str:
+        if mode is CircuitKey.ORIGIN_ROUTE:
+            return f"{self.origin} {self.route or 'unknown'}"
+        if mode is CircuitKey.ORIGIN_METHOD:
+            return f"{self.origin} {self.method}"
+        return self.origin
+
+
+def origin_of(url: str) -> str:
+    """Normalize a URL to its origin: ``scheme://host:port`` lowercased, default ports explicit."""
+    parts = urlsplit(url)
+    scheme = (parts.scheme or "http").lower()
+    host = (parts.hostname or "").lower()
+    port = parts.port if parts.port is not None else _DEFAULT_PORTS.get(scheme)
+    return f"{scheme}://{host}:{port}" if port is not None else f"{scheme}://{host}"
+
+
+__all__ = [
+    "IDEMPOTENT_METHODS",
+    "Attempt",
+    "CircuitKey",
+    "ConnMetrics",
+    "FailureKind",
+    "Outcome",
+    "RequestInfo",
+    "ResolvedTimeouts",
+    "origin_of",
+]

clientwright/core/native.py

@@ -0,0 +1,84 @@
+"""Validation of raw native passthrough options.
+
+``PoolManager(**kw)``-style constructors swallow any typo silently; here every
+unknown slot, reserved key, misspelled parameter and config collision is a
+loud, actionable error at build time.
+"""
+
+from __future__ import annotations
+
+import difflib
+import inspect
+from collections.abc import Callable, Mapping
+
+from .config import NativeOptions
+from .errors import (
+    NativeConfigConflictError,
+    ReservedNativeKeyError,
+    UnknownNativeKeyError,
+    UnknownNativeSlotError,
+)
+
+
+def _suggest(key: str, candidates: list[str]) -> str | None:
+    matches = difflib.get_close_matches(key, candidates, n=1, cutoff=0.6)
+    return matches[0] if matches else None
+
+
+def _signature_keys(target: Callable[..., object]) -> tuple[frozenset[str], bool]:
+    """Keyword-acceptable parameter names and whether **kwargs is present."""
+    signature = inspect.signature(target)
+    names = set()
+    has_var_keyword = False
+    for parameter in signature.parameters.values():
+        if parameter.kind in (inspect.Parameter.POSITIONAL_OR_KEYWORD, inspect.Parameter.KEYWORD_ONLY):
+            names.add(parameter.name)
+        elif parameter.kind is inspect.Parameter.VAR_KEYWORD:
+            has_var_keyword = True
+    names.discard("self")
+    return frozenset(names), has_var_keyword
+
+
+def validate_native(
+    native: NativeOptions,
+    *,
+    slots: frozenset[str],
+    reserved: Mapping[str, Mapping[str, str]],
+    allowed: Mapping[str, frozenset[str] | None],
+    signature_targets: Mapping[str, Callable[..., object]],
+    config_conflicts: Mapping[str, Mapping[str, str]],
+) -> dict[str, dict[str, object]]:
+    """Validate and return per-slot native kwargs.
+
+    ``config_conflicts`` maps slot -> {native_key: explicitly-set config field};
+    the adapter builds it from fields the user actually set (not UNSET), so the
+    "conflict is an error" rule fires exactly when both sides were specified.
+    """
+    validated: dict[str, dict[str, object]] = {}
+    for slot, values in native.slots.items():
+        if slot not in slots:
+            raise UnknownNativeSlotError(slot, tuple(sorted(slots)))
+        reserved_keys = reserved.get(slot, {})
+        allowlist = allowed.get(slot)
+        signature_keys: frozenset[str] | None = None
+        has_var_keyword = False
+        if allowlist is None and slot in signature_targets:
+            signature_keys, has_var_keyword = _signature_keys(signature_targets[slot])
+        conflicts = config_conflicts.get(slot, {})
+        slot_values: dict[str, object] = {}
+        for key, value in values.items():
+            if key in reserved_keys:
+                raise ReservedNativeKeyError(slot, key, reserved_keys[key])
+            if key in conflicts:
+                raise NativeConfigConflictError(slot, key, conflicts[key])
+            if allowlist is not None:
+                if key not in allowlist:
+                    raise UnknownNativeKeyError(slot, key, _suggest(key, sorted(allowlist)))
+            elif signature_keys is not None and not has_var_keyword and key not in signature_keys:
+                raise UnknownNativeKeyError(slot, key, _suggest(key, sorted(signature_keys)))
+            slot_values[key] = value
+        validated[slot] = slot_values
+    return validated
+
+
+__all__ = ["validate_native"]

clientwright/core/options.py

@@ -0,0 +1,46 @@
+"""Ambient per-call options for adapters without a native per-request channel.
+
+httpx carries route/idempotency in ``request.extensions``; aiohttp, requests
+and urllib3 have no such container, so the options travel through a ContextVar
+set by the caller around the call. A task or thread-local context started
+under ``call_options`` inherits it; siblings do not.
+
+    with call_options(route="/users/{id}", idempotent=True):
+        session.post(f"/users/{user_id}")
+
+One shared channel on purpose: the block applies to whichever clientwright
+client sends inside it, uniformly across adapters.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Generator
+from contextlib import contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class CallOptions:
+    route: str | None = None
+    idempotent: bool | None = None
+
+
+_CALL_OPTIONS: ContextVar[CallOptions | None] = ContextVar("clientwright_call_options", default=None)
+
+
+def current_call_options() -> CallOptions | None:
+    return _CALL_OPTIONS.get()
+
+
+@contextmanager
+def call_options(*, route: str | None = None, idempotent: bool | None = None) -> Generator[CallOptions]:
+    options = CallOptions(route=route, idempotent=idempotent)
+    token = _CALL_OPTIONS.set(options)
+    try:
+        yield options
+    finally:
+        _CALL_OPTIONS.reset(token)
+
+
+__all__ = ["CallOptions", "call_options", "current_call_options"]