enable child channel plugins (grpc#12578)

Implements grpc/proposal#529

Author: AgraVator

api/src/main/java/io/grpc/ChannelConfigurator.java

@@ -0,0 +1,71 @@
+/*
+ * Copyright 2026 The gRPC Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.grpc;
+
+
+
+/**
+ * A configurator for child channels created by gRPC's internal infrastructure.
+ *
+ * <p>This interface allows users to inject configuration (such as credentials, interceptors,
+ * or flow control settings) into channels created automatically by gRPC for control plane
+ * operations. Common use cases include:
+ * <ul>
+ * <li>xDS control plane connections</li>
+ * <li>Load Balancing helper channels (OOB channels)</li>
+ * </ul>
+ *
+ * <p><strong>Usage Example:</strong>
+ * <pre>{@code
+ * // 1. Define the configurator
+ * ChannelConfigurator configurator = builder -> {
+ *   builder.maxInboundMessageSize(4 * 1024 * 1024);
+ * };
+ *
+ * // 2. Apply to parent channel - automatically used for ALL child channels
+ * ManagedChannel channel = ManagedChannelBuilder
+ *     .forTarget("xds:///my-service")
+ *     .childChannelConfigurator(configurator)
+ *     .build();
+ * }</pre>
+ *
+ * <p>Implementations must be thread-safe as the configure methods may be invoked concurrently
+ * by multiple internal components.
+ *
+ * @since 1.83.0
+ */
+@ExperimentalApi("https://github.com/grpc/grpc-java/issues/12574")
+@FunctionalInterface
+public interface ChannelConfigurator {
+
+  /**
+   * Configures a builder for a new child channel.
+   *
+   * <p>This method is invoked synchronously during the creation of the child channel,
+   * before {@link ManagedChannelBuilder#build()} is called.
+   *
+   * <p><strong>Note:</strong> Implementations must only apply configurations to the
+   * provided builder and must NOT call {@code builder.build()} themselves.
+   *
+   * <p><strong>Note:</strong> The provided {@code builder} is generic ({@code ?}). Implementations
+   * should use universal configuration methods (like {@code intercept()}, {@code userAgent()})
+   * on the builder rather than casting it to specific implementation types.
+   *
+   * @param builder the mutable channel builder for the new child channel
+   */
+  void configureChannelBuilder(ManagedChannelBuilder<?> builder);
+}

api/src/main/java/io/grpc/ForwardingChannelBuilder.java

@@ -242,6 +242,13 @@ public T disableServiceConfigLookUp() {
     return thisT();
   }
 
+
+  @Override
+  public T childChannelConfigurator(ChannelConfigurator channelConfigurator) {
+    delegate().childChannelConfigurator(channelConfigurator);
+    return thisT();
+  }
+
   /**
    * Returns the correctly typed version of the builder.
    */

api/src/main/java/io/grpc/ForwardingChannelBuilder2.java

@@ -269,6 +269,13 @@ public <X> T setNameResolverArg(NameResolver.Args.Key<X> key, X value) {
     return thisT();
   }
 
+
+  @Override
+  public T childChannelConfigurator(ChannelConfigurator channelConfigurator) {
+    delegate().childChannelConfigurator(channelConfigurator);
+    return thisT();
+  }
+
   /**
    * Returns the {@link ManagedChannel} built by the delegate by default. Overriding method can
    * return different value.

api/src/main/java/io/grpc/ManagedChannelBuilder.java

@@ -666,6 +666,23 @@ public <X> T setNameResolverArg(NameResolver.Args.Key<X> key, X value) {
     throw new UnsupportedOperationException();
   }
 
+
+  /**
+   * Sets a configurator that will be applied to all internal child channels created by this
+   * channel.
+   *
+   * <p>This allows injecting universal configuration (like interceptors)
+   * into auxiliary channels created by gRPC infrastructure, such as xDS control plane connections.
+   *
+   * @param channelConfigurator the configurator to apply.
+   * @return this
+   * @since 1.83.0
+   */
+  @ExperimentalApi("https://github.com/grpc/grpc-java/issues/12574")
+  public T childChannelConfigurator(ChannelConfigurator channelConfigurator) {
+    throw new UnsupportedOperationException("Not implemented");
+  }
+
   /**
    * Builds a channel using the given parameters.
    *

api/src/main/java/io/grpc/NameResolver.java

@@ -358,6 +358,7 @@ public static final class Args {
     private final MetricRecorder metricRecorder;
     @Nullable private final NameResolverRegistry nameResolverRegistry;
     @Nullable private final IdentityHashMap<Key<?>, Object> customArgs;
+    private final ChannelConfigurator channelConfigurator;
 
     private Args(Builder builder) {
       this.defaultPort = checkNotNull(builder.defaultPort, "defaultPort not set");
@@ -373,6 +374,7 @@ private Args(Builder builder) {
           : new MetricRecorder() {};
       this.nameResolverRegistry = builder.nameResolverRegistry;
       this.customArgs = cloneCustomArgs(builder.customArgs);
+      this.channelConfigurator = builder.channelConfigurator;
     }
 
     /**
@@ -471,6 +473,16 @@ public ChannelLogger getChannelLogger() {
       return channelLogger;
     }
 
+    /**
+     * Returns the configurator for child channels.
+     *
+     * @since 1.83.0
+     */
+    @ExperimentalApi("https://github.com/grpc/grpc-java/issues/12574")
+    public ChannelConfigurator getChildChannelConfigurator() {
+      return channelConfigurator;
+    }
+
     /**
      * Returns the Executor on which this resolver should execute long-running or I/O bound work.
      * Null if no Executor was set.
@@ -549,6 +561,7 @@ public Builder toBuilder() {
       builder.setOverrideAuthority(overrideAuthority);
       builder.setMetricRecorder(metricRecorder);
       builder.setNameResolverRegistry(nameResolverRegistry);
+      builder.setChildChannelConfigurator(channelConfigurator);
       builder.customArgs = cloneCustomArgs(customArgs);
       return builder;
     }
@@ -579,6 +592,7 @@ public static final class Builder {
       private MetricRecorder metricRecorder;
       private NameResolverRegistry nameResolverRegistry;
       private IdentityHashMap<Key<?>, Object> customArgs;
+      private ChannelConfigurator channelConfigurator = builder -> { };
 
       Builder() {
       }
@@ -694,6 +708,17 @@ public Builder setNameResolverRegistry(NameResolverRegistry registry) {
         return this;
       }
 
+      /**
+       * See {@link Args#getChildChannelConfigurator()}. This is an optional field.
+       *
+       * @since 1.83.0
+       */
+      @ExperimentalApi("https://github.com/grpc/grpc-java/issues/12574")
+      public Builder setChildChannelConfigurator(ChannelConfigurator channelConfigurator) {
+        this.channelConfigurator = checkNotNull(channelConfigurator, "channelConfigurator");
+        return this;
+      }
+
       /**
        * Builds an {@link Args}.
        *

api/src/test/java/io/grpc/NameResolverTest.java

@@ -22,6 +22,7 @@
 import static org.mockito.Mockito.verify;
 
 import com.google.common.base.Objects;
+import io.grpc.ChannelConfigurator;
 import io.grpc.NameResolver.ConfigOrError;
 import io.grpc.NameResolver.Listener2;
 import io.grpc.NameResolver.ResolutionResult;
@@ -72,6 +73,8 @@ public class NameResolverTest {
   private final int customArgValue = 42;
   @Mock NameResolver.Listener mockListener;
 
+  private final ChannelConfigurator channelConfigurator = builder -> { };
+
   @Test
   public void args() {
     NameResolver.Args args = createArgs();
@@ -84,6 +87,7 @@ public void args() {
     assertThat(args.getOffloadExecutor()).isSameInstanceAs(executor);
     assertThat(args.getOverrideAuthority()).isSameInstanceAs(overrideAuthority);
     assertThat(args.getMetricRecorder()).isSameInstanceAs(metricRecorder);
+    assertThat(args.getChildChannelConfigurator()).isSameInstanceAs(channelConfigurator);
     assertThat(args.getArg(FOO_ARG_KEY)).isEqualTo(customArgValue);
     assertThat(args.getArg(BAR_ARG_KEY)).isNull();
 
@@ -97,6 +101,7 @@ public void args() {
     assertThat(args2.getOffloadExecutor()).isSameInstanceAs(executor);
     assertThat(args2.getOverrideAuthority()).isSameInstanceAs(overrideAuthority);
     assertThat(args.getMetricRecorder()).isSameInstanceAs(metricRecorder);
+    assertThat(args2.getChildChannelConfigurator()).isSameInstanceAs(channelConfigurator);
     assertThat(args.getArg(FOO_ARG_KEY)).isEqualTo(customArgValue);
     assertThat(args.getArg(BAR_ARG_KEY)).isNull();
 
@@ -115,10 +120,47 @@ private NameResolver.Args createArgs() {
         .setOffloadExecutor(executor)
         .setOverrideAuthority(overrideAuthority)
         .setMetricRecorder(metricRecorder)
+        .setChildChannelConfigurator(channelConfigurator)
         .setArg(FOO_ARG_KEY, customArgValue)
         .build();
   }
 
+  @Test
+  public void args_childChannelConfigurator() {
+    final ManagedChannelBuilder<?>[] capturedBuilder = new ManagedChannelBuilder<?>[1];
+    ChannelConfigurator channelConfigurator = new ChannelConfigurator() {
+      @Override
+      public void configureChannelBuilder(ManagedChannelBuilder<?> builder) {
+        capturedBuilder[0] = builder;
+      }
+    };
+
+    SynchronizationContext realSyncContext = new SynchronizationContext(
+        new Thread.UncaughtExceptionHandler() {
+          @Override
+          public void uncaughtException(Thread t, Throwable e) {
+            throw new AssertionError(e);
+          }
+        });
+
+    NameResolver.Args args = NameResolver.Args.newBuilder()
+        .setDefaultPort(8080)
+        .setProxyDetector(mock(ProxyDetector.class))
+        .setSynchronizationContext(realSyncContext)
+        .setServiceConfigParser(mock(NameResolver.ServiceConfigParser.class))
+        .setChannelLogger(mock(ChannelLogger.class))
+        .setChildChannelConfigurator(channelConfigurator)
+        .build();
+
+    ChannelConfigurator configurator = args.getChildChannelConfigurator();
+    assertThat(configurator).isSameInstanceAs(channelConfigurator);
+    
+    // Validate configurator accepts builders
+    ManagedChannelBuilder<?> mockBuilder = mock(ManagedChannelBuilder.class);
+    configurator.configureChannelBuilder(mockBuilder);
+    assertThat(capturedBuilder[0]).isSameInstanceAs(mockBuilder);
+  }
+
   @Test
   @SuppressWarnings("deprecation")
   public void startOnOldListener_wrapperListener2UsedToStart() {

core/src/main/java/io/grpc/internal/ManagedChannelImpl.java

@@ -37,6 +37,7 @@
 import io.grpc.CallCredentials;
 import io.grpc.CallOptions;
 import io.grpc.Channel;
+import io.grpc.ChannelConfigurator;
 import io.grpc.ChannelCredentials;
 import io.grpc.ChannelLogger;
 import io.grpc.ChannelLogger.ChannelLogLevel;
@@ -155,6 +156,14 @@ public Result selectConfig(PickSubchannelArgs args) {
   private static final LoadBalancer.PickDetailsConsumer NOOP_PICK_DETAILS_CONSUMER =
       new LoadBalancer.PickDetailsConsumer() {};
 
+  /**
+   * Retrieves the user-provided configuration function for internal child channels.
+   *
+   * <p>This is intended for use by gRPC internal components
+   * that are responsible for creating auxiliary {@code ManagedChannel} instances.
+   */
+  private final ChannelConfigurator channelConfigurator;
+
   private final InternalLogId logId;
   private final String target;
   @Nullable
@@ -545,6 +554,8 @@ ClientStream newSubstream(
       Supplier<Stopwatch> stopwatchSupplier,
       List<ClientInterceptor> interceptors,
       final TimeProvider timeProvider) {
+    this.channelConfigurator = checkNotNull(builder.channelConfigurator,
+            "channelConfigurator");
     this.target = checkNotNull(builder.target, "target");
     this.logId = InternalLogId.allocate("Channel", target);
     this.timeProvider = checkNotNull(timeProvider, "timeProvider");
@@ -589,7 +600,8 @@ ClientStream newSubstream(
             .setOffloadExecutor(this.offloadExecutorHolder)
             .setOverrideAuthority(this.authorityOverride)
             .setMetricRecorder(this.metricRecorder)
-            .setNameResolverRegistry(builder.nameResolverRegistry);
+            .setNameResolverRegistry(builder.nameResolverRegistry)
+            .setChildChannelConfigurator(this.channelConfigurator);
     builder.copyAllNameResolverCustomArgsTo(nameResolverArgsBuilder);
     this.nameResolverArgs = nameResolverArgsBuilder.build();
     this.nameResolver = getNameResolver(
@@ -1489,6 +1501,11 @@ protected ManagedChannelBuilder<?> delegate() {
 
       ResolvingOobChannelBuilder builder = new ResolvingOobChannelBuilder();
 
+      // Note that we follow the global configurator pattern and try to fuse the configurations as
+      // soon as the builder gets created
+      channelConfigurator.configureChannelBuilder(builder);
+      builder.childChannelConfigurator(channelConfigurator);
+
       return builder
           // TODO(zdapeng): executors should not outlive the parent channel.
           .executor(executor)

core/src/main/java/io/grpc/internal/ManagedChannelImplBuilder.java

@@ -29,6 +29,7 @@
 import io.grpc.CallCredentials;
 import io.grpc.CallOptions;
 import io.grpc.Channel;
+import io.grpc.ChannelConfigurator;
 import io.grpc.ChannelCredentials;
 import io.grpc.ClientCall;
 import io.grpc.ClientInterceptor;
@@ -149,6 +150,8 @@ public static ManagedChannelBuilder<?> forTarget(String target) {
   }
 
 
+  ChannelConfigurator channelConfigurator = builder -> { };
+
   ObjectPool<? extends Executor> executorPool = DEFAULT_EXECUTOR_POOL;
 
   ObjectPool<? extends Executor> offloadExecutorPool = DEFAULT_EXECUTOR_POOL;
@@ -756,6 +759,14 @@ protected ManagedChannelImplBuilder addMetricSink(MetricSink metricSink) {
     return this;
   }
 
+  @Override
+  public ManagedChannelImplBuilder childChannelConfigurator(
+      ChannelConfigurator channelConfigurator) {
+    this.channelConfigurator = checkNotNull(channelConfigurator,
+        "childChannelConfigurator");
+    return this;
+  }
+
   @Override
   public ManagedChannel build() {
     ClientTransportFactory clientTransportFactory =