const (
// ClusterResourceTypeName represents the transport agnostic name for the
// cluster resource.
ClusterResourceTypeName = "ClusterResource"
)
const (
// EndpointsResourceTypeName represents the transport agnostic name for the
// endpoint resource.
EndpointsResourceTypeName = "EndpointsResource"
)
FederationScheme is the scheme of a federation resource name.
const FederationScheme = "xdstp"
const (
// ListenerResourceTypeName represents the transport agnostic name for the
// listener resource.
ListenerResourceTypeName = "ListenerResource"
)
const (
// RouteConfigTypeName represents the transport agnostic name for the
// route config resource.
RouteConfigTypeName = "RouteConfigResource"
)
RandInt63n overwrites grpcrand for control in tests.
var RandInt63n = grpcrand.Int63n
ValidateClusterAndConstructClusterUpdateForTesting exports the validateClusterAndConstructClusterUpdate function for testing purposes.
var ValidateClusterAndConstructClusterUpdateForTesting = validateClusterAndConstructClusterUpdate
func IsClusterResource(url string) bool
IsClusterResource returns true if the provider URL corresponds to an xDS Cluster resource.
func IsEndpointsResource(url string) bool
IsEndpointsResource returns true if the provider URL corresponds to an xDS Endpoints resource.
func IsHTTPConnManagerResource(url string) bool
IsHTTPConnManagerResource returns true if the provider URL corresponds to an xDS HTTPConnManager resource.
func IsListenerResource(url string) bool
IsListenerResource returns true if the provider URL corresponds to an xDS Listener resource.
func IsRouteConfigResource(url string) bool
IsRouteConfigResource returns true if the provider URL corresponds to an xDS RouteConfig resource.
func NewErrorf(t ErrorType, format string, args ...any) error
NewErrorf creates an xds client error. The callbacks are called with this error, to pass additional information about the error.
func UnwrapResource(r *anypb.Any) (*anypb.Any, error)
UnwrapResource unwraps and returns the inner resource if it's in a resource wrapper. The original resource is returned if it's not wrapped.
func WatchCluster(p Producer, name string, w ClusterWatcher) (cancel func())
WatchCluster uses xDS to discover the configuration associated with the provided cluster resource name.
func WatchEndpoints(p Producer, name string, w EndpointsWatcher) (cancel func())
WatchEndpoints uses xDS to discover the configuration associated with the provided endpoints resource name.
func WatchListener(p Producer, name string, w ListenerWatcher) (cancel func())
WatchListener uses xDS to discover the configuration associated with the provided listener resource name.
func WatchRouteConfig(p Producer, name string, w RouteConfigWatcher) (cancel func())
WatchRouteConfig uses xDS to discover the configuration associated with the provided route configuration resource name.
ClusterResourceData wraps the configuration of a Cluster resource as received from the management server.
Implements the ResourceData interface.
type ClusterResourceData struct {
ResourceData
// TODO: We have always stored update structs by value. See if this can be
// switched to a pointer?
Resource ClusterUpdate
}
func (c *ClusterResourceData) Equal(other ResourceData) bool
Equal returns true if other is equal to r.
func (c *ClusterResourceData) Raw() *anypb.Any
Raw returns the underlying raw protobuf form of the cluster resource.
func (c *ClusterResourceData) ToJSON() string
ToJSON returns a JSON string representation of the resource data.
ClusterType is the type of cluster from a received CDS response.
type ClusterType int
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
)
ClusterUpdate contains information from a received CDS response, which is of interest to the registered CDS watcher.
type ClusterUpdate struct {
ClusterType ClusterType
// ClusterName is the clusterName being watched for through CDS.
ClusterName string
// EDSServiceName is an optional name for EDS. If it's not set, the balancer
// should watch ClusterName for the EDS resources.
EDSServiceName string
// LRSServerConfig contains configuration about the xDS server that sent
// this cluster resource. This is also the server where load reports are to
// be sent, for this cluster.
LRSServerConfig *bootstrap.ServerConfig
// SecurityCfg contains security configuration sent by the control plane.
SecurityCfg *SecurityConfig
// MaxRequests for circuit breaking, if any (otherwise nil).
MaxRequests *uint32
// DNSHostName is used only for cluster type DNS. It's the DNS name to
// resolve in "host:port" form
DNSHostName string
// PrioritizedClusterNames is used only for cluster type aggregate. It represents
// a prioritized list of cluster names.
PrioritizedClusterNames []string
// LBPolicy represents the locality and endpoint picking policy in JSON,
// which will be the child policy of xds_cluster_impl.
LBPolicy json.RawMessage
// OutlierDetection is the outlier detection configuration for this cluster.
// If nil, it means this cluster does not use the outlier detection feature.
OutlierDetection json.RawMessage
// Raw is the resource from the xds response.
Raw *anypb.Any
// TelemetryLabels are the string valued metadata of filter_metadata type
// "com.google.csm.telemetry_labels" with keys "service_name" or
// "service_namespace".
TelemetryLabels map[string]string
}
ClusterWatcher wraps the callbacks to be invoked for different events corresponding to the cluster resource being watched.
type ClusterWatcher interface {
// OnUpdate is invoked to report an update for the resource being watched.
OnUpdate(*ClusterResourceData)
// OnError is invoked under different error conditions including but not
// limited to the following:
// - authority mentioned in the resource is not found
// - resource name parsing error
// - resource deserialization error
// - resource validation error
// - ADS stream failure
// - connection failure
OnError(error)
// OnResourceDoesNotExist is invoked for a specific error condition where
// the requested resource is not found on the xDS management server.
OnResourceDoesNotExist()
}
CompositeMatcher is a matcher that holds onto many matchers and aggregates the matching results.
type CompositeMatcher struct {
// contains filtered or unexported fields
}
func RouteToMatcher(r *Route) (*CompositeMatcher, error)
RouteToMatcher converts a route to a Matcher to match incoming RPC's against.
func (a *CompositeMatcher) Match(info iresolver.RPCInfo) bool
Match returns true if all matchers return true.
func (a *CompositeMatcher) String() string
DecodeOptions wraps the options required by ResourceType implementation for decoding configuration received from the xDS management server.
type DecodeOptions struct {
// BootstrapConfig contains the complete bootstrap configuration passed to
// the xDS client. This contains useful data for resource validation.
BootstrapConfig *bootstrap.Config
// ServerConfig contains the server config (from the above bootstrap
// configuration) of the xDS server from which the current resource, for
// which Decode() is being invoked, was received.
ServerConfig *bootstrap.ServerConfig
}
DecodeResult is the result of a decode operation.
type DecodeResult struct {
// Name is the name of the resource being watched.
Name string
// Resource contains the configuration associated with the resource being
// watched.
Resource ResourceData
}
Endpoint contains information of an endpoint.
type Endpoint struct {
Address string
HealthStatus EndpointHealthStatus
Weight uint32
}
EndpointHealthStatus represents the health status of an endpoint.
type EndpointHealthStatus int32
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
)
EndpointsResourceData wraps the configuration of an Endpoints resource as received from the management server.
Implements the ResourceData interface.
type EndpointsResourceData struct {
ResourceData
// TODO: We have always stored update structs by value. See if this can be
// switched to a pointer?
Resource EndpointsUpdate
}
func (e *EndpointsResourceData) Equal(other ResourceData) bool
Equal returns true if other is equal to r.
func (e *EndpointsResourceData) Raw() *anypb.Any
Raw returns the underlying raw protobuf form of the listener resource.
func (e *EndpointsResourceData) ToJSON() string
ToJSON returns a JSON string representation of the resource data.
EndpointsUpdate contains an EDS update.
type EndpointsUpdate struct {
Drops []OverloadDropConfig
// Localities in the EDS response with `load_balancing_weight` field not set
// or explicitly set to 0 are ignored while parsing the resource, and
// therefore do not show up here.
Localities []Locality
// Raw is the resource from the xds response.
Raw *anypb.Any
}
EndpointsWatcher wraps the callbacks to be invoked for different events corresponding to the endpoints resource being watched.
type EndpointsWatcher interface {
// OnUpdate is invoked to report an update for the resource being watched.
OnUpdate(*EndpointsResourceData)
// OnError is invoked under different error conditions including but not
// limited to the following:
// - authority mentioned in the resource is not found
// - resource name parsing error
// - resource deserialization error
// - resource validation error
// - ADS stream failure
// - connection failure
OnError(error)
// OnResourceDoesNotExist is invoked for a specific error condition where
// the requested resource is not found on the xDS management server.
OnResourceDoesNotExist()
}
ErrorType is the type of the error that the watcher will receive from the xds client.
type ErrorType int
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
// ErrorTypeResourceTypeUnsupported indicates the receipt of a message from
// the management server with resources of an unsupported resource type.
ErrorTypeResourceTypeUnsupported
// ErrTypeStreamFailedAfterRecv indicates an ADS stream error, after
// successful receipt of at least one message from the server.
ErrTypeStreamFailedAfterRecv
)
func ErrType(e error) ErrorType
ErrType returns the error's type.
FilterChain captures information from within a FilterChain message in a Listener resource.
type FilterChain struct {
// SecurityCfg contains transport socket security configuration.
SecurityCfg *SecurityConfig
// HTTPFilters represent the HTTP Filters that comprise this FilterChain.
HTTPFilters []HTTPFilter
// RouteConfigName is the route configuration name for this FilterChain.
//
// Exactly one of RouteConfigName and InlineRouteConfig is set.
RouteConfigName string
// InlineRouteConfig is the inline route configuration (RDS response)
// returned for this filter chain.
//
// Exactly one of RouteConfigName and InlineRouteConfig is set.
InlineRouteConfig *RouteConfigUpdate
// UsableRouteConfiguration is the routing configuration for this filter
// chain (LDS + RDS).
UsableRouteConfiguration *atomic.Pointer[UsableRouteConfiguration]
}
func (fc *FilterChain) ConstructUsableRouteConfiguration(config RouteConfigUpdate) *UsableRouteConfiguration
ConstructUsableRouteConfiguration takes Route Configuration and converts it into matchable route configuration, with instantiated HTTP Filters per route.
FilterChainLookupParams wraps parameters to be passed to Lookup.
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
}
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:
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.
type FilterChainManager struct {
// RouteConfigNames are the route configuration names which need to be
// dynamically queried for RDS Configuration for any FilterChains which
// specify to load RDS Configuration dynamically.
RouteConfigNames map[string]bool
// contains filtered or unexported fields
}
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 (fcm *FilterChainManager) FilterChains() []*FilterChain
FilterChains returns the filter chains for this filter chain manager.
func (fcm *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.
func (fcm *FilterChainManager) Validate(f func(fc *FilterChain) error) error
Validate takes a function to validate the FilterChains in this manager.
HTTPFilter represents one HTTP filter from an LDS response's HTTP connection manager field.
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
}
HashPolicy specifies the HashPolicy if the upstream cluster uses a hashing load balancer.
type HashPolicy struct {
HashPolicyType HashPolicyType
Terminal bool
// Fields used for type HEADER.
HeaderName string
Regex *regexp.Regexp
RegexSubstitution string
}
HashPolicyType specifies the type of HashPolicy from a received RDS Response.
type HashPolicyType int
const (
// HashPolicyTypeHeader specifies to hash a Header in the incoming request.
HashPolicyTypeHeader HashPolicyType = iota
// HashPolicyTypeChannelID specifies to hash a unique Identifier of the
// Channel. This is a 64-bit random int computed at initialization time.
HashPolicyTypeChannelID
)
HeaderMatcher represents header matchers.
type HeaderMatcher struct {
Name string
InvertMatch *bool
ExactMatch *string
RegexMatch *regexp.Regexp
PrefixMatch *string
SuffixMatch *string
RangeMatch *Int64Range
PresentMatch *bool
StringMatch *matcher.StringMatcher
}
InboundListenerConfig contains information about the inbound listener, i.e the server-side listener.
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
}
Int64Range is a range for header range match.
type Int64Range struct {
Start int64
End int64
}
ListenerResourceData wraps the configuration of a Listener resource as received from the management server.
Implements the ResourceData interface.
type ListenerResourceData struct {
ResourceData
// TODO: We have always stored update structs by value. See if this can be
// switched to a pointer?
Resource ListenerUpdate
}
func (l *ListenerResourceData) Equal(other ResourceData) bool
Equal returns true if other is equal to l.
func (l *ListenerResourceData) Raw() *anypb.Any
Raw returns the underlying raw protobuf form of the listener resource.
func (l *ListenerResourceData) ToJSON() string
ToJSON returns a JSON string representation of the resource data.
ListenerUpdate contains information received in an LDS response, which is of interest to the registered LDS watcher.
type ListenerUpdate struct {
// RouteConfigName is the route configuration name corresponding to the
// target which is being watched through LDS.
//
// Exactly one of RouteConfigName and InlineRouteConfig is set.
RouteConfigName string
// InlineRouteConfig is the inline route configuration (RDS response)
// returned inside LDS.
//
// Exactly 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
}
ListenerWatcher wraps the callbacks to be invoked for different events corresponding to the listener resource being watched.
type ListenerWatcher interface {
// OnUpdate is invoked to report an update for the resource being watched.
OnUpdate(*ListenerResourceData)
// OnError is invoked under different error conditions including but not
// limited to the following:
// - authority mentioned in the resource is not found
// - resource name parsing error
// - resource deserialization error
// - resource validation error
// - ADS stream failure
// - connection failure
OnError(error)
// OnResourceDoesNotExist is invoked for a specific error condition where
// the requested resource is not found on the xDS management server.
OnResourceDoesNotExist()
}
Locality contains information of a locality.
type Locality struct {
Endpoints []Endpoint
ID internal.LocalityID
Priority uint32
Weight uint32
}
Name contains the parsed component of an xDS resource name.
An xDS resource name is in the format of xdstp://[{authority}]/{resource type}/{id/*}?{context parameters}{#processing directive,*}
See https://github.com/cncf/xds/blob/main/proposals/TP1-xds-transport-next.md#uri-based-xds-resource-names for details, and examples.
type Name struct {
Scheme string
Authority string
Type string
ID string
ContextParams map[string]string
// contains filtered or unexported fields
}
func ParseName(name string) *Name
ParseName splits the name and returns a struct representation of the Name.
If the name isn't a valid new-style xDS name, field ID is set to the input. Note that this is not an error, because we still support the old-style resource names (those not starting with "xdstp:").
The caller can tell if the parsing is successful by checking the returned Scheme.
func (n *Name) String() string
String returns a canonicalized string of name. The context parameters are sorted by the keys.
OverloadDropConfig contains the config to drop overloads.
type OverloadDropConfig struct {
Category string
Numerator uint32
Denominator uint32
}
Producer contains a single method to discover resource configuration from a remote management server using xDS APIs.
The xdsclient package provides a concrete implementation of this interface.
type Producer interface {
// WatchResource uses xDS to discover the resource associated with the
// provided resource name. The resource type implementation determines how
// xDS requests are sent out and how responses are deserialized and
// validated. Upon receipt of a response from the management server, an
// appropriate callback on the watcher is invoked.
WatchResource(rType Type, resourceName string, watcher ResourceWatcher) (cancel func())
}
ResourceData contains the configuration data sent by the xDS management server, associated with the resource being watched. Every resource type must provide an implementation of this interface to represent the configuration received from the xDS management server.
type ResourceData interface {
// Equal returns true if the passed in resource data is equal to that of the
// receiver.
Equal(ResourceData) bool
// ToJSON returns a JSON string representation of the resource data.
ToJSON() string
Raw() *anypb.Any
// contains filtered or unexported methods
}
ResourceWatcher wraps the callbacks to be invoked for different events corresponding to the resource being watched.
type ResourceWatcher interface {
// OnUpdate is invoked to report an update for the resource being watched.
// The ResourceData parameter needs to be type asserted to the appropriate
// type for the resource being watched.
OnUpdate(ResourceData)
// OnError is invoked under different error conditions including but not
// limited to the following:
// - authority mentioned in the resource is not found
// - resource name parsing error
// - resource deserialization error
// - resource validation error
// - ADS stream failure
// - connection failure
OnError(error)
// OnResourceDoesNotExist is invoked for a specific error condition where
// the requested resource is not found on the xDS management server.
OnResourceDoesNotExist()
}
RetryBackoff describes the backoff policy for retries.
type RetryBackoff struct {
BaseInterval time.Duration // initial backoff duration between attempts
MaxInterval time.Duration // maximum backoff duration
}
RetryConfig contains all retry-related configuration in either a VirtualHost or Route.
type RetryConfig struct {
// RetryOn is a set of status codes on which to retry. Only Canceled,
// DeadlineExceeded, Internal, ResourceExhausted, and Unavailable are
// supported; any other values will be omitted.
RetryOn map[codes.Code]bool
NumRetries uint32 // maximum number of retry attempts
RetryBackoff RetryBackoff // retry backoff policy
}
Route is both a specification of how to match a request as well as an indication of the action to take upon match.
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
HashPolicies []*HashPolicy
// If the matchers above indicate a match, the below configuration is used.
// 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
RetryConfig *RetryConfig
ActionType RouteActionType
// Only one of the following fields (WeightedClusters or
// ClusterSpecifierPlugin) will be set for a route.
WeightedClusters map[string]WeightedCluster
// ClusterSpecifierPlugin is the name of the Cluster Specifier Plugin that
// this Route is linked to, if specified by xDS.
ClusterSpecifierPlugin string
}
RouteActionType is the action of the route from a received RDS response.
type RouteActionType int
const (
// RouteActionUnsupported are routing types currently unsupported by grpc.
// According to A36, "A Route with an inappropriate action causes RPCs
// matching that route to fail."
RouteActionUnsupported RouteActionType = iota
// RouteActionRoute is the expected route type on the client side. Route
// represents routing a request to some upstream cluster. On the client
// side, if an RPC matches to a route that is not RouteActionRoute, the RPC
// will fail according to A36.
RouteActionRoute
// RouteActionNonForwardingAction is the expected route type on the server
// side. NonForwardingAction represents when a route will generate a
// response directly, without forwarding to an upstream host.
RouteActionNonForwardingAction
)
RouteConfigResourceData wraps the configuration of a RouteConfiguration resource as received from the management server.
Implements the ResourceData interface.
type RouteConfigResourceData struct {
ResourceData
// TODO: We have always stored update structs by value. See if this can be
// switched to a pointer?
Resource RouteConfigUpdate
}
func (r *RouteConfigResourceData) Equal(other ResourceData) bool
Equal returns true if other is equal to r.
func (r *RouteConfigResourceData) Raw() *anypb.Any
Raw returns the underlying raw protobuf form of the route configuration resource.
func (r *RouteConfigResourceData) ToJSON() string
ToJSON returns a JSON string representation of the resource data.
RouteConfigUpdate contains information received in an RDS response, which is of interest to the registered RDS watcher.
type RouteConfigUpdate struct {
VirtualHosts []*VirtualHost
// ClusterSpecifierPlugins are the LB Configurations for any
// ClusterSpecifierPlugins referenced by the Route Table.
ClusterSpecifierPlugins map[string]clusterspecifier.BalancerConfig
// Raw is the resource from the xds response.
Raw *anypb.Any
}
RouteConfigWatcher wraps the callbacks to be invoked for different events corresponding to the route configuration resource being watched.
type RouteConfigWatcher interface {
// OnUpdate is invoked to report an update for the resource being watched.
OnUpdate(*RouteConfigResourceData)
// OnError is invoked under different error conditions including but not
// limited to the following:
// - authority mentioned in the resource is not found
// - resource name parsing error
// - resource deserialization error
// - resource validation error
// - ADS stream failure
// - connection failure
OnError(error)
// OnResourceDoesNotExist is invoked for a specific error condition where
// the requested resource is not found on the xDS management server.
OnResourceDoesNotExist()
}
RouteWithInterceptors captures information in a Route, and contains a usable matcher and also instantiated HTTP Filters.
type RouteWithInterceptors struct {
// M is the matcher used to match to this route.
M *CompositeMatcher
// ActionType is the type of routing action to initiate once matched to.
ActionType RouteActionType
// Interceptors are interceptors instantiated for this route. These will be
// constructed from a combination of the top level configuration and any
// HTTP Filter overrides present in Virtual Host or Route.
Interceptors []resolver.ServerInterceptor
}
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 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 []matcher.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
}
func (sc *SecurityConfig) Equal(other *SecurityConfig) bool
Equal returns true if sc is equal to other.
ServiceStatus is the status of the update.
type ServiceStatus int
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
)
SourceType specifies the connection source IP match type.
type SourceType int
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 wraps all resource-type specific functionality. Each supported resource type will provide an implementation of this interface.
type Type interface {
// TypeURL is the xDS type URL of this resource type for v3 transport.
TypeURL() string
// TypeName identifies resources in a transport protocol agnostic way. This
// can be used for logging/debugging purposes, as well in cases where the
// resource type name is to be uniquely identified but the actual
// functionality provided by the resource type is not required.
//
// TODO: once Type is renamed to ResourceType, rename TypeName to
// ResourceTypeName.
TypeName() string
// AllResourcesRequiredInSotW indicates whether this resource type requires
// that all resources be present in every SotW response from the server. If
// true, a response that does not include a previously seen resource will be
// interpreted as a deletion of that resource.
AllResourcesRequiredInSotW() bool
// Decode deserializes and validates an xDS resource serialized inside the
// provided `Any` proto, as received from the xDS management server.
//
// If protobuf deserialization fails or resource validation fails,
// returns a non-nil error. Otherwise, returns a fully populated
// DecodeResult.
Decode(*DecodeOptions, *anypb.Any) (*DecodeResult, error)
}
UpdateErrorMetadata is part of UpdateMetadata. It contains the error state when a response is NACKed.
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
}
UpdateMetadata contains the metadata for each update, including timestamp, raw message, and so on.
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
}
UpdateValidatorFunc performs validations on update structs using context/logic available at the xdsClient layer. Since these validation are performed on internal update structs, they can be shared between different API clients.
type UpdateValidatorFunc func(any) error
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 UpdateWithMD struct {
MD UpdateMetadata
Raw *anypb.Any
}
UsableRouteConfiguration contains a matchable route configuration, with instantiated HTTP Filters per route.
type UsableRouteConfiguration struct {
VHS []VirtualHostWithInterceptors
Err error
}
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 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
RetryConfig *RetryConfig
}
func FindBestMatchingVirtualHost(host string, vHosts []*VirtualHost) *VirtualHost
FindBestMatchingVirtualHost returns the virtual host whose domains field best matches host
The domains field support 4 different matching pattern types:
- Exact match
- Suffix match (e.g. “*ABC”)
- Prefix match (e.g. “ABC*)
- Universal match (e.g. “*”)
The best match is defined as:
- A match is better if it’s matching pattern type is better.
* Exact match > suffix match > prefix match > universal match.
- If two matches are of the same pattern type, the longer match is
better.
* This is to compare the length of the matching pattern, e.g. “*ABCDE” >
“*ABC”
VirtualHostWithInterceptors captures information present in a VirtualHost update, and also contains routes with instantiated HTTP Filters.
type VirtualHostWithInterceptors struct {
// Domains are the domain names which map to this Virtual Host. On the
// server side, this will be dictated by the :authority header of the
// incoming RPC.
Domains []string
// Routes are the Routes for this Virtual Host.
Routes []RouteWithInterceptors
}
func FindBestMatchingVirtualHostServer(authority string, vHosts []VirtualHostWithInterceptors) *VirtualHostWithInterceptors
FindBestMatchingVirtualHostServer returns the virtual host whose domains field best matches authority.
WeightedCluster contains settings for an xds ActionType.WeightedCluster.
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
}
| Name | Synopsis |
|---|---|
| .. | |