clientwright 0.1.0__py3-none-any.whl

clientwright/contrib/deadline.py

@@ -0,0 +1,107 @@
+"""deadline-budget integration (``[deadline]`` extra).
+
+The core stays zero-dependency: the engine consumes the structural
+``DeadlineSource`` protocol, and this module supplies sources backed by a
+deadline-budget ``BudgetContext`` - plus the ambient channel that carries one.
+
+deadline-budget deliberately has no implicit context: a ``BudgetContext`` is
+handed from call site to call site by argument. A client engine sits far below
+the code that knows the budget, so the ambient channel lives here::
+
+    from clientwright.contrib.deadline import AmbientDeadlineSource, use_budget
+
+    deps = AdapterDeps(deadline_source=AmbientDeadlineSource())
+    client = build("httpx", config, deps)
+
+    with use_budget(BudgetContext.create(total_seconds=5.0)):
+        await client.get("/users")  # runs with what is left of those 5 seconds
+
+Without the block every call behaves exactly as before: the ambient source
+finds no budget and the engine falls back to the configured total.
+
+Typed structurally on purpose - this module never imports deadline-budget, so
+any object with ``remaining()``/``expired()`` fits; the ``[deadline]`` extra
+exists to pin the library for services that use the real one. A ContextVar is
+per-task: a task started under ``use_budget`` inherits the budget (a fan-out
+shares one deadline), siblings do not.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Generator
+from contextlib import contextmanager
+from contextvars import ContextVar, Token
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class DeadlineBudgetProtocol(Protocol):
+    """What a source needs of a request budget: the shape of ``deadline_budget.BudgetContext``."""
+
+    def remaining(self) -> float:
+        """Seconds left; negative once the deadline has passed."""
+        ...
+
+    def expired(self) -> bool: ...
+
+
+_CURRENT_BUDGET: ContextVar[DeadlineBudgetProtocol | None] = ContextVar("clientwright_budget", default=None)
+
+
+def current_budget() -> DeadlineBudgetProtocol | None:
+    """The budget installed for the current task, or None if there is none."""
+    return _CURRENT_BUDGET.get()
+
+
+@contextmanager
+def use_budget(budget: DeadlineBudgetProtocol | None) -> Generator[DeadlineBudgetProtocol | None]:
+    """Install ``budget`` as the current one for the duration of the block.
+
+    The previous value is restored on the way out, so nesting works and an
+    inner budget cannot outlive its block. Passing None detaches an inherited
+    budget - for background work that must not die with the request that
+    spawned it.
+    """
+    token: Token[DeadlineBudgetProtocol | None] = _CURRENT_BUDGET.set(budget)
+    try:
+        yield budget
+    finally:
+        _CURRENT_BUDGET.reset(token)
+
+
+class BudgetDeadlineSource:
+    """DeadlineSource over ONE fixed budget - for a client scoped to a request."""
+
+    __slots__ = ("_budget",)
+
+    def __init__(self, budget: DeadlineBudgetProtocol) -> None:
+        self._budget = budget
+
+    def remaining(self) -> float | None:
+        return self._budget.remaining()
+
+
+class AmbientDeadlineSource:
+    """DeadlineSource reading whatever ``use_budget`` installed in this task.
+
+    The right default for a long-lived client: each call picks up the budget
+    of the request being served, and calls outside any budget run unbounded
+    by it (only the configured total applies).
+    """
+
+    __slots__ = ()
+
+    def remaining(self) -> float | None:
+        budget = current_budget()
+        if budget is None:
+            return None
+        return budget.remaining()
+
+
+__all__ = [
+    "AmbientDeadlineSource",
+    "BudgetDeadlineSource",
+    "DeadlineBudgetProtocol",
+    "current_budget",
+    "use_budget",
+]

clientwright/contrib/dishka.py

@@ -0,0 +1,80 @@
+"""Dishka integration (``[dishka]`` extra): APP-scope runtime, leak-free lifecycle.
+
+Two lessons from the legacy kit are structural here:
+
+- ``ClientRuntime`` (circuits, retry budgets, per-origin limiters) is APP
+  scope. A REQUEST-scoped runtime resets breaker state on every request and
+  turns the circuit breaker into decoration.
+- The client is provided by a GENERATOR provide whose finally closes it - the
+  legacy provider parked ``aclose`` on an AsyncExitStack that nothing ever
+  closed, leaking a client per request.
+
+Usage::
+
+    container = make_async_container(
+        ClientwrightProvider("httpx", config),
+        ...,
+    )
+    handle = await container.get(ClientHandle)
+    client: httpx.AsyncClient = handle.client
+
+Known limitation: the ``http_client_circuit_state`` gauge is wired when the
+ADAPTER builds the runtime; a runtime built here (to be shared) has no
+telemetry listener, so state-change events are not exported as a gauge.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from dataclasses import replace
+from typing import Any
+
+try:
+    from dishka import Provider, Scope, provide
+except ImportError as exc:  # pragma: no cover - exercised only without the extra
+    raise ImportError("Dishka integration requires clientwright[dishka]; install it.") from exc
+
+from ..core.config import ClientConfig
+from ..core.contracts.adapter import AdapterDeps, default_deps
+from ..core.plan import ClientHandle, ClientRuntime
+from ..core.registry import resolve_adapter
+
+
+class ClientwrightProvider(Provider):
+    """One async native client with an APP-scope runtime and guaranteed close.
+
+    For several upstreams, instantiate one provider per upstream in separate
+    containers, or subclass and add typed aliases (e.g. a provider returning
+    ``httpx.AsyncClient`` from the handle) for ergonomic injection.
+    """
+
+    scope = Scope.APP
+
+    def __init__(self, adapter: str, config: ClientConfig, deps: AdapterDeps | None = None) -> None:
+        super().__init__()
+        self._adapter = adapter
+        self._config = config
+        self._deps = deps or default_deps()
+
+    @provide
+    def client_runtime(self) -> ClientRuntime:
+        if self._deps.runtime is not None:
+            return self._deps.runtime
+        return ClientRuntime.for_config(self._config, clock=self._deps.clock)
+
+    @provide
+    async def client_handle(self, runtime: ClientRuntime) -> AsyncIterator[ClientHandle[Any]]:
+        adapter = resolve_adapter(self._adapter)()
+        handle: ClientHandle[Any] = adapter.build_async(self._config, replace(self._deps, runtime=runtime))
+        try:
+            yield handle
+        finally:
+            # The whole point: close travels WITH the provide, not on a stack
+            # nobody closes.
+            if handle.aclose is not None:
+                await handle.aclose()
+            elif handle.close is not None:
+                handle.close()
+
+
+__all__ = ["ClientwrightProvider"]

