balancer: expose parent ClientConn via Unwrap() on all embedding wrappers

Several types in the balancer tree wrap a balancer.ClientConn by
anonymously embedding it. Add an Unwrap() balancer.ClientConn method to
each of them so that gRPC-internal callers can walk up the wrapping
chain to reach the underlying parent ClientConn. This is the
mirror-image contract of what errors.Unwrap provides for error trees.

The method is a one-liner returning the embedded field, and doesn't
change any existing behavior. It exists so a follow-up change can rely
on it to inherit parent-channel telemetry (stats handlers and
interceptors) onto balancer-owned control channels (e.g. the RLS
control channel) without resorting to reflection over private fields.

Wrappers touched:
  internal/balancer/gracefulswitch.balancerWrapper
  internal/balancergroup.subBalancerWrapper
  internal/xds/balancer/clusterimpl.clusterImplBalancer
  internal/xds/balancer/outlierdetection.outlierDetectionBalancer
  internal/xds/balancer/priority.ignoreResolveNowClientConn
  balancer/grpclb.lbCacheClientConn
  balancer/ringhash.ringhashBalancer

RELEASE NOTES: none

Author: sushanb

balancer/grpclb/grpclb_util.go

@@ -91,6 +91,13 @@ func (ccc *lbCacheClientConn) RemoveSubConn(sc balancer.SubConn) {
 	logger.Errorf("RemoveSubConn(%v) called unexpectedly", sc)
 }
 
+// Unwrap returns the ClientConn that this wrapper delegates to. It lets
+// gRPC-internal callers walk past the grpclb subconn-cache layer to reach the
+// underlying parent ClientConn.
+func (ccc *lbCacheClientConn) Unwrap() balancer.ClientConn {
+	return ccc.ClientConn
+}
+
 type lbCacheSubConn struct {
 	balancer.SubConn
 	ccc *lbCacheClientConn

balancer/ringhash/ringhash.go

@@ -178,6 +178,13 @@ func (b *ringhashBalancer) UpdateState(state balancer.State) {
 	b.updatePickerLocked()
 }
 
+// Unwrap returns the ClientConn that this wrapper delegates to. It lets
+// gRPC-internal callers walk past the ring-hash layer to reach the underlying
+// parent ClientConn.
+func (b *ringhashBalancer) Unwrap() balancer.ClientConn {
+	return b.ClientConn
+}
+
 func (b *ringhashBalancer) UpdateClientConnState(ccs balancer.ClientConnState) error {
 	if b.logger.V(2) {
 		b.logger.Infof("Received update from resolver, balancer config: %+v", pretty.ToJSON(ccs.BalancerConfig))

internal/balancer/gracefulswitch/gracefulswitch.go

@@ -302,6 +302,13 @@ type balancerWrapper struct {
 	subconns  map[balancer.SubConn]bool // subconns created by this balancer
 }
 
+// Unwrap returns the ClientConn that this wrapper delegates to. It lets
+// gRPC-internal callers walk past the graceful-switch layer to reach the
+// underlying parent ClientConn.
+func (bw *balancerWrapper) Unwrap() balancer.ClientConn {
+	return bw.ClientConn
+}
+
 // Close closes the underlying LB policy and shuts down the subconns it
 // created. bw must not be referenced via balancerCurrent or balancerPending in
 // gsb when called. gsb.mu must not be held.  Does not panic with a nil

internal/balancergroup/balancergroup.go

@@ -73,6 +73,13 @@ type subBalancerWrapper struct {
 	balancer *gracefulswitch.Balancer
 }
 
+// Unwrap returns the ClientConn that this wrapper delegates to. It lets
+// gRPC-internal callers walk past the balancer-group layer to reach the
+// underlying parent ClientConn.
+func (sbc *subBalancerWrapper) Unwrap() balancer.ClientConn {
+	return sbc.ClientConn
+}
+
 // UpdateState overrides balancer.ClientConn, to keep state and picker.
 func (sbc *subBalancerWrapper) UpdateState(state balancer.State) {
 	sbc.mu.Lock()

internal/xds/balancer/clusterimpl/clusterimpl.go

@@ -390,6 +390,13 @@ func (b *clusterImplBalancer) handleSecurityConfig(config *xdsresource.SecurityC
 	return nil
 }
 
+// Unwrap returns the ClientConn that this wrapper delegates to. It lets
+// gRPC-internal callers walk past the cluster_impl layer to reach the
+// underlying parent ClientConn.
+func (b *clusterImplBalancer) Unwrap() balancer.ClientConn {
+	return b.ClientConn
+}
+
 func (b *clusterImplBalancer) UpdateClientConnState(s balancer.ClientConnState) error {
 	defer clientConnUpdateHook()
 

internal/xds/balancer/outlierdetection/balancer.go

@@ -233,6 +233,13 @@ type outlierDetectionBalancer struct {
 	pickerUpdateCh *buffer.Unbounded[any]
 }
 
+// Unwrap returns the ClientConn that this wrapper delegates to. It lets
+// gRPC-internal callers walk past the outlier-detection layer to reach the
+// underlying parent ClientConn.
+func (b *outlierDetectionBalancer) Unwrap() balancer.ClientConn {
+	return b.ClientConn
+}
+
 // noopConfig returns whether this balancer is configured with a logical no-op
 // configuration or not.
 //

internal/xds/balancer/priority/ignore_resolve_now.go

@@ -48,3 +48,10 @@ func (i *ignoreResolveNowClientConn) ResolveNow(o resolver.ResolveNowOptions) {
 	}
 	i.ClientConn.ResolveNow(o)
 }
+
+// Unwrap returns the ClientConn that this wrapper delegates to. It lets
+// gRPC-internal callers walk past the priority layer to reach the underlying
+// parent ClientConn.
+func (i *ignoreResolveNowClientConn) Unwrap() balancer.ClientConn {
+	return i.ClientConn
+}