grpc, balancer, rls: implement gRFC A110 child channel options (Go)

Introduces the mechanism from gRFC A110 (Child Channel Options) for
propagating user-provided DialOptions to internal child channels
created by an LB policy (RLS's control channel is the motivating
example). Prior to this change, stats handlers or interceptors
configured on the parent ClientConn had no way to reach the RLS
control channel, so per-attempt telemetry (e.g.
grpc.client.attempt.duration) did not cover the RouteLookup RPC.

New public API:

* grpc.WithChildChannelOptions(opts ...DialOption) DialOption — a
  parent-channel DialOption that lists DialOptions to be applied to
  any internal child channels the parent (or its resolvers/LB
  policies) opens. Opaque to the parent per A110: the options are
  NOT applied to the parent itself.

* balancer.BuildOptions.ChildChannelOptions ([]any, holding
  grpc.DialOption) — how gRPC hands those options down to LB policies
  that open their own child channels. Typed as []any to avoid an
  import cycle with the grpc package; balancers cast each element.

RLS's control channel now:

* Applies balancer.BuildOptions.ChildChannelOptions as its baseline
  DialOptions (so user-provided stats handlers / interceptors take
  effect on RouteLookup RPCs), then layers RLS-mandatory options
  (authority, creds, service config) on top so they win on conflict.
* Adds grpc.WithChildChannelOptions(...) on top so any channels the
  control channel itself opens continue to inherit the same options.

