package xdsclient

import "google.golang.org/grpc/xds/internal/xdsclient"

Package xdsclient implements a full fledged gRPC client for the xDS API used by the xds resolver and balancer implementations.

Index ¶

• Constants
• Variables
• func ClearAllCountersForTesting()
• func ClearCounterForTesting(clusterName, edsServiceName string)
• func DumpResources() *v3statuspb.ClientStatusResponse
• func SetClient(state resolver.State, c XDSClient) resolver.State
• type ClusterRequestsCounter
• func GetClusterRequestsCounter(clusterName, edsServiceName string) *ClusterRequestsCounter
• func (c *ClusterRequestsCounter) EndRequest()
• func (c *ClusterRequestsCounter) StartRequest(max uint32) error
• type OptionsForTesting
• type Pool
• func NewPool(config *bootstrap.Config) *Pool
• func (p *Pool) BootstrapConfigForTesting() *bootstrap.Config
• func (p *Pool) DumpResources() *v3statuspb.ClientStatusResponse
• func (p *Pool) GetClientForTesting(name string) (XDSClient, func(), error)
• func (p *Pool) NewClient(name string, metricsRecorder estats.MetricsRecorder) (XDSClient, func(), error)
• func (p *Pool) NewClientForTesting(opts OptionsForTesting) (XDSClient, func(), error)
• func (p *Pool) SetFallbackBootstrapConfig(config *bootstrap.Config)
• func (p *Pool) UnsetBootstrapConfigForTesting()
• type XDSClient
• func FromResolverState(state resolver.State) XDSClient

Constants ¶

const (
	// NameForServer represents the value to be passed as name when creating an xDS
	// client from xDS-enabled gRPC servers. This is a well-known dedicated key
	// value, and is defined in gRFC A71.
	NameForServer = "#server"
)

Variables ¶

var (

	// ErrClientClosed is returned when the xDS client is closed.
	ErrClientClosed = errors.New("xds: the xDS client is closed")
)

Functions ¶

func ClearAllCountersForTesting ¶

func ClearAllCountersForTesting()

ClearAllCountersForTesting clears all the counters. Should be only used in tests.

func ClearCounterForTesting ¶

func ClearCounterForTesting(clusterName, edsServiceName string)

ClearCounterForTesting clears the counter for the service. Should be only used in tests.

func DumpResources ¶

func DumpResources() *v3statuspb.ClientStatusResponse

DumpResources returns the status and contents of all xDS resources. It uses xDS clients from the default pool.

func SetClient ¶

func SetClient(state resolver.State, c XDSClient) resolver.State

SetClient sets c in state and returns the new state.

Types ¶

type ClusterRequestsCounter ¶

type ClusterRequestsCounter struct {
	ClusterName    string
	EDSServiceName string
	// contains filtered or unexported fields
}

ClusterRequestsCounter is used to track the total inflight requests for a service with the provided name.

func GetClusterRequestsCounter ¶

func GetClusterRequestsCounter(clusterName, edsServiceName string) *ClusterRequestsCounter

GetClusterRequestsCounter returns the ClusterRequestsCounter with the provided serviceName. If one does not exist, it creates it.

func (*ClusterRequestsCounter) EndRequest ¶

func (c *ClusterRequestsCounter) EndRequest()

EndRequest ends a request for a service, decrementing its number of requests by 1.

func (*ClusterRequestsCounter) StartRequest ¶

func (c *ClusterRequestsCounter) StartRequest(max uint32) error

StartRequest starts a request for a cluster, incrementing its number of requests by 1. Returns an error if the max number of requests is exceeded.

type OptionsForTesting ¶

type OptionsForTesting struct {
	// Name is a unique name for this xDS client.
	Name string

	// WatchExpiryTimeout is the timeout for xDS resource watch expiry. If
	// unspecified, uses the default value used in non-test code.
	WatchExpiryTimeout time.Duration

	// StreamBackoffAfterFailure is the backoff function used to determine the
	// backoff duration after stream failures.
	// If unspecified, uses the default value used in non-test code.
	StreamBackoffAfterFailure func(int) time.Duration

	// MetricsRecorder is the metrics recorder the xDS Client will use. If
	// unspecified, uses a no-op MetricsRecorder.
	MetricsRecorder estats.MetricsRecorder
}

OptionsForTesting contains options to configure xDS client creation for testing purposes only.

type Pool ¶

