365 lines
14 KiB
Go
365 lines
14 KiB
Go
|
/*
|
||
|
|
*
|
||
|
|
* 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
|
||
|
|
}
|
||
|
|
|
||
|
|
// 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.
|
||
|
|
UpdateBalancerState(s connectivity.State, p Picker)
|
||
|
|
|
||
|
|
// ResolveNow is called by balancer to notify gRPC to do a name resolving.
|
||
|
|
ResolveNow(resolver.ResolveNowOption)
|
||
|
|
|
||
|
|
// 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)
|
||
|
|
}
|
||
|
|
|
||
|
|
// PickOptions contains addition information for the Pick operation.
|
||
|
|
type PickOptions struct {
|
||
|
|
// FullMethodName is the method name that NewClientStream() is called
|
||
|
|
// with. The canonical format is /service/Method.
|
||
|
|
FullMethodName string
|
||
|
|
}
|
||
|
|
|
||
|
|
// 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 = 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().
|
||
|
|
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:
|
||
|
|
// - 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 unavailable 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, opts PickOptions) (conn SubConn, done func(DoneInfo), err 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 connectivity.State
|
||
|
|
// TODO: add last connection 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
|
||
|
|
}
|
||
|
|
|
||
|
|
// 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.
|
||
|
|
UpdateClientConnState(ClientConnState)
|
||
|
|
// 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.
|
||
|
|
numTransientFailure uint64 // Number of addrConns in transientFailure.
|
||
|
|
}
|
||
|
|
|
||
|
|
// 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
|
||
|
|
case connectivity.TransientFailure:
|
||
|
|
cse.numTransientFailure += updateVal
|
||
|
|
}
|
||
|
|
}
|
||
|
|
|
||
|
|
// Evaluate.
|
||
|
|
if cse.numReady > 0 {
|
||
|
|
return connectivity.Ready
|
||
|
|
}
|
||
|
|
if cse.numConnecting > 0 {
|
||
|
|
return connectivity.Connecting
|
||
|
|
}
|
||
|
|
return connectivity.TransientFailure
|
||
|
|
}
|