Upgrade to 0.12

[github/fretlink/terraform-provider-statuscake.git] / vendor / google.golang.org / grpc / balancer / balancer.go

/*
 *
 * Copyright 2017 gRPC authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 */

// Package balancer defines APIs for load balancing in gRPC.
// All APIs in this package are experimental.
package balancer

import (
        "context"
        "errors"
        "net"
        "strings"

        "google.golang.org/grpc/connectivity"
        "google.golang.org/grpc/credentials"
        "google.golang.org/grpc/internal"
        "google.golang.org/grpc/metadata"
        "google.golang.org/grpc/resolver"
)

var (
        // m is a map from name to balancer builder.
        m = make(map[string]Builder)
)

// Register registers the balancer builder to the balancer map. b.Name
// (lowercased) will be used as the name registered with this builder.
//
// NOTE: this function must only be called during initialization time (i.e. in
// an init() function), and is not thread-safe. If multiple Balancers are
// registered with the same name, the one registered last will take effect.
func Register(b Builder) {
        m[strings.ToLower(b.Name())] = b
}

// unregisterForTesting deletes the balancer with the given name from the
// balancer map.
//
// This function is not thread-safe.
func unregisterForTesting(name string) {
        delete(m, name)
}

func init() {
        internal.BalancerUnregister = unregisterForTesting
}

// Get returns the resolver builder registered with the given name.
// Note that the compare is done in a case-insenstive fashion.
// If no builder is register with the name, nil will be returned.
func Get(name string) Builder {
        if b, ok := m[strings.ToLower(name)]; ok {
                return b
        }
        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.
//
// The reconnect backoff will be applied on the list, not a single address.
// For example, try_on_all_addresses -> backoff -> try_on_all_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.
//
// 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.
type SubConn interface {
        // UpdateAddresses updates the addresses used in this SubConn.
        // gRPC checks if currently-connected address is still in the new list.
        // If it's in the list, the connection will be kept.
        // If it's not in the list, the connection will gracefully closed, and
        // a new connection will be created.
        //
        // This will trigger a state transition for the SubConn.
        UpdateAddresses([]resolver.Address)
        // Connect starts the connecting for this SubConn.
        Connect()
}

// NewSubConnOptions contains options to create new SubConn.
type NewSubConnOptions struct {
        // 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.
        CredsBundle credentials.Bundle
        // HealthCheckEnabled indicates whether health check service should be
        // enabled on this SubConn
        HealthCheckEnabled bool
}

// ClientConn represents a gRPC ClientConn.
//
// 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.
type ClientConn interface {
        // NewSubConn is called by balancer to create a new SubConn.
        // It doesn't block and wait for the connections to be established.
        // Behaviors of the SubConn can be controlled by options.
        NewSubConn([]resolver.Address, NewSubConnOptions) (SubConn, error)
        // RemoveSubConn removes the SubConn from ClientConn.
        // The SubConn will be shutdown.
        RemoveSubConn(SubConn)

        // UpdateBalancerState is called by balancer to nofity gRPC that some internal
        // state in balancer has changed.
        //
        // gRPC will update the connectivity state of the ClientConn, and will call pick
        // on the new picker to pick new SubConn.
        UpdateBalancerState(s connectivity.State, p Picker)

        // ResolveNow is called by balancer to notify gRPC to do a name resolving.
        ResolveNow(resolver.ResolveNowOption)

        // Target returns the dial target for this ClientConn.
        Target() string
}

// 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 credentials.TransportCredentials
        // CredsBundle is the credentials bundle that the Balancer can use.
        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 func(context.Context, string) (net.Conn, error)
        // ChannelzParentID is the entity parent's channelz unique identification number.
        ChannelzParentID int64
}

// Builder creates a balancer.
type Builder interface {
        // Build creates a new balancer with the ClientConn.
        Build(cc ClientConn, opts BuildOptions) Balancer
        // Name returns the name of balancers built by this builder.
        // It will be used to pick balancers (for example in service config).
        Name() string
}

// PickOptions contains addition information for the Pick operation.
type PickOptions struct {
        // FullMethodName is the method name that NewClientStream() is called
        // with. The canonical format is /service/Method.
        FullMethodName string
        // Header contains the metadata from the RPC's client header.  The metadata
        // should not be modified; make a copy first if needed.
        Header metadata.MD
}

// DoneInfo contains additional information for done.
type DoneInfo struct {
        // Err is the rpc error the RPC finished with. It could be nil.
        Err error
        // Trailer contains the metadata from the RPC's trailer, if present.
        Trailer metadata.MD
        // BytesSent indicates if any bytes have been sent to the server.
        BytesSent bool
        // BytesReceived indicates if any byte has been received from the server.
        BytesReceived bool
}

var (
        // ErrNoSubConnAvailable indicates no SubConn is available for pick().
        // gRPC will block the RPC until a new picker is available via UpdateBalancerState().
        ErrNoSubConnAvailable = errors.New("no SubConn is available")
        // ErrTransientFailure indicates all SubConns are in TransientFailure.
        // WaitForReady RPCs will block, non-WaitForReady RPCs will fail.
        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().
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.
        //
        // If the returned error is not nil:
        // - If the error is ErrNoSubConnAvailable, gRPC will block until UpdateBalancerState()
        // - If the error is ErrTransientFailure:
        //   - 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 unavailable error.
        //
        // The returned done() function will be called once the rpc has finished, with the
        // final status of that RPC.
        // done may be nil if balancer doesn't care about the RPC status.
        Pick(ctx context.Context, opts PickOptions) (conn SubConn, done func(DoneInfo), err error)
}

// Balancer takes input from gRPC, manages SubConns, and collects and aggregates
// the connectivity states.
//
// 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.
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.
        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.
        HandleResolvedAddrs([]resolver.Address, error)
        // 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.
        numTransientFailure uint64 // Number of addrConns in transientFailure.
}

// RecordTransition records state change happening in subConn and based on that
// it evaluates what aggregated state should be.
//
//  - 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.
//
// Idle and Shutdown are not considered.
func (cse *ConnectivityStateEvaluator) RecordTransition(oldState, newState connectivity.State) connectivity.State {
        // Update counters.
        for idx, state := range []connectivity.State{oldState, newState} {
                updateVal := 2*uint64(idx) - 1 // -1 for oldState and +1 for new.
                switch state {
                case connectivity.Ready:
                        cse.numReady += updateVal
                case connectivity.Connecting:
                        cse.numConnecting += updateVal
                case connectivity.TransientFailure:
                        cse.numTransientFailure += updateVal
                }
        }

        // Evaluate.
        if cse.numReady > 0 {
                return connectivity.Ready
        }
        if cse.numConnecting > 0 {
                return connectivity.Connecting
        }
        return connectivity.TransientFailure
}