client

package
v1.39.0-dev Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 11, 2021 License: Apache-2.0 Imports: 39 Imported by: 0

Documentation

Overview

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

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ClearCounterForTesting added in v1.36.0 

func ClearCounterForTesting(serviceName string)

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

func IsClusterResource added in v1.32.0 

func IsClusterResource(url string) bool

IsClusterResource returns true if the provider URL corresponds to an xDS Cluster resource.

func IsEndpointsResource added in v1.32.0 

func IsEndpointsResource(url string) bool

IsEndpointsResource returns true if the provider URL corresponds to an xDS Endpoints resource.

func IsHTTPConnManagerResource added in v1.32.0 

func IsHTTPConnManagerResource(url string) bool

IsHTTPConnManagerResource returns true if the provider URL corresponds to an xDS HTTPConnManager resource.

func IsListenerResource added in v1.32.0 

func IsListenerResource(url string) bool

IsListenerResource returns true if the provider URL corresponds to an xDS Listener resource.

func IsRouteConfigResource added in v1.32.0 

func IsRouteConfigResource(url string) bool

IsRouteConfigResource returns true if the provider URL corresponds to an xDS RouteConfig resource.

func NewErrorf added in v1.30.0 

func NewErrorf(t ErrorType, format string, args ...interface{}) error

NewErrorf creates an xds client error. The callbacks are called with this error, to pass additional information about the error.

func RegisterAPIClientBuilder added in v1.32.0 

func RegisterAPIClientBuilder(b APIClientBuilder)

RegisterAPIClientBuilder registers a client builder for xDS transport protocol version specified by b.Version().

NOTE: this function must only be called during initialization time (i.e. in an init() function), and is not thread-safe. If multiple builders are registered for the same version, the one registered last will take effect.

Types

type APIClient added in v1.32.0 

type APIClient interface {
	// AddWatch adds a watch for an xDS resource given its type and name.
	AddWatch(ResourceType, string)

	// RemoveWatch cancels an already registered watch for an xDS resource
	// given its type and name.
	RemoveWatch(ResourceType, string)

	// Close cleans up resources allocated by the API client.
	Close()
	// contains filtered or unexported methods
}

APIClient represents the functionality provided by transport protocol version specific implementations of the xDS client.

TODO: unexport this interface and all the methods after the PR to make xdsClient sharable by clients. AddWatch and RemoveWatch are exported for v2/v3 to override because they need to keep track of LDS name for RDS to use. After the share xdsClient change, that's no longer necessary. After that, we will still keep this interface for testing purposes.

type APIClientBuilder added in v1.32.0 

type APIClientBuilder interface {
	// Build builds a transport protocol specific implementation of the xDS
	// client based on the provided clientConn to the management server and the
	// provided options.
	Build(*grpc.ClientConn, BuildOptions) (APIClient, error)
	// Version returns the xDS transport protocol version used by clients build
	// using this builder.
	Version() version.TransportAPI
}

APIClientBuilder creates an xDS client for a specific xDS transport protocol version.

type BuildOptions added in v1.32.0 

type BuildOptions struct {
	// Parent is a top-level xDS client which has the intelligence to take
	// appropriate action based on xDS responses received from the management
	// server.
	Parent UpdateHandler
	// NodeProto contains the Node proto to be used in xDS requests. The actual
	// type depends on the transport protocol version used.
	NodeProto proto.Message
	// Backoff returns the amount of time to backoff before retrying broken
	// streams.
	Backoff func(int) time.Duration
	// Logger provides enhanced logging capabilities.
	Logger *grpclog.PrefixLogger
}

BuildOptions contains options to be passed to client builders.

type Client added in v1.26.0 

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

Client 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.

The xds client is a singleton. It will be shared by the xds resolver and balancer implementations, across multiple ClientConns and Servers.

func New added in v1.26.0 

func New() (*Client, error)

New returns a new xdsClient configured by the bootstrap file specified in env variable GRPC_XDS_BOOTSTRAP or GRPC_XDS_BOOTSTRAP_CONFIG.

The returned xdsClient is a singleton. This function creates the xds client if it doesn't already exist.

