blob: 37ef74a100978f783e78620d9e6d1085394d0d2d [file] [log] [blame]
khenaidoo5fc5cea2021-08-11 17:39:16 -04001/*
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// A SubConn represents a single connection to a gRPC backend service.
79//
80// Each SubConn contains a list of addresses.
81//
82// All SubConns start in IDLE, and will not try to connect. To trigger the
83// connecting, Balancers must call Connect. If a connection re-enters IDLE,
84// Balancers must call Connect again to trigger a new connection attempt.
85//
86// gRPC will try to connect to the addresses in sequence, and stop trying the
87// remainder once the first connection is successful. If an attempt to connect
88// to all addresses encounters an error, the SubConn will enter
89// TRANSIENT_FAILURE for a backoff period, and then transition to IDLE.
90//
91// Once established, if a connection is lost, the SubConn will transition
92// directly to IDLE.
93//
94// This interface is to be implemented by gRPC. Users should not need their own
95// implementation of this interface. For situations like testing, any
96// implementations should embed this interface. This allows gRPC to add new
97// methods to this interface.
98type SubConn interface {
99 // UpdateAddresses updates the addresses used in this SubConn.
100 // gRPC checks if currently-connected address is still in the new list.
101 // If it's in the list, the connection will be kept.
102 // If it's not in the list, the connection will gracefully closed, and
103 // a new connection will be created.
104 //
105 // This will trigger a state transition for the SubConn.
106 //
107 // Deprecated: This method is now part of the ClientConn interface and will
108 // eventually be removed from here.
109 UpdateAddresses([]resolver.Address)
110 // Connect starts the connecting for this SubConn.
111 Connect()
112}
113
114// NewSubConnOptions contains options to create new SubConn.
115type NewSubConnOptions struct {
116 // CredsBundle is the credentials bundle that will be used in the created
117 // SubConn. If it's nil, the original creds from grpc DialOptions will be
118 // used.
119 //
120 // Deprecated: Use the Attributes field in resolver.Address to pass
121 // arbitrary data to the credential handshaker.
122 CredsBundle credentials.Bundle
123 // HealthCheckEnabled indicates whether health check service should be
124 // enabled on this SubConn
125 HealthCheckEnabled bool
126}
127
128// State contains the balancer's state relevant to the gRPC ClientConn.
129type State struct {
130 // State contains the connectivity state of the balancer, which is used to
131 // determine the state of the ClientConn.
132 ConnectivityState connectivity.State
133 // Picker is used to choose connections (SubConns) for RPCs.
134 Picker Picker
135}
136
137// ClientConn represents a gRPC ClientConn.
138//
139// This interface is to be implemented by gRPC. Users should not need a
140// brand new implementation of this interface. For the situations like
141// testing, the new implementation should embed this interface. This allows
142// gRPC to add new methods to this interface.
143type ClientConn interface {
144 // NewSubConn is called by balancer to create a new SubConn.
145 // It doesn't block and wait for the connections to be established.
146 // Behaviors of the SubConn can be controlled by options.
147 NewSubConn([]resolver.Address, NewSubConnOptions) (SubConn, error)
148 // RemoveSubConn removes the SubConn from ClientConn.
149 // The SubConn will be shutdown.
150 RemoveSubConn(SubConn)
151 // UpdateAddresses updates the addresses used in the passed in SubConn.
152 // gRPC checks if the currently connected address is still in the new list.
153 // If so, the connection will be kept. Else, the connection will be
154 // gracefully closed, and a new connection will be created.
155 //
156 // This will trigger a state transition for the SubConn.
157 UpdateAddresses(SubConn, []resolver.Address)
158
159 // UpdateState notifies gRPC that the balancer's internal state has
160 // changed.
161 //
162 // gRPC will update the connectivity state of the ClientConn, and will call
163 // Pick on the new Picker to pick new SubConns.
164 UpdateState(State)
165
166 // ResolveNow is called by balancer to notify gRPC to do a name resolving.
167 ResolveNow(resolver.ResolveNowOptions)
168
169 // Target returns the dial target for this ClientConn.
170 //
171 // Deprecated: Use the Target field in the BuildOptions instead.
172 Target() string
173}
174
175// BuildOptions contains additional information for Build.
176type BuildOptions struct {
khenaidoo257f3192021-12-15 16:46:37 -0500177 // DialCreds is the transport credentials to use when communicating with a
178 // remote load balancer server. Balancer implementations which do not
179 // communicate with a remote load balancer server can ignore this field.
khenaidoo5fc5cea2021-08-11 17:39:16 -0400180 DialCreds credentials.TransportCredentials
khenaidoo257f3192021-12-15 16:46:37 -0500181 // CredsBundle is the credentials bundle to use when communicating with a
182 // remote load balancer server. Balancer implementations which do not
183 // communicate with a remote load balancer server can ignore this field.
khenaidoo5fc5cea2021-08-11 17:39:16 -0400184 CredsBundle credentials.Bundle
khenaidoo257f3192021-12-15 16:46:37 -0500185 // Dialer is the custom dialer to use when communicating with a remote load
186 // balancer server. Balancer implementations which do not communicate with a
187 // remote load balancer server can ignore this field.
khenaidoo5fc5cea2021-08-11 17:39:16 -0400188 Dialer func(context.Context, string) (net.Conn, error)
khenaidoo257f3192021-12-15 16:46:37 -0500189 // Authority is the server name to use as part of the authentication
190 // handshake when communicating with a remote load balancer server. Balancer
191 // implementations which do not communicate with a remote load balancer
192 // server can ignore this field.
193 Authority string
194 // ChannelzParentID is the parent ClientConn's channelz ID.
khenaidoo5fc5cea2021-08-11 17:39:16 -0400195 ChannelzParentID int64
196 // CustomUserAgent is the custom user agent set on the parent ClientConn.
197 // The balancer should set the same custom user agent if it creates a
198 // ClientConn.
199 CustomUserAgent string
khenaidoo257f3192021-12-15 16:46:37 -0500200 // Target contains the parsed address info of the dial target. It is the
201 // same resolver.Target as passed to the resolver. See the documentation for
202 // the resolver.Target type for details about what it contains.
khenaidoo5fc5cea2021-08-11 17:39:16 -0400203 Target resolver.Target
204}
205
206// Builder creates a balancer.
207type Builder interface {
208 // Build creates a new balancer with the ClientConn.
209 Build(cc ClientConn, opts BuildOptions) Balancer
210 // Name returns the name of balancers built by this builder.
211 // It will be used to pick balancers (for example in service config).
212 Name() string
213}
214
215// ConfigParser parses load balancer configs.
216type ConfigParser interface {
217 // ParseConfig parses the JSON load balancer config provided into an
218 // internal form or returns an error if the config is invalid. For future
219 // compatibility reasons, unknown fields in the config should be ignored.
220 ParseConfig(LoadBalancingConfigJSON json.RawMessage) (serviceconfig.LoadBalancingConfig, error)
221}
222
223// PickInfo contains additional information for the Pick operation.
224type PickInfo struct {
225 // FullMethodName is the method name that NewClientStream() is called
226 // with. The canonical format is /service/Method.
227 FullMethodName string
228 // Ctx is the RPC's context, and may contain relevant RPC-level information
229 // like the outgoing header metadata.
230 Ctx context.Context
231}
232
233// DoneInfo contains additional information for done.
234type DoneInfo struct {
235 // Err is the rpc error the RPC finished with. It could be nil.
236 Err error
237 // Trailer contains the metadata from the RPC's trailer, if present.
238 Trailer metadata.MD
239 // BytesSent indicates if any bytes have been sent to the server.
240 BytesSent bool
241 // BytesReceived indicates if any byte has been received from the server.
242 BytesReceived bool
243 // ServerLoad is the load received from server. It's usually sent as part of
244 // trailing metadata.
245 //
246 // The only supported type now is *orca_v1.LoadReport.
247 ServerLoad interface{}
248}
249
250var (
251 // ErrNoSubConnAvailable indicates no SubConn is available for pick().
252 // gRPC will block the RPC until a new picker is available via UpdateState().
253 ErrNoSubConnAvailable = errors.New("no SubConn is available")
254 // ErrTransientFailure indicates all SubConns are in TransientFailure.
255 // WaitForReady RPCs will block, non-WaitForReady RPCs will fail.
256 //
257 // Deprecated: return an appropriate error based on the last resolution or
258 // connection attempt instead. The behavior is the same for any non-gRPC
259 // status error.
260 ErrTransientFailure = errors.New("all SubConns are in TransientFailure")
261)
262
263// PickResult contains information related to a connection chosen for an RPC.
264type PickResult struct {
265 // SubConn is the connection to use for this pick, if its state is Ready.
266 // If the state is not Ready, gRPC will block the RPC until a new Picker is
267 // provided by the balancer (using ClientConn.UpdateState). The SubConn
268 // must be one returned by ClientConn.NewSubConn.
269 SubConn SubConn
270
271 // Done is called when the RPC is completed. If the SubConn is not ready,
272 // this will be called with a nil parameter. If the SubConn is not a valid
273 // type, Done may not be called. May be nil if the balancer does not wish
274 // to be notified when the RPC completes.
275 Done func(DoneInfo)
276}
277
278// TransientFailureError returns e. It exists for backward compatibility and
279// will be deleted soon.
280//
281// Deprecated: no longer necessary, picker errors are treated this way by
282// default.
283func TransientFailureError(e error) error { return e }
284
285// Picker is used by gRPC to pick a SubConn to send an RPC.
286// Balancer is expected to generate a new picker from its snapshot every time its
287// internal state has changed.
288//
289// The pickers used by gRPC can be updated by ClientConn.UpdateState().
290type Picker interface {
291 // Pick returns the connection to use for this RPC and related information.
292 //
293 // Pick should not block. If the balancer needs to do I/O or any blocking
294 // or time-consuming work to service this call, it should return
295 // ErrNoSubConnAvailable, and the Pick call will be repeated by gRPC when
296 // the Picker is updated (using ClientConn.UpdateState).
297 //
298 // If an error is returned:
299 //
300 // - If the error is ErrNoSubConnAvailable, gRPC will block until a new
301 // Picker is provided by the balancer (using ClientConn.UpdateState).
302 //
303 // - If the error is a status error (implemented by the grpc/status
304 // package), gRPC will terminate the RPC with the code and message
305 // provided.
306 //
307 // - For all other errors, wait for ready RPCs will wait, but non-wait for
308 // ready RPCs will be terminated with this error's Error() string and
309 // status code Unavailable.
310 Pick(info PickInfo) (PickResult, error)
311}
312
313// Balancer takes input from gRPC, manages SubConns, and collects and aggregates
314// the connectivity states.
315//
316// It also generates and updates the Picker used by gRPC to pick SubConns for RPCs.
317//
318// UpdateClientConnState, ResolverError, UpdateSubConnState, and Close are
319// guaranteed to be called synchronously from the same goroutine. There's no
320// guarantee on picker.Pick, it may be called anytime.
321type Balancer interface {
322 // UpdateClientConnState is called by gRPC when the state of the ClientConn
323 // changes. If the error returned is ErrBadResolverState, the ClientConn
324 // will begin calling ResolveNow on the active name resolver with
325 // exponential backoff until a subsequent call to UpdateClientConnState
326 // returns a nil error. Any other errors are currently ignored.
327 UpdateClientConnState(ClientConnState) error
328 // ResolverError is called by gRPC when the name resolver reports an error.
329 ResolverError(error)
330 // UpdateSubConnState is called by gRPC when the state of a SubConn
331 // changes.
332 UpdateSubConnState(SubConn, SubConnState)
333 // Close closes the balancer. The balancer is not required to call
334 // ClientConn.RemoveSubConn for its existing SubConns.
335 Close()
336}
337
338// ExitIdler is an optional interface for balancers to implement. If
339// implemented, ExitIdle will be called when ClientConn.Connect is called, if
340// the ClientConn is idle. If unimplemented, ClientConn.Connect will cause
341// all SubConns to connect.
342//
343// Notice: it will be required for all balancers to implement this in a future
344// release.
345type ExitIdler interface {
346 // ExitIdle instructs the LB policy to reconnect to backends / exit the
347 // IDLE state, if appropriate and possible. Note that SubConns that enter
348 // the IDLE state will not reconnect until SubConn.Connect is called.
349 ExitIdle()
350}
351
352// SubConnState describes the state of a SubConn.
353type SubConnState struct {
354 // ConnectivityState is the connectivity state of the SubConn.
355 ConnectivityState connectivity.State
356 // ConnectionError is set if the ConnectivityState is TransientFailure,
357 // describing the reason the SubConn failed. Otherwise, it is nil.
358 ConnectionError error
359}
360
361// ClientConnState describes the state of a ClientConn relevant to the
362// balancer.
363type ClientConnState struct {
364 ResolverState resolver.State
365 // The parsed load balancing configuration returned by the builder's
366 // ParseConfig method, if implemented.
367 BalancerConfig serviceconfig.LoadBalancingConfig
368}
369
370// ErrBadResolverState may be returned by UpdateClientConnState to indicate a
371// problem with the provided name resolver data.
372var ErrBadResolverState = errors.New("bad resolver state")
373
374// ConnectivityStateEvaluator takes the connectivity states of multiple SubConns
375// and returns one aggregated connectivity state.
376//
377// It's not thread safe.
378type ConnectivityStateEvaluator struct {
379 numReady uint64 // Number of addrConns in ready state.
380 numConnecting uint64 // Number of addrConns in connecting state.
381 numTransientFailure uint64 // Number of addrConns in transient failure state.
382 numIdle uint64 // Number of addrConns in idle state.
383}
384
385// RecordTransition records state change happening in subConn and based on that
386// it evaluates what aggregated state should be.
387//
Joey Armstrongba3d9d12024-01-15 14:22:11 -0500388// - If at least one SubConn in Ready, the aggregated state is Ready;
389// - Else if at least one SubConn in Connecting, the aggregated state is Connecting;
390// - Else if at least one SubConn is TransientFailure, the aggregated state is Transient Failure;
391// - Else if at least one SubConn is Idle, the aggregated state is Idle;
392// - Else there are no subconns and the aggregated state is Transient Failure
khenaidoo5fc5cea2021-08-11 17:39:16 -0400393//
394// Shutdown is not considered.
395func (cse *ConnectivityStateEvaluator) RecordTransition(oldState, newState connectivity.State) connectivity.State {
396 // Update counters.
397 for idx, state := range []connectivity.State{oldState, newState} {
398 updateVal := 2*uint64(idx) - 1 // -1 for oldState and +1 for new.
399 switch state {
400 case connectivity.Ready:
401 cse.numReady += updateVal
402 case connectivity.Connecting:
403 cse.numConnecting += updateVal
404 case connectivity.TransientFailure:
405 cse.numTransientFailure += updateVal
406 case connectivity.Idle:
407 cse.numIdle += updateVal
408 }
409 }
410
411 // Evaluate.
412 if cse.numReady > 0 {
413 return connectivity.Ready
414 }
415 if cse.numConnecting > 0 {
416 return connectivity.Connecting
417 }
418 if cse.numTransientFailure > 0 {
419 return connectivity.TransientFailure
420 }
421 if cse.numIdle > 0 {
422 return connectivity.Idle
423 }
424 return connectivity.TransientFailure
425}