vendor/google.golang.org/grpc/balancer/balancer.go - device-management - Gitiles

 /*
  *
  * Copyright 2017 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 balancer defines APIs for load balancing in gRPC.
 // All APIs in this package are experimental.
 package balancer

 import (
 	"context"
 	"encoding/json"
 	"errors"
 	"net"
 	"strings"

 	"google.golang.org/grpc/connectivity"
 	"google.golang.org/grpc/credentials"
 	"google.golang.org/grpc/internal"
 	"google.golang.org/grpc/metadata"
 	"google.golang.org/grpc/resolver"
 	"google.golang.org/grpc/serviceconfig"
 )

 var (
 	// m is a map from name to balancer builder.
 	m = make(map[string]Builder)
 )

 // Register registers the balancer builder to the balancer map. b.Name
 // (lowercased) will be used as the name registered with this builder.  If the
 // Builder implements ConfigParser, ParseConfig will be called when new service
 // configs are received by the resolver, and the result will be provided to the
 // Balancer in UpdateClientConnState.
 //
 // NOTE: this function must only be called during initialization time (i.e. in
 // an init() function), and is not thread-safe. If multiple Balancers are
 // registered with the same name, the one registered last will take effect.
 func Register(b Builder) {
 	m[strings.ToLower(b.Name())] = b
 }

 // unregisterForTesting deletes the balancer with the given name from the
 // balancer map.
 //
 // This function is not thread-safe.
 func unregisterForTesting(name string) {
 	delete(m, name)
 }

 func init() {
 	internal.BalancerUnregister = unregisterForTesting
 }

 // Get returns the resolver builder registered with the given name.
 // Note that the compare is done in a case-insensitive fashion.
 // If no builder is register with the name, nil will be returned.
 func Get(name string) Builder {
 	if b, ok := m[strings.ToLower(name)]; ok {
 		return b
 	}
 	return nil
 }

 // SubConn represents a gRPC sub connection.
 // Each sub connection contains a list of addresses. gRPC will
 // try to connect to them (in sequence), and stop trying the
 // remainder once one connection is successful.
 //
 // The reconnect backoff will be applied on the list, not a single address.
 // For example, try_on_all_addresses -> backoff -> try_on_all_addresses.
 //
 // All SubConns start in IDLE, and will not try to connect. To trigger
 // the connecting, Balancers must call Connect.
 // When the connection encounters an error, it will reconnect immediately.
 // When the connection becomes IDLE, it will not reconnect unless Connect is
 // called.
 //
 // This interface is to be implemented by gRPC. Users should not need a
 // brand new implementation of this interface. For the situations like
 // testing, the new implementation should embed this interface. This allows
 // gRPC to add new methods to this interface.
 type SubConn interface {
 	// UpdateAddresses updates the addresses used in this SubConn.
 	// gRPC checks if currently-connected address is still in the new list.
 	// If it's in the list, the connection will be kept.
 	// If it's not in the list, the connection will gracefully closed, and
 	// a new connection will be created.
 	//
 	// This will trigger a state transition for the SubConn.
 	UpdateAddresses([]resolver.Address)
 	// Connect starts the connecting for this SubConn.
 	Connect()
 }

 // NewSubConnOptions contains options to create new SubConn.
 type NewSubConnOptions struct {
 	// CredsBundle is the credentials bundle that will be used in the created
 	// SubConn. If it's nil, the original creds from grpc DialOptions will be
 	// used.
 	CredsBundle credentials.Bundle
 	// HealthCheckEnabled indicates whether health check service should be
 	// enabled on this SubConn
 	HealthCheckEnabled bool
 }

 // State contains the balancer's state relevant to the gRPC ClientConn.
 type State struct {
 	// State contains the connectivity state of the balancer, which is used to
 	// determine the state of the ClientConn.
 	ConnectivityState connectivity.State
 	// Picker is used to choose connections (SubConns) for RPCs.
 	Picker V2Picker
 }

 // ClientConn represents a gRPC ClientConn.
 //
 // This interface is to be implemented by gRPC. Users should not need a
 // brand new implementation of this interface. For the situations like
 // testing, the new implementation should embed this interface. This allows
 // gRPC to add new methods to this interface.
 type ClientConn interface {
 	// NewSubConn is called by balancer to create a new SubConn.
 	// It doesn't block and wait for the connections to be established.
 	// Behaviors of the SubConn can be controlled by options.
 	NewSubConn([]resolver.Address, NewSubConnOptions) (SubConn, error)
 	// RemoveSubConn removes the SubConn from ClientConn.
 	// The SubConn will be shutdown.
 	RemoveSubConn(SubConn)

 	// UpdateBalancerState is called by balancer to notify gRPC that some internal
 	// state in balancer has changed.
 	//
 	// gRPC will update the connectivity state of the ClientConn, and will call pick
 	// on the new picker to pick new SubConn.
 	//
 	// Deprecated: use UpdateState instead
 	UpdateBalancerState(s connectivity.State, p Picker)

 	// UpdateState notifies gRPC that the balancer's internal state has
 	// changed.
 	//
 	// gRPC will update the connectivity state of the ClientConn, and will call pick
 	// on the new picker to pick new SubConns.
 	UpdateState(State)

 	// ResolveNow is called by balancer to notify gRPC to do a name resolving.
 	ResolveNow(resolver.ResolveNowOptions)

 	// Target returns the dial target for this ClientConn.
 	//
 	// Deprecated: Use the Target field in the BuildOptions instead.
 	Target() string
 }

 // BuildOptions contains additional information for Build.
 type BuildOptions struct {
 	// DialCreds is the transport credential the Balancer implementation can
 	// use to dial to a remote load balancer server. The Balancer implementations
 	// can ignore this if it does not need to talk to another party securely.
 	DialCreds credentials.TransportCredentials
 	// CredsBundle is the credentials bundle that the Balancer can use.
 	CredsBundle credentials.Bundle
 	// Dialer is the custom dialer the Balancer implementation can use to dial
 	// to a remote load balancer server. The Balancer implementations
 	// can ignore this if it doesn't need to talk to remote balancer.
 	Dialer func(context.Context, string) (net.Conn, error)
 	// ChannelzParentID is the entity parent's channelz unique identification number.
 	ChannelzParentID int64
 	// Target contains the parsed address info of the dial target. It is the 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
 }

 // Builder creates a balancer.
 type Builder interface {
 	// Build creates a new balancer with the ClientConn.
 	Build(cc ClientConn, opts BuildOptions) Balancer
 	// Name returns the name of balancers built by this builder.
 	// It will be used to pick balancers (for example in service config).
 	Name() string
 }

 // ConfigParser parses load balancer configs.
 type ConfigParser interface {
 	// ParseConfig parses the JSON load balancer config provided into an
 	// internal form or returns an error if the config is invalid.  For future
 	// compatibility reasons, unknown fields in the config should be ignored.
 	ParseConfig(LoadBalancingConfigJSON json.RawMessage) (serviceconfig.LoadBalancingConfig, error)
 }

 // PickInfo contains additional information for the Pick operation.
 type PickInfo struct {
 	// FullMethodName is the method name that NewClientStream() is called
 	// with. The canonical format is /service/Method.
 	FullMethodName string
 	// Ctx is the RPC's context, and may contain relevant RPC-level information
 	// like the outgoing header metadata.
 	Ctx context.Context
 }

 // DoneInfo contains additional information for done.
 type DoneInfo struct {
 	// Err is the rpc error the RPC finished with. It could be nil.
 	Err error
 	// Trailer contains the metadata from the RPC's trailer, if present.
 	Trailer metadata.MD
 	// BytesSent indicates if any bytes have been sent to the server.
 	BytesSent bool
 	// BytesReceived indicates if any byte has been received from the server.
 	BytesReceived bool
 	// ServerLoad is the load received from server. It's usually sent as part of
 	// trailing metadata.
 	//
 	// The only supported type now is *orca_v1.LoadReport.
 	ServerLoad interface{}
 }

 var (
 	// ErrNoSubConnAvailable indicates no SubConn is available for pick().
 	// gRPC will block the RPC until a new picker is available via UpdateBalancerState().
 	ErrNoSubConnAvailable = errors.New("no SubConn is available")
 	// ErrTransientFailure indicates all SubConns are in TransientFailure.
 	// WaitForReady RPCs will block, non-WaitForReady RPCs will fail.
 	ErrTransientFailure = TransientFailureError(errors.New("all SubConns are in TransientFailure"))
 )

 // Picker is used by gRPC to pick a SubConn to send an RPC.
 // Balancer is expected to generate a new picker from its snapshot every time its
 // internal state has changed.
 //
 // The pickers used by gRPC can be updated by ClientConn.UpdateBalancerState().
 //
 // Deprecated: use V2Picker instead
 type Picker interface {
 	// Pick returns the SubConn to be used to send the RPC.
 	// The returned SubConn must be one returned by NewSubConn().
 	//
 	// This functions is expected to return:
 	// - a SubConn that is known to be READY;
 	// - ErrNoSubConnAvailable if no SubConn is available, but progress is being
 	//   made (for example, some SubConn is in CONNECTING mode);
 	// - other errors if no active connecting is happening (for example, all SubConn
 	//   are in TRANSIENT_FAILURE mode).
 	//
 	// If a SubConn is returned:
 	// - If it is READY, gRPC will send the RPC on it;
 	// - If it is not ready, or becomes not ready after it's returned, gRPC will
 	//   block until UpdateBalancerState() is called and will call pick on the
 	//   new picker. The done function returned from Pick(), if not nil, will be
 	//   called with nil error, no bytes sent and no bytes received.
 	//
 	// If the returned error is not nil:
 	// - If the error is ErrNoSubConnAvailable, gRPC will block until UpdateBalancerState()
 	// - If the error is ErrTransientFailure or implements IsTransientFailure()
 	//   bool, returning true:
 	//   - If the RPC is wait-for-ready, gRPC will block until UpdateBalancerState()
 	//     is called to pick again;
 	//   - Otherwise, RPC will fail with unavailable error.
 	// - Else (error is other non-nil error):
 	//   - The RPC will fail with the error's status code, or Unknown if it is
 	//     not a status error.
 	//
 	// The returned done() function will be called once the rpc has finished,
 	// with the final status of that RPC.  If the SubConn returned is not a
 	// valid SubConn type, done may not be called.  done may be nil if balancer
 	// doesn't care about the RPC status.
 	Pick(ctx context.Context, info PickInfo) (conn SubConn, done func(DoneInfo), err error)
 }

 // PickResult contains information related to a connection chosen for an RPC.
 type PickResult struct {
 	// SubConn is the connection to use for this pick, if its state is Ready.
 	// If the state is not Ready, gRPC will block the RPC until a new Picker is
 	// provided by the balancer (using ClientConn.UpdateState).  The SubConn
 	// must be one returned by ClientConn.NewSubConn.
 	SubConn SubConn

 	// Done is called when the RPC is completed.  If the SubConn is not ready,
 	// this will be called with a nil parameter.  If the SubConn is not a valid
 	// type, Done may not be called.  May be nil if the balancer does not wish
 	// to be notified when the RPC completes.
 	Done func(DoneInfo)
 }

 type transientFailureError struct {
 	error
 }

 func (e *transientFailureError) IsTransientFailure() bool { return true }

 // TransientFailureError wraps err in an error implementing
 // IsTransientFailure() bool, returning true.
 func TransientFailureError(err error) error {
 	return &transientFailureError{error: err}
 }

 // V2Picker is used by gRPC to pick a SubConn to send an RPC.
 // Balancer is expected to generate a new picker from its snapshot every time its
 // internal state has changed.
 //
 // The pickers used by gRPC can be updated by ClientConn.UpdateBalancerState().
 type V2Picker interface {
 	// Pick returns the connection to use for this RPC and related information.
 	//
 	// Pick should not block.  If the balancer needs to do I/O or any blocking
 	// or time-consuming work to service this call, it should return
 	// ErrNoSubConnAvailable, and the Pick call will be repeated by gRPC when
 	// the Picker is updated (using ClientConn.UpdateState).
 	//
 	// If an error is returned:
 	//
 	// - If the error is ErrNoSubConnAvailable, gRPC will block until a new
 	//   Picker is provided by the balancer (using ClientConn.UpdateState).
 	//
 	// - If the error implements IsTransientFailure() bool, returning true,
 	//   wait for ready RPCs will wait, but non-wait for ready RPCs will be
 	//   terminated with this error's Error() string and status code
 	//   Unavailable.
 	//
 	// - Any other errors terminate all RPCs with the code and message
 	//   provided.  If the error is not a status error, it will be converted by
 	//   gRPC to a status error with code Unknown.
 	Pick(info PickInfo) (PickResult, error)
 }

 // Balancer takes input from gRPC, manages SubConns, and collects and aggregates
 // the connectivity states.
 //
 // It also generates and updates the Picker used by gRPC to pick SubConns for RPCs.
 //
 // HandleSubConnectionStateChange, HandleResolvedAddrs and Close are guaranteed
 // to be called synchronously from the same goroutine.
 // There's no guarantee on picker.Pick, it may be called anytime.
 type Balancer interface {
 	// HandleSubConnStateChange is called by gRPC when the connectivity state
 	// of sc has changed.
 	// Balancer is expected to aggregate all the state of SubConn and report
 	// that back to gRPC.
 	// Balancer should also generate and update Pickers when its internal state has
 	// been changed by the new state.
 	//
 	// Deprecated: if V2Balancer is implemented by the Balancer,
 	// UpdateSubConnState will be called instead.
 	HandleSubConnStateChange(sc SubConn, state connectivity.State)
 	// HandleResolvedAddrs is called by gRPC to send updated resolved addresses to
 	// balancers.
 	// Balancer can create new SubConn or remove SubConn with the addresses.
 	// An empty address slice and a non-nil error will be passed if the resolver returns
 	// non-nil error to gRPC.
 	//
 	// Deprecated: if V2Balancer is implemented by the Balancer,
 	// UpdateClientConnState will be called instead.
 	HandleResolvedAddrs([]resolver.Address, error)
 	// Close closes the balancer. The balancer is not required to call
 	// ClientConn.RemoveSubConn for its existing SubConns.
 	Close()
 }

 // SubConnState describes the state of a SubConn.
 type SubConnState struct {
 	// ConnectivityState is the connectivity state of the SubConn.
 	ConnectivityState connectivity.State
 	// ConnectionError is set if the ConnectivityState is TransientFailure,
 	// describing the reason the SubConn failed.  Otherwise, it is nil.
 	ConnectionError error
 }

 // ClientConnState describes the state of a ClientConn relevant to the
 // balancer.
 type ClientConnState struct {
 	ResolverState resolver.State
 	// The parsed load balancing configuration returned by the builder's
 	// ParseConfig method, if implemented.
 	BalancerConfig serviceconfig.LoadBalancingConfig
 }

 // ErrBadResolverState may be returned by UpdateClientConnState to indicate a
 // problem with the provided name resolver data.
 var ErrBadResolverState = errors.New("bad resolver state")

 // V2Balancer is defined for documentation purposes.  If a Balancer also
 // implements V2Balancer, its UpdateClientConnState method will be called
 // instead of HandleResolvedAddrs and its UpdateSubConnState will be called
 // instead of HandleSubConnStateChange.
 type V2Balancer interface {
 	// UpdateClientConnState is called by gRPC when the state of the ClientConn
 	// changes.  If the error returned is ErrBadResolverState, the ClientConn
 	// will begin calling ResolveNow on the active name resolver with
 	// exponential backoff until a subsequent call to UpdateClientConnState
 	// returns a nil error.  Any other errors are currently ignored.
 	UpdateClientConnState(ClientConnState) error
 	// ResolverError is called by gRPC when the name resolver reports an error.
 	ResolverError(error)
 	// UpdateSubConnState is called by gRPC when the state of a SubConn
 	// changes.
 	UpdateSubConnState(SubConn, SubConnState)
 	// Close closes the balancer. The balancer is not required to call
 	// ClientConn.RemoveSubConn for its existing SubConns.
 	Close()
 }

 // ConnectivityStateEvaluator takes the connectivity states of multiple SubConns
 // and returns one aggregated connectivity state.
 //
 // It's not thread safe.
 type ConnectivityStateEvaluator struct {
 	numReady      uint64 // Number of addrConns in ready state.
 	numConnecting uint64 // Number of addrConns in connecting state.
 }

 // RecordTransition records state change happening in subConn and based on that
 // it evaluates what aggregated state should be.
 //
 //  - If at least one SubConn in Ready, the aggregated state is Ready;
 //  - Else if at least one SubConn in Connecting, the aggregated state is Connecting;
 //  - Else the aggregated state is TransientFailure.
 //
 // Idle and Shutdown are not considered.
 func (cse *ConnectivityStateEvaluator) RecordTransition(oldState, newState connectivity.State) connectivity.State {
 	// Update counters.
 	for idx, state := range []connectivity.State{oldState, newState} {
 		updateVal := 2*uint64(idx) - 1 // -1 for oldState and +1 for new.
 		switch state {
 		case connectivity.Ready:
 			cse.numReady += updateVal
 		case connectivity.Connecting:
 			cse.numConnecting += updateVal
 		}
 	}

 	// Evaluate.
 	if cse.numReady > 0 {
 		return connectivity.Ready
 	}
 	if cse.numConnecting > 0 {
 		return connectivity.Connecting
 	}
 	return connectivity.TransientFailure
 }
	/*
	*
	* Copyright 2017 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 balancer defines APIs for load balancing in gRPC.
	// All APIs in this package are experimental.
	package balancer

	import (
	"context"
	"encoding/json"
	"errors"
	"net"
	"strings"

	"google.golang.org/grpc/connectivity"
	"google.golang.org/grpc/credentials"
	"google.golang.org/grpc/internal"
	"google.golang.org/grpc/metadata"
	"google.golang.org/grpc/resolver"
	"google.golang.org/grpc/serviceconfig"
	)

	var (
	// m is a map from name to balancer builder.
	m = make(map[string]Builder)
	)

	// Register registers the balancer builder to the balancer map. b.Name
	// (lowercased) will be used as the name registered with this builder. If the
	// Builder implements ConfigParser, ParseConfig will be called when new service
	// configs are received by the resolver, and the result will be provided to the
	// Balancer in UpdateClientConnState.
	//
	// NOTE: this function must only be called during initialization time (i.e. in
	// an init() function), and is not thread-safe. If multiple Balancers are
	// registered with the same name, the one registered last will take effect.
	func Register(b Builder) {
	m[strings.ToLower(b.Name())] = b
	}

	// unregisterForTesting deletes the balancer with the given name from the
	// balancer map.
	//
	// This function is not thread-safe.
	func unregisterForTesting(name string) {
	delete(m, name)
	}

	func init() {
	internal.BalancerUnregister = unregisterForTesting
	}

	// Get returns the resolver builder registered with the given name.
	// Note that the compare is done in a case-insensitive fashion.
	// If no builder is register with the name, nil will be returned.
	func Get(name string) Builder {
	if b, ok := m[strings.ToLower(name)]; ok {
	return b
	}
	return nil
	}

	// SubConn represents a gRPC sub connection.
	// Each sub connection contains a list of addresses. gRPC will
	// try to connect to them (in sequence), and stop trying the
	// remainder once one connection is successful.
	//
	// The reconnect backoff will be applied on the list, not a single address.
	// For example, try_on_all_addresses -> backoff -> try_on_all_addresses.
	//
	// All SubConns start in IDLE, and will not try to connect. To trigger
	// the connecting, Balancers must call Connect.
	// When the connection encounters an error, it will reconnect immediately.
	// When the connection becomes IDLE, it will not reconnect unless Connect is
	// called.
	//
	// This interface is to be implemented by gRPC. Users should not need a
	// brand new implementation of this interface. For the situations like
	// testing, the new implementation should embed this interface. This allows
	// gRPC to add new methods to this interface.
	type SubConn interface {
	// UpdateAddresses updates the addresses used in this SubConn.
	// gRPC checks if currently-connected address is still in the new list.
	// If it's in the list, the connection will be kept.
	// If it's not in the list, the connection will gracefully closed, and
	// a new connection will be created.
	//
	// This will trigger a state transition for the SubConn.
	UpdateAddresses([]resolver.Address)
	// Connect starts the connecting for this SubConn.
	Connect()
	}

	// NewSubConnOptions contains options to create new SubConn.
	type NewSubConnOptions struct {
	// CredsBundle is the credentials bundle that will be used in the created
	// SubConn. If it's nil, the original creds from grpc DialOptions will be
	// used.
	CredsBundle credentials.Bundle
	// HealthCheckEnabled indicates whether health check service should be
	// enabled on this SubConn
	HealthCheckEnabled bool
	}

	// State contains the balancer's state relevant to the gRPC ClientConn.
	type State struct {
	// State contains the connectivity state of the balancer, which is used to
	// determine the state of the ClientConn.
	ConnectivityState connectivity.State
	// Picker is used to choose connections (SubConns) for RPCs.
	Picker V2Picker
	}

	// ClientConn represents a gRPC ClientConn.
	//
	// This interface is to be implemented by gRPC. Users should not need a
	// brand new implementation of this interface. For the situations like
	// testing, the new implementation should embed this interface. This allows
	// gRPC to add new methods to this interface.
	type ClientConn interface {
	// NewSubConn is called by balancer to create a new SubConn.
	// It doesn't block and wait for the connections to be established.
	// Behaviors of the SubConn can be controlled by options.
	NewSubConn([]resolver.Address, NewSubConnOptions) (SubConn, error)
	// RemoveSubConn removes the SubConn from ClientConn.
	// The SubConn will be shutdown.
	RemoveSubConn(SubConn)

	// UpdateBalancerState is called by balancer to notify gRPC that some internal
	// state in balancer has changed.
	//
	// gRPC will update the connectivity state of the ClientConn, and will call pick
	// on the new picker to pick new SubConn.
	//
	// Deprecated: use UpdateState instead
	UpdateBalancerState(s connectivity.State, p Picker)

	// UpdateState notifies gRPC that the balancer's internal state has
	// changed.
	//
	// gRPC will update the connectivity state of the ClientConn, and will call pick
	// on the new picker to pick new SubConns.
	UpdateState(State)

	// ResolveNow is called by balancer to notify gRPC to do a name resolving.
	ResolveNow(resolver.ResolveNowOptions)

	// Target returns the dial target for this ClientConn.
	//
	// Deprecated: Use the Target field in the BuildOptions instead.
	Target() string
	}

	// BuildOptions contains additional information for Build.
	type BuildOptions struct {
	// DialCreds is the transport credential the Balancer implementation can
	// use to dial to a remote load balancer server. The Balancer implementations
	// can ignore this if it does not need to talk to another party securely.
	DialCreds credentials.TransportCredentials
	// CredsBundle is the credentials bundle that the Balancer can use.
	CredsBundle credentials.Bundle
	// Dialer is the custom dialer the Balancer implementation can use to dial
	// to a remote load balancer server. The Balancer implementations
	// can ignore this if it doesn't need to talk to remote balancer.
	Dialer func(context.Context, string) (net.Conn, error)
	// ChannelzParentID is the entity parent's channelz unique identification number.
	ChannelzParentID int64
	// Target contains the parsed address info of the dial target. It is the 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
	}

	// Builder creates a balancer.
	type Builder interface {
	// Build creates a new balancer with the ClientConn.
	Build(cc ClientConn, opts BuildOptions) Balancer
	// Name returns the name of balancers built by this builder.
	// It will be used to pick balancers (for example in service config).
	Name() string
	}

	// ConfigParser parses load balancer configs.
	type ConfigParser interface {
	// ParseConfig parses the JSON load balancer config provided into an
	// internal form or returns an error if the config is invalid. For future
	// compatibility reasons, unknown fields in the config should be ignored.
	ParseConfig(LoadBalancingConfigJSON json.RawMessage) (serviceconfig.LoadBalancingConfig, error)
	}

	// PickInfo contains additional information for the Pick operation.
	type PickInfo struct {
	// FullMethodName is the method name that NewClientStream() is called
	// with. The canonical format is /service/Method.
	FullMethodName string
	// Ctx is the RPC's context, and may contain relevant RPC-level information
	// like the outgoing header metadata.
	Ctx context.Context
	}

	// DoneInfo contains additional information for done.
	type DoneInfo struct {
	// Err is the rpc error the RPC finished with. It could be nil.
	Err error
	// Trailer contains the metadata from the RPC's trailer, if present.
	Trailer metadata.MD
	// BytesSent indicates if any bytes have been sent to the server.
	BytesSent bool
	// BytesReceived indicates if any byte has been received from the server.
	BytesReceived bool
	// ServerLoad is the load received from server. It's usually sent as part of
	// trailing metadata.
	//
	// The only supported type now is *orca_v1.LoadReport.
	ServerLoad interface{}
	}

	var (
	// ErrNoSubConnAvailable indicates no SubConn is available for pick().
	// gRPC will block the RPC until a new picker is available via UpdateBalancerState().
	ErrNoSubConnAvailable = errors.New("no SubConn is available")
	// ErrTransientFailure indicates all SubConns are in TransientFailure.
	// WaitForReady RPCs will block, non-WaitForReady RPCs will fail.
	ErrTransientFailure = TransientFailureError(errors.New("all SubConns are in TransientFailure"))
	)

	// Picker is used by gRPC to pick a SubConn to send an RPC.
	// Balancer is expected to generate a new picker from its snapshot every time its
	// internal state has changed.
	//
	// The pickers used by gRPC can be updated by ClientConn.UpdateBalancerState().
	//
	// Deprecated: use V2Picker instead
	type Picker interface {
	// Pick returns the SubConn to be used to send the RPC.
	// The returned SubConn must be one returned by NewSubConn().
	//
	// This functions is expected to return:
	// - a SubConn that is known to be READY;
	// - ErrNoSubConnAvailable if no SubConn is available, but progress is being
	// made (for example, some SubConn is in CONNECTING mode);
	// - other errors if no active connecting is happening (for example, all SubConn
	// are in TRANSIENT_FAILURE mode).
	//
	// If a SubConn is returned:
	// - If it is READY, gRPC will send the RPC on it;
	// - If it is not ready, or becomes not ready after it's returned, gRPC will
	// block until UpdateBalancerState() is called and will call pick on the
	// new picker. The done function returned from Pick(), if not nil, will be
	// called with nil error, no bytes sent and no bytes received.
	//
	// If the returned error is not nil:
	// - If the error is ErrNoSubConnAvailable, gRPC will block until UpdateBalancerState()
	// - If the error is ErrTransientFailure or implements IsTransientFailure()
	// bool, returning true:
	// - If the RPC is wait-for-ready, gRPC will block until UpdateBalancerState()
	// is called to pick again;
	// - Otherwise, RPC will fail with unavailable error.
	// - Else (error is other non-nil error):
	// - The RPC will fail with the error's status code, or Unknown if it is
	// not a status error.
	//
	// The returned done() function will be called once the rpc has finished,
	// with the final status of that RPC. If the SubConn returned is not a
	// valid SubConn type, done may not be called. done may be nil if balancer
	// doesn't care about the RPC status.
	Pick(ctx context.Context, info PickInfo) (conn SubConn, done func(DoneInfo), err error)
	}

	// PickResult contains information related to a connection chosen for an RPC.
	type PickResult struct {
	// SubConn is the connection to use for this pick, if its state is Ready.
	// If the state is not Ready, gRPC will block the RPC until a new Picker is
	// provided by the balancer (using ClientConn.UpdateState). The SubConn
	// must be one returned by ClientConn.NewSubConn.
	SubConn SubConn

	// Done is called when the RPC is completed. If the SubConn is not ready,
	// this will be called with a nil parameter. If the SubConn is not a valid
	// type, Done may not be called. May be nil if the balancer does not wish
	// to be notified when the RPC completes.
	Done func(DoneInfo)
	}

	type transientFailureError struct {
	error
	}

	func (e *transientFailureError) IsTransientFailure() bool { return true }

	// TransientFailureError wraps err in an error implementing
	// IsTransientFailure() bool, returning true.
	func TransientFailureError(err error) error {
	return &transientFailureError{error: err}
	}

	// V2Picker is used by gRPC to pick a SubConn to send an RPC.
	// Balancer is expected to generate a new picker from its snapshot every time its
	// internal state has changed.
	//
	// The pickers used by gRPC can be updated by ClientConn.UpdateBalancerState().
	type V2Picker interface {
	// Pick returns the connection to use for this RPC and related information.
	//
	// Pick should not block. If the balancer needs to do I/O or any blocking
	// or time-consuming work to service this call, it should return
	// ErrNoSubConnAvailable, and the Pick call will be repeated by gRPC when
	// the Picker is updated (using ClientConn.UpdateState).
	//
	// If an error is returned:
	//
	// - If the error is ErrNoSubConnAvailable, gRPC will block until a new
	// Picker is provided by the balancer (using ClientConn.UpdateState).
	//
	// - If the error implements IsTransientFailure() bool, returning true,
	// wait for ready RPCs will wait, but non-wait for ready RPCs will be
	// terminated with this error's Error() string and status code
	// Unavailable.
	//
	// - Any other errors terminate all RPCs with the code and message
	// provided. If the error is not a status error, it will be converted by
	// gRPC to a status error with code Unknown.
	Pick(info PickInfo) (PickResult, error)
	}

	// Balancer takes input from gRPC, manages SubConns, and collects and aggregates
	// the connectivity states.
	//
	// It also generates and updates the Picker used by gRPC to pick SubConns for RPCs.
	//
	// HandleSubConnectionStateChange, HandleResolvedAddrs and Close are guaranteed
	// to be called synchronously from the same goroutine.
	// There's no guarantee on picker.Pick, it may be called anytime.
	type Balancer interface {
	// HandleSubConnStateChange is called by gRPC when the connectivity state
	// of sc has changed.
	// Balancer is expected to aggregate all the state of SubConn and report
	// that back to gRPC.
	// Balancer should also generate and update Pickers when its internal state has
	// been changed by the new state.
	//
	// Deprecated: if V2Balancer is implemented by the Balancer,
	// UpdateSubConnState will be called instead.
	HandleSubConnStateChange(sc SubConn, state connectivity.State)
	// HandleResolvedAddrs is called by gRPC to send updated resolved addresses to
	// balancers.
	// Balancer can create new SubConn or remove SubConn with the addresses.
	// An empty address slice and a non-nil error will be passed if the resolver returns
	// non-nil error to gRPC.
	//
	// Deprecated: if V2Balancer is implemented by the Balancer,
	// UpdateClientConnState will be called instead.
	HandleResolvedAddrs([]resolver.Address, error)
	// Close closes the balancer. The balancer is not required to call
	// ClientConn.RemoveSubConn for its existing SubConns.
	Close()
	}

	// SubConnState describes the state of a SubConn.
	type SubConnState struct {
	// ConnectivityState is the connectivity state of the SubConn.
	ConnectivityState connectivity.State
	// ConnectionError is set if the ConnectivityState is TransientFailure,
	// describing the reason the SubConn failed. Otherwise, it is nil.
	ConnectionError error
	}

	// ClientConnState describes the state of a ClientConn relevant to the
	// balancer.
	type ClientConnState struct {
	ResolverState resolver.State
	// The parsed load balancing configuration returned by the builder's
	// ParseConfig method, if implemented.
	BalancerConfig serviceconfig.LoadBalancingConfig
	}

	// ErrBadResolverState may be returned by UpdateClientConnState to indicate a
	// problem with the provided name resolver data.
	var ErrBadResolverState = errors.New("bad resolver state")

	// V2Balancer is defined for documentation purposes. If a Balancer also
	// implements V2Balancer, its UpdateClientConnState method will be called
	// instead of HandleResolvedAddrs and its UpdateSubConnState will be called
	// instead of HandleSubConnStateChange.
	type V2Balancer interface {
	// UpdateClientConnState is called by gRPC when the state of the ClientConn
	// changes. If the error returned is ErrBadResolverState, the ClientConn
	// will begin calling ResolveNow on the active name resolver with
	// exponential backoff until a subsequent call to UpdateClientConnState
	// returns a nil error. Any other errors are currently ignored.
	UpdateClientConnState(ClientConnState) error
	// ResolverError is called by gRPC when the name resolver reports an error.
	ResolverError(error)
	// UpdateSubConnState is called by gRPC when the state of a SubConn
	// changes.
	UpdateSubConnState(SubConn, SubConnState)
	// Close closes the balancer. The balancer is not required to call
	// ClientConn.RemoveSubConn for its existing SubConns.
	Close()
	}

	// ConnectivityStateEvaluator takes the connectivity states of multiple SubConns
	// and returns one aggregated connectivity state.
	//
	// It's not thread safe.
	type ConnectivityStateEvaluator struct {
	numReady uint64 // Number of addrConns in ready state.
	numConnecting uint64 // Number of addrConns in connecting state.
	}

	// RecordTransition records state change happening in subConn and based on that
	// it evaluates what aggregated state should be.
	//
	// - If at least one SubConn in Ready, the aggregated state is Ready;
	// - Else if at least one SubConn in Connecting, the aggregated state is Connecting;
	// - Else the aggregated state is TransientFailure.
	//
	// Idle and Shutdown are not considered.
	func (cse *ConnectivityStateEvaluator) RecordTransition(oldState, newState connectivity.State) connectivity.State {
	// Update counters.
	for idx, state := range []connectivity.State{oldState, newState} {
	updateVal := 2*uint64(idx) - 1 // -1 for oldState and +1 for new.
	switch state {
	case connectivity.Ready:
	cse.numReady += updateVal
	case connectivity.Connecting:
	cse.numConnecting += updateVal
	}
	}

	// Evaluate.
	if cse.numReady > 0 {
	return connectivity.Ready
	}
	if cse.numConnecting > 0 {
	return connectivity.Connecting
	}
	return connectivity.TransientFailure
	}