feat: a container-owned channel pool for the Dishka providers, shared by every upstream told to borrow it

Closes #31

Author: AlexeyShalaev

README.md

@@ -284,7 +284,7 @@ names the extra to install.
 | `interceptors.metrics` | Counters, latency histograms and an in-flight gauge | core¹ |
 | `metrics.GrpcClientMetrics` | The Prometheus collector for them, shaped to join `grpc-server-kit`'s series | `metrics` |
 | `health.HealthChecker` | Background `grpc.health.v1` probing with per-target backoff | `health` |
-| `dishka.*` | Dishka providers owning the factory's lifecycle, one component per upstream | `dishka` |
+| `dishka.*` | Dishka providers owning the factory's lifecycle, one component per upstream, one pool shared by several | `dishka` |
 | `protocols` / `validation` / `utils` | Settings seams, target validation, channel and metadata helpers | core |
 
 ¹ The metrics interceptor records through `GrpcClientMetricsProtocol` and works
@@ -299,7 +299,7 @@ with any backend you pass. The `[metrics]` extra only supplies the usual one.
 | `metrics` | `prometheus-client` | `GrpcClientMetrics`, the Prometheus collector; a custom registry needs no extra |
 | `deadline` | `deadline-budget` | `AsyncDeadlineBudgetInterceptor` (the layer is skipped without it) |
 | `settings` | `pydantic` | `BaseGrpcClientSettings` and the section models |
-| `dishka` | `dishka` | `grpc_client_providers` and the three providers behind it |
+| `dishka` | `dishka` | `grpc_client_providers`, the three providers behind it, and the pool provider several upstreams share |
 | `observability` | `metrics` + `tracing` | both of the above |
 | `all` | `deadline` + `dishka` + `health` + `metrics` + `settings` + `tracing` | everything |
 