Regression test: TestRLSControlChannelChildChannelOptions covers both
the positive case (WithChildChannelOptions -> RouteLookup RPCs appear
in grpc.client.attempt.duration) and the negative case (without it,
RouteLookup RPCs are NOT observed by the parent's stats handler,
enforcing A110's "opaque to P" contract).

Verified end-to-end against a real Bigtable DirectPath workload: 99
RouteLookup attempts to dns:///bigtablerls.googleapis.com show up in
grpc.client.attempt.duration with method, target, and status labels
populated correctly.

RELEASE NOTES:
* grpc: add WithChildChannelOptions DialOption per gRFC A110 to configure DialOptions that should be applied to internal child channels created by LB policies (e.g. the RLS control channel) or resolvers.
* balancer: add BuildOptions.ChildChannelOptions so LB policies that open their own child channels can plumb the parent's child-channel options through.
* rls: RouteLookup RPCs issued on the RLS control channel now honor DialOptions passed via grpc.WithChildChannelOptions, so per-attempt telemetry (e.g. grpc.client.attempt.duration) can cover them.

Author: sushanb

balancer/balancer.go

@@ -216,6 +216,17 @@ type BuildOptions struct {
 	// same resolver.Target as passed to the resolver. See the documentation for
 	// the resolver.Target type for details about what it contains.
 	Target resolver.Target
+	// ChildChannelOptions contains DialOptions to apply to any internal child
+	// channels (for example, an RLS balancer's control channel) created by
+	// this LB policy. Balancers that open their own child channels should
+	// pass these options to grpc.NewClient AND propagate them further via
+	// grpc.WithChildChannelOptions so any nested internal channels also
+	// inherit them. See gRFC A110: Child Channel Options.
+	//
+	// The element type is google.golang.org/grpc.DialOption, typed as any
+	// here to avoid an import cycle between the balancer and grpc packages.
+	// Balancers cast each element to grpc.DialOption when passing it on.
+	ChildChannelOptions []any
 }
 
 // Builder creates a balancer.

balancer/rls/control_channel.go

@@ -138,12 +138,21 @@ func (cc *controlChannel) OnMessage(msg any) {
 
 // dialOpts constructs the dial options for the control plane channel.
 func (cc *controlChannel) dialOpts(bOpts balancer.BuildOptions, serviceConfig string) ([]grpc.DialOption, error) {
+	// Per gRFC A110, user-provided child channel options are applied first as
+	// a baseline, then RLS's mandatory internal options (authority, creds,
+	// service config) are applied last so they win on conflict for
+	// single-value settings. Additive DialOptions (stats handlers,
+	// interceptors) accumulate from both. WithChildChannelOptions is also
+	// re-added so any channels this control channel opens itself inherit
+	// the same set recursively.
+	dopts := childDialOptionsFromBOpts(bOpts)
+
 	// The control plane channel will use the same authority as the parent
 	// channel for server authorization. This ensures that the identity of the
 	// RLS server and the identity of the backends is the same, so if the RLS
 	// config is injected by an attacker, it cannot cause leakage of private
 	// information contained in headers set by the application.
-	dopts := []grpc.DialOption{grpc.WithAuthority(bOpts.Authority)}
+	dopts = append(dopts, grpc.WithAuthority(bOpts.Authority))
 	if bOpts.Dialer != nil {
 		dopts = append(dopts, grpc.WithContextDialer(bOpts.Dialer))
 	}
@@ -180,6 +189,26 @@ func (cc *controlChannel) dialOpts(bOpts balancer.BuildOptions, serviceConfig st
 	return dopts, nil
 }
 
+// childDialOptionsFromBOpts returns the DialOptions to apply to the RLS
+// control channel that come from balancer.BuildOptions.ChildChannelOptions
+// (per gRFC A110), plus a WithChildChannelOptions wrapper so nested channels
+// keep inheriting them. Returns nil when no child options were provided.
+func childDialOptionsFromBOpts(bOpts balancer.BuildOptions) []grpc.DialOption {
+	if len(bOpts.ChildChannelOptions) == 0 {
+		return nil
+	}
+	child := make([]grpc.DialOption, 0, len(bOpts.ChildChannelOptions))
+	for _, o := range bOpts.ChildChannelOptions {
+		if do, ok := o.(grpc.DialOption); ok {
+			child = append(child, do)
+		}
+	}
+	// Include the options twice: once to apply on this channel, and once
+	// wrapped in WithChildChannelOptions so any channels opened by this
+	// control channel also inherit them.
+	return append(child, grpc.WithChildChannelOptions(child...))
+}
+
 func (cc *controlChannel) close() {
 	cc.dropConnStateSubscriber()
 	cc.cc.Close()

balancer/rls/metrics_test.go

@@ -373,3 +373,79 @@ func (s) TestRLSFailedRPCMetric(t *testing.T) {
 		}
 	}
 }
+
+// TestRLSControlChannelChildChannelOptions verifies the gRFC A110 plumbing:
+// when a user passes an OpenTelemetry stats handler DialOption via
+// grpc.WithChildChannelOptions on the parent channel, the RLS control channel
+// records grpc.client.attempt.duration data points for RouteLookup RPCs. The
+// negative case is also covered: without WithChildChannelOptions, no
+// RouteLookup metric data point should appear (the parent's own OTel handler
+// must not leak onto the child channel under A110's "opaque to P" rule).
+func (s) TestRLSControlChannelChildChannelOptions(t *testing.T) {
+	rlsServer, _ := rlstest.SetupFakeRLSServer(t, nil)
+	rlsConfig := buildBasicRLSConfigWithChildPolicy(t, t.Name(), rlsServer.Address)
+	backend := &stubserver.StubServer{
+		EmptyCallF: func(context.Context, *testpb.Empty) (*testpb.Empty, error) {
+			return &testpb.Empty{}, nil
+		},
+	}
+	if err := backend.StartServer(); err != nil {
+		t.Fatalf("Failed to start backend: %v", err)
+	}
+	defer backend.Stop()
+	rlsConfig.RouteLookupConfig.DefaultTarget = backend.Address
+
+	const rlsMethod = "grpc.lookup.v1.RouteLookupService/RouteLookup"
+	newClient := func(t *testing.T, useChildOpts bool) *metric.ManualReader {
+		r := startManualResolverWithConfig(t, rlsConfig)
+		reader := metric.NewManualReader()
+		provider := metric.NewMeterProvider(metric.WithReader(reader))
+		mo := opentelemetry.MetricsOptions{MeterProvider: provider}
+		otelDO := opentelemetry.DialOption(opentelemetry.Options{MetricsOptions: mo})
+		dialOpts := []grpc.DialOption{
+			grpc.WithResolvers(r),
+			grpc.WithTransportCredentials(insecure.NewCredentials()),
+			otelDO,
+		}
+		if useChildOpts {
+			dialOpts = append(dialOpts, grpc.WithChildChannelOptions(otelDO))
+		}
+		cc, err := grpc.NewClient(r.Scheme()+":///", dialOpts...)
+		if err != nil {
+			t.Fatalf("grpc.NewClient failed: %v", err)
+		}
+		t.Cleanup(func() { cc.Close() })
+
+		ctx, cancel := context.WithTimeout(context.Background(), defaultTestTimeout)
+		defer cancel()
+		if _, err := testgrpc.NewTestServiceClient(cc).EmptyCall(ctx, &testpb.Empty{}); err != nil {
+			t.Fatalf("client.EmptyCall failed: %v", err)
+		}
+		return reader
+	}
+	seesRouteLookup := func(reader *metric.ManualReader) bool {
+		ctx, cancel := context.WithTimeout(context.Background(), defaultTestTimeout)
+		defer cancel()
+		md, ok := metricsDataFromReader(ctx, reader)["grpc.client.attempt.duration"]
+		if !ok {
+			return false
+		}
+		hist, ok := md.Data.(metricdata.Histogram[float64])
+		if !ok {
+			return false
+		}
+		for _, dp := range hist.DataPoints {
+			if v, ok := dp.Attributes.Value("grpc.method"); ok && v.AsString() == rlsMethod {
+				return true
+			}
+		}
+		return false
+	}
+
+	if got := seesRouteLookup(newClient(t, true)); !got {
+		t.Fatalf("with WithChildChannelOptions: grpc.client.attempt.duration missing a data point for method %q", rlsMethod)
+	}
+	if got := seesRouteLookup(newClient(t, false)); got {
+		t.Fatalf("without WithChildChannelOptions: grpc.client.attempt.duration unexpectedly has a data point for method %q; A110 requires child options be opt-in", rlsMethod)
+	}
+}

balancer_wrapper.go

@@ -86,13 +86,14 @@ func newCCBalancerWrapper(cc *ClientConn) *ccBalancerWrapper {
 	ccb := &ccBalancerWrapper{
 		cc: cc,
 		opts: balancer.BuildOptions{
-			DialCreds:       cc.dopts.copts.TransportCredentials,
-			CredsBundle:     cc.dopts.copts.CredsBundle,
-			Dialer:          cc.dopts.copts.Dialer,
-			Authority:       cc.authority,
-			CustomUserAgent: cc.dopts.copts.UserAgent,
-			ChannelzParent:  cc.channelz,
-			Target:          cc.parsedTarget,
+			DialCreds:           cc.dopts.copts.TransportCredentials,
+			CredsBundle:         cc.dopts.copts.CredsBundle,
+			Dialer:              cc.dopts.copts.Dialer,
+			Authority:           cc.authority,
+			CustomUserAgent:     cc.dopts.copts.UserAgent,
+			ChannelzParent:      cc.channelz,
+			Target:              cc.parsedTarget,
+			ChildChannelOptions: childChannelOptionsForBalancer(cc.dopts.childChannelOptions),
 		},
 		serializer:       grpcsync.NewCallbackSerializer(ctx),
 		serializerCancel: cancel,
@@ -101,6 +102,21 @@ func newCCBalancerWrapper(cc *ClientConn) *ccBalancerWrapper {
 	return ccb
 }
 
+// childChannelOptionsForBalancer converts a []DialOption into the []any shape
+// exposed on balancer.BuildOptions.ChildChannelOptions. The typing indirection
+// avoids an import cycle between the balancer and grpc packages. Returns nil
+// when there are no options so balancers can nil-check cheaply.
+func childChannelOptionsForBalancer(opts []DialOption) []any {
+	if len(opts) == 0 {
+		return nil
+	}
+	out := make([]any, len(opts))
+	for i, o := range opts {
+		out[i] = o
+	}
+	return out
+}
+
 func (ccb *ccBalancerWrapper) MetricsRecorder() stats.MetricsRecorder {
 	return ccb.cc.metricsRecorderList
 }

dialoptions.go

@@ -96,6 +96,12 @@ type dialOptions struct {
 	maxCallAttempts             int
 	enableLocalDNSResolution    bool // Specifies if target hostnames should be resolved when proxying is enabled.
 	useProxy                    bool // Specifies if a server should be connected via proxy.
+
+	// childChannelOptions are DialOptions that the parent ClientConn does not
+	// apply to itself, but that must be plumbed onto any internal child
+	// channels the parent (or its LB policies/resolvers) creates. See gRFC
+	// A110: Child Channel Options.
+	childChannelOptions []DialOption
 }
 
 // DialOption configures how we set up the connection.
@@ -630,6 +636,28 @@ func WithChainStreamInterceptor(interceptors ...StreamClientInterceptor) DialOpt
 	})
 }
 
+// WithChildChannelOptions returns a DialOption that specifies DialOptions to
+// be applied to any internal child channels created by this ClientConn or by
+// its resolvers and LB policies (for example, the RLS balancer's control
+// channel or an xDS resolver's control-plane channel).
+//
+// The options are opaque to the parent ClientConn — they are not applied to
+// the parent channel itself. Child channels are also configured to propagate
+// these options to their own child channels, so a StatsHandler or
+// interceptor set here applies to any depth of nested internal channels.
+//
+// This implements the Go section of gRFC A110: Child Channel Options.
+//
+// # Experimental
+//
+// Notice: This API is EXPERIMENTAL and may be changed or removed in a later
+// release.
+func WithChildChannelOptions(opts ...DialOption) DialOption {
+	return newFuncDialOption(func(o *dialOptions) {
+		o.childChannelOptions = opts
+	})
+}
+
 // WithAuthority returns a DialOption that specifies the value to be used as the
 // :authority pseudo-header and as the server name in authentication handshake.
 // This overrides all other ways of setting authority on the channel, but can be