grpc-client-kit 0.1.0__py3-none-any.whl

grpc_client_kit/client.py

@@ -0,0 +1,236 @@
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from typing import (
+    Any,
+)
+
+import grpc.aio
+
+from .balancers import LoadBalancer
+from .channel import ChannelKey, ChannelPool
+from .config import GrpcClientConfig
+from .protocols import ChannelProviderProtocol
+
+logger = logging.getLogger(__name__)
+
+
+class GrpcClient[T]:
+    """Factory for gRPC stubs. Manages target selection and channel acquisition from pool.
+
+    Interceptor Chains:
+        A chain is built per target and cached, because gRPC binds interceptors to a channel when
+        the channel is created. Stateful interceptors — the circuit breaker above all — therefore
+        track one backend each: a single failing member of a load-balanced set can no longer trip
+        the breaker for its healthy peers. Pass ``interceptor_factory`` to get that isolation;
+        passing a ready ``interceptors`` list instead shares one chain (and one breaker) across
+        every target of this client.
+
+    Ownership Semantics:
+        This client DOES NOT own the `ChannelPool` it uses. It is a lightweight wrapper that
+        acquires channels from a shared pool. Closing the client (via __aexit__) does NOT
+        close the underlying channels or the pool.
+    """
+
+    def __init__(
+        self,
+        stub_class: type[T],
+        config: GrpcClientConfig,
+        pool: ChannelProviderProtocol,
+        balancer: LoadBalancer | None = None,
+        interceptors: list[grpc.aio.ClientInterceptor] | None = None,
+        interceptor_factory: Callable[[str], list[grpc.aio.ClientInterceptor]] | None = None,
+    ) -> None:
+        """Initialize the gRPC client.
+
+        Args:
+            stub_class: The gRPC stub class to instantiate (e.g., MyServiceStub).
+            config: Configuration for the client (target, security, etc.).
+            pool: The channel pool to acquire channels from.
+            balancer: Optional load balancer for multiple targets.
+            interceptors: Optional ready chain, shared by every target of this client.
+            interceptor_factory: Optional builder called once per target to create a dedicated
+                chain for it.
+
+        Raises:
+            ValueError: If target configuration is ambiguous or missing, or if both an interceptor
+                chain and an interceptor factory are given.
+        """
+        self._stub_class = stub_class
+        self._config = config
+        self._pool = pool
+        self._balancer = balancer
+
+        if interceptors is not None and interceptor_factory is not None:
+            raise ValueError(
+                "Ambiguous interceptors: provide either 'interceptors' (one shared chain) "
+                "or 'interceptor_factory' (a chain per target), not both."
+            )
+
+        self._static_interceptors = list(interceptors) if interceptors is not None else None
+        self._interceptor_factory = interceptor_factory
+        self._chains: dict[str, list[grpc.aio.ClientInterceptor]] = {}
+        self._warned_native_retry = False
+        # Target, config and chain are fixed per target, so the pool identity is too: computing it
+        # (validation, option merging, chain tokens) once per target instead of once per call keeps
+        # that work off the hot path.
+        self._channel_keys: dict[str, ChannelKey] = {}
+
+        self._validate_target_configuration()
+
+    def _validate_target_configuration(self) -> None:
+        """Ensure that either a single target or a balancer is provided, but not both."""
+        if self._balancer and self._config.target:
+            raise ValueError(
+                "Ambiguous target: both 'balancer' and 'config.target' provided. "
+                "Use 'balancer' for multiple targets or 'config.target' for a single target."
+            )
+        if not self._balancer and not self._config.target:
+            raise ValueError("No target specified: provide either 'balancer' or 'config.target'")
+
+    def interceptors_for(self, target: str) -> list[grpc.aio.ClientInterceptor]:
+        """Return this client's interceptor chain for one target.
+
+        The chain is built at most once per target and then reused. That caching is what keeps the
+        pool key stable: rebuilding the chain on every call would mint a new channel identity each
+        time and the pool would open a channel per RPC.
+
+        Args:
+            target: The target address (host:port) the chain will be bound to.
+
+        Returns:
+            The interceptor chain for the target, empty when the client has no interceptors.
+        """
+        chain = self._chains.get(target)
+        if chain is None:
+            if self._static_interceptors is not None:
+                chain = self._static_interceptors
+            elif self._interceptor_factory is not None:
+                chain = self._interceptor_factory(target)
+            else:
+                chain = []
+            self._chains[target] = chain
+            self._warn_on_native_retry_overlap(chain)
+        return chain
+
+    def _warn_on_native_retry_overlap(self, chain: list[grpc.aio.ClientInterceptor]) -> None:
+        """Warn once when kit retries are stacked on top of native service-config retries.
+
+        Native ``retryPolicy`` runs inside the channel, below every interceptor, so the two layers
+        multiply: kit attempts times native attempts reach the server — a retry storm the kit's own
+        logs and metrics cannot see. The channel options pass through untouched on purpose (native
+        retries *without* kit retries are a fully supported configuration); only the combination is
+        worth a warning.
+        """
+        if self._warned_native_retry:
+            return
+
+        options = self._config.channel_options() or []
+        service_config = next((value for name, value in options if name == "grpc.service_config"), None)
+        if service_config is None or "retryPolicy" not in str(service_config):
+            return
+
+        from .interceptors.base import logical_interceptor  # noqa: PLC0415 - avoids import cycle at module load
+        from .interceptors.retry import AsyncRetryInterceptor  # noqa: PLC0415
+
+        if any(isinstance(logical_interceptor(entry), AsyncRetryInterceptor) for entry in chain):
+            self._warned_native_retry = True
+            logger.warning(
+                "Both kit retries and a native retryPolicy are configured for %s: the two layers "
+                "multiply (kit attempts x native attempts reach the server). Configure one source "
+                "of retries — drop the kit RetryConfig, or remove retryPolicy from grpc.service_config.",
+                self._config.target or "the balanced targets",
+            )
+
+    async def circuit_breaker_states(self) -> dict[str, dict[str, Any]]:
+        """Snapshot the circuit breakers of every chain this client has built.
+
+        During an incident this is the question an operator asks first — "is the breaker open, or
+        is the backend down?" — and it must be answerable without spelunking through the chain.
+
+        Returns:
+            Mapping of target to that target's breaker snapshot (method to status). Targets whose
+            chain has no breaker, or no chain built yet, are absent.
+        """
+        from .interceptors.base import logical_interceptor  # noqa: PLC0415 - avoids import cycle at module load
+        from .interceptors.circuit_breaker import AsyncCircuitBreakerInterceptor  # noqa: PLC0415
+
+        snapshot: dict[str, dict[str, Any]] = {}
+        for target, chain in self._chains.items():
+            for entry in chain:
+                owner = logical_interceptor(entry)
+                if isinstance(owner, AsyncCircuitBreakerInterceptor):
+                    snapshot[target] = dict(await owner.get_states())
+                    break
+        return snapshot
+
+    async def connect(self) -> T:
+        """Acquires a channel from the pool and returns a new stub instance.
+
+        Returns:
+            An instance of the stub_class configured with a pooled channel.
+
+        Raises:
+            NoHealthyTargetsError: If balancer is used and no healthy targets are available.
+            ValueError: If target is not specified.
+        """
+        target: str | None
+        if self._balancer:
+            target = await self._balancer.select_target()
+        else:
+            target = self._config.target
+
+        if target is None:
+            # This should be caught by _validate_target_configuration but adding check for mypy
+            raise ValueError("Target is not specified")
+
+        interceptors = self.interceptors_for(target)
+        if isinstance(self._pool, ChannelPool):
+            key = self._channel_keys.get(target)
+            if key is None:
+                key = self._pool.make_key(
+                    target,
+                    insecure=self._config.insecure,
+                    credentials=self._config.credentials,
+                    # Explicit options plus whatever the connectivity tuning adds; built the same
+                    # way every time, so the pool keeps recognising the channel it already has.
+                    options=self._config.channel_options(),
+                    compression=self._config.compression,
+                    interceptors=interceptors,
+                )
+                self._channel_keys[target] = key
+            channel = await self._pool.get_channel(target, interceptors=interceptors, key=key)
+        else:
+            # A custom provider speaks only the protocol surface, which has no key parameter.
+            channel = await self._pool.get_channel(
+                target,
+                insecure=self._config.insecure,
+                credentials=self._config.credentials,
+                options=self._config.channel_options(),
+                compression=self._config.compression,
+                interceptors=interceptors,
+            )
+
+        # Mypy might complain about calling a generic type as a class
+        return self._stub_class(channel)  # type: ignore[call-arg]
+
+    async def __aenter__(self) -> T:
+        """Async context manager entry. Calls connect()."""
+        return await self.connect()
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: Any | None,
+    ) -> None:
+        """Context manager exit.
+
+        NOTE: This does NOT close the underlying channel, as channels are managed by the ChannelPool.
+        The pool owns channel lifetimes; idle connections are parked by gRPC core, not closed.
+        """
+        return None
+
+
+__all__ = ["GrpcClient"]