clientwright/core/__init__.py

@@ -0,0 +1,6 @@
+"""Pure kernel of clientwright.
+
+Everything under ``clientwright.core`` depends on the standard library only.
+Deleting ``clientwright/adapters`` must leave this package importable and its
+tests green; CI enforces the rule with import-linter contracts.
+"""

clientwright/core/balancer/__init__.py

@@ -0,0 +1 @@
+"""Client-side balancing seam. v1 ships the seam only, no implementation."""

clientwright/core/balancer/policy.py

@@ -0,0 +1,23 @@
+"""Target resolution seam for future client-side load balancing.
+
+Deliberately empty of implementations: in k8s/service-mesh environments client
+LB is usually harmful. The seam costs nothing because ``RequestView.retarget``
+already exists for owned redirects.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Protocol, runtime_checkable
+
+from ..model import Attempt, RequestInfo
+
+
+@runtime_checkable
+class TargetResolverProtocol(Protocol):
+    """Pure target choice; no health RPCs, no I/O."""
+
+    def pick(self, info: RequestInfo, history: Sequence[Attempt]) -> str: ...
+
+
+__all__ = ["TargetResolverProtocol"]

clientwright/core/capabilities.py

@@ -0,0 +1,156 @@
+"""Machine-readable declarations of what each adapter can and cannot do.
+
+Uniformity is sold by policy and telemetry schema, not by pretending semantics
+match: every divergence is declared here, validated at build time, and visible
+in the ``ConfigApplicationReport`` instead of a README paragraph.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from enum import StrEnum
+
+from .config import UnsupportedPolicy
+from .errors import UnsupportedCapabilityError
+from .model import FailureKind
+
+logger = logging.getLogger("clientwright.capabilities")
+
+
+class Support(StrEnum):
+    NATIVE = "native"
+    EMULATED = "emulated"
+    DEGRADED = "degraded"
+    ABSENT = "absent"
+
+
+class Capability(StrEnum):
+    TIMEOUT_TOTAL = "timeout_total"
+    TIMEOUT_ATTEMPT = "timeout_attempt"
+    TIMEOUT_CONNECT = "timeout_connect"
+    TIMEOUT_READ = "timeout_read"
+    TIMEOUT_WRITE = "timeout_write"
+    TIMEOUT_POOL = "timeout_pool"
+    DEADLINE_HARD = "deadline_hard"
+    POOL_LIMIT_TOTAL = "pool_limit_total"
+    POOL_LIMIT_PER_HOST = "pool_limit_per_host"
+    KEEPALIVE = "keepalive"
+    POOL_METRICS = "pool_metrics"
+    CONN_METRICS = "conn_metrics"
+    REDIRECTS_OWNABLE = "redirects_ownable"
+    NATIVE_RETRY_DISABLEABLE = "native_retry_disableable"
+    PER_CALL_OPTIONS = "per_call_options"
+    RETROFIT = "retrofit"
+    EXACT_NATIVE_TYPE = "exact_native_type"
+    BALANCER = "balancer"
+    HTTP2 = "http2"
+    HTTP3 = "http3"
+    PROXY = "proxy"
+
+
+class DurationBoundary(StrEnum):
+    HEADERS = "headers"
+    FULL = "full"
+
+
+class SeamGranularity(StrEnum):
+    HOP = "hop"
+    LOGICAL = "logical"
+
+
+@dataclass(frozen=True, slots=True)
+class AdapterCapabilities:
+    """Everything an adapter admits about itself, in one frozen record."""
+
+    adapter: str
+    seam: str
+    granularity: SeamGranularity
+    boundary: DurationBoundary
+    support: Mapping[Capability, Support]
+    emits: frozenset[FailureKind]
+    collapses: Mapping[FailureKind, FailureKind] = field(default_factory=dict)
+    notes: Mapping[str, str] = field(default_factory=dict)
+
+    def support_of(self, capability: Capability) -> Support:
+        return self.support.get(capability, Support.ABSENT)
+
+
+@dataclass(frozen=True, slots=True)
+class ConfigApplicationReport:
+    """What actually happened when a config met an adapter."""
+
+    adapter: str
+    applied_natively: frozenset[Capability] = frozenset()
+    emulated: frozenset[Capability] = frozenset()
+    dropped: Mapping[Capability, str] = field(default_factory=dict)
+    dead_retryable_kinds: frozenset[FailureKind] = frozenset()
+    collapsed_kinds: Mapping[FailureKind, FailureKind] = field(default_factory=dict)
+    native_overrides: Mapping[str, tuple[str, ...]] = field(default_factory=dict)
+
+    @property
+    def has_issues(self) -> bool:
+        return bool(self.dropped or self.dead_retryable_kinds)
+
+    def issues(self) -> list[str]:
+        problems = [f"{capability.value}: {reason}" for capability, reason in self.dropped.items()]
+        if self.dead_retryable_kinds:
+            dead = ", ".join(sorted(kind.value for kind in self.dead_retryable_kinds))
+            problems.append(f"retryable_kinds never emitted by {self.adapter}: {dead}")
+        return problems
+
+    def enforce(self, policy: UnsupportedPolicy) -> None:
+        """Apply the on_unsupported policy: raise, warn or stay silent."""
+        if not self.has_issues or policy is UnsupportedPolicy.IGNORE:
+            return
+        problems = self.issues()
+        if policy is UnsupportedPolicy.STRICT:
+            raise UnsupportedCapabilityError(
+                f"Adapter {self.adapter!r} cannot express the requested config: " + "; ".join(problems)
+            )
+        for problem in problems:
+            logger.warning("Adapter %s: %s", self.adapter, problem)
+
+
+def dead_retryable_kinds(
+    requested: frozenset[FailureKind], capabilities: AdapterCapabilities
+) -> frozenset[FailureKind]:
+    """Kinds the retry policy waits for but the adapter can never produce.
+
+    Collapsed kinds count as reachable through their coarser target.
+    """
+    reachable = set(capabilities.emits)
+    for source, target in capabilities.collapses.items():
+        if target in reachable:
+            reachable.add(source)
+    return frozenset(requested - reachable)
+
+
+def capabilities_matrix() -> dict[str, AdapterCapabilities]:
+    """Capability records of every registered adapter.
+
+    Adapter capability modules are zero-dependency and are imported dynamically
+    by registry path, so the matrix builds in an environment without a single
+    extra installed (and the core->adapters import-linter contract holds:
+    there are no static imports).
+    """
+    return _capability_records()
+
+
+def _capability_records() -> dict[str, AdapterCapabilities]:
+    from .registry import capability_records  # noqa: PLC0415 - deferred to keep module init order acyclic
+
+    return capability_records()
+
+
+__all__ = [
+    "AdapterCapabilities",
+    "Capability",
+    "ConfigApplicationReport",
+    "DurationBoundary",
+    "SeamGranularity",
+    "Support",
+    "capabilities_matrix",
+    "dead_retryable_kinds",
+]