blob: 9258858ed755b4e63398d5b5005119020305c7f6 [file] [log] [blame]
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -07001/*
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.
21package balancer
22
23import (
24 "context"
25 "encoding/json"
26 "errors"
27 "net"
28 "strings"
29
30 "google.golang.org/grpc/connectivity"
31 "google.golang.org/grpc/credentials"
32 "google.golang.org/grpc/internal"
33 "google.golang.org/grpc/metadata"
34 "google.golang.org/grpc/resolver"
35 "google.golang.org/grpc/serviceconfig"
36)
37
38var (
39 // m is a map from name to balancer builder.
40 m = make(map[string]Builder)
41)
42
43// Register registers the balancer builder to the balancer map. b.Name
44// (lowercased) will be used as the name registered with this builder. If the
45// Builder implements ConfigParser, ParseConfig will be called when new service
46// configs are received by the resolver, and the result will be provided to the
47// Balancer in UpdateClientConnState.
48//
49// NOTE: this function must only be called during initialization time (i.e. in
50// an init() function), and is not thread-safe. If multiple Balancers are
51// registered with the same name, the one registered last will take effect.
52func Register(b Builder) {
53 m[strings.ToLower(b.Name())] = b
54}
55
56// unregisterForTesting deletes the balancer with the given name from the
57// balancer map.
58//
59// This function is not thread-safe.
60func unregisterForTesting(name string) {
61 delete(m, name)
62}
63
64func init() {
65 internal.BalancerUnregister = unregisterForTesting
66}
67
68// Get returns the resolver builder registered with the given name.
69// Note that the compare is done in a case-insensitive fashion.
70// If no builder is register with the name, nil will be returned.
71func Get(name string) Builder {
72 if b, ok := m[strings.ToLower(name)]; ok {
73 return b
74 }
75 return nil
76}
77
78// SubConn represents a gRPC sub connection.
79// Each sub connection contains a list of addresses. gRPC will
80// try to connect to them (in sequence), and stop trying the
81// remainder once one connection is successful.
82//
83// The reconnect backoff will be applied on the list, not a single address.
84// For example, try_on_all_addresses -> backoff -> try_on_all_addresses.
85//
86// All SubConns start in IDLE, and will not try to connect. To trigger
87// the connecting, Balancers must call Connect.
88// When the connection encounters an error, it will reconnect immediately.
89// When the connection becomes IDLE, it will not reconnect unless Connect is
90// called.
91//
92// This interface is to be implemented by gRPC. Users should not need a
93// brand new implementation of this interface. For the situations like
94// testing, the new implementation should embed this interface. This allows
95// gRPC to add new methods to this interface.
96type SubConn interface {
97 // UpdateAddresses updates the addresses used in this SubConn.
98 // gRPC checks if currently-connected address is still in the new list.
99 // If it's in the list, the connection will be kept.
100 // If it's not in the list, the connection will gracefully closed, and
101 // a new connection will be created.
102 //
103 // This will trigger a state transition for the SubConn.
104 UpdateAddresses([]resolver.Address)
105 // Connect starts the connecting for this SubConn.
106 Connect()
107}
108
109// NewSubConnOptions contains options to create new SubConn.
110type NewSubConnOptions struct {
111 // CredsBundle is the credentials bundle that will be used in the created
112 // SubConn. If it's nil, the original creds from grpc DialOptions will be
113 // used.
114 CredsBundle credentials.Bundle
115 // HealthCheckEnabled indicates whether health check service should be
116 // enabled on this SubConn
117 HealthCheckEnabled bool
118}
119
Arjun E K57a7fcb2020-01-30 06:44:45 +0000120// State contains the balancer's state relevant to the gRPC ClientConn.
121type State struct {
122 // State contains the connectivity state of the balancer, which is used to
123 // determine the state of the ClientConn.
124 ConnectivityState connectivity.State
125 // Picker is used to choose connections (SubConns) for RPCs.
126 Picker V2Picker
127}
128
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700129// ClientConn represents a gRPC ClientConn.
130//
131// This interface is to be implemented by gRPC. Users should not need a
132// brand new implementation of this interface. For the situations like
133// testing, the new implementation should embed this interface. This allows
134// gRPC to add new methods to this interface.
135type ClientConn interface {
136 // NewSubConn is called by balancer to create a new SubConn.
137 // It doesn't block and wait for the connections to be established.
138 // Behaviors of the SubConn can be controlled by options.
139 NewSubConn([]resolver.Address, NewSubConnOptions) (SubConn, error)
140 // RemoveSubConn removes the SubConn from ClientConn.
141 // The SubConn will be shutdown.
142 RemoveSubConn(SubConn)
143
144 // UpdateBalancerState is called by balancer to notify gRPC that some internal
145 // state in balancer has changed.
146 //
147 // gRPC will update the connectivity state of the ClientConn, and will call pick
148 // on the new picker to pick new SubConn.
Arjun E K57a7fcb2020-01-30 06:44:45 +0000149 //
150 // Deprecated: use UpdateState instead
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700151 UpdateBalancerState(s connectivity.State, p Picker)
152
Arjun E K57a7fcb2020-01-30 06:44:45 +0000153 // UpdateState notifies gRPC that the balancer's internal state has
154 // changed.
155 //
156 // gRPC will update the connectivity state of the ClientConn, and will call pick
157 // on the new picker to pick new SubConns.
158 UpdateState(State)
159
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700160 // ResolveNow is called by balancer to notify gRPC to do a name resolving.
Arjun E K57a7fcb2020-01-30 06:44:45 +0000161 ResolveNow(resolver.ResolveNowOptions)
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700162
163 // Target returns the dial target for this ClientConn.
164 //
165 // Deprecated: Use the Target field in the BuildOptions instead.
166 Target() string
167}
168
169// BuildOptions contains additional information for Build.
170type BuildOptions struct {
171 // DialCreds is the transport credential the Balancer implementation can
172 // use to dial to a remote load balancer server. The Balancer implementations
173 // can ignore this if it does not need to talk to another party securely.
174 DialCreds credentials.TransportCredentials
175 // CredsBundle is the credentials bundle that the Balancer can use.
176 CredsBundle credentials.Bundle
177 // Dialer is the custom dialer the Balancer implementation can use to dial
178 // to a remote load balancer server. The Balancer implementations
179 // can ignore this if it doesn't need to talk to remote balancer.
180 Dialer func(context.Context, string) (net.Conn, error)
181 // ChannelzParentID is the entity parent's channelz unique identification number.
182 ChannelzParentID int64
183 // Target contains the parsed address info of the dial target. It is the same resolver.Target as
184 // passed to the resolver.
185 // See the documentation for the resolver.Target type for details about what it contains.
186 Target resolver.Target
187}
188
189// Builder creates a balancer.
190type Builder interface {
191 // Build creates a new balancer with the ClientConn.
192 Build(cc ClientConn, opts BuildOptions) Balancer
193 // Name returns the name of balancers built by this builder.
194 // It will be used to pick balancers (for example in service config).
195 Name() string
196}
197
198// ConfigParser parses load balancer configs.
199type ConfigParser interface {
200 // ParseConfig parses the JSON load balancer config provided into an
201 // internal form or returns an error if the config is invalid. For future
202 // compatibility reasons, unknown fields in the config should be ignored.
203 ParseConfig(LoadBalancingConfigJSON json.RawMessage) (serviceconfig.LoadBalancingConfig, error)
204}
205
Arjun E K57a7fcb2020-01-30 06:44:45 +0000206// PickInfo contains additional information for the Pick operation.
207type PickInfo struct {
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700208 // FullMethodName is the method name that NewClientStream() is called
209 // with. The canonical format is /service/Method.
210 FullMethodName string
Arjun E K57a7fcb2020-01-30 06:44:45 +0000211 // Ctx is the RPC's context, and may contain relevant RPC-level information
212 // like the outgoing header metadata.
213 Ctx context.Context
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700214}
215
216// DoneInfo contains additional information for done.
217type DoneInfo struct {
218 // Err is the rpc error the RPC finished with. It could be nil.
219 Err error
220 // Trailer contains the metadata from the RPC's trailer, if present.
221 Trailer metadata.MD
222 // BytesSent indicates if any bytes have been sent to the server.
223 BytesSent bool
224 // BytesReceived indicates if any byte has been received from the server.
225 BytesReceived bool
226 // ServerLoad is the load received from server. It's usually sent as part of
227 // trailing metadata.
228 //
229 // The only supported type now is *orca_v1.LoadReport.
230 ServerLoad interface{}
231}
232
233var (
234 // ErrNoSubConnAvailable indicates no SubConn is available for pick().
235 // gRPC will block the RPC until a new picker is available via UpdateBalancerState().
236 ErrNoSubConnAvailable = errors.New("no SubConn is available")
237 // ErrTransientFailure indicates all SubConns are in TransientFailure.
238 // WaitForReady RPCs will block, non-WaitForReady RPCs will fail.
Arjun E K57a7fcb2020-01-30 06:44:45 +0000239 ErrTransientFailure = TransientFailureError(errors.New("all SubConns are in TransientFailure"))
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700240)
241
242// Picker is used by gRPC to pick a SubConn to send an RPC.
243// Balancer is expected to generate a new picker from its snapshot every time its
244// internal state has changed.
245//
246// The pickers used by gRPC can be updated by ClientConn.UpdateBalancerState().
Arjun E K57a7fcb2020-01-30 06:44:45 +0000247//
248// Deprecated: use V2Picker instead
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700249type Picker interface {
250 // Pick returns the SubConn to be used to send the RPC.
251 // The returned SubConn must be one returned by NewSubConn().
252 //
253 // This functions is expected to return:
254 // - a SubConn that is known to be READY;
255 // - ErrNoSubConnAvailable if no SubConn is available, but progress is being
256 // made (for example, some SubConn is in CONNECTING mode);
257 // - other errors if no active connecting is happening (for example, all SubConn
258 // are in TRANSIENT_FAILURE mode).
259 //
260 // If a SubConn is returned:
261 // - If it is READY, gRPC will send the RPC on it;
262 // - If it is not ready, or becomes not ready after it's returned, gRPC will
263 // block until UpdateBalancerState() is called and will call pick on the
264 // new picker. The done function returned from Pick(), if not nil, will be
265 // called with nil error, no bytes sent and no bytes received.
266 //
267 // If the returned error is not nil:
268 // - If the error is ErrNoSubConnAvailable, gRPC will block until UpdateBalancerState()
Arjun E K57a7fcb2020-01-30 06:44:45 +0000269 // - If the error is ErrTransientFailure or implements IsTransientFailure()
270 // bool, returning true:
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700271 // - If the RPC is wait-for-ready, gRPC will block until UpdateBalancerState()
272 // is called to pick again;
273 // - Otherwise, RPC will fail with unavailable error.
274 // - Else (error is other non-nil error):
Arjun E K57a7fcb2020-01-30 06:44:45 +0000275 // - The RPC will fail with the error's status code, or Unknown if it is
276 // not a status error.
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700277 //
278 // The returned done() function will be called once the rpc has finished,
279 // with the final status of that RPC. If the SubConn returned is not a
280 // valid SubConn type, done may not be called. done may be nil if balancer
281 // doesn't care about the RPC status.
Arjun E K57a7fcb2020-01-30 06:44:45 +0000282 Pick(ctx context.Context, info PickInfo) (conn SubConn, done func(DoneInfo), err error)
283}
284
285// PickResult contains information related to a connection chosen for an RPC.
286type PickResult struct {
287 // SubConn is the connection to use for this pick, if its state is Ready.
288 // If the state is not Ready, gRPC will block the RPC until a new Picker is
289 // provided by the balancer (using ClientConn.UpdateState). The SubConn
290 // must be one returned by ClientConn.NewSubConn.
291 SubConn SubConn
292
293 // Done is called when the RPC is completed. If the SubConn is not ready,
294 // this will be called with a nil parameter. If the SubConn is not a valid
295 // type, Done may not be called. May be nil if the balancer does not wish
296 // to be notified when the RPC completes.
297 Done func(DoneInfo)
298}
299
300type transientFailureError struct {
301 error
302}
303
304func (e *transientFailureError) IsTransientFailure() bool { return true }
305
306// TransientFailureError wraps err in an error implementing
307// IsTransientFailure() bool, returning true.
308func TransientFailureError(err error) error {
309 return &transientFailureError{error: err}
310}
311
312// V2Picker is used by gRPC to pick a SubConn to send an RPC.
313// Balancer is expected to generate a new picker from its snapshot every time its
314// internal state has changed.
315//
316// The pickers used by gRPC can be updated by ClientConn.UpdateBalancerState().
317type V2Picker interface {
318 // Pick returns the connection to use for this RPC and related information.
319 //
320 // Pick should not block. If the balancer needs to do I/O or any blocking
321 // or time-consuming work to service this call, it should return
322 // ErrNoSubConnAvailable, and the Pick call will be repeated by gRPC when
323 // the Picker is updated (using ClientConn.UpdateState).
324 //
325 // If an error is returned:
326 //
327 // - If the error is ErrNoSubConnAvailable, gRPC will block until a new
328 // Picker is provided by the balancer (using ClientConn.UpdateState).
329 //
330 // - If the error implements IsTransientFailure() bool, returning true,
331 // wait for ready RPCs will wait, but non-wait for ready RPCs will be
332 // terminated with this error's Error() string and status code
333 // Unavailable.
334 //
335 // - Any other errors terminate all RPCs with the code and message
336 // provided. If the error is not a status error, it will be converted by
337 // gRPC to a status error with code Unknown.
338 Pick(info PickInfo) (PickResult, error)
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700339}
340
341// Balancer takes input from gRPC, manages SubConns, and collects and aggregates
342// the connectivity states.
343//
344// It also generates and updates the Picker used by gRPC to pick SubConns for RPCs.
345//
346// HandleSubConnectionStateChange, HandleResolvedAddrs and Close are guaranteed
347// to be called synchronously from the same goroutine.
348// There's no guarantee on picker.Pick, it may be called anytime.
349type Balancer interface {
350 // HandleSubConnStateChange is called by gRPC when the connectivity state
351 // of sc has changed.
352 // Balancer is expected to aggregate all the state of SubConn and report
353 // that back to gRPC.
354 // Balancer should also generate and update Pickers when its internal state has
355 // been changed by the new state.
356 //
357 // Deprecated: if V2Balancer is implemented by the Balancer,
358 // UpdateSubConnState will be called instead.
359 HandleSubConnStateChange(sc SubConn, state connectivity.State)
360 // HandleResolvedAddrs is called by gRPC to send updated resolved addresses to
361 // balancers.
362 // Balancer can create new SubConn or remove SubConn with the addresses.
363 // An empty address slice and a non-nil error will be passed if the resolver returns
364 // non-nil error to gRPC.
365 //
366 // Deprecated: if V2Balancer is implemented by the Balancer,
367 // UpdateClientConnState will be called instead.
368 HandleResolvedAddrs([]resolver.Address, error)
369 // Close closes the balancer. The balancer is not required to call
370 // ClientConn.RemoveSubConn for its existing SubConns.
371 Close()
372}
373
374// SubConnState describes the state of a SubConn.
375type SubConnState struct {
Arjun E K57a7fcb2020-01-30 06:44:45 +0000376 // ConnectivityState is the connectivity state of the SubConn.
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700377 ConnectivityState connectivity.State
Arjun E K57a7fcb2020-01-30 06:44:45 +0000378 // ConnectionError is set if the ConnectivityState is TransientFailure,
379 // describing the reason the SubConn failed. Otherwise, it is nil.
380 ConnectionError error
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700381}
382
383// ClientConnState describes the state of a ClientConn relevant to the
384// balancer.
385type ClientConnState struct {
386 ResolverState resolver.State
387 // The parsed load balancing configuration returned by the builder's
388 // ParseConfig method, if implemented.
389 BalancerConfig serviceconfig.LoadBalancingConfig
390}
391
Arjun E K57a7fcb2020-01-30 06:44:45 +0000392// ErrBadResolverState may be returned by UpdateClientConnState to indicate a
393// problem with the provided name resolver data.
394var ErrBadResolverState = errors.New("bad resolver state")
395
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700396// V2Balancer is defined for documentation purposes. If a Balancer also
397// implements V2Balancer, its UpdateClientConnState method will be called
398// instead of HandleResolvedAddrs and its UpdateSubConnState will be called
399// instead of HandleSubConnStateChange.
400type V2Balancer interface {
401 // UpdateClientConnState is called by gRPC when the state of the ClientConn
Arjun E K57a7fcb2020-01-30 06:44:45 +0000402 // changes. If the error returned is ErrBadResolverState, the ClientConn
403 // will begin calling ResolveNow on the active name resolver with
404 // exponential backoff until a subsequent call to UpdateClientConnState
405 // returns a nil error. Any other errors are currently ignored.
406 UpdateClientConnState(ClientConnState) error
407 // ResolverError is called by gRPC when the name resolver reports an error.
408 ResolverError(error)
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700409 // UpdateSubConnState is called by gRPC when the state of a SubConn
410 // changes.
411 UpdateSubConnState(SubConn, SubConnState)
412 // Close closes the balancer. The balancer is not required to call
413 // ClientConn.RemoveSubConn for its existing SubConns.
414 Close()
415}
416
417// ConnectivityStateEvaluator takes the connectivity states of multiple SubConns
418// and returns one aggregated connectivity state.
419//
420// It's not thread safe.
421type ConnectivityStateEvaluator struct {
Arjun E K57a7fcb2020-01-30 06:44:45 +0000422 numReady uint64 // Number of addrConns in ready state.
423 numConnecting uint64 // Number of addrConns in connecting state.
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700424}
425
426// RecordTransition records state change happening in subConn and based on that
427// it evaluates what aggregated state should be.
428//
429// - If at least one SubConn in Ready, the aggregated state is Ready;
430// - Else if at least one SubConn in Connecting, the aggregated state is Connecting;
431// - Else the aggregated state is TransientFailure.
432//
433// Idle and Shutdown are not considered.
434func (cse *ConnectivityStateEvaluator) RecordTransition(oldState, newState connectivity.State) connectivity.State {
435 // Update counters.
436 for idx, state := range []connectivity.State{oldState, newState} {
437 updateVal := 2*uint64(idx) - 1 // -1 for oldState and +1 for new.
438 switch state {
439 case connectivity.Ready:
440 cse.numReady += updateVal
441 case connectivity.Connecting:
442 cse.numConnecting += updateVal
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700443 }
444 }
445
446 // Evaluate.
447 if cse.numReady > 0 {
448 return connectivity.Ready
449 }
450 if cse.numConnecting > 0 {
451 return connectivity.Connecting
452 }
453 return connectivity.TransientFailure
454}