Note that the first invocation of New() or NewWithConfig() sets the client singleton. The following calls will return the singleton xds client without checking or using the config.

func NewWithConfig added in v1.37.0 

func NewWithConfig(config *bootstrap.Config) (*Client, error)

NewWithConfig returns a new xdsClient configured by the given config.

The returned xdsClient is a singleton. This function creates the xds client if it doesn't already exist.

Note that the first invocation of New() or NewWithConfig() sets the client singleton. The following calls will return the singleton xds client without checking or using the config.

This function is internal only, for c2p resolver to use. DO NOT use this elsewhere. Use New() instead.

func NewWithConfigForTesting added in v1.34.0 

func NewWithConfigForTesting(config *bootstrap.Config, watchExpiryTimeout time.Duration) (*Client, error)

NewWithConfigForTesting is exported for testing only.

Note that this function doesn't set the singleton, so that the testing states don't leak.

func (*Client) BootstrapConfig added in v1.34.0 

func (c *Client) BootstrapConfig() *bootstrap.Config

BootstrapConfig returns the configuration read from the bootstrap file. Callers must treat the return value as read-only.

func (*Client) Close added in v1.26.0 

func (c *Client) Close()

Close closes the client. It does ref count of the xds client implementation, and closes the gRPC connection to the management server when ref count reaches 0.

func (Client) DumpCDS added in v1.37.0 

func (c Client) DumpCDS() (string, map[string]UpdateWithMD)

DumpCDS returns the status and contents of CDS.

func (Client) DumpEDS added in v1.37.0 

func (c Client) DumpEDS() (string, map[string]UpdateWithMD)

DumpEDS returns the status and contents of EDS.

func (Client) DumpLDS added in v1.37.0 

func (c Client) DumpLDS() (string, map[string]UpdateWithMD)

DumpLDS returns the status and contents of LDS.

func (Client) DumpRDS added in v1.37.0 

func (c Client) DumpRDS() (string, map[string]UpdateWithMD)

DumpRDS returns the status and contents of RDS.

func (Client) NewClusters added in v1.32.0 

func (c Client) NewClusters(updates map[string]ClusterUpdate, metadata UpdateMetadata)

NewClusters is called by the underlying xdsAPIClient when it receives an xDS response.

A response can contain multiple resources. They will be parsed and put in a map from resource name to the resource content.

func (Client) NewEndpoints added in v1.32.0 

func (c Client) NewEndpoints(updates map[string]EndpointsUpdate, metadata UpdateMetadata)

NewEndpoints is called by the underlying xdsAPIClient when it receives an xDS response.

A response can contain multiple resources. They will be parsed and put in a map from resource name to the resource content.

func (Client) NewListeners added in v1.32.0 

func (c Client) NewListeners(updates map[string]ListenerUpdate, metadata UpdateMetadata)

NewListeners is called by the underlying xdsAPIClient when it receives an xDS response.

A response can contain multiple resources. They will be parsed and put in a map from resource name to the resource content.

func (Client) NewRouteConfigs added in v1.32.0 

func (c Client) NewRouteConfigs(updates map[string]RouteConfigUpdate, metadata UpdateMetadata)

NewRouteConfigs is called by the underlying xdsAPIClient when it receives an xDS response.

A response can contain multiple resources. They will be parsed and put in a map from resource name to the resource content.

func (Client) ReportLoad added in v1.26.0 

func (c Client) ReportLoad(server string) (*load.Store, func())

ReportLoad starts an load reporting stream to the given server. If the server is not an empty string, and is different from the management server, a new ClientConn will be created.

The same options used for creating the Client will be used (including NodeProto, and dial options if necessary).

It returns a Store for the user to report loads, a function to cancel the load reporting stream.

func (Client) WatchCluster added in v1.26.0 

func (c Client) WatchCluster(clusterName string, cb func(ClusterUpdate, error)) (cancel func())

WatchCluster uses CDS to discover information about the provided clusterName.

WatchCluster can be called multiple times, with same or different clusterNames. Each call will start an independent watcher for the resource.

Note that during 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. The caller needs to handle this case.

