docs(gax-grpc): clarify runtime capping of maxResizeDelta and simplify static pool config

Author: lqiu96

sdk-platform-java/gax-java/gax-grpc/src/main/java/com/google/api/gax/grpc/ChannelPool.java

@@ -335,12 +335,22 @@ void resize() {
     int delta = tentativeTarget - currentSize;
     int dampenedTarget = tentativeTarget;
     // Dampen the rate of change if the desired delta exceeds the maximum allowed step size.
-    if (Math.abs(delta) > settings.getMaxResizeDelta()) {
-      // Limit the change to maxResizeDelta, maintaining the correct direction (positive or
+    // Ensure that the step size is capped by the max channel count to handle small pool
+    // configurations.
+    int effectiveMaxResizeDelta =
+        Math.min(settings.getMaxResizeDelta(), settings.getMaxChannelCount());
+    if (Math.abs(delta) > effectiveMaxResizeDelta) {
+      // Limit the change to effectiveMaxResizeDelta, maintaining the correct direction (positive or
       // negative).
-      dampenedTarget = currentSize + (int) Math.copySign(settings.getMaxResizeDelta(), delta);
+      dampenedTarget = currentSize + (int) Math.copySign(effectiveMaxResizeDelta, delta);
     }
 
+    // Ensure that the calculated dampedTarget value will never exceed the maxChannelCount or fall
+    // below minChannelCount
+    dampenedTarget =
+        Math.max(
+            settings.getMinChannelCount(), Math.min(settings.getMaxChannelCount(), dampenedTarget));
+
     // Only count as "resized" if the thresholds are crossed and Gax attempts to scale. Checking
     // that `dampenedTarget != currentSize` would cause false positives when the pool is within
     // bounds but not at the target (target aims for the middle of the bounds)

sdk-platform-java/gax-java/gax-grpc/src/main/java/com/google/api/gax/grpc/ChannelPoolSettings.java

@@ -139,9 +139,8 @@ public static ChannelPoolSettings staticallySized(int size) {
         .setMaxRpcsPerChannel(Integer.MAX_VALUE)
         .setMinChannelCount(size)
         .setMaxChannelCount(size)
-        // Static pools don't resize so this value doesn't affect operation. However,
-        // validation still checks that resize delta doesn't exceed channel pool size.
-        .setMaxResizeDelta(Math.min(DEFAULT_MAX_RESIZE_DELTA, size))
+        // Static pools don't resize so this value doesn't affect operation.
+        .setMaxResizeDelta(DEFAULT_MAX_RESIZE_DELTA)
         .build();
   }
 
@@ -207,7 +206,8 @@ public abstract static class Builder {
     /**
      * Sets the maximum number of channels that can be added or removed in a single resize cycle.
      * This acts as a rate limiter to prevent wild fluctuations. The pool resizes periodically
-     * according to {@link #RESIZE_INTERVAL} (default 1 minute).
+     * according to {@link #RESIZE_INTERVAL} (default 1 minute). During resizing, this value is
+     * effectively capped by the bound configured via {@link #setMaxChannelCount}.
      */
     public abstract Builder setMaxResizeDelta(int count);
 

sdk-platform-java/gax-java/gax-grpc/src/test/java/com/google/api/gax/grpc/ChannelPoolTest.java

@@ -892,6 +892,42 @@ void minChannelsClampedToMaxChannelCountUnderHighLoad() throws Exception {
     assertThat(pool.entries.get()).hasSize(5);
   }
 
+  @Test
+  void resizeDampenedByMaxResizeDelta() throws Exception {
+    ScheduledExecutorService executor = Mockito.mock(ScheduledExecutorService.class);
+    FixedExecutorProvider provider = FixedExecutorProvider.create(executor);
+
+    List<ManagedChannel> channels = new ArrayList<>();
+    ChannelFactory channelFactory = createMockChannelFactory(channels, null);
+
+    pool =
+        new ChannelPool(
+            ChannelPoolSettings.builder()
+                .setInitialChannelCount(1)
+                .setMinRpcsPerChannel(1)
+                .setMaxRpcsPerChannel(2)
+                .setMaxResizeDelta(2) // Limit growth to 2 channels per cycle
+                .setMinChannelCount(1)
+                .setMaxChannelCount(10)
+                .build(),
+            channelFactory,
+            provider);
+    assertThat(pool.entries.get()).hasSize(1);
+
+    // Add 20 RPCs, which would require 10 channels (20/2)
+    // Desired delta is +9 (10 - 1)
+    // maxResizeDelta is 2, so it should be dampened to 2
+    for (int i = 0; i < 20; i++) {
+      ClientCalls.futureUnaryCall(
+          pool.newCall(METHOD_RECOGNIZE, CallOptions.DEFAULT), Color.getDefaultInstance());
+    }
+
+    pool.resize();
+
+    // Should be dampened to 1 + 2 = 3 channels
+    assertThat(pool.entries.get()).hasSize(3);
+  }
+
   @Test
   void maxChannelsClampedToMinChannelCountUnderLowLoad() throws Exception {
     ScheduledExecutorService executor = Mockito.mock(ScheduledExecutorService.class);