vendor/google.golang.org/grpc/balancer/balancer.go

   1 /*
   2  *
   3  * Copyright 2017 gRPC authors.
   4  *
   5  * Licensed under the Apache License, Version 2.0 (the "License");
   6  * you may not use this file except in compliance with the License.
   7  * You may obtain a copy of the License at
   8  *
   9  *     http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  * Unless required by applicable law or agreed to in writing, software
  12  * distributed under the License is distributed on an "AS IS" BASIS,
  13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  * See the License for the specific language governing permissions and
  15  * limitations under the License.
  16  *
  17  */
  18
  19 // Package balancer defines APIs for load balancing in gRPC.
  20 // All APIs in this package are experimental.
  21 package balancer
  22
  23 import (
  24         "errors"
  25         "net"
  26
  27         "golang.org/x/net/context"
  28         "google.golang.org/grpc/connectivity"
  29         "google.golang.org/grpc/credentials"
  30         "google.golang.org/grpc/resolver"
  31 )
  32
  33 var (
  34         // m is a map from name to balancer builder.
  35         m = make(map[string]Builder)
  36 )
  37
  38 // Register registers the balancer builder to the balancer map.
  39 // b.Name will be used as the name registered with this builder.
  40 func Register(b Builder) {
  41         m[b.Name()] = b
  42 }
  43
  44 // Get returns the resolver builder registered with the given name.
  45 // If no builder is register with the name, nil will be returned.
  46 func Get(name string) Builder {
  47         if b, ok := m[name]; ok {
  48                 return b
  49         }
  50         return nil
  51 }
  52
  53 // SubConn represents a gRPC sub connection.
  54 // Each sub connection contains a list of addresses. gRPC will
  55 // try to connect to them (in sequence), and stop trying the
  56 // remainder once one connection is successful.
  57 //
  58 // The reconnect backoff will be applied on the list, not a single address.
  59 // For example, try_on_all_addresses -> backoff -> try_on_all_addresses.
  60 //
  61 // All SubConns start in IDLE, and will not try to connect. To trigger
  62 // the connecting, Balancers must call Connect.
  63 // When the connection encounters an error, it will reconnect immediately.
  64 // When the connection becomes IDLE, it will not reconnect unless Connect is
  65 // called.
  66 type SubConn interface {
  67         // UpdateAddresses updates the addresses used in this SubConn.
  68         // gRPC checks if currently-connected address is still in the new list.
  69         // If it's in the list, the connection will be kept.
  70         // If it's not in the list, the connection will gracefully closed, and
  71         // a new connection will be created.
  72         //
  73         // This will trigger a state transition for the SubConn.
  74         UpdateAddresses([]resolver.Address)
  75         // Connect starts the connecting for this SubConn.
  76         Connect()
  77 }
  78
  79 // NewSubConnOptions contains options to create new SubConn.
  80 type NewSubConnOptions struct{}
  81
  82 // ClientConn represents a gRPC ClientConn.
  83 type ClientConn interface {
  84         // NewSubConn is called by balancer to create a new SubConn.
  85         // It doesn't block and wait for the connections to be established.
  86         // Behaviors of the SubConn can be controlled by options.
  87         NewSubConn([]resolver.Address, NewSubConnOptions) (SubConn, error)
  88         // RemoveSubConn removes the SubConn from ClientConn.
  89         // The SubConn will be shutdown.
  90         RemoveSubConn(SubConn)
  91
  92         // UpdateBalancerState is called by balancer to nofity gRPC that some internal
  93         // state in balancer has changed.
  94         //
  95         // gRPC will update the connectivity state of the ClientConn, and will call pick
  96         // on the new picker to pick new SubConn.
  97         UpdateBalancerState(s connectivity.State, p Picker)
  98
  99         // Target returns the dial target for this ClientConn.
 100         Target() string
 101 }
 102
 103 // BuildOptions contains additional information for Build.
 104 type BuildOptions struct {
 105         // DialCreds is the transport credential the Balancer implementation can
 106         // use to dial to a remote load balancer server. The Balancer implementations
 107         // can ignore this if it does not need to talk to another party securely.
 108         DialCreds credentials.TransportCredentials
 109         // Dialer is the custom dialer the Balancer implementation can use to dial
 110         // to a remote load balancer server. The Balancer implementations
 111         // can ignore this if it doesn't need to talk to remote balancer.
 112         Dialer func(context.Context, string) (net.Conn, error)
 113 }
 114
 115 // Builder creates a balancer.
 116 type Builder interface {
 117         // Build creates a new balancer with the ClientConn.
 118         Build(cc ClientConn, opts BuildOptions) Balancer
 119         // Name returns the name of balancers built by this builder.
 120         // It will be used to pick balancers (for example in service config).
 121         Name() string
 122 }
 123
 124 // PickOptions contains addition information for the Pick operation.
 125 type PickOptions struct{}
 126
 127 // DoneInfo contains additional information for done.
 128 type DoneInfo struct {
 129         // Err is the rpc error the RPC finished with. It could be nil.
 130         Err error
 131 }
 132
 133 var (
 134         // ErrNoSubConnAvailable indicates no SubConn is available for pick().
 135         // gRPC will block the RPC until a new picker is available via UpdateBalancerState().
 136         ErrNoSubConnAvailable = errors.New("no SubConn is available")
 137         // ErrTransientFailure indicates all SubConns are in TransientFailure.
 138         // WaitForReady RPCs will block, non-WaitForReady RPCs will fail.
 139         ErrTransientFailure = errors.New("all SubConns are in TransientFailure")
 140 )
 141
 142 // Picker is used by gRPC to pick a SubConn to send an RPC.
 143 // Balancer is expected to generate a new picker from its snapshot everytime its
 144 // internal state has changed.
 145 //
 146 // The pickers used by gRPC can be updated by ClientConn.UpdateBalancerState().
 147 type Picker interface {
 148         // Pick returns the SubConn to be used to send the RPC.
 149         // The returned SubConn must be one returned by NewSubConn().
 150         //
 151         // This functions is expected to return:
 152         // - a SubConn that is known to be READY;
 153         // - ErrNoSubConnAvailable if no SubConn is available, but progress is being
 154         //   made (for example, some SubConn is in CONNECTING mode);
 155         // - other errors if no active connecting is happening (for example, all SubConn
 156         //   are in TRANSIENT_FAILURE mode).
 157         //
 158         // If a SubConn is returned:
 159         // - If it is READY, gRPC will send the RPC on it;
 160         // - If it is not ready, or becomes not ready after it's returned, gRPC will block
 161         //   this call until a new picker is updated and will call pick on the new picker.
 162         //
 163         // If the returned error is not nil:
 164         // - If the error is ErrNoSubConnAvailable, gRPC will block until UpdateBalancerState()
 165         // - If the error is ErrTransientFailure:
 166         //   - If the RPC is wait-for-ready, gRPC will block until UpdateBalancerState()
 167         //     is called to pick again;
 168         //   - Otherwise, RPC will fail with unavailable error.
 169         // - Else (error is other non-nil error):
 170         //   - The RPC will fail with unavailable error.
 171         //
 172         // The returned done() function will be called once the rpc has finished, with the
 173         // final status of that RPC.
 174         // done may be nil if balancer doesn't care about the RPC status.
 175         Pick(ctx context.Context, opts PickOptions) (conn SubConn, done func(DoneInfo), err error)
 176 }
 177
 178 // Balancer takes input from gRPC, manages SubConns, and collects and aggregates
 179 // the connectivity states.
 180 //
 181 // It also generates and updates the Picker used by gRPC to pick SubConns for RPCs.
 182 //
 183 // HandleSubConnectionStateChange, HandleResolvedAddrs and Close are guaranteed
 184 // to be called synchronously from the same goroutine.
 185 // There's no guarantee on picker.Pick, it may be called anytime.
 186 type Balancer interface {
 187         // HandleSubConnStateChange is called by gRPC when the connectivity state
 188         // of sc has changed.
 189         // Balancer is expected to aggregate all the state of SubConn and report
 190         // that back to gRPC.
 191         // Balancer should also generate and update Pickers when its internal state has
 192         // been changed by the new state.
 193         HandleSubConnStateChange(sc SubConn, state connectivity.State)
 194         // HandleResolvedAddrs is called by gRPC to send updated resolved addresses to
 195         // balancers.
 196         // Balancer can create new SubConn or remove SubConn with the addresses.
 197         // An empty address slice and a non-nil error will be passed if the resolver returns
 198         // non-nil error to gRPC.
 199         HandleResolvedAddrs([]resolver.Address, error)
 200         // Close closes the balancer. The balancer is not required to call
 201         // ClientConn.RemoveSubConn for its existing SubConns.
 202         Close()
 203 }