func (Client) WatchEndpoints added in v1.29.0 

func (c Client) WatchEndpoints(clusterName string, cb func(EndpointsUpdate, error)) (cancel func())

WatchEndpoints uses EDS to discover endpoints in the provided clusterName.

WatchEndpoints can be called multiple times, with same or different clusterNames. Each call will start an independent watcher for the resource.

Note that during 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. The caller needs to handle this case.

func (Client) WatchListener added in v1.32.0 

func (c Client) WatchListener(serviceName string, cb func(ListenerUpdate, error)) (cancel func())

WatchListener uses LDS to discover information about the provided listener.

Note that during 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. The caller needs to handle this case.

func (Client) WatchRouteConfig added in v1.34.0 

func (c Client) WatchRouteConfig(routeName string, cb func(RouteConfigUpdate, error)) (cancel func())

WatchRouteConfig starts a listener watcher for the service..

Note that during 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. The caller needs to handle this case.

type ClusterType added in v1.38.0 

type ClusterType int

ClusterType is the type of cluster from a received CDS response. 

const (
	// ClusterTypeEDS represents the EDS cluster type, which will delegate endpoint
	// discovery to the management server.
	ClusterTypeEDS ClusterType = iota
	// ClusterTypeLogicalDNS represents the Logical DNS cluster type, which essentially
	// maps to the gRPC behavior of using the DNS resolver with pick_first LB policy.
	ClusterTypeLogicalDNS
	// ClusterTypeAggregate represents the Aggregate Cluster type, which provides a
	// prioritized list of clusters to use. It is used for failover between clusters
	// with a different configuration.
	ClusterTypeAggregate
)

type ClusterUpdate added in v1.30.0 

type ClusterUpdate struct {
	ClusterType ClusterType
	// ServiceName is the service name corresponding to the clusterName which
	// is being watched for through CDS.
	ServiceName string
	// EnableLRS indicates whether or not load should be reported through LRS.
	EnableLRS bool
	// SecurityCfg contains security configuration sent by the control plane.
	SecurityCfg *SecurityConfig
	// MaxRequests for circuit breaking, if any (otherwise nil).
	MaxRequests *uint32

	// Raw is the resource from the xds response.
	Raw *anypb.Any

	// PrioritizedClusterNames is used only for cluster type aggregate. It represents
	// a prioritized list of cluster names.
	PrioritizedClusterNames []string
}

ClusterUpdate contains information from a received CDS response, which is of interest to the registered CDS watcher.

type Endpoint added in v1.26.0 

type Endpoint struct {
	Address      string
	HealthStatus EndpointHealthStatus
	Weight       uint32
}

Endpoint contains information of an endpoint.

type EndpointHealthStatus added in v1.26.0 

type EndpointHealthStatus int32

EndpointHealthStatus represents the health status of an endpoint. 

const (
	// EndpointHealthStatusUnknown represents HealthStatus UNKNOWN.
	EndpointHealthStatusUnknown EndpointHealthStatus = iota
	// EndpointHealthStatusHealthy represents HealthStatus HEALTHY.
	EndpointHealthStatusHealthy
	// EndpointHealthStatusUnhealthy represents HealthStatus UNHEALTHY.
	EndpointHealthStatusUnhealthy
	// EndpointHealthStatusDraining represents HealthStatus DRAINING.
	EndpointHealthStatusDraining
	// EndpointHealthStatusTimeout represents HealthStatus TIMEOUT.
	EndpointHealthStatusTimeout
	// EndpointHealthStatusDegraded represents HealthStatus DEGRADED.
	EndpointHealthStatusDegraded
)

type EndpointsUpdate added in v1.30.0 

type EndpointsUpdate struct {
	Drops      []OverloadDropConfig
	Localities []Locality

	// Raw is the resource from the xds response.
	Raw *anypb.Any
}

EndpointsUpdate contains an EDS update.

type ErrResourceTypeUnsupported added in v1.32.0 

type ErrResourceTypeUnsupported struct {
	ErrStr string
}

ErrResourceTypeUnsupported is an error used to indicate an unsupported xDS resource type. The wrapped ErrStr contains the details.

