clientwright 0.1.0__py3-none-any.whl

clientwright/core/plan.py

@@ -0,0 +1,190 @@
+"""Compiled call plans, the APP-scope runtime and client handles."""
+
+from __future__ import annotations
+
+import time
+import weakref
+from collections.abc import Awaitable, Callable, Mapping
+from dataclasses import dataclass
+from random import Random
+from typing import Any
+
+from .capabilities import (
+    AdapterCapabilities,
+    Capability,
+    ConfigApplicationReport,
+    Support,
+    dead_retryable_kinds,
+)
+from .config import ClientConfig, RetryMode, resolve
+from .model import FailureKind, ResolvedTimeouts
+from .policy.budget import RetryBudgetRegistry
+from .policy.circuit import CircuitRegistry, StateListener
+from .policy.concurrency import AsyncOriginLimiter, SyncOriginLimiter
+from .policy.retry import DefaultRetryPolicy
+from .policy.timeout import TimeoutPlanner, base_timeouts
+
+
+class ClientRuntime:
+    """State that must outlive REQUEST-scoped clients: circuits, budgets, limiters.
+
+    Give this APP scope in DI. A fresh runtime per client makes the circuit
+    breaker and retry budget decorative.
+    """
+
+    def __init__(
+        self,
+        *,
+        clock: Callable[[], float] | None = None,
+        rng: Random | None = None,
+        circuits: CircuitRegistry | None = None,
+        retry_budgets: RetryBudgetRegistry | None = None,
+        async_limiter: AsyncOriginLimiter | None = None,
+        sync_limiter: SyncOriginLimiter | None = None,
+    ) -> None:
+        self.clock: Callable[[], float] = clock or time.monotonic
+        self.rng = rng or Random()  # noqa: S311 - jitter, not cryptography
+        self.circuits = circuits
+        self.retry_budgets = retry_budgets
+        self.async_limiter = async_limiter
+        self.sync_limiter = sync_limiter
+
+    @classmethod
+    def for_config(
+        cls,
+        config: ClientConfig,
+        *,
+        clock: Callable[[], float] | None = None,
+        rng: Random | None = None,
+        circuit_listener: StateListener | None = None,
+    ) -> ClientRuntime:
+        resolved_clock = clock or time.monotonic
+        circuits = (
+            CircuitRegistry(config.circuit_breaker, resolved_clock, circuit_listener)
+            if config.circuit_breaker is not None
+            else None
+        )
+        retry_budgets = (
+            RetryBudgetRegistry(config.retry.budget_ratio)
+            if config.retry is not None and config.retry.budget_ratio is not None
+            else None
+        )
+        per_host = resolve(config.pool.max_connections_per_host, None)
+        async_limiter = AsyncOriginLimiter(per_host) if per_host is not None else None
+        sync_limiter = SyncOriginLimiter(per_host) if per_host is not None else None
+        return cls(
+            clock=resolved_clock,
+            rng=rng,
+            circuits=circuits,
+            retry_budgets=retry_budgets,
+            async_limiter=async_limiter,
+            sync_limiter=sync_limiter,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class CallPlan:
+    """Everything the engine needs, compiled once at build time."""
+
+    config: ClientConfig
+    capabilities: AdapterCapabilities
+    planner: TimeoutPlanner
+    retry_policy: DefaultRetryPolicy | None
+    report: ConfigApplicationReport
+    use_origin_limiter: bool
+    # False under RetryMode.DELEGATED: attempts live below the seam, inside the
+    # native retry machinery, and a single fake attempt record would be a lie.
+    emit_attempt_metrics: bool = True
+
+
+def compile_plan(
+    config: ClientConfig,
+    capabilities: AdapterCapabilities,
+    *,
+    native_timeout_defaults: ResolvedTimeouts,
+    applied_natively: frozenset[Capability] = frozenset(),
+    emulated: frozenset[Capability] = frozenset(),
+    dropped: Mapping[Capability, str] | None = None,
+    native_overrides: Mapping[str, tuple[str, ...]] | None = None,
+) -> CallPlan:
+    """Compile config against capabilities; the caller enforces the report."""
+    dead: frozenset[FailureKind] = frozenset()
+    retry_policy: DefaultRetryPolicy | None = None
+    if config.retry is not None and config.retry.mode is RetryMode.OWNED:
+        retry_policy = DefaultRetryPolicy(config.retry)
+        dead = dead_retryable_kinds(config.retry.retryable_kinds, capabilities)
+    report = ConfigApplicationReport(
+        adapter=capabilities.adapter,
+        applied_natively=applied_natively,
+        emulated=emulated,
+        dropped=dict(dropped or {}),
+        dead_retryable_kinds=dead,
+        collapsed_kinds=dict(capabilities.collapses),
+        native_overrides=dict(native_overrides or {}),
+    )
+    per_host = resolve(config.pool.max_connections_per_host, None)
+    use_origin_limiter = (
+        per_host is not None and capabilities.support_of(Capability.POOL_LIMIT_PER_HOST) is Support.EMULATED
+    )
+    delegated = config.retry is not None and config.retry.mode is RetryMode.DELEGATED
+    return CallPlan(
+        config=config,
+        capabilities=capabilities,
+        planner=TimeoutPlanner(base_timeouts(config.timeout, native_timeout_defaults), config.caller_override),
+        retry_policy=retry_policy,
+        report=report,
+        use_origin_limiter=use_origin_limiter,
+        emit_attempt_metrics=not delegated,
+    )
+
+
+@dataclass(slots=True)
+class ClientHandle[ClientT]:
+    """The real native client plus everything clientwright knows about it."""
+
+    client: ClientT
+    adapter: str
+    capabilities: AdapterCapabilities
+    report: ConfigApplicationReport
+    runtime: ClientRuntime
+    plan: CallPlan
+    aclose: Callable[[], Awaitable[None]] | None = None
+    close: Callable[[], None] | None = None
+
+
+# The handle lives ON the client instance: the client<->handle reference cycle
+# is collectable by the garbage collector once the caller drops both, unlike a
+# module-global registry whose strong value would pin the client forever.
+_HANDLE_ATTRIBUTE = "_clientwright_handle"
+
+# Fallback for exotic clients without __dict__; entries here live as long as
+# the handle does, which is as long as the client (documented limitation).
+_HANDLE_FALLBACK: weakref.WeakKeyDictionary[Any, ClientHandle[Any]] = weakref.WeakKeyDictionary()
+
+
+def register_handle(client: object, handle: ClientHandle[Any]) -> None:
+    try:
+        object.__setattr__(client, _HANDLE_ATTRIBUTE, handle)
+    except (AttributeError, TypeError):
+        _HANDLE_FALLBACK[client] = handle
+
+
+def inspect_client(client: object) -> ClientHandle[Any] | None:
+    """The handle of a built client, or None for foreign objects."""
+    handle = getattr(client, _HANDLE_ATTRIBUTE, None)
+    if handle is not None:
+        return handle  # type: ignore[no-any-return]
+    try:
+        return _HANDLE_FALLBACK.get(client)
+    except TypeError:  # not weak-referenceable: certainly not a client we built
+        return None
+
+
+__all__ = [
+    "CallPlan",
+    "ClientHandle",
+    "ClientRuntime",
+    "compile_plan",
+    "inspect_client",
+    "register_handle",
+]

clientwright/core/policy/__init__.py

@@ -0,0 +1 @@
+"""Pure policies: no I/O, no awaits, one implementation for both runtimes."""

clientwright/core/policy/budget.py

@@ -0,0 +1,76 @@
+"""Monotonic deadlines and per-origin retry budgets."""
+
+from __future__ import annotations
+
+import threading
+from collections import OrderedDict
+from collections.abc import Callable
+
+
+class Deadline:
+    """Wall-of-time budget of one logical call, measured on a monotonic clock."""
+
+    __slots__ = ("_clock", "_expires_at", "total")
+
+    def __init__(self, total: float | None, clock: Callable[[], float]) -> None:
+        self.total = total
+        self._clock = clock
+        self._expires_at = None if total is None else clock() + total
+
+    @classmethod
+    def intersect(cls, clock: Callable[[], float], *totals: float | None) -> Deadline:
+        """The tightest of several budgets; ``None`` entries do not constrain."""
+        bounded = [total for total in totals if total is not None]
+        return cls(min(bounded) if bounded else None, clock)
+
+    def remaining(self) -> float | None:
+        if self._expires_at is None:
+            return None
+        return self._expires_at - self._clock()
+
+    @property
+    def expired(self) -> bool:
+        remaining = self.remaining()
+        return remaining is not None and remaining <= 0
+
+
+class RetryBudgetRegistry:
+    """Token-bucket retry budget per origin.
+
+    Every logical call earns ``ratio`` tokens; every retry spends one. With the
+    default ratio of 0.1 at most ~10% of traffic can be retries, which prevents
+    retry storms against a struggling upstream.
+    """
+
+    _MAX_TOKENS = 10.0
+
+    def __init__(self, ratio: float | None, max_origins: int = 512) -> None:
+        self._ratio = ratio
+        self._max_origins = max_origins
+        self._tokens: OrderedDict[str, float] = OrderedDict()
+        self._lock = threading.Lock()
+
+    def earn(self, origin: str) -> None:
+        if self._ratio is None:
+            return
+        with self._lock:
+            tokens = self._tokens.pop(origin, None)
+            # A fresh origin starts with a FULL bucket: an initial burst of
+            # retries is allowed, the sustained rate is capped by the ratio.
+            self._tokens[origin] = self._MAX_TOKENS if tokens is None else min(tokens + self._ratio, self._MAX_TOKENS)
+            while len(self._tokens) > self._max_origins:
+                self._tokens.popitem(last=False)
+
+    def try_spend(self, origin: str) -> bool:
+        if self._ratio is None:
+            return True
+        with self._lock:
+            tokens = self._tokens.get(origin, 0.0)
+            if tokens < 1.0:
+                return False
+            self._tokens[origin] = tokens - 1.0
+            self._tokens.move_to_end(origin)
+            return True
+
+
+__all__ = ["Deadline", "RetryBudgetRegistry"]

clientwright/core/policy/circuit.py

@@ -0,0 +1,169 @@
+"""Circuit breaker registry: monotonic clock, LRU-capped keys, thread-safe.
+
+One signal per logical call: the engine calls ``check`` once before the attempt
+loop and ``record`` once with the final outcome, so retries cannot pump the
+failure counter of a single call. A call that dies without a classified outcome
+(cancellation, adapter fault) is ``record_aborted`` - it releases its half-open
+slot but is neither a success nor a failure signal.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from collections import OrderedDict
+from collections.abc import Callable
+from dataclasses import dataclass
+from enum import StrEnum
+
+from ..config import CircuitBreakerConfig
+from ..errors import CircuitOpenError
+from ..model import FailureKind, Outcome
+
+logger = logging.getLogger("clientwright.circuit")
+
+
+class CircuitState(StrEnum):
+    CLOSED = "closed"
+    OPEN = "open"
+    HALF_OPEN = "half_open"
+
+
+@dataclass(slots=True)
+class _KeyState:
+    state: CircuitState = CircuitState.CLOSED
+    failures: int = 0
+    opened_at: float = 0.0
+    half_open_in_flight: int = 0
+
+    @property
+    def evictable(self) -> bool:
+        """Only cold, fully closed circuits may be LRU-evicted."""
+        return self.state is CircuitState.CLOSED and self.failures == 0 and self.half_open_in_flight == 0
+
+
+StateListener = Callable[[str, CircuitState], None]
+
+
+@dataclass(frozen=True, slots=True)
+class CircuitSnapshot:
+    state: CircuitState
+    failures: int
+
+
+class CircuitRegistry:
+    """Per-key circuit state machines behind one lock (operations are O(1)).
+
+    The state listener is invoked AFTER the lock is released, so a slow or
+    re-entrant listener (one that calls ``snapshot()`` or triggers another
+    call on a shared runtime) can neither stall other callers nor deadlock.
+    """
+
+    def __init__(
+        self,
+        config: CircuitBreakerConfig,
+        clock: Callable[[], float],
+        on_state_change: StateListener | None = None,
+    ) -> None:
+        self._config = config
+        self._clock = clock
+        self._on_state_change = on_state_change
+        self._states: OrderedDict[str, _KeyState] = OrderedDict()
+        self._lock = threading.Lock()
+
+    def _get(self, key: str) -> _KeyState:
+        state = self._states.pop(key, None)
+        if state is None:
+            state = _KeyState()
+        self._states[key] = state
+        if len(self._states) > self._config.max_keys:
+            # Evict the least recently used COLD entry; an OPEN or HALF_OPEN
+            # circuit must never be silently disarmed, so the cap is soft when
+            # every entry is hot.
+            for candidate_key, candidate in self._states.items():
+                if candidate_key != key and candidate.evictable:
+                    del self._states[candidate_key]
+                    break
+        return state
+
+    def _notify(self, transitions: list[tuple[str, CircuitState]]) -> None:
+        if self._on_state_change is None:
+            return
+        for key, state in transitions:
+            try:
+                self._on_state_change(key, state)
+            except Exception:
+                logger.debug("Circuit state listener failed for %s", key, exc_info=True)
+
+    def check(self, key: str) -> None:
+        """Admit or reject the logical call; may transition OPEN -> HALF_OPEN.
+
+        The call that performs the transition consumes one half-open slot, so at
+        most ``half_open_max_calls`` trial calls are in flight (the legacy kit
+        let the transitioning call fly for free).
+        """
+        config = self._config
+        transitions: list[tuple[str, CircuitState]] = []
+        try:
+            with self._lock:
+                state = self._get(key)
+                if state.state is CircuitState.OPEN:
+                    elapsed = self._clock() - state.opened_at
+                    if elapsed < config.recovery_timeout:
+                        raise CircuitOpenError(key, retry_after=config.recovery_timeout - elapsed)
+                    state.state = CircuitState.HALF_OPEN
+                    state.half_open_in_flight = 0
+                    transitions.append((key, CircuitState.HALF_OPEN))
+                if state.state is CircuitState.HALF_OPEN:
+                    if state.half_open_in_flight >= config.half_open_max_calls:
+                        raise CircuitOpenError(key)
+                    state.half_open_in_flight += 1
+        finally:
+            self._notify(transitions)
+
+    def _trips(self, outcome: Outcome) -> bool:
+        kind = outcome.kind
+        if kind is None or kind not in self._config.trip_kinds:
+            return False
+        if kind is FailureKind.STATUS:
+            return outcome.status_code is not None and outcome.status_code >= 500
+        return True
+
+    def record(self, key: str, outcome: Outcome) -> None:
+        """Record the FINAL outcome of one admitted logical call."""
+        config = self._config
+        transitions: list[tuple[str, CircuitState]] = []
+        with self._lock:
+            state = self._get(key)
+            if state.state is CircuitState.HALF_OPEN and state.half_open_in_flight > 0:
+                state.half_open_in_flight -= 1
+            if self._trips(outcome):
+                state.failures += 1
+                if state.state is CircuitState.HALF_OPEN or (
+                    state.state is CircuitState.CLOSED and state.failures >= config.fail_threshold
+                ):
+                    state.state = CircuitState.OPEN
+                    state.opened_at = self._clock()
+                    state.half_open_in_flight = 0
+                    transitions.append((key, CircuitState.OPEN))
+            else:
+                if state.state is CircuitState.HALF_OPEN:
+                    state.state = CircuitState.CLOSED
+                    transitions.append((key, CircuitState.CLOSED))
+                state.failures = 0
+        self._notify(transitions)
+
+    def record_aborted(self, key: str) -> None:
+        """An admitted call died without a classified outcome (cancellation,
+        adapter fault): release its half-open slot, count nothing."""
+        with self._lock:
+            state = self._get(key)
+            if state.state is CircuitState.HALF_OPEN and state.half_open_in_flight > 0:
+                state.half_open_in_flight -= 1
+
+    def snapshot(self) -> dict[str, CircuitSnapshot]:
+        with self._lock:
+            return {key: CircuitSnapshot(state=s.state, failures=s.failures) for key, s in self._states.items()}
+
+
+__all__ = ["CircuitRegistry", "CircuitSnapshot", "CircuitState"]

clientwright/core/policy/concurrency.py

@@ -0,0 +1,98 @@
+"""Per-origin in-flight limiters emulating a per-host connection limit.
+
+This limits in-flight REQUESTS, not connections - close but not identical,
+which is why adapters relying on it declare ``POOL_LIMIT_PER_HOST: EMULATED``.
+
+The async limiter keys its semaphores by the RUNNING EVENT LOOP: an APP-scoped
+runtime may serve several loops over its lifetime (worker threads, sequential
+``asyncio.run`` calls, test suites), and an ``asyncio.Semaphore`` binds to the
+loop of its first contended acquire. Per-loop state also dies with its loop,
+so slots consumed in a dead loop cannot shrink the limit forever.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+import weakref
+from types import TracebackType
+
+
+class AsyncOriginLimiter:
+    """Per-(event loop, origin) semaphores; safe to share across loops and threads."""
+
+    def __init__(self, limit: int) -> None:
+        self._limit = limit
+        self._per_loop: weakref.WeakKeyDictionary[asyncio.AbstractEventLoop, dict[str, asyncio.Semaphore]] = (
+            weakref.WeakKeyDictionary()
+        )
+        self._lock = threading.Lock()
+
+    def _semaphore(self, origin: str) -> asyncio.Semaphore:
+        loop = asyncio.get_running_loop()
+        with self._lock:
+            per_origin = self._per_loop.get(loop)
+            if per_origin is None:
+                per_origin = {}
+                self._per_loop[loop] = per_origin
+            semaphore = per_origin.get(origin)
+            if semaphore is None:
+                semaphore = asyncio.Semaphore(self._limit)
+                per_origin[origin] = semaphore
+        return semaphore
+
+    def acquire(self, origin: str) -> _AsyncSlot:
+        return _AsyncSlot(self._semaphore(origin))
+
+
+class _AsyncSlot:
+    def __init__(self, semaphore: asyncio.Semaphore) -> None:
+        self._semaphore = semaphore
+
+    async def __aenter__(self) -> None:
+        await self._semaphore.acquire()
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self._semaphore.release()
+
+
+class SyncOriginLimiter:
+    def __init__(self, limit: int) -> None:
+        self._limit = limit
+        self._semaphores: dict[str, threading.BoundedSemaphore] = {}
+        self._lock = threading.Lock()
+
+    def _semaphore(self, origin: str) -> threading.BoundedSemaphore:
+        with self._lock:
+            semaphore = self._semaphores.get(origin)
+            if semaphore is None:
+                semaphore = threading.BoundedSemaphore(self._limit)
+                self._semaphores[origin] = semaphore
+            return semaphore
+
+    def acquire(self, origin: str) -> _SyncSlot:
+        return _SyncSlot(self._semaphore(origin))
+
+
+class _SyncSlot:
+    def __init__(self, semaphore: threading.BoundedSemaphore) -> None:
+        self._semaphore = semaphore
+
+    def __enter__(self) -> None:
+        self._semaphore.acquire()
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self._semaphore.release()
+
+
+__all__ = ["AsyncOriginLimiter", "SyncOriginLimiter"]

clientwright/core/policy/retry.py

@@ -0,0 +1,80 @@
+"""Retry decision policy: a pure function shared by the sync and async engines.
+
+``decide`` never sleeps, never logs and knows nothing about coroutines; the
+engine owns the loop, the sleeping and the budget accounting.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from random import Random
+
+from ..config import RetryConfig
+from ..model import Attempt, FailureKind, RequestInfo
+
+# A retry whose backoff would land this close to the deadline is pointless.
+_DEADLINE_SLACK = 0.001
+
+
+@dataclass(frozen=True, slots=True)
+class RetryDecision:
+    retry: bool
+    delay: float = 0.0
+    reason: str = ""
+
+
+class DefaultRetryPolicy:
+    """Config-driven policy implementing the org-wide retry semantics."""
+
+    def __init__(self, config: RetryConfig) -> None:
+        self._config = config
+
+    def _wants_retry(self, attempt: Attempt) -> str | None:
+        """Reason string when the last outcome is retry-worthy, else None."""
+        outcome = attempt.outcome
+        if outcome.status_code is not None and outcome.status_code in self._config.retryable_status:
+            return f"status_{outcome.status_code}"
+        kind = outcome.kind
+        if kind is not None and kind is not FailureKind.STATUS and kind in self._config.retryable_kinds:
+            return f"kind_{kind.value}"
+        return None
+
+    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:
+            return min(retry_after, config.retry_after_max)
+        delay = min(config.initial_backoff * config.multiplier ** (attempt_index - 1), config.max_backoff)
+        if config.jitter:
+            delay *= 1.0 + rng.uniform(-config.jitter, config.jitter)
+        return max(delay, 0.0)
+
+    def decide(
+        self,
+        *,
+        info: RequestInfo,
+        history: Sequence[Attempt],
+        remaining: float | None,
+        replayable: bool,
+        rng: Random,
+    ) -> RetryDecision:
+        if not history:
+            return RetryDecision(retry=False, reason="no_attempts")
+        config = self._config
+        last = history[-1]
+        reason = self._wants_retry(last)
+        if reason is None:
+            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:
+            return RetryDecision(retry=False, reason="method")
+        if config.require_replayable_body and not replayable:
+            return RetryDecision(retry=False, reason="non_replayable")
+        delay = self._backoff(len(history), last.outcome.retry_after, rng)
+        if remaining is not None and delay + _DEADLINE_SLACK >= remaining:
+            return RetryDecision(retry=False, reason="deadline")
+        return RetryDecision(retry=True, delay=delay, reason=reason)
+
+
+__all__ = ["DefaultRetryPolicy", "RetryDecision"]

clientwright/core/policy/timeout.py

@@ -0,0 +1,64 @@
+"""Per-attempt timeout planning.
+
+The planner starts from base phases (config knobs already resolved against the
+adapter's native defaults at build time), merges the caller's per-call override
+according to ``CallerOverride``, then clamps every phase and the attempt
+ceiling by the remaining total budget.
+"""
+
+from __future__ import annotations
+
+from ..config import CallerOverride, TimeoutConfig, resolve
+from ..errors import CallError
+from ..model import ResolvedTimeouts
+
+
+class CallerOverrideForbiddenError(CallError):
+    def __init__(self) -> None:
+        super().__init__("Per-call timeout overrides are forbidden by config (caller_override=raise)")
+
+
+def base_timeouts(config: TimeoutConfig, native_defaults: ResolvedTimeouts) -> ResolvedTimeouts:
+    """Resolve UNSET phases against the adapter's native defaults, once, at build."""
+    return ResolvedTimeouts(
+        connect=resolve(config.connect, native_defaults.connect),
+        read=resolve(config.read, native_defaults.read),
+        write=resolve(config.write, native_defaults.write),
+        pool_acquire=resolve(config.pool_acquire, native_defaults.pool_acquire),
+        attempt=resolve(config.attempt, None),
+    )
+
+
+class TimeoutPlanner:
+    __slots__ = ("_base", "_caller_override")
+
+    def __init__(self, base: ResolvedTimeouts, caller_override: CallerOverride) -> None:
+        self._base = base
+        self._caller_override = caller_override
+
+    @staticmethod
+    def _clamp(phase: float | None, remaining: float | None) -> float | None:
+        if remaining is None:
+            return phase
+        if phase is None:
+            return remaining
+        return min(phase, remaining)
+
+    def plan(self, *, remaining: float | None, caller: ResolvedTimeouts | None) -> ResolvedTimeouts:
+        base = self._base
+        if caller is not None:
+            if self._caller_override is CallerOverride.RAISE:
+                raise CallerOverrideForbiddenError
+            if self._caller_override is CallerOverride.CALLER_WINS:
+                base = caller
+        attempt = self._clamp(base.attempt, remaining)
+        return ResolvedTimeouts(
+            connect=self._clamp(base.connect, remaining),
+            read=self._clamp(base.read, remaining),
+            write=self._clamp(base.write, remaining),
+            pool_acquire=self._clamp(base.pool_acquire, remaining),
+            attempt=attempt,
+        )
+
+
+__all__ = ["CallerOverrideForbiddenError", "TimeoutPlanner", "base_timeouts"]