enable child channel plugins

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

@@ -0,0 +1,70 @@
+/*
+ * Copyright 2025 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;
+
+import java.util.function.Consumer;
+
+/**
+ * A configurer 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 configurer
+ * ChildChannelConfigurer configurer = builder -> {
+ *   builder.intercept(new MyAuthInterceptor());
+ *   builder.maxInboundMessageSize(4 * 1024 * 1024);
+ * };
+ *
+ * // 2. Apply to parent channel - automatically used for ALL child channels
+ * ManagedChannel channel = ManagedChannelBuilder
+ *     .forTarget("xds:///my-service")
+ *     .childChannelConfigurer(configurer)
+ *     .build();
+ * }</pre>
+ *
+ * <p>Implementations must be thread-safe as {@link #accept} may be invoked concurrently
+ * by multiple internal components.
+ *
+ * @since 1.79.0
+ */
+@ExperimentalApi("https://github.com/grpc/grpc-java/issues/12574")
+@FunctionalInterface
+public interface ChildChannelConfigurer extends Consumer<ManagedChannelBuilder<?>> {
+
+  /**
+   * 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>Note: The provided {@code builder} is generic (`?`). Implementations should use
+   * universal configuration methods (like {@code intercept()}, {@code userAgent()}) rather
+   * than casting to specific implementation types.
+   *
+   * @param builder the mutable channel builder for the new child channel
+   */
+  @Override
+  void accept(ManagedChannelBuilder<?> builder);
+}

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

@@ -0,0 +1,99 @@
+/*
+ * Copyright 2025 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;
+
+import static com.google.common.base.Preconditions.checkNotNull;
+
+import java.util.logging.Level;
+import java.util.logging.Logger;
+
+/**
+ * Utilities for working with {@link ChildChannelConfigurer}.
+ *
+ * @since 1.79.0
+ */
+@ExperimentalApi("https://github.com/grpc/grpc-java/issues/12574")
+public final class ChildChannelConfigurers {
+  private static final Logger logger = Logger.getLogger(ChildChannelConfigurers.class.getName());
+
+  // Singleton no-op instance to avoid object churn
+  private static final ChildChannelConfigurer NO_OP = builder -> {
+  };
+
+  private ChildChannelConfigurers() { // Prevent instantiation
+  }
+
+  /**
+   * Returns a configurer that does nothing.
+   * Useful as a default value to avoid null checks in internal code.
+   */
+  public static ChildChannelConfigurer noOp() {
+    return NO_OP;
+  }
+
+  /**
+   * Returns a configurer that applies all the given configurers in sequence.
+   *
+   * <p>If any configurer in the chain throws an exception, the remaining ones are skipped
+   * (unless wrapped in {@link #safe(ChildChannelConfigurer)}).
+   *
+   * @param configurers the configurers to apply in order. Null elements are ignored.
+   */
+  public static ChildChannelConfigurer compose(ChildChannelConfigurer... configurers) {
+    checkNotNull(configurers, "configurers");
+    return builder -> {
+      for (ChildChannelConfigurer configurer : configurers) {
+        if (configurer != null) {
+          configurer.accept(builder);
+        }
+      }
+    };
+  }
+
+  /**
+   * Returns a configurer that applies the delegate but catches and logs any exceptions.
+   *
+   * <p>This prevents a buggy configurer (e.g., one that fails metric setup) from crashing
+   * the critical path of channel creation.
+   *
+   * @param delegate the configurer to wrap.
+   */
+  public static ChildChannelConfigurer safe(ChildChannelConfigurer delegate) {
+    checkNotNull(delegate, "delegate");
+    return builder -> {
+      try {
+        delegate.accept(builder);
+      } catch (Exception e) {
+        logger.log(Level.WARNING, "Failed to apply child channel configuration", e);
+      }
+    };
+  }
+
+  /**
+   * Returns a configurer that applies the delegate only if the given condition is true.
+   *
+   * <p>Useful for applying interceptors only in specific environments (e.g., Debug/Test).
+   *
+   * @param condition true to apply the delegate, false to do nothing.
+   * @param delegate the configurer to apply if condition is true.
+   */
+  public static ChildChannelConfigurer conditional(boolean condition,
+                                                   ChildChannelConfigurer delegate) {
+    checkNotNull(delegate, "delegate");
+    return condition ? delegate : NO_OP;
+  }
+}

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

@@ -242,6 +242,24 @@ public T disableServiceConfigLookUp() {
     return thisT();
   }
 
+  @Override
+  public T configureChannel(ManagedChannel parentChannel) {
+    delegate().configureChannel(parentChannel);
+    return thisT();
+  }
+
+  @Override
+  public T configureChannel(Server parentServer) {
+    delegate().configureChannel(parentServer);
+    return thisT();
+  }
+
+  @Override
+  public T childChannelConfigurer(ChildChannelConfigurer childChannelConfigurer) {
+    delegate().childChannelConfigurer(childChannelConfigurer);
+    return thisT();
+  }
+
   /**
    * Returns the correctly typed version of the builder.
    */

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

@@ -95,7 +95,7 @@ public T intercept(ClientInterceptor... interceptors) {
   }
 
   @Override