grpc_client_kit/config.py

@@ -0,0 +1,185 @@
+"""Client configuration: what a channel is opened with, and how it is kept alive."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import (
+    Any,
+)
+
+import grpc
+
+
+def _milliseconds(seconds: float) -> int:
+    """Convert a duration in seconds into the milliseconds gRPC channel arguments are given in."""
+    return round(seconds * 1000)
+
+
+@dataclass(frozen=True, slots=True)
+class ConnectivityConfig:
+    """How a channel keeps its connection alive, and how fast it comes back after losing it.
+
+    These are gRPC channel arguments, which means two things. They are set once, when the channel is
+    created, and cannot be changed afterwards; and they are spelled as an untyped list of
+    ``("grpc.some_thing_ms", 30000)`` pairs that every caller currently has to remember, in the
+    right unit, by heart. This is that list, named, in seconds, and validated.
+
+    Keepalive pings detect a connection that has silently gone away — a dropped NAT mapping, a load
+    balancer that closed one side, a peer that vanished — which TCP alone can leave undetected until
+    a call has already hung on it. The reconnect backoff decides how long a channel that has lost
+    its connection waits before dialing again, and gRPC's own upper bound for that (two minutes) is
+    a long time for a backend that restarts in seconds.
+
+    Opt-in, deliberately. Pinging is a conversation the server has to agree to: it enforces its own
+    minimum interval and answers a client that pings too often with ``GOAWAY`` and
+    ``ENHANCE_YOUR_CALM``, so a client library that switched this on for everybody would be a way to
+    get connections dropped by servers that were never configured for it. The defaults here are what
+    a caller gets once they have decided to tune the channel at all: conservative enough for a
+    server left at its own defaults, which permits pings on a connection with calls in flight.
+
+    Attributes:
+        keepalive_time: Seconds of inactivity before a keepalive ping is sent. ``None`` leaves
+            gRPC's default, which is not to ping at all.
+        keepalive_timeout: Seconds to wait for the ping to be answered before the connection is
+            considered dead.
+        permit_without_calls: Whether to keep pinging while no call is in flight. Off by default:
+            this is the case servers police most tightly, and an idle connection that dies is
+            usually cheaper to re-establish than to keep watching.
+        max_pings_without_data: How many pings may be sent on a connection carrying no data before
+            the client stops; 0 means no limit.
+        initial_reconnect_backoff: Seconds to wait before the first reconnect attempt.
+        min_reconnect_backoff: Lower bound for the wait between reconnect attempts. ``None`` leaves
+            gRPC's default, which also bounds how long a single connect attempt may take.
+        max_reconnect_backoff: Upper bound for the wait between reconnect attempts, which is what
+            decides how long a client keeps failing after a backend is already back.
+    """
+
+    keepalive_time: float | None = 30.0
+    keepalive_timeout: float | None = 10.0
+    permit_without_calls: bool = False
+    max_pings_without_data: int | None = 2
+    initial_reconnect_backoff: float | None = 1.0
+    min_reconnect_backoff: float | None = None
+    max_reconnect_backoff: float | None = 30.0
+
+    def __post_init__(self) -> None:
+        """Validate the configuration.
+
+        Raises:
+            ValueError: If a duration is not positive, if the ping allowance is negative, or if the
+                reconnect bounds contradict each other.
+        """
+        durations = {
+            "keepalive_time": self.keepalive_time,
+            "keepalive_timeout": self.keepalive_timeout,
+            "initial_reconnect_backoff": self.initial_reconnect_backoff,
+            "min_reconnect_backoff": self.min_reconnect_backoff,
+            "max_reconnect_backoff": self.max_reconnect_backoff,
+        }
+        for name, value in durations.items():
+            # None is how a field says "leave gRPC's default"; 0 would be a different setting
+            # altogether, and not one any of these arguments has a meaning for.
+            if value is not None and value <= 0:
+                raise ValueError(f"{name} must be positive, or None to keep the gRPC default")
+
+        if self.max_pings_without_data is not None and self.max_pings_without_data < 0:
+            raise ValueError("max_pings_without_data must be non-negative (0 means no limit)")
+
+        if (
+            self.min_reconnect_backoff is not None
+            and self.max_reconnect_backoff is not None
+            and self.min_reconnect_backoff > self.max_reconnect_backoff
+        ):
+            raise ValueError("min_reconnect_backoff must not exceed max_reconnect_backoff")
+
+    def to_options(self) -> list[tuple[str, Any]]:
+        """Return these settings as gRPC channel arguments.
+
+        The order is the declaration order of the fields and never varies, which is what keeps a
+        channel's identity stable: options are part of the channel pool's key (see
+        `channel.ChannelKey`), so a list assembled differently from one call to the next would open
+        a new channel each time.
+
+        Returns:
+            The channel arguments, in seconds converted to the milliseconds gRPC expects. Fields
+            left at ``None`` contribute nothing, so gRPC keeps its own default for them.
+        """
+        options: list[tuple[str, Any]] = []
+
+        if self.keepalive_time is not None:
+            options.append(("grpc.keepalive_time_ms", _milliseconds(self.keepalive_time)))
+        if self.keepalive_timeout is not None:
+            options.append(("grpc.keepalive_timeout_ms", _milliseconds(self.keepalive_timeout)))
+
+        options.append(("grpc.keepalive_permit_without_calls", int(self.permit_without_calls)))
+
+        if self.max_pings_without_data is not None:
+            options.append(("grpc.http2.max_pings_without_data", self.max_pings_without_data))
+        if self.initial_reconnect_backoff is not None:
+            options.append(("grpc.initial_reconnect_backoff_ms", _milliseconds(self.initial_reconnect_backoff)))
+        if self.min_reconnect_backoff is not None:
+            options.append(("grpc.min_reconnect_backoff_ms", _milliseconds(self.min_reconnect_backoff)))
+        if self.max_reconnect_backoff is not None:
+            options.append(("grpc.max_reconnect_backoff_ms", _milliseconds(self.max_reconnect_backoff)))
+
+        return options
+
+
+@dataclass(slots=True)
+class GrpcClientConfig:
+    """Core configuration for establishing a gRPC channel connection.
+
+    Attributes:
+        target: The target address (host:port) or a gRPC-compatible resolver URI.
+        insecure: Whether to use an insecure channel (default: False).
+        credentials: SSL/TLS credentials for secure channels.
+        options: A list of key-value pairs to configure the gRPC channel. Anything set here wins
+            over `connectivity`.
+        compression: The compression algorithm to use for the channel.
+        connectivity: Keepalive and reconnect tuning, spelled in seconds instead of as raw channel
+            arguments. ``None`` leaves every one of those arguments at gRPC's own default.
+    """
+
+    target: str | None = None
+    insecure: bool = False
+    credentials: grpc.ChannelCredentials | None = None
+    options: list[tuple[str, Any]] | None = None
+    compression: grpc.Compression | None = None
+    connectivity: ConnectivityConfig | None = None
+
+    def __post_init__(self) -> None:
+        """Validate configuration."""
+        if self.insecure and self.credentials:
+            raise ValueError("Cannot provide credentials for an insecure channel")
+
+    def channel_options(self) -> list[tuple[str, Any]] | None:
+        """Return the full option list a channel is opened with.
+
+        Explicit `options` come first and untouched, followed by the arguments `connectivity` stands
+        for — minus any whose key the caller already used. Filtering those out is what makes "an
+        explicit option wins" true in the only sense gRPC can honour it: the argument is passed once,
+        with the caller's value, so there is no duplicate for gRPC to resolve one way or the other.
+
+        The result is a pure function of the configuration, in a fixed order, which matters because
+        the pool keys channels by their options among other things (see `channel.ChannelKey`): two
+        clients configured alike share a channel, and one client asking twice does not open two.
+        Without `connectivity` the caller's own list is handed back as it is — ``None`` included — so
+        a client that does not tune anything keeps exactly the channel identity it always had.
+
+        Returns:
+            The options to open the channel with, or None when there are none at all.
+        """
+        if self.connectivity is None:
+            return self.options
+
+        explicit = self.options or []
+        already_set = {key for key, _ in explicit}
+        derived = [(key, value) for key, value in self.connectivity.to_options() if key not in already_set]
+
+        if not derived:
+            return self.options
+
+        return [*explicit, *derived]
+
+
+__all__ = ["ConnectivityConfig", "GrpcClientConfig"]

grpc_client_kit/deadline.py

@@ -0,0 +1,122 @@
+"""The deadline budget of the request in flight, and the ambient context that carries it.
+
+`deadline-budget` deliberately has **no implicit context**: a `BudgetContext` is created by whoever
+starts the request and handed from one call site to the next by argument. That is the right default
+for a budget library and the wrong shape for a client kit — an interceptor sits far below the code
+that knows what the budget is, and none of the layers in between would carry it. Nothing propagates
+a deadline between services today; this module supplies the one piece that was missing, a contextvar
+holding the current budget, plus the two functions that write and read it.
+
+Installing a budget is the caller's job, and the chain only closes when they do it::
+
+    from deadline_budget import BudgetContext
+    from grpc_client_kit import use_budget
+
+    with use_budget(BudgetContext.create(total_seconds=5.0)):
+        await client.fetch_user(user_id)   # issued with what is left of those 5 seconds
+
+Without that block every call behaves exactly as it did before: the interceptor finds no budget and
+touches nothing. The kit provides the mechanism, not the magic — a service that never installs a
+budget propagates nothing, however many interceptors it runs.
+
+A `ContextVar` is per-task, which gives the semantics a deadline needs: a task started while a
+budget is installed inherits it, so a fan-out shares one deadline, while a budget installed inside
+one task is invisible to its siblings and cannot leak out of it.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar, Token
+from typing import Protocol, runtime_checkable
+
+# HAS_DEADLINE_BUDGET tells whether `deadline-budget` (the `deadline` extra) is importable. When it
+# is False the deadline interceptor is left out of the chain and everything here still works: the
+# contextvar is typed structurally, so it never needs the library to describe what it holds.
+try:
+    from deadline_budget import DeadlineExceededError
+
+    HAS_DEADLINE_BUDGET = True
+except ImportError:  # pragma: no cover - only reachable without the "deadline" extra
+    HAS_DEADLINE_BUDGET = False
+
+    class DeadlineExceededError(Exception):  # type: ignore[no-redef]
+        """Stand-in that keeps this module importable, and its ``except`` clauses evaluable."""
+
+
+@runtime_checkable
+class DeadlineBudgetProtocol(Protocol):
+    """What the kit needs of a request budget: the shape of `deadline_budget.BudgetContext`.
+
+    Typing against the shape rather than against the class is what keeps the library optional — the
+    kit never imports `deadline-budget` to describe a budget — and it leaves the door open for a
+    caller who tracks deadlines their own way.
+    """
+
+    def timeout_for_call(self, call_name: str, reserve_for_next: float = 0.0) -> float:
+        """Return the timeout the named call may use, bounded by what is left of the budget.
+
+        Args:
+            call_name: Name the per-call caps are keyed by.
+            reserve_for_next: Seconds to keep back for the steps that follow this call.
+
+        Returns:
+            The timeout in seconds.
+
+        Raises:
+            DeadlineExceededError: If the budget is already exhausted.
+        """
+        ...
+
+    def remaining(self) -> float:
+        """Return the seconds left, which is negative once the deadline has passed."""
+        ...
+
+    def expired(self) -> bool:
+        """Return whether the budget is exhausted."""
+        ...
+
+
+# The budget of the request being served, or None when nobody installed one. Read on every outgoing
+# call by `interceptors.deadline.AsyncDeadlineBudgetInterceptor`.
+_CURRENT_BUDGET: ContextVar[DeadlineBudgetProtocol | None] = ContextVar("grpc_client_kit_budget", default=None)
+
+
+def current_budget() -> DeadlineBudgetProtocol | None:
+    """Return the budget installed for the current task, or None if there is none.
+
+    Returns:
+        The budget `use_budget` last installed in this context, or None.
+    """
+    return _CURRENT_BUDGET.get()
+
+
+@contextmanager
+def use_budget(budget: DeadlineBudgetProtocol | None) -> Iterator[DeadlineBudgetProtocol | None]:
+    """Install `budget` as the current one for the duration of the block.
+
+    The previous value is restored on the way out, whether the block ends normally or by exception,
+    so nesting works and an inner budget cannot outlive its block. Passing None is the way to detach
+    an inherited budget — for background work that must not die with the request that spawned it.
+
+    Args:
+        budget: The budget to install, or None to run this block without one.
+
+    Yields:
+        The budget that was installed, for convenience at the call site.
+    """
+    token: Token[DeadlineBudgetProtocol | None] = _CURRENT_BUDGET.set(budget)
+    try:
+        yield budget
+    finally:
+        _CURRENT_BUDGET.reset(token)
+
+
+__all__ = [
+    "HAS_DEADLINE_BUDGET",
+    "DeadlineBudgetProtocol",
+    "DeadlineExceededError",
+    "current_budget",
+    "use_budget",
+]