func (ErrResourceTypeUnsupported) Error added in v1.32.0 

func (e ErrResourceTypeUnsupported) Error() string

Error helps implements the error interface.

type ErrorType added in v1.30.0 

type ErrorType int

ErrorType is the type of the error that the watcher will receive from the xds client. 

const (
	// ErrorTypeUnknown indicates the error doesn't have a specific type. It is
	// the default value, and is returned if the error is not an xds error.
	ErrorTypeUnknown ErrorType = iota
	// ErrorTypeConnection indicates a connection error from the gRPC client.
	ErrorTypeConnection
	// ErrorTypeResourceNotFound indicates a resource is not found from the xds
	// response. It's typically returned if the resource is removed in the xds
	// server.
	ErrorTypeResourceNotFound
)

func ErrType added in v1.30.0 

func ErrType(e error) ErrorType

ErrType returns the error's type.

type FilterChain added in v1.37.0 

type FilterChain struct {
	// SecurityCfg contains transport socket security configuration.
	SecurityCfg *SecurityConfig
}

FilterChain captures information from within a FilterChain message in a Listener resource.

Currently, this simply contains the security configuration found in the 'transport_socket' field of the filter chain. The actual set of filters associated with this filter chain are not captured here, since we do not support these filters on the server-side yet.

type FilterChainLookupParams added in v1.38.0 

type FilterChainLookupParams struct {
	// IsUnspecified indicates whether the server is listening on a wildcard
	// address, "0.0.0.0" for IPv4 and "::" for IPv6. Only when this is set to
	// true, do we consider the destination prefixes specified in the filter
	// chain match criteria.
	IsUnspecifiedListener bool
	// DestAddr is the local address of an incoming connection.
	DestAddr net.IP
	// SourceAddr is the remote address of an incoming connection.
	SourceAddr net.IP
	// SourcePort is the remote port of an incoming connection.
	SourcePort int
}

FilterChainLookupParams wraps parameters to be passed to Lookup.

type FilterChainManager added in v1.38.0 

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

FilterChainManager contains all the match criteria specified through all filter chains in a single Listener resource. It also contains the default filter chain specified in the Listener resource. It provides two important pieces of functionality:

  1. Validate the filter chains in an incoming Listener resource to make sure that there aren't filter chains which contain the same match criteria.
  2. As part of performing the above validation, it builds an internal data structure which will if used to look up the matching filter chain at connection time.

The logic specified in the documentation around the xDS FilterChainMatch proto mentions 8 criteria to match on. The following order applies:

1. Destination port. 2. Destination IP address. 3. Server name (e.g. SNI for TLS protocol), 4. Transport protocol. 5. Application protocols (e.g. ALPN for TLS protocol). 6. Source type (e.g. any, local or external network). 7. Source IP address. 8. Source port.

func NewFilterChainManager added in v1.38.0 

func NewFilterChainManager(lis *v3listenerpb.Listener) (*FilterChainManager, error)

NewFilterChainManager parses the received Listener resource and builds a FilterChainManager. Returns a non-nil error on validation failures.

This function is only exported so that tests outside of this package can create a FilterChainManager.

func (*FilterChainManager) Lookup added in v1.38.0 

func (fci *FilterChainManager) Lookup(params FilterChainLookupParams) (*FilterChain, error)

Lookup returns the most specific matching filter chain to be used for an incoming connection on the server side.

Returns a non-nil error if no matching filter chain could be found or multiple matching filter chains were found, and in both cases, the incoming connection must be dropped.

type HTTPFilter added in v1.37.0 

type HTTPFilter struct {
	// Name is an arbitrary name of the filter.  Used for applying override
	// settings in virtual host / route / weighted cluster configuration (not
	// yet supported).
	Name string
	// Filter is the HTTP filter found in the registry for the config type.
	Filter httpfilter.Filter
	// Config contains the filter's configuration
	Config httpfilter.FilterConfig
}

HTTPFilter represents one HTTP filter from an LDS response's HTTP connection manager field.

type HeaderMatcher added in v1.31.0 