type Pool struct {
	// contains filtered or unexported fields
}

Pool represents a pool of xDS clients that share the same bootstrap configuration.

var (
	// DefaultPool is the default pool for xDS clients. It is created at init
	// time by reading bootstrap configuration from env vars.
	DefaultPool *Pool
)

func NewPool ¶

func NewPool(config *bootstrap.Config) *Pool

NewPool creates a new xDS client pool with the given bootstrap config.

If a nil bootstrap config is passed and SetFallbackBootstrapConfig is not called before a call to NewClient, the latter will fail. i.e. if there is an attempt to create an xDS client from the pool without specifying bootstrap configuration (either at pool creation time or by setting the fallback bootstrap configuration), xDS client creation will fail.

func (*Pool) BootstrapConfigForTesting ¶

func (p *Pool) BootstrapConfigForTesting() *bootstrap.Config

BootstrapConfigForTesting returns the bootstrap configuration used by the pool. The caller should not mutate the returned config.

To be used only for testing purposes.

func (*Pool) DumpResources ¶

func (p *Pool) DumpResources() *v3statuspb.ClientStatusResponse

DumpResources returns the status and contents of all xDS resources.

func (*Pool) GetClientForTesting ¶

func (p *Pool) GetClientForTesting(name string) (XDSClient, func(), error)

GetClientForTesting returns an xDS client created earlier using the given name from the pool. If the client with the given name doesn't already exist, it returns an error.

The second return value represents a close function which the caller is expected to invoke once they are done using the client. It is safe for the caller to invoke this close function multiple times.

Testing Only

This function should ONLY be used for testing purposes.

func (*Pool) NewClient ¶

func (p *Pool) NewClient(name string, metricsRecorder estats.MetricsRecorder) (XDSClient, func(), error)

NewClient returns an xDS client with the given name from the pool. If the client doesn't already exist, it creates a new xDS client and adds it to the pool.

The second return value represents a close function which the caller is expected to invoke once they are done using the client. It is safe for the caller to invoke this close function multiple times.

func (*Pool) NewClientForTesting ¶

func (p *Pool) NewClientForTesting(opts OptionsForTesting) (XDSClient, func(), error)

NewClientForTesting returns an xDS client configured with the provided options from the pool. If the client doesn't already exist, it creates a new xDS client and adds it to the pool.

The second return value represents a close function which the caller is expected to invoke once they are done using the client. It is safe for the caller to invoke this close function multiple times.

Testing Only

This function should ONLY be used for testing purposes.

func (*Pool) SetFallbackBootstrapConfig ¶

func (p *Pool) SetFallbackBootstrapConfig(config *bootstrap.Config)

SetFallbackBootstrapConfig is used to specify a bootstrap configuration that will be used as a fallback when the bootstrap environment variables are not defined.

func (*Pool) UnsetBootstrapConfigForTesting ¶

func (p *Pool) UnsetBootstrapConfigForTesting()

UnsetBootstrapConfigForTesting unsets the bootstrap configuration used by the pool.

To be used only for testing purposes.

type XDSClient ¶

type XDSClient interface {
	// WatchResource uses xDS to discover the resource associated with the
	// provided resource name. The resource type implementation determines how
	// xDS responses are are deserialized and validated, as received from the
	// xDS management server. Upon receipt of a response from the management
	// server, an appropriate callback on the watcher is invoked.
	//
	// Most callers will not have a need to use this API directly. They will
	// instead use a resource-type-specific wrapper API provided by the relevant
	// resource type implementation.
	//
	//
	// During a race (e.g. an xDS response is received while the user is calling
	// cancel()), there's a small window where the callback can be called after
	// the watcher is canceled. Callers need to handle this case.
	WatchResource(rType xdsresource.Type, resourceName string, watcher xdsresource.ResourceWatcher) (cancel func())

	ReportLoad(*bootstrap.ServerConfig) (*load.Store, func())

	BootstrapConfig() *bootstrap.Config
}

XDSClient is a full fledged gRPC client which queries a set of discovery APIs (collectively termed as xDS) on a remote management server, to discover various dynamic resources.

func FromResolverState ¶

func FromResolverState(state resolver.State) XDSClient

FromResolverState returns the Client from state, or nil if not present.

Source Files ¶

attributes.go authority.go channel.go client.go clientimpl.go clientimpl_loadreport.go clientimpl_watchers.go logging.go pool.go requests_counter.go

Directories ¶