grpc_client_kit/errors.py

@@ -0,0 +1,51 @@
+"""The common ancestor of every failure the kit raises on its own authority.
+
+A caller talking to a gRPC service sees two very different families of failure: the server said no
+(an ordinary `grpc.aio.AioRpcError` carrying the server's status), and the *kit* said no before or
+instead of the network — an open circuit breaker, an exhausted deadline budget, a balancer with no
+healthy target left, a health checker that was never started. Telling them apart matters: the
+first is an answer, the second is local state, and retrying or alerting on them differs.
+``except GrpcClientKitError`` is the one handler that catches exactly the second family.
+
+Kit failures that stand in for an RPC outcome — the breaker's rejection, the exhausted budget —
+additionally derive from `grpc.aio.AioRpcError`, so an existing ``except AioRpcError`` (and every
+logging, metrics and tracing layer) keeps seeing them as the call failures they are.
+"""
+
+from __future__ import annotations
+
+
+class GrpcClientKitError(Exception):
+    """Base class of every failure raised by the kit itself rather than by a server."""
+
+
+class HealthCheckerNotRunningError(GrpcClientKitError, RuntimeError):
+    """Raised when health state is requested but no check loop can ever produce it.
+
+    Lives here rather than in `health` so that catching it does not require the ``[health]``
+    extra: the caller of a balancer meets this error, and a balancer works on a bare install.
+    Also a `RuntimeError` — being asked before ``start()`` is a lifecycle mistake in the calling
+    code, and existing ``except RuntimeError`` handlers keep working.
+
+    Attributes:
+        target: The target whose health was requested.
+    """
+
+    def __init__(self, target: str) -> None:
+        """Initialize the error.
+
+        Args:
+            target: The target whose health was requested.
+        """
+        self.target = target
+        super().__init__(
+            f"HealthChecker is not running, so the health of '{target}' is unknown. "
+            "Call start() before routing traffic (a factory that owns the checker must be "
+            "entered with 'async with')."
+        )
+
+
+__all__ = [
+    "GrpcClientKitError",
+    "HealthCheckerNotRunningError",
+]