@@ -335,7 +335,7 @@ Full documentation at [bedrock-python.github.io/grpc-client-kit](https://bedrock
 | [Load balancing](https://bedrock-python.github.io/grpc-client-kit/guide/load-balancing/) | round-robin, random and weighted selection with health filtering |
 | [Health](https://bedrock-python.github.io/grpc-client-kit/guide/health/) | `grpc.health.v1` probing, per-target backoff and cold starts |
 | [Observability](https://bedrock-python.github.io/grpc-client-kit/guide/observability/) | log records, CLIENT spans and the metrics an RPC emits |
-| [Dependency injection](https://bedrock-python.github.io/grpc-client-kit/guide/dependency-injection/) | the Dishka providers, what they own, and one component per upstream |
+| [Dependency injection](https://bedrock-python.github.io/grpc-client-kit/guide/dependency-injection/) | the Dishka providers, what they own, one component per upstream, one pool shared by several |
 | [Advanced](https://bedrock-python.github.io/grpc-client-kit/guide/advanced/) | interceptors that re-issue calls, target validation and ownership |
 | [API reference](https://bedrock-python.github.io/grpc-client-kit/reference/) | generated from the source |
 | [For AI agents](https://bedrock-python.github.io/grpc-client-kit/agents/) | the whole API surface, the rules that break code when broken and a map of the rest, on one page to hand to a coding assistant |

docs/agents.md

@@ -325,15 +325,22 @@ The label names, their order and the buckets are grpc-server-kit's `GrpcServerMe
 |---|---|---|
 | `GrpcClientSettingsProvider(settings, *, component=None)` | `GrpcClientSettingsProtocol` | holds the settings object; `BaseGrpcClientSettings` or anything structural |
 | `PrometheusGrpcClientMetricsProvider(*, prefix=None, component=None)` | `GrpcClientMetricsProtocol \| None` | `get_grpc_client_metrics(prefix)` when `settings.metrics_enabled`, else `None`; `None` with a warning without `[metrics]` |
-| `AsyncGrpcClientProvider(*, shutdown_grace=5.0, ready_timeout=10.0, component=None)` | `GrpcClientFactory` | APP scope, async generator: `async with GrpcClientFactory(settings, metrics=...)` entered on first resolution, left on `container.close()` |
-| `grpc_client_providers(settings, *, component=None, metrics_prefix=None, shutdown_grace=5.0, ready_timeout=10.0)` | `tuple[Provider, ...]` | the three above, for `make_async_container(*grpc_client_providers(settings))` |
+| `AsyncGrpcClientProvider(*, shutdown_grace=5.0, ready_timeout=10.0, shared_pool=False, component=None)` | `GrpcClientFactory` | APP scope, async generator: `async with GrpcClientFactory(settings, metrics=...)` entered on first resolution, left on `container.close()`; `shared_pool=True` borrows the default component's `ChannelPool` (`FromComponent("")`) instead of building one |
+| `AsyncChannelPoolProvider(settings=None, *, metrics=None, shutdown_grace=5.0, component=None)` | `ChannelPool` | APP scope, async generator: the pool shared upstreams borrow, sized by a `ChannelPoolSettingsProtocol`, `close_all(grace=shutdown_grace)` on `container.close()`; `metrics` is handed in, not requested |
+| `grpc_client_providers(settings, *, component=None, metrics_prefix=None, shutdown_grace=5.0, ready_timeout=10.0, shared_pool=False)` | `tuple[Provider, ...]` | the first three above, for `make_async_container(*grpc_client_providers(settings))` |
 
 The factory provider requests the settings and the registry through their protocols, so a
 container with `AsyncGrpcClientProvider` and no provider of `GrpcClientMetricsProtocol | None`
 is refused when it is built. Several upstreams are several Dishka components: one bundle per
 upstream with `component="users"`, resolved with `container.get(GrpcClientFactory,
 component="users")` or `Annotated[GrpcClientFactory, FromComponent("users")]`; each component
-resolves its own settings, and all of them hand out the one cached collector.
+resolves its own settings, and all of them hand out the one cached collector. One pool for all
+of them is `AsyncChannelPoolProvider(settings.grpc_pool, metrics=get_grpc_client_metrics())` in
+the default component and `shared_pool=True` on every bundle: the factories borrow it, the
+container drains it once, after them, with the pool provider's grace (the bundle's
+`shutdown_grace` then applies to nothing), and each upstream keeps its own settings and its own
+health checker. A `shared_pool=True` bundle with no `ChannelPool` in the default component is
+refused at build.
 
 ### Protocols and helpers
 
@@ -360,7 +367,7 @@ named beside them:
 | `create_aio_channel` | `grpc_client_kit.utils` |
 | `BaseGrpcClientSettings`, `BaseConnectivitySettings`, `BaseChannelPoolSettings`, `BaseTimeoutSettings`, `BaseRetrySettings`, `BaseCircuitBreakerSettings`, `BaseWaitForReadySettings`, `BaseDeadlineBudgetSettings`, `BaseLoadBalancerSettings`, `BaseHealthCheckerSettings` | `grpc_client_kit.settings` (needs `[settings]`) |
 | `GrpcClientMetrics`, `get_grpc_client_metrics`, `DEFAULT_GRPC_BUCKETS` | `grpc_client_kit.metrics` (needs `[metrics]`) |
-| `AsyncGrpcClientProvider`, `GrpcClientSettingsProvider`, `PrometheusGrpcClientMetricsProvider`, `grpc_client_providers` | `grpc_client_kit.dishka` (needs `[dishka]`) |
+| `AsyncChannelPoolProvider`, `AsyncGrpcClientProvider`, `GrpcClientSettingsProvider`, `PrometheusGrpcClientMetricsProvider`, `grpc_client_providers` | `grpc_client_kit.dishka` (needs `[dishka]`) |
 
 `ChannelWrapper` and `chain_token` in `grpc_client_kit.channel`, and `MethodCircuitState` in
 `grpc_client_kit.interceptors.circuit_breaker`, are internals left out of the public surface on
@@ -633,7 +640,7 @@ Fetch a page when the task is the one named beside it.
 | [Native gRPC or the kit?](guide/native-vs-kit.md) | deciding which layer owns LB, retries, idling and health |
 | [Health checking](guide/health.md) | the probe loop, cold starts, backoff, status callbacks |
 | [Observability](guide/observability.md) | what a log record, a metric sample and a span actually contain, and the shipped Prometheus collector |
-| [Dependency injection](guide/dependency-injection.md) | the Dishka providers, what resolving and closing does, one component per upstream |
+| [Dependency injection](guide/dependency-injection.md) | the Dishka providers, what resolving and closing does, one component per upstream, one pool shared by several |
 | [Advanced](guide/advanced.md) | target validation, plain `grpc.aio` interceptors |
 | [API reference](reference/index.md) | an exact signature, field or docstring — HTML only, see above |
 | [Changelog](changelog.md) | what changed between versions |

docs/guide/advanced.md

@@ -56,5 +56,6 @@ The pool is application-scoped, the factory too, and clients are cheap enough
 to be request-scoped. `grpc_client_kit.dishka` (the `dishka` extra) ships the
 providers that own that lifecycle — resolve `GrpcClientFactory`, and closing
 the container closes the pool — with one Dishka component per upstream when a
-service has several. See [Dependency injection](dependency-injection.md),
-which also spells the two `async with` blocks out for any other container.
+service has several, and one pool for all of them when they should share it.
+See [Dependency injection](dependency-injection.md), which also spells the
+two `async with` blocks out for any other container.

docs/guide/channels.md

@@ -227,7 +227,9 @@ rather than handed out — a channel the pool no longer tracks would leak past
 shutdown.
 
 A factory handed an existing pool (`GrpcClientFactory(pool=pool)`) borrows it
-and never closes it: whoever created the pool closes it. And a factory used
+and never closes it: whoever created the pool closes it — in a Dishka
+container, [the pool provider](dependency-injection.md#one-pool-for-several-upstreams),
+once, after the factories that borrowed it. And a factory used
 without `async with` never starts its health checker — `create_client` warns
 about exactly that, because the resulting client would route traffic by
 unverified health data.

docs/guide/configuration.md

@@ -214,7 +214,10 @@ USERS_GRPC__SUCCESS_LOG_LEVEL=DEBUG
 
 A variable reaches exactly one section, through its prefix; a bare `TARGET`
 or `MAX_ATTEMPTS` in the pod reaches nothing, because no section scrapes the
-environment by itself. A block that defaults to `None` — `retry`,
+environment by itself. A pool several upstreams share is a section of its
+own — `grpc_pool: BaseChannelPoolSettings` next to them, `GRPC_POOL__*` —
+handed to [the pool provider](dependency-injection.md#one-pool-for-several-upstreams)
+rather than read from any one upstream. A block that defaults to `None` — `retry`,
 `circuit_breaker`, `wait_for_ready`, `deadline_budget`, `balancer`,
 `health_checker`, `connectivity` — comes into being the moment one of its
 variables is set; `pool` and `timeout` are present by default, and

docs/guide/dependency-injection.md

@@ -27,14 +27,17 @@ await container.close()  # leaves it: stops the checker, closes the pool
 ```
 
 `grpc_client_providers(settings, *, component=None, metrics_prefix=None,
-shutdown_grace=5.0, ready_timeout=10.0)` returns the three providers below,
-which can also be registered one by one:
+shutdown_grace=5.0, ready_timeout=10.0, shared_pool=False)` returns the first
+three providers below, which can also be registered one by one; the fourth is
+registered on its own, by the containers whose upstreams
+[share one pool](#one-pool-for-several-upstreams):
 
 | Provider | Provides | Notes |
 | :--- | :--- | :--- |
 | `GrpcClientSettingsProvider(settings)` | `GrpcClientSettingsProtocol` | Holds the settings object: [`BaseGrpcClientSettings`](configuration.md#from-the-environment) or anything structural |
 | `PrometheusGrpcClientMetricsProvider(prefix=None)` | `GrpcClientMetricsProtocol \| None` | The [shipped collector](observability.md#the-shipped-collector) when `settings.metrics_enabled`, `None` otherwise |
-| `AsyncGrpcClientProvider(shutdown_grace=5.0, ready_timeout=10.0)` | `GrpcClientFactory` | APP scope, from an async generator: entered on first resolution, left when the container closes |
+| `AsyncGrpcClientProvider(shutdown_grace=5.0, ready_timeout=10.0, shared_pool=False)` | `GrpcClientFactory` | APP scope, from an async generator: entered on first resolution, left when the container closes; `shared_pool=True` borrows the default component's `ChannelPool` instead of building one |
+| `AsyncChannelPoolProvider(settings=None, metrics=None, shutdown_grace=5.0)` | `ChannelPool` | APP scope, from an async generator: the pool several upstreams share, sized by a `ChannelPoolSettingsProtocol`, drained with `shutdown_grace` when the container closes |
 
 The factory provider *requests* the settings and the registry through their
 protocols rather than taking them in its constructor, so a settings object
@@ -101,6 +104,62 @@ collector is the exception by design — it is cached per prefix, so both
 components hand out the same instance, and the two upstreams' series are told
 apart by the `service` label rather than by separate metrics.
 
+### One pool for several upstreams
+
+Registered that way, each component's factory builds a pool of its own, as it
+does outside a container. Upstreams whose retry and timeout policy differ but
+whose channels should sit in one pool — one set of
+[pool statistics](observability.md#pool-statistics), one section configuring
+it — register the pool once, in the default component, and tell each bundle to
+borrow it:
+
+```python
+from grpc_client_kit.dishka import AsyncChannelPoolProvider, grpc_client_providers
+from grpc_client_kit.metrics import get_grpc_client_metrics
+
+container = make_async_container(
+    AsyncChannelPoolProvider(settings.grpc_pool, metrics=get_grpc_client_metrics()),
+    *grpc_client_providers(settings.users_grpc, component="users", shared_pool=True),
+    *grpc_client_providers(settings.orders_grpc, component="orders", shared_pool=True),
+)
+
+pool = await container.get(ChannelPool)  # the one both factories draw from
+```
+
+`AsyncChannelPoolProvider` provides `ChannelPool` in APP scope the way the
+factory provider provides the factory: built on first resolution, drained with
+`close_all(grace=shutdown_grace)` when the container closes. It is sized by a
+`ChannelPoolSettingsProtocol` — a
+[`BaseChannelPoolSettings`](configuration.md#from-the-environment) nested at
+the top of the service's settings is one deployment-wide section,
+`GRPC_POOL__MAX_CHANNELS_PER_TARGET` and `GRPC_POOL__IDLE_TIMEOUT`, next to
+the per-upstream ones — and is at the pool's own defaults without one.
+`metrics=` is the registry its statistics
+are reported into, handed in rather than requested: a container with one
+component per upstream has a registry per component and none in the default
+one, so there is no single seam for the pool to ask; `get_grpc_client_metrics()`
+is the instance the bundles hand out.
+
+A factory with `shared_pool=True` resolves `ChannelPool` from the default
+component (`Annotated[ChannelPool, FromComponent("")]`, so anything providing
+`ChannelPool` there will do) and is `GrpcClientFactory(pool=...)`: it
+[borrows the pool and never closes it](channels.md#ownership-and-shutdown),
+and owns nothing but its health checker. The container closes generators in
+reverse order of entry, so every factory leaves — stopping its checker —
+before the pool is drained, and the pool is drained exactly once. The bundle's
+`shutdown_grace` then has nothing to apply to; the pool provider's is the one
+in-flight RPCs get. The upstream's own `pool` block is not read either: the
+pool was built before the factory asked.
+
+Three things stay per upstream. The settings and the policy they carry, which
+is the point. The health checker, because it probes that upstream's
+`targets`; two health-checked upstreams sharing a pool are two checkers, each
+[marking its own addresses](health.md) in the one pool. And the choice: a
+bundle registered without `shared_pool` next to shared ones builds and owns
+its own pool as before. A `shared_pool=True` bundle in a container with no
+`ChannelPool` in the default component is refused when the container is built,
+like a missing registry seam.
+
 ## By hand, or with another container
 
 Nothing here is Dishka-specific beyond the provider classes. Any container