-  protected T interceptWithTarget(InterceptorFactory factory) {
+  public T interceptWithTarget(InterceptorFactory factory) {
     delegate().interceptWithTarget(factory);
     return thisT();
   }
@@ -258,7 +258,7 @@ public T disableServiceConfigLookUp() {
   }
 
   @Override
-  protected T addMetricSink(MetricSink metricSink) {
+  public T addMetricSink(MetricSink metricSink) {
     delegate().addMetricSink(metricSink);
     return thisT();
   }
@@ -269,6 +269,24 @@ public <X> T setNameResolverArg(NameResolver.Args.Key<X> key, X value) {
     return thisT();
   }
 
+  @Override
+  public T configureChannel(ManagedChannel parentChannel) {
+    delegate().configureChannel(parentChannel);
+    return thisT();
+  }
+
+  @Override
+  public T configureChannel(Server parentServer) {
+    delegate().configureChannel(parentServer);
+    return thisT();
+  }
+
+  @Override
+  public T childChannelConfigurer(ChildChannelConfigurer childChannelConfigurer) {
+    delegate().childChannelConfigurer(childChannelConfigurer);
+    return thisT();
+  }
+
   /**
    * Returns the {@link ManagedChannel} built by the delegate by default. Overriding method can
    * return different value.

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

@@ -192,6 +192,18 @@ public T setBinaryLog(BinaryLog binaryLog) {
     return thisT();
   }
 
+  @Override
+  public T configureChannel(Server parentServer) {
+    delegate().configureChannel(parentServer);
+    return thisT();
+  }
+
+  @Override
+  public T childChannelConfigurer(ChildChannelConfigurer childChannelConfigurer) {
+    delegate().childChannelConfigurer(childChannelConfigurer);
+    return thisT();
+  }
+
   /**
    * Returns the {@link Server} built by the delegate by default. Overriding method can return
    * different value.

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

@@ -85,6 +85,23 @@ public ConnectivityState getState(boolean requestConnection) {
     throw new UnsupportedOperationException("Not implemented");
   }
 
+  /**
+   * Returns the configurer for child channels.
+   *
+   * <p>This method is intended for use by the internal gRPC infrastructure (specifically
+   * load balancers and the channel builder) to propagate configuration to child channels.
+   * Application code should not call this method.
+   *
+   * @return the configurer, or {@code noOp()} if none is set.
+   * @since 1.79.0
+   */
+  @Internal
+  public ChildChannelConfigurer getChildChannelConfigurer() {
+    // Return noOP() by default so we don't break existing custom ManagedChannel implementations
+    // (like wrappers or mocks) that don't override this method.
+    return ChildChannelConfigurers.noOp();
+  }
+
   /**
    * Registers a one-off callback that will be run if the connectivity state of the channel diverges
    * from the given {@code source}, which is typically what has just been returned by {@link

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

@@ -160,17 +160,14 @@ public T offloadExecutor(Executor executor) {
   public abstract T intercept(ClientInterceptor... interceptors);
 
   /**
-   * Internal-only: Adds a factory that will construct an interceptor based on the channel's target.
+   * Adds a factory that will construct an interceptor based on the channel's target.
    * This can be used to work around nameResolverFactory() changing the target string.
    */
-  @Internal
-  protected T interceptWithTarget(InterceptorFactory factory) {
+  public T interceptWithTarget(InterceptorFactory factory) {
     throw new UnsupportedOperationException();
   }
 
-  /** Internal-only. */
-  @Internal
-  protected interface InterceptorFactory {
+  public interface InterceptorFactory {
     ClientInterceptor newInterceptor(String target);
   }
 
@@ -638,8 +635,7 @@ public T disableServiceConfigLookUp() {
    * @return this
    * @since 1.64.0
    */
-  @Internal
-  protected T addMetricSink(MetricSink metricSink) {
+  public T addMetricSink(MetricSink metricSink) {
     throw new UnsupportedOperationException();
   }
 
@@ -661,6 +657,53 @@ public <X> T setNameResolverArg(NameResolver.Args.Key<X> key, X value) {
     throw new UnsupportedOperationException();
   }
 
+  /**
+   * Configures this builder using settings derived from an existing parent channel.
+   *
+   * <p>This method is typically used by internal components (like LoadBalancers) when creating
+   * child channels to ensure they inherit relevant configuration (like the
+   * {@link ChildChannelConfigurer}) from the parent.
+   *
+   * @param parentChannel the channel to inherit configuration from
+   * @return this
+   * @since 1.79.0
+   */
+  @ExperimentalApi("https://github.com/grpc/grpc-java/issues/12574")
+  public T configureChannel(ManagedChannel parentChannel) {
+    throw new UnsupportedOperationException();
+  }
+
+  /**
+   * Configures this builder using settings derived from an existing parent server.
+   *
+   * <p>This method is typically used by internal components (like LoadBalancers) when creating
+   * child channels to ensure they inherit relevant configuration (like the
+   * {@link ChildChannelConfigurer}) from the parent.
+   *
+   * @param parentServer the server to inherit configuration from
+   * @return this
+   * @since 1.79.0
+   */
+  @ExperimentalApi("https://github.com/grpc/grpc-java/issues/12574")
+  public T configureChannel(Server parentServer) {
+    throw new UnsupportedOperationException();
+  }
+
+  /**
+   * Sets a configurer that will be applied to all internal child channels created by this channel.
+   *
+   * <p>This allows injecting configuration (like credentials, interceptors, or flow control)
+   * into auxiliary channels created by gRPC infrastructure, such as xDS control plane connections.
+   *
+   * @param childChannelConfigurer the configurer to apply.
+   * @return this
+   * @since 1.79.0
+   */
+  @ExperimentalApi("https://github.com/grpc/grpc-java/issues/12574")
+  public T childChannelConfigurer(ChildChannelConfigurer childChannelConfigurer) {
+    throw new UnsupportedOperationException("Not implemented");
+  }
+
   /**
    * Builds a channel using the given parameters.
    *