Updating to latest protos and device-management interface, releasing 2.0
Change-Id: I2d2ebf5b305d6d06b8d01c49d4d67e7ff050f5d4
diff --git a/vendor/google.golang.org/grpc/balancer/balancer.go b/vendor/google.golang.org/grpc/balancer/balancer.go
index 9258858..bcc6f54 100644
--- a/vendor/google.golang.org/grpc/balancer/balancer.go
+++ b/vendor/google.golang.org/grpc/balancer/balancer.go
@@ -75,24 +75,26 @@
return nil
}
-// SubConn represents a gRPC sub connection.
-// Each sub connection contains a list of addresses. gRPC will
-// try to connect to them (in sequence), and stop trying the
-// remainder once one connection is successful.
+// A SubConn represents a single connection to a gRPC backend service.
//
-// The reconnect backoff will be applied on the list, not a single address.
-// For example, try_on_all_addresses -> backoff -> try_on_all_addresses.
+// Each SubConn contains a list of addresses.
//
-// All SubConns start in IDLE, and will not try to connect. To trigger
-// the connecting, Balancers must call Connect.
-// When the connection encounters an error, it will reconnect immediately.
-// When the connection becomes IDLE, it will not reconnect unless Connect is
-// called.
+// All SubConns start in IDLE, and will not try to connect. To trigger the
+// connecting, Balancers must call Connect. If a connection re-enters IDLE,
+// Balancers must call Connect again to trigger a new connection attempt.
//
-// This interface is to be implemented by gRPC. Users should not need a
-// brand new implementation of this interface. For the situations like
-// testing, the new implementation should embed this interface. This allows
-// gRPC to add new methods to this interface.
+// gRPC will try to connect to the addresses in sequence, and stop trying the
+// remainder once the first connection is successful. If an attempt to connect
+// to all addresses encounters an error, the SubConn will enter
+// TRANSIENT_FAILURE for a backoff period, and then transition to IDLE.
+//
+// Once established, if a connection is lost, the SubConn will transition
+// directly to IDLE.
+//
+// This interface is to be implemented by gRPC. Users should not need their own
+// implementation of this interface. For situations like testing, any
+// implementations should embed this interface. This allows gRPC to add new
+// methods to this interface.
type SubConn interface {
// UpdateAddresses updates the addresses used in this SubConn.
// gRPC checks if currently-connected address is still in the new list.
@@ -101,6 +103,9 @@
// a new connection will be created.
//
// This will trigger a state transition for the SubConn.
+ //
+ // Deprecated: This method is now part of the ClientConn interface and will
+ // eventually be removed from here.
UpdateAddresses([]resolver.Address)
// Connect starts the connecting for this SubConn.
Connect()
@@ -111,6 +116,9 @@
// CredsBundle is the credentials bundle that will be used in the created
// SubConn. If it's nil, the original creds from grpc DialOptions will be
// used.
+ //
+ // Deprecated: Use the Attributes field in resolver.Address to pass
+ // arbitrary data to the credential handshaker.
CredsBundle credentials.Bundle
// HealthCheckEnabled indicates whether health check service should be
// enabled on this SubConn
@@ -123,7 +131,7 @@
// determine the state of the ClientConn.
ConnectivityState connectivity.State
// Picker is used to choose connections (SubConns) for RPCs.
- Picker V2Picker
+ Picker Picker
}
// ClientConn represents a gRPC ClientConn.
@@ -140,21 +148,19 @@
// RemoveSubConn removes the SubConn from ClientConn.
// The SubConn will be shutdown.
RemoveSubConn(SubConn)
-
- // UpdateBalancerState is called by balancer to notify gRPC that some internal
- // state in balancer has changed.
+ // UpdateAddresses updates the addresses used in the passed in SubConn.
+ // gRPC checks if the currently connected address is still in the new list.
+ // If so, the connection will be kept. Else, the connection will be
+ // gracefully closed, and a new connection will be created.
//
- // gRPC will update the connectivity state of the ClientConn, and will call pick
- // on the new picker to pick new SubConn.
- //
- // Deprecated: use UpdateState instead
- UpdateBalancerState(s connectivity.State, p Picker)
+ // This will trigger a state transition for the SubConn.
+ UpdateAddresses(SubConn, []resolver.Address)
// UpdateState notifies gRPC that the balancer's internal state has
// changed.
//
- // gRPC will update the connectivity state of the ClientConn, and will call pick
- // on the new picker to pick new SubConns.
+ // gRPC will update the connectivity state of the ClientConn, and will call
+ // Pick on the new Picker to pick new SubConns.
UpdateState(State)
// ResolveNow is called by balancer to notify gRPC to do a name resolving.
@@ -168,21 +174,32 @@
// BuildOptions contains additional information for Build.
type BuildOptions struct {
- // DialCreds is the transport credential the Balancer implementation can
- // use to dial to a remote load balancer server. The Balancer implementations
- // can ignore this if it does not need to talk to another party securely.
+ // DialCreds is the transport credentials to use when communicating with a
+ // remote load balancer server. Balancer implementations which do not
+ // communicate with a remote load balancer server can ignore this field.
DialCreds credentials.TransportCredentials
- // CredsBundle is the credentials bundle that the Balancer can use.
+ // CredsBundle is the credentials bundle to use when communicating with a
+ // remote load balancer server. Balancer implementations which do not
+ // communicate with a remote load balancer server can ignore this field.
CredsBundle credentials.Bundle
- // Dialer is the custom dialer the Balancer implementation can use to dial
- // to a remote load balancer server. The Balancer implementations
- // can ignore this if it doesn't need to talk to remote balancer.
+ // Dialer is the custom dialer to use when communicating with a remote load
+ // balancer server. Balancer implementations which do not communicate with a
+ // remote load balancer server can ignore this field.
Dialer func(context.Context, string) (net.Conn, error)
- // ChannelzParentID is the entity parent's channelz unique identification number.
+ // Authority is the server name to use as part of the authentication
+ // handshake when communicating with a remote load balancer server. Balancer
+ // implementations which do not communicate with a remote load balancer
+ // server can ignore this field.
+ Authority string
+ // ChannelzParentID is the parent ClientConn's channelz ID.
ChannelzParentID int64
- // Target contains the parsed address info of the dial target. It is the same resolver.Target as
- // passed to the resolver.
- // See the documentation for the resolver.Target type for details about what it contains.
+ // CustomUserAgent is the custom user agent set on the parent ClientConn.
+ // The balancer should set the same custom user agent if it creates a
+ // ClientConn.
+ CustomUserAgent string
+ // Target contains the parsed address info of the dial target. It is the
+ // same resolver.Target as passed to the resolver. See the documentation for
+ // the resolver.Target type for details about what it contains.
Target resolver.Target
}
@@ -232,56 +249,17 @@
var (
// ErrNoSubConnAvailable indicates no SubConn is available for pick().
- // gRPC will block the RPC until a new picker is available via UpdateBalancerState().
+ // gRPC will block the RPC until a new picker is available via UpdateState().
ErrNoSubConnAvailable = errors.New("no SubConn is available")
// ErrTransientFailure indicates all SubConns are in TransientFailure.
// WaitForReady RPCs will block, non-WaitForReady RPCs will fail.
- ErrTransientFailure = TransientFailureError(errors.New("all SubConns are in TransientFailure"))
+ //
+ // Deprecated: return an appropriate error based on the last resolution or
+ // connection attempt instead. The behavior is the same for any non-gRPC
+ // status error.
+ ErrTransientFailure = errors.New("all SubConns are in TransientFailure")
)
-// Picker is used by gRPC to pick a SubConn to send an RPC.
-// Balancer is expected to generate a new picker from its snapshot every time its
-// internal state has changed.
-//
-// The pickers used by gRPC can be updated by ClientConn.UpdateBalancerState().
-//
-// Deprecated: use V2Picker instead
-type Picker interface {
- // Pick returns the SubConn to be used to send the RPC.
- // The returned SubConn must be one returned by NewSubConn().
- //
- // This functions is expected to return:
- // - a SubConn that is known to be READY;
- // - ErrNoSubConnAvailable if no SubConn is available, but progress is being
- // made (for example, some SubConn is in CONNECTING mode);
- // - other errors if no active connecting is happening (for example, all SubConn
- // are in TRANSIENT_FAILURE mode).
- //
- // If a SubConn is returned:
- // - If it is READY, gRPC will send the RPC on it;
- // - If it is not ready, or becomes not ready after it's returned, gRPC will
- // block until UpdateBalancerState() is called and will call pick on the
- // new picker. The done function returned from Pick(), if not nil, will be
- // called with nil error, no bytes sent and no bytes received.
- //
- // If the returned error is not nil:
- // - If the error is ErrNoSubConnAvailable, gRPC will block until UpdateBalancerState()
- // - If the error is ErrTransientFailure or implements IsTransientFailure()
- // bool, returning true:
- // - If the RPC is wait-for-ready, gRPC will block until UpdateBalancerState()
- // is called to pick again;
- // - Otherwise, RPC will fail with unavailable error.
- // - Else (error is other non-nil error):
- // - The RPC will fail with the error's status code, or Unknown if it is
- // not a status error.
- //
- // The returned done() function will be called once the rpc has finished,
- // with the final status of that RPC. If the SubConn returned is not a
- // valid SubConn type, done may not be called. done may be nil if balancer
- // doesn't care about the RPC status.
- Pick(ctx context.Context, info PickInfo) (conn SubConn, done func(DoneInfo), err error)
-}
-
// PickResult contains information related to a connection chosen for an RPC.
type PickResult struct {
// SubConn is the connection to use for this pick, if its state is Ready.
@@ -297,24 +275,19 @@
Done func(DoneInfo)
}
-type transientFailureError struct {
- error
-}
+// TransientFailureError returns e. It exists for backward compatibility and
+// will be deleted soon.
+//
+// Deprecated: no longer necessary, picker errors are treated this way by
+// default.
+func TransientFailureError(e error) error { return e }
-func (e *transientFailureError) IsTransientFailure() bool { return true }
-
-// TransientFailureError wraps err in an error implementing
-// IsTransientFailure() bool, returning true.
-func TransientFailureError(err error) error {
- return &transientFailureError{error: err}
-}
-
-// V2Picker is used by gRPC to pick a SubConn to send an RPC.
+// Picker is used by gRPC to pick a SubConn to send an RPC.
// Balancer is expected to generate a new picker from its snapshot every time its
// internal state has changed.
//
-// The pickers used by gRPC can be updated by ClientConn.UpdateBalancerState().
-type V2Picker interface {
+// The pickers used by gRPC can be updated by ClientConn.UpdateState().
+type Picker interface {
// Pick returns the connection to use for this RPC and related information.
//
// Pick should not block. If the balancer needs to do I/O or any blocking
@@ -327,14 +300,13 @@
// - If the error is ErrNoSubConnAvailable, gRPC will block until a new
// Picker is provided by the balancer (using ClientConn.UpdateState).
//
- // - If the error implements IsTransientFailure() bool, returning true,
- // wait for ready RPCs will wait, but non-wait for ready RPCs will be
- // terminated with this error's Error() string and status code
- // Unavailable.
+ // - If the error is a status error (implemented by the grpc/status
+ // package), gRPC will terminate the RPC with the code and message
+ // provided.
//
- // - Any other errors terminate all RPCs with the code and message
- // provided. If the error is not a status error, it will be converted by
- // gRPC to a status error with code Unknown.
+ // - For all other errors, wait for ready RPCs will wait, but non-wait for
+ // ready RPCs will be terminated with this error's Error() string and
+ // status code Unavailable.
Pick(info PickInfo) (PickResult, error)
}
@@ -343,34 +315,40 @@
//
// It also generates and updates the Picker used by gRPC to pick SubConns for RPCs.
//
-// HandleSubConnectionStateChange, HandleResolvedAddrs and Close are guaranteed
-// to be called synchronously from the same goroutine.
-// There's no guarantee on picker.Pick, it may be called anytime.
+// UpdateClientConnState, ResolverError, UpdateSubConnState, and Close are
+// guaranteed to be called synchronously from the same goroutine. There's no
+// guarantee on picker.Pick, it may be called anytime.
type Balancer interface {
- // HandleSubConnStateChange is called by gRPC when the connectivity state
- // of sc has changed.
- // Balancer is expected to aggregate all the state of SubConn and report
- // that back to gRPC.
- // Balancer should also generate and update Pickers when its internal state has
- // been changed by the new state.
- //
- // Deprecated: if V2Balancer is implemented by the Balancer,
- // UpdateSubConnState will be called instead.
- HandleSubConnStateChange(sc SubConn, state connectivity.State)
- // HandleResolvedAddrs is called by gRPC to send updated resolved addresses to
- // balancers.
- // Balancer can create new SubConn or remove SubConn with the addresses.
- // An empty address slice and a non-nil error will be passed if the resolver returns
- // non-nil error to gRPC.
- //
- // Deprecated: if V2Balancer is implemented by the Balancer,
- // UpdateClientConnState will be called instead.
- HandleResolvedAddrs([]resolver.Address, error)
+ // UpdateClientConnState is called by gRPC when the state of the ClientConn
+ // changes. If the error returned is ErrBadResolverState, the ClientConn
+ // will begin calling ResolveNow on the active name resolver with
+ // exponential backoff until a subsequent call to UpdateClientConnState
+ // returns a nil error. Any other errors are currently ignored.
+ UpdateClientConnState(ClientConnState) error
+ // ResolverError is called by gRPC when the name resolver reports an error.
+ ResolverError(error)
+ // UpdateSubConnState is called by gRPC when the state of a SubConn
+ // changes.
+ UpdateSubConnState(SubConn, SubConnState)
// Close closes the balancer. The balancer is not required to call
// ClientConn.RemoveSubConn for its existing SubConns.
Close()
}
+// ExitIdler is an optional interface for balancers to implement. If
+// implemented, ExitIdle will be called when ClientConn.Connect is called, if
+// the ClientConn is idle. If unimplemented, ClientConn.Connect will cause
+// all SubConns to connect.
+//
+// Notice: it will be required for all balancers to implement this in a future
+// release.
+type ExitIdler interface {
+ // ExitIdle instructs the LB policy to reconnect to backends / exit the
+ // IDLE state, if appropriate and possible. Note that SubConns that enter
+ // the IDLE state will not reconnect until SubConn.Connect is called.
+ ExitIdle()
+}
+
// SubConnState describes the state of a SubConn.
type SubConnState struct {
// ConnectivityState is the connectivity state of the SubConn.
@@ -393,34 +371,15 @@
// problem with the provided name resolver data.
var ErrBadResolverState = errors.New("bad resolver state")
-// V2Balancer is defined for documentation purposes. If a Balancer also
-// implements V2Balancer, its UpdateClientConnState method will be called
-// instead of HandleResolvedAddrs and its UpdateSubConnState will be called
-// instead of HandleSubConnStateChange.
-type V2Balancer interface {
- // UpdateClientConnState is called by gRPC when the state of the ClientConn
- // changes. If the error returned is ErrBadResolverState, the ClientConn
- // will begin calling ResolveNow on the active name resolver with
- // exponential backoff until a subsequent call to UpdateClientConnState
- // returns a nil error. Any other errors are currently ignored.
- UpdateClientConnState(ClientConnState) error
- // ResolverError is called by gRPC when the name resolver reports an error.
- ResolverError(error)
- // UpdateSubConnState is called by gRPC when the state of a SubConn
- // changes.
- UpdateSubConnState(SubConn, SubConnState)
- // Close closes the balancer. The balancer is not required to call
- // ClientConn.RemoveSubConn for its existing SubConns.
- Close()
-}
-
// ConnectivityStateEvaluator takes the connectivity states of multiple SubConns
// and returns one aggregated connectivity state.
//
// It's not thread safe.
type ConnectivityStateEvaluator struct {
- numReady uint64 // Number of addrConns in ready state.
- numConnecting uint64 // Number of addrConns in connecting state.
+ numReady uint64 // Number of addrConns in ready state.
+ numConnecting uint64 // Number of addrConns in connecting state.
+ numTransientFailure uint64 // Number of addrConns in transient failure state.
+ numIdle uint64 // Number of addrConns in idle state.
}
// RecordTransition records state change happening in subConn and based on that
@@ -428,9 +387,11 @@
//
// - If at least one SubConn in Ready, the aggregated state is Ready;
// - Else if at least one SubConn in Connecting, the aggregated state is Connecting;
-// - Else the aggregated state is TransientFailure.
+// - Else if at least one SubConn is TransientFailure, the aggregated state is Transient Failure;
+// - Else if at least one SubConn is Idle, the aggregated state is Idle;
+// - Else there are no subconns and the aggregated state is Transient Failure
//
-// Idle and Shutdown are not considered.
+// Shutdown is not considered.
func (cse *ConnectivityStateEvaluator) RecordTransition(oldState, newState connectivity.State) connectivity.State {
// Update counters.
for idx, state := range []connectivity.State{oldState, newState} {
@@ -440,6 +401,10 @@
cse.numReady += updateVal
case connectivity.Connecting:
cse.numConnecting += updateVal
+ case connectivity.TransientFailure:
+ cse.numTransientFailure += updateVal
+ case connectivity.Idle:
+ cse.numIdle += updateVal
}
}
@@ -450,5 +415,11 @@
if cse.numConnecting > 0 {
return connectivity.Connecting
}
+ if cse.numTransientFailure > 0 {
+ return connectivity.TransientFailure
+ }
+ if cse.numIdle > 0 {
+ return connectivity.Idle
+ }
return connectivity.TransientFailure
}