| /* |
| * |
| * 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" |
| "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" |
| ) |
| |
| 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. |
| // |
| // 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. |
| 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 |
| } |
| |
| // 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 |
| } |
| |
| // 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 |
| // Header contains the metadata from the RPC's client header. The metadata |
| // should not be modified; make a copy first if needed. |
| Header metadata.MD |
| } |
| |
| // 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 |
| } |
| |
| 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. |
| // |
| // 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. |
| 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. |
| HandleResolvedAddrs([]resolver.Address, error) |
| // 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 |
| } |