feat: add support of dynamic channel pooling

[rahul2393]

Description

This PR adds support for Dynamic Channel Pooling (DCP), which enables automatic scaling of gRPC channels based on load.

Dynamic Channel Pool is disabled by default and must be explicitly enabled via enableDynamicChannelPool(). DCP will be enabled by default in a future release.

Basic Usage (with Spanner defaults)

SpannerOptions options = SpannerOptions.newBuilder()
    .setProjectId("my-project")
    .enableDynamicChannelPool()  // Required to enable DCP
    .build();

Custom Configuration

For custom configuration, use setGcpChannelPoolOptions(GcpChannelPoolOptions):

SpannerOptions options = SpannerOptions.newBuilder()
    .setProjectId("my-project")
    .enableDynamicChannelPool()
    .setGcpChannelPoolOptions(
        GcpChannelPoolOptions.newBuilder()
            .setMaxSize(15)
            .setMinSize(3)
            .setInitSize(5)
            .setDynamicScaling(10, 30, Duration.ofMinutes(5))
            .setAffinityKeyLifetime(Duration.ofMinutes(10))
            .setCleanupInterval(Duration.ofMinutes(1))
            .build())
    .build();

Spanner Default Configuration

When enableDynamicChannelPool() is called without custom GcpChannelPoolOptions, Spanner-specific defaults are applied via SpannerOptions.createDefaultDynamicChannelPoolOptions():

Option	Default	Description
Max Size	10	Maximum channels (won't scale above)
Min Size	2	Minimum channels (won't scale below)
Initial Size	4	Initial number of channels
Max RPC/Channel	25	RPCs/channel threshold to scale up
Min RPC/Channel	15	RPCs/channel threshold to scale down
Scale Down Interval	3 min	How often to check for scale down
Affinity Key Lifetime	10 min	TTL for affinity keys
Cleanup Interval	1 min	Cleanup frequency for stale keys

API Summary

Method	Description
enableDynamicChannelPool()	Enables dynamic channel pooling
disableDynamicChannelPool()	Disables dynamic channel pooling
isDynamicChannelPoolEnabled()	Returns whether DCP is enabled
setGcpChannelPoolOptions(GcpChannelPoolOptions)	Sets custom channel pool options
getGcpChannelPoolOptions()	Returns the channel pool options
SpannerOptions.createDefaultDynamicChannelPoolOptions()	Static factory for Spanner defaults

Behavior Notes

• DCP requires gRPC-GCP extension (enabled by default)
• Calling setNumChannels(int) disables DCP even if explicitly enabled
• Channel IDs in request headers (e.g., X-Goog-Spanner-Request-Id) now reflect the actual physical channel selected by grpc-gcp, rather than the logical channel hint computed by the client
• Validation of channel pool options (min/max channels, RPC thresholds, etc.) is delegated to grpc-gcp's GcpChannelPoolOptions.Builder

[gemini-code-assist]

Code Review

This pull request introduces support for dynamic channel pooling in the Spanner client, which is a significant enhancement. The changes are well-structured across configuration (SpannerOptions), RPC implementation (GapicSpannerRpc), and interceptors (RequestIdInterceptor). The feature is controlled by a comprehensive set of new options, with sensible defaults and validation. The inclusion of extensive unit tests for both the new options and the interceptor logic is commendable. My review includes a couple of suggestions to improve robustness and align the implementation with the documented behavior.

[olavloite]

Does this change the behavior for customers who are currently using grpc-gcp? (I would think not, considering that it seems like the channel pool size was set to options.getNumChannels() before this change as well)

[rahul2393]

No, because when poolSize = 0, grpc-gcp uses initSize from GcpChannelPoolOptions. Previously, numChannels was used as the pool size. The change is intentional to let DCP control initialization.