type HeaderMatcher struct {
	Name         string
	InvertMatch  *bool
	ExactMatch   *string
	RegexMatch   *regexp.Regexp
	PrefixMatch  *string
	SuffixMatch  *string
	RangeMatch   *Int64Range
	PresentMatch *bool
}

HeaderMatcher represents header matchers.

type InboundListenerConfig added in v1.37.0 

type InboundListenerConfig struct {
	// Address is the local address on which the inbound listener is expected to
	// accept incoming connections.
	Address string
	// Port is the local port on which the inbound listener is expected to
	// accept incoming connections.
	Port string
	// FilterChains is the list of filter chains associated with this listener.
	FilterChains *FilterChainManager
}

InboundListenerConfig contains information about the inbound listener, i.e the server-side listener.

type Int64Range added in v1.31.0 

type Int64Range struct {
	Start int64
	End   int64
}

Int64Range is a range for header range match.

type ListenerUpdate added in v1.32.0 

type ListenerUpdate struct {
	// RouteConfigName is the route configuration name corresponding to the
	// target which is being watched through LDS.
	//
	// Only one of RouteConfigName and InlineRouteConfig is set.
	RouteConfigName string
	// InlineRouteConfig is the inline route configuration (RDS response)
	// returned inside LDS.
	//
	// Only one of RouteConfigName and InlineRouteConfig is set.
	InlineRouteConfig *RouteConfigUpdate

	// MaxStreamDuration contains the HTTP connection manager's
	// common_http_protocol_options.max_stream_duration field, or zero if
	// unset.
	MaxStreamDuration time.Duration
	// HTTPFilters is a list of HTTP filters (name, config) from the LDS
	// response.
	HTTPFilters []HTTPFilter
	// InboundListenerCfg contains inbound listener configuration.
	InboundListenerCfg *InboundListenerConfig

	// Raw is the resource from the xds response.
	Raw *anypb.Any
}

ListenerUpdate contains information received in an LDS response, which is of interest to the registered LDS watcher.

type Locality added in v1.26.0 

type Locality struct {
	Endpoints []Endpoint
	ID        internal.LocalityID
	Priority  uint32
	Weight    uint32
}

Locality contains information of a locality.

type OverloadDropConfig added in v1.26.0 

type OverloadDropConfig struct {
	Category    string
	Numerator   uint32
	Denominator uint32
}

OverloadDropConfig contains the config to drop overloads.

type ResourceType added in v1.32.0 

type ResourceType int

ResourceType identifies resources in a transport protocol agnostic way. These will be used in transport version agnostic code, while the versioned API clients will map these to appropriate version URLs. 

const (
	UnknownResource ResourceType = iota
	ListenerResource
	HTTPConnManagerResource
	RouteConfigResource
	ClusterResource
	EndpointsResource
)

Version agnostic resource type constants.

func (ResourceType) String added in v1.32.0 

func (r ResourceType) String() string

type Route added in v1.31.0 

type Route struct {
	Path   *string
	Prefix *string
	Regex  *regexp.Regexp
	// Indicates if prefix/path matching should be case insensitive. The default
	// is false (case sensitive).
	CaseInsensitive bool
	Headers         []*HeaderMatcher
	Fraction        *uint32

	// If the matchers above indicate a match, the below configuration is used.
	WeightedClusters map[string]WeightedCluster
	// If MaxStreamDuration is nil, it indicates neither of the route action's
	// max_stream_duration fields (grpc_timeout_header_max nor
	// max_stream_duration) were set.  In this case, the ListenerUpdate's
	// MaxStreamDuration field should be used.  If MaxStreamDuration is set to
	// an explicit zero duration, the application's deadline should be used.
	MaxStreamDuration *time.Duration
	// HTTPFilterConfigOverride contains any HTTP filter config overrides for
	// the route which may be present.  An individual filter's override may be
	// unused if the matching WeightedCluster contains an override for that
	// filter.
	HTTPFilterConfigOverride map[string]httpfilter.FilterConfig
}

Route is both a specification of how to match a request as well as an indication of the action to take upon match.

type RouteConfigUpdate added in v1.32.0 

type RouteConfigUpdate struct {
	VirtualHosts []*VirtualHost

	// Raw is the resource from the xds response.
	Raw *anypb.Any
}

RouteConfigUpdate contains information received in an RDS response, which is of interest to the registered RDS watcher.

type SecurityConfig added in v1.34.0 

type SecurityConfig struct {
	// RootInstanceName identifies the certProvider plugin to be used to fetch
	// root certificates. This instance name will be resolved to the plugin name
	// and its associated configuration from the certificate_providers field of
	// the bootstrap file.
	RootInstanceName string
	// RootCertName is the certificate name to be passed to the plugin (looked
	// up from the bootstrap file) while fetching root certificates.
	RootCertName string
	// IdentityInstanceName identifies the certProvider plugin to be used to
	// fetch identity certificates. This instance name will be resolved to the
	// plugin name and its associated configuration from the
	// certificate_providers field of the bootstrap file.
	IdentityInstanceName string
	// IdentityCertName is the certificate name to be passed to the plugin
	// (looked up from the bootstrap file) while fetching identity certificates.
	IdentityCertName string
	// SubjectAltNameMatchers is an optional list of match criteria for SANs
	// specified on the peer certificate. Used only on the client-side.
	//
	// Some intricacies:
	// - If this field is empty, then any peer certificate is accepted.
	// - If the peer certificate contains a wildcard DNS SAN, and an `exact`
	//   matcher is configured, a wildcard DNS match is performed instead of a
	//   regular string comparison.
	SubjectAltNameMatchers []xds.StringMatcher
	// RequireClientCert indicates if the server handshake process expects the
	// client to present a certificate. Set to true when performing mTLS. Used
	// only on the server-side.
	RequireClientCert bool
}

SecurityConfig contains the security configuration received as part of the Cluster resource on the client-side, and as part of the Listener resource on the server-side.

type ServiceRequestsCounter added in v1.35.0 

type ServiceRequestsCounter struct {
	ServiceName string
	// contains filtered or unexported fields
}

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

func GetServiceRequestsCounter added in v1.35.0 

func GetServiceRequestsCounter(serviceName string) *ServiceRequestsCounter

GetServiceRequestsCounter returns the ServiceRequestsCounter with the provided serviceName. If one does not exist, it creates it.

func (*ServiceRequestsCounter) EndRequest added in v1.35.0 

func (c *ServiceRequestsCounter) EndRequest()

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

func (*ServiceRequestsCounter) StartRequest added in v1.35.0 

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

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

type ServiceStatus added in v1.37.0 

type ServiceStatus int

ServiceStatus is the status of the update. 

const (
	// ServiceStatusUnknown is the default state, before a watch is started for
	// the resource.
	ServiceStatusUnknown ServiceStatus = iota
	// ServiceStatusRequested is when the watch is started, but before and
	// response is received.
	ServiceStatusRequested
	// ServiceStatusNotExist is when the resource doesn't exist in
	// state-of-the-world responses (e.g. LDS and CDS), which means the resource
	// is removed by the management server.
	ServiceStatusNotExist // Resource is removed in the server, in LDS/CDS.
	// ServiceStatusACKed is when the resource is ACKed.
	ServiceStatusACKed
	// ServiceStatusNACKed is when the resource is NACKed.
	ServiceStatusNACKed
)

type SourceType added in v1.37.0 

type SourceType int

SourceType specifies the connection source IP match type. 

const (
	// SourceTypeAny matches connection attempts from any source.
	SourceTypeAny SourceType = iota
	// SourceTypeSameOrLoopback matches connection attempts from the same host.
	SourceTypeSameOrLoopback
	// SourceTypeExternal matches connection attempts from a different host.
	SourceTypeExternal
)

type TransportHelper added in v1.32.0 

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

TransportHelper contains all xDS transport protocol related functionality which is common across different versioned client implementations.

TransportHelper takes care of sending and receiving xDS requests and responses on an ADS stream. It also takes care of ACK/NACK handling. It delegates to the actual versioned client implementations wherever appropriate.

Implements the APIClient interface which makes it possible for versioned client implementations to embed this type, and thereby satisfy the interface requirements.

func NewTransportHelper added in v1.32.0 

func NewTransportHelper(vc VersionedClient, logger *grpclog.PrefixLogger, backoff func(int) time.Duration) *TransportHelper

NewTransportHelper creates a new transport helper to be used by versioned client implementations.

func (*TransportHelper) AddWatch added in v1.32.0 

func (t *TransportHelper) AddWatch(rType ResourceType, resourceName string)

AddWatch adds a watch for an xDS resource given its type and name.

func (*TransportHelper) Close added in v1.32.0 

func (t *TransportHelper) Close()

Close closes the transport helper.

func (*TransportHelper) RemoveWatch added in v1.32.0 

func (t *TransportHelper) RemoveWatch(rType ResourceType, resourceName string)

RemoveWatch cancels an already registered watch for an xDS resource given its type and name.

type UpdateErrorMetadata added in v1.37.0 

type UpdateErrorMetadata struct {
	// Version is the version of the NACKed response.
	Version string
	// Err contains why the response was NACKed.
	Err error
	// Timestamp is when the NACKed response was received.
	Timestamp time.Time
}

UpdateErrorMetadata is part of UpdateMetadata. It contains the error state when a response is NACKed.

type UpdateHandler added in v1.32.0 

type UpdateHandler interface {
	// NewListeners handles updates to xDS listener resources.
	NewListeners(map[string]ListenerUpdate, UpdateMetadata)
	// NewRouteConfigs handles updates to xDS RouteConfiguration resources.
	NewRouteConfigs(map[string]RouteConfigUpdate, UpdateMetadata)
	// NewClusters handles updates to xDS Cluster resources.
	NewClusters(map[string]ClusterUpdate, UpdateMetadata)
	// NewEndpoints handles updates to xDS ClusterLoadAssignment (or tersely
	// referred to as Endpoints) resources.
	NewEndpoints(map[string]EndpointsUpdate, UpdateMetadata)
}

UpdateHandler receives and processes (by taking appropriate actions) xDS resource updates from an APIClient for a specific version.

type UpdateMetadata added in v1.37.0 

type UpdateMetadata struct {
	// Status is the status of this resource, e.g. ACKed, NACKed, or
	// Not_exist(removed).
	Status ServiceStatus
	// Version is the version of the xds response. Note that this is the version
	// of the resource in use (previous ACKed). If a response is NACKed, the
	// NACKed version is in ErrState.
	Version string
	// Timestamp is when the response is received.
	Timestamp time.Time
	// ErrState is set when the update is NACKed.
	ErrState *UpdateErrorMetadata
}

UpdateMetadata contains the metadata for each update, including timestamp, raw message, and so on.

func UnmarshalCluster added in v1.32.0 

func UnmarshalCluster(version string, resources []*anypb.Any, logger *grpclog.PrefixLogger) (map[string]ClusterUpdate, UpdateMetadata, error)

UnmarshalCluster processes resources received in an CDS response, validates them, and transforms them into a native struct which contains only fields we are interested in.

func UnmarshalEndpoints added in v1.32.0 

func UnmarshalEndpoints(version string, resources []*anypb.Any, logger *grpclog.PrefixLogger) (map[string]EndpointsUpdate, UpdateMetadata, error)

UnmarshalEndpoints processes resources received in an EDS response, validates them, and transforms them into a native struct which contains only fields we are interested in.

func UnmarshalListener added in v1.32.0 

func UnmarshalListener(version string, resources []*anypb.Any, logger *grpclog.PrefixLogger) (map[string]ListenerUpdate, UpdateMetadata, error)

UnmarshalListener processes resources received in an LDS response, validates them, and transforms them into a native struct which contains only fields we are interested in.

func UnmarshalRouteConfig added in v1.32.0 

func UnmarshalRouteConfig(version string, resources []*anypb.Any, logger *grpclog.PrefixLogger) (map[string]RouteConfigUpdate, UpdateMetadata, error)

UnmarshalRouteConfig processes resources received in an RDS response, validates them, and transforms them into a native struct which contains only fields we are interested in. The provided hostname determines the route configuration resources of interest.

type UpdateWithMD added in v1.37.0 

type UpdateWithMD struct {
	MD  UpdateMetadata
	Raw *anypb.Any
}

UpdateWithMD contains the raw message of the update and the metadata, including version, raw message, timestamp.

This is to be used for config dump and CSDS, not directly by users (like resolvers/balancers).

type VersionedClient added in v1.32.0 

type VersionedClient interface {
	// NewStream returns a new xDS client stream specific to the underlying
	// transport protocol version.
	NewStream(ctx context.Context) (grpc.ClientStream, error)

	// SendRequest constructs and sends out a DiscoveryRequest message specific
	// to the underlying transport protocol version.
	SendRequest(s grpc.ClientStream, resourceNames []string, rType ResourceType, version, nonce, errMsg string) error

	// RecvResponse uses the provided stream to receive a response specific to
	// the underlying transport protocol version.
	RecvResponse(s grpc.ClientStream) (proto.Message, error)

	// HandleResponse parses and validates the received response and notifies
	// the top-level client which in turn notifies the registered watchers.
	//
	// Return values are: resourceType, version, nonce, error.
	// If the provided protobuf message contains a resource type which is not
	// supported, implementations must return an error of type
	// ErrResourceTypeUnsupported.
	HandleResponse(proto.Message) (ResourceType, string, string, error)

	// NewLoadStatsStream returns a new LRS client stream specific to the underlying
	// transport protocol version.
	NewLoadStatsStream(ctx context.Context, cc *grpc.ClientConn) (grpc.ClientStream, error)

	// SendFirstLoadStatsRequest constructs and sends the first request on the
	// LRS stream.
	SendFirstLoadStatsRequest(s grpc.ClientStream) error

	// HandleLoadStatsResponse receives the first response from the server which
	// contains the load reporting interval and the clusters for which the
	// server asks the client to report load for.
	//
	// If the response sets SendAllClusters to true, the returned clusters is
	// nil.
	HandleLoadStatsResponse(s grpc.ClientStream) (clusters []string, _ time.Duration, _ error)

	// SendLoadStatsRequest will be invoked at regular intervals to send load
	// report with load data reported since the last time this method was
	// invoked.
	SendLoadStatsRequest(s grpc.ClientStream, loads []*load.Data) error
}

VersionedClient is the interface to be provided by the transport protocol specific client implementations. This mainly deals with the actual sending and receiving of messages.

type VirtualHost added in v1.34.0 

type VirtualHost struct {
	Domains []string
	// Routes contains a list of routes, each containing matchers and
	// corresponding action.
	Routes []*Route
	// HTTPFilterConfigOverride contains any HTTP filter config overrides for
	// the virtual host which may be present.  An individual filter's override
	// may be unused if the matching Route contains an override for that
	// filter.
	HTTPFilterConfigOverride map[string]httpfilter.FilterConfig
}

VirtualHost contains the routes for a list of Domains.

Note that the domains in this slice can be a wildcard, not an exact string. The consumer of this struct needs to find the best match for its hostname.

type WeightedCluster added in v1.37.0 

type WeightedCluster struct {
	// Weight is the relative weight of the cluster.  It will never be zero.
	Weight uint32
	// HTTPFilterConfigOverride contains any HTTP filter config overrides for
	// the weighted cluster which may be present.
	HTTPFilterConfigOverride map[string]httpfilter.FilterConfig
}

WeightedCluster contains settings for an xds RouteAction.WeightedCluster.

Source Files

View all Source files

Directories

Path Synopsis
Package bootstrap provides the functionality to initialize certain aspects of an xDS client by reading a bootstrap file.
 Package bootstrap provides the functionality to initialize certain aspects of an xDS client by reading a bootstrap file.
Package load provides functionality to record and maintain load data.
 Package load provides functionality to record and maintain load data.
Package v2 provides xDS v2 transport protocol specific functionality.
 Package v2 provides xDS v2 transport protocol specific functionality.
Package v3 provides xDS v3 transport protocol specific functionality.
 Package v3 provides xDS v3 transport protocol specific functionality.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.