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