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.
 21package balancer
 22
 23import (
 24	"context"
 25	"encoding/json"
 26	"errors"
 27	"net"
 28	"strings"
 29
 30	"google.golang.org/grpc/channelz"
 31	"google.golang.org/grpc/connectivity"
 32	"google.golang.org/grpc/credentials"
 33	estats "google.golang.org/grpc/experimental/stats"
 34	"google.golang.org/grpc/grpclog"
 35	"google.golang.org/grpc/internal"
 36	"google.golang.org/grpc/metadata"
 37	"google.golang.org/grpc/resolver"
 38	"google.golang.org/grpc/serviceconfig"
 39)
 40
 41var (
 42	// m is a map from name to balancer builder.
 43	m = make(map[string]Builder)
 44
 45	logger = grpclog.Component("balancer")
 46)
 47
 48// Register registers the balancer builder to the balancer map. b.Name
 49// (lowercased) will be used as the name registered with this builder.  If the
 50// Builder implements ConfigParser, ParseConfig will be called when new service
 51// configs are received by the resolver, and the result will be provided to the
 52// Balancer in UpdateClientConnState.
 53//
 54// NOTE: this function must only be called during initialization time (i.e. in
 55// an init() function), and is not thread-safe. If multiple Balancers are
 56// registered with the same name, the one registered last will take effect.
 57func Register(b Builder) {
 58	name := strings.ToLower(b.Name())
 59	if name != b.Name() {
 60		// TODO: Skip the use of strings.ToLower() to index the map after v1.59
 61		// is released to switch to case sensitive balancer registry. Also,
 62		// remove this warning and update the docstrings for Register and Get.
 63		logger.Warningf("Balancer registered with name %q. grpc-go will be switching to case sensitive balancer registries soon", b.Name())
 64	}
 65	m[name] = b
 66}
 67
 68// unregisterForTesting deletes the balancer with the given name from the
 69// balancer map.
 70//
 71// This function is not thread-safe.
 72func unregisterForTesting(name string) {
 73	delete(m, name)
 74}
 75
 76func init() {
 77	internal.BalancerUnregister = unregisterForTesting
 78	internal.ConnectedAddress = connectedAddress
 79	internal.SetConnectedAddress = setConnectedAddress
 80}
 81
 82// Get returns the resolver builder registered with the given name.
 83// Note that the compare is done in a case-insensitive fashion.
 84// If no builder is register with the name, nil will be returned.
 85func Get(name string) Builder {
 86	if strings.ToLower(name) != name {
 87		// TODO: Skip the use of strings.ToLower() to index the map after v1.59
 88		// is released to switch to case sensitive balancer registry. Also,
 89		// remove this warning and update the docstrings for Register and Get.
 90		logger.Warningf("Balancer retrieved for name %q. grpc-go will be switching to case sensitive balancer registries soon", name)
 91	}
 92	if b, ok := m[strings.ToLower(name)]; ok {
 93		return b
 94	}
 95	return nil
 96}
 97
 98// NewSubConnOptions contains options to create new SubConn.
 99type NewSubConnOptions struct {
100	// CredsBundle is the credentials bundle that will be used in the created
101	// SubConn. If it's nil, the original creds from grpc DialOptions will be
102	// used.
103	//
104	// Deprecated: Use the Attributes field in resolver.Address to pass
105	// arbitrary data to the credential handshaker.
106	CredsBundle credentials.Bundle
107	// HealthCheckEnabled indicates whether health check service should be
108	// enabled on this SubConn
109	HealthCheckEnabled bool
110	// StateListener is called when the state of the subconn changes.  If nil,
111	// Balancer.UpdateSubConnState will be called instead.  Will never be
112	// invoked until after Connect() is called on the SubConn created with
113	// these options.
114	StateListener func(SubConnState)
115}
116
117// State contains the balancer's state relevant to the gRPC ClientConn.
118type State struct {
119	// State contains the connectivity state of the balancer, which is used to
120	// determine the state of the ClientConn.
121	ConnectivityState connectivity.State
122	// Picker is used to choose connections (SubConns) for RPCs.
123	Picker Picker
124}
125
126// ClientConn represents a gRPC ClientConn.
127//
128// This interface is to be implemented by gRPC. Users should not need a
129// brand new implementation of this interface. For the situations like
130// testing, the new implementation should embed this interface. This allows
131// gRPC to add new methods to this interface.
132//
133// NOTICE: This interface is intended to be implemented by gRPC, or intercepted
134// by custom load balancing polices.  Users should not need their own complete
135// implementation of this interface -- they should always delegate to a
136// ClientConn passed to Builder.Build() by embedding it in their
137// implementations. An embedded ClientConn must never be nil, or runtime panics
138// will occur.
139type ClientConn interface {
140	// NewSubConn is called by balancer to create a new SubConn.
141	// It doesn't block and wait for the connections to be established.
142	// Behaviors of the SubConn can be controlled by options.
143	//
144	// Deprecated: please be aware that in a future version, SubConns will only
145	// support one address per SubConn.
146	NewSubConn([]resolver.Address, NewSubConnOptions) (SubConn, error)
147	// RemoveSubConn removes the SubConn from ClientConn.
148	// The SubConn will be shutdown.
149	//
150	// Deprecated: use SubConn.Shutdown instead.
151	RemoveSubConn(SubConn)
152	// UpdateAddresses updates the addresses used in the passed in SubConn.
153	// gRPC checks if the currently connected address is still in the new list.
154	// If so, the connection will be kept. Else, the connection will be
155	// gracefully closed, and a new connection will be created.
156	//
157	// This may trigger a state transition for the SubConn.
158	//
159	// Deprecated: this method will be removed.  Create new SubConns for new
160	// addresses instead.
161	UpdateAddresses(SubConn, []resolver.Address)
162
163	// UpdateState notifies gRPC that the balancer's internal state has
164	// changed.
165	//
166	// gRPC will update the connectivity state of the ClientConn, and will call
167	// Pick on the new Picker to pick new SubConns.
168	UpdateState(State)
169
170	// ResolveNow is called by balancer to notify gRPC to do a name resolving.
171	ResolveNow(resolver.ResolveNowOptions)
172
173	// Target returns the dial target for this ClientConn.
174	//
175	// Deprecated: Use the Target field in the BuildOptions instead.
176	Target() string
177
178	// MetricsRecorder provides the metrics recorder that balancers can use to
179	// record metrics. Balancer implementations which do not register metrics on
180	// metrics registry and record on them can ignore this method. The returned
181	// MetricsRecorder is guaranteed to never be nil.
182	MetricsRecorder() estats.MetricsRecorder
183
184	// EnforceClientConnEmbedding is included to force implementers to embed
185	// another implementation of this interface, allowing gRPC to add methods
186	// without breaking users.
187	internal.EnforceClientConnEmbedding
188}
189
190// BuildOptions contains additional information for Build.
191type BuildOptions struct {
192	// DialCreds is the transport credentials to use when communicating with a
193	// remote load balancer server. Balancer implementations which do not
194	// communicate with a remote load balancer server can ignore this field.
195	DialCreds credentials.TransportCredentials
196	// CredsBundle is the credentials bundle to use when communicating with a
197	// remote load balancer server. Balancer implementations which do not
198	// communicate with a remote load balancer server can ignore this field.
199	CredsBundle credentials.Bundle
200	// Dialer is the custom dialer to use when communicating with a remote load
201	// balancer server. Balancer implementations which do not communicate with a
202	// remote load balancer server can ignore this field.
203	Dialer func(context.Context, string) (net.Conn, error)
204	// Authority is the server name to use as part of the authentication
205	// handshake when communicating with a remote load balancer server. Balancer
206	// implementations which do not communicate with a remote load balancer
207	// server can ignore this field.
208	Authority string
209	// ChannelzParent is the parent ClientConn's channelz channel.
210	ChannelzParent channelz.Identifier
211	// CustomUserAgent is the custom user agent set on the parent ClientConn.
212	// The balancer should set the same custom user agent if it creates a
213	// ClientConn.
214	CustomUserAgent string
215	// Target contains the parsed address info of the dial target. It is the
216	// same resolver.Target as passed to the resolver. See the documentation for
217	// the resolver.Target type for details about what it contains.
218	Target resolver.Target
219}
220
221// Builder creates a balancer.
222type Builder interface {
223	// Build creates a new balancer with the ClientConn.
224	Build(cc ClientConn, opts BuildOptions) Balancer
225	// Name returns the name of balancers built by this builder.
226	// It will be used to pick balancers (for example in service config).
227	Name() string
228}
229
230// ConfigParser parses load balancer configs.
231type ConfigParser interface {
232	// ParseConfig parses the JSON load balancer config provided into an
233	// internal form or returns an error if the config is invalid.  For future
234	// compatibility reasons, unknown fields in the config should be ignored.
235	ParseConfig(LoadBalancingConfigJSON json.RawMessage) (serviceconfig.LoadBalancingConfig, error)
236}
237
238// PickInfo contains additional information for the Pick operation.
239type PickInfo struct {
240	// FullMethodName is the method name that NewClientStream() is called
241	// with. The canonical format is /service/Method.
242	FullMethodName string
243	// Ctx is the RPC's context, and may contain relevant RPC-level information
244	// like the outgoing header metadata.
245	Ctx context.Context
246}
247
248// DoneInfo contains additional information for done.
249type DoneInfo struct {
250	// Err is the rpc error the RPC finished with. It could be nil.
251	Err error
252	// Trailer contains the metadata from the RPC's trailer, if present.
253	Trailer metadata.MD
254	// BytesSent indicates if any bytes have been sent to the server.
255	BytesSent bool
256	// BytesReceived indicates if any byte has been received from the server.
257	BytesReceived bool
258	// ServerLoad is the load received from server. It's usually sent as part of
259	// trailing metadata.
260	//
261	// The only supported type now is *orca_v3.LoadReport.
262	ServerLoad any
263}
264
265var (
266	// ErrNoSubConnAvailable indicates no SubConn is available for pick().
267	// gRPC will block the RPC until a new picker is available via UpdateState().
268	ErrNoSubConnAvailable = errors.New("no SubConn is available")
269	// ErrTransientFailure indicates all SubConns are in TransientFailure.
270	// WaitForReady RPCs will block, non-WaitForReady RPCs will fail.
271	//
272	// Deprecated: return an appropriate error based on the last resolution or
273	// connection attempt instead.  The behavior is the same for any non-gRPC
274	// status error.
275	ErrTransientFailure = errors.New("all SubConns are in TransientFailure")
276)
277
278// PickResult contains information related to a connection chosen for an RPC.
279type PickResult struct {
280	// SubConn is the connection to use for this pick, if its state is Ready.
281	// If the state is not Ready, gRPC will block the RPC until a new Picker is
282	// provided by the balancer (using ClientConn.UpdateState).  The SubConn
283	// must be one returned by ClientConn.NewSubConn.
284	SubConn SubConn
285
286	// Done is called when the RPC is completed.  If the SubConn is not ready,
287	// this will be called with a nil parameter.  If the SubConn is not a valid
288	// type, Done may not be called.  May be nil if the balancer does not wish
289	// to be notified when the RPC completes.
290	Done func(DoneInfo)
291
292	// Metadata provides a way for LB policies to inject arbitrary per-call
293	// metadata. Any metadata returned here will be merged with existing
294	// metadata added by the client application.
295	//
296	// LB policies with child policies are responsible for propagating metadata
297	// injected by their children to the ClientConn, as part of Pick().
298	Metadata metadata.MD
299}
300
301// TransientFailureError returns e.  It exists for backward compatibility and
302// will be deleted soon.
303//
304// Deprecated: no longer necessary, picker errors are treated this way by
305// default.
306func TransientFailureError(e error) error { return e }
307
308// Picker is used by gRPC to pick a SubConn to send an RPC.
309// Balancer is expected to generate a new picker from its snapshot every time its
310// internal state has changed.
311//
312// The pickers used by gRPC can be updated by ClientConn.UpdateState().
313type Picker interface {
314	// Pick returns the connection to use for this RPC and related information.
315	//
316	// Pick should not block.  If the balancer needs to do I/O or any blocking
317	// or time-consuming work to service this call, it should return
318	// ErrNoSubConnAvailable, and the Pick call will be repeated by gRPC when
319	// the Picker is updated (using ClientConn.UpdateState).
320	//
321	// If an error is returned:
322	//
323	// - If the error is ErrNoSubConnAvailable, gRPC will block until a new
324	//   Picker is provided by the balancer (using ClientConn.UpdateState).
325	//
326	// - If the error is a status error (implemented by the grpc/status
327	//   package), gRPC will terminate the RPC with the code and message
328	//   provided.
329	//
330	// - For all other errors, wait for ready RPCs will wait, but non-wait for
331	//   ready RPCs will be terminated with this error's Error() string and
332	//   status code Unavailable.
333	Pick(info PickInfo) (PickResult, error)
334}
335
336// Balancer takes input from gRPC, manages SubConns, and collects and aggregates
337// the connectivity states.
338//
339// It also generates and updates the Picker used by gRPC to pick SubConns for RPCs.
340//
341// UpdateClientConnState, ResolverError, UpdateSubConnState, and Close are
342// guaranteed to be called synchronously from the same goroutine.  There's no
343// guarantee on picker.Pick, it may be called anytime.
344type Balancer interface {
345	// UpdateClientConnState is called by gRPC when the state of the ClientConn
346	// changes.  If the error returned is ErrBadResolverState, the ClientConn
347	// will begin calling ResolveNow on the active name resolver with
348	// exponential backoff until a subsequent call to UpdateClientConnState
349	// returns a nil error.  Any other errors are currently ignored.
350	UpdateClientConnState(ClientConnState) error
351	// ResolverError is called by gRPC when the name resolver reports an error.
352	ResolverError(error)
353	// UpdateSubConnState is called by gRPC when the state of a SubConn
354	// changes.
355	//
356	// Deprecated: Use NewSubConnOptions.StateListener when creating the
357	// SubConn instead.
358	UpdateSubConnState(SubConn, SubConnState)
359	// Close closes the balancer. The balancer is not currently required to
360	// call SubConn.Shutdown for its existing SubConns; however, this will be
361	// required in a future release, so it is recommended.
362	Close()
363}
364
365// ExitIdler is an optional interface for balancers to implement.  If
366// implemented, ExitIdle will be called when ClientConn.Connect is called, if
367// the ClientConn is idle.  If unimplemented, ClientConn.Connect will cause
368// all SubConns to connect.
369//
370// Notice: it will be required for all balancers to implement this in a future
371// release.
372type ExitIdler interface {
373	// ExitIdle instructs the LB policy to reconnect to backends / exit the
374	// IDLE state, if appropriate and possible.  Note that SubConns that enter
375	// the IDLE state will not reconnect until SubConn.Connect is called.
376	ExitIdle()
377}
378
379// ClientConnState describes the state of a ClientConn relevant to the
380// balancer.
381type ClientConnState struct {
382	ResolverState resolver.State
383	// The parsed load balancing configuration returned by the builder's
384	// ParseConfig method, if implemented.
385	BalancerConfig serviceconfig.LoadBalancingConfig
386}
387
388// ErrBadResolverState may be returned by UpdateClientConnState to indicate a
389// problem with the provided name resolver data.
390var ErrBadResolverState = errors.New("bad resolver state")