client

Documentation

Overview

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

Index

• func NewErrorf(t ErrorType, format string, args ...interface{}) error
• type AddLocalityOptions
• type Client
  • func New(opts Options) (*Client, error)
  • func (c *Client) Close()
  • func (c *Client) ReportLoad(server string, clusterName string, loadStore lrs.Store) func()
  • func (c *Client) WatchCluster(clusterName string, cb func(ClusterUpdate, error)) (cancel func())
  • func (c *Client) WatchEndpoints(clusterName string, cb func(EndpointsUpdate, error)) (cancel func())
  • func (c *Client) WatchService(serviceName string, cb func(ServiceUpdate, error)) (cancel func())
• type ClusterLoadAssignmentBuilder
  • func NewClusterLoadAssignmentBuilder(clusterName string, dropPercents []uint32) *ClusterLoadAssignmentBuilder
  • func (clab *ClusterLoadAssignmentBuilder) AddLocality(subzone string, weight uint32, priority uint32, addrsWithPort []string, ...)
  • func (clab *ClusterLoadAssignmentBuilder) Build() *xdspb.ClusterLoadAssignment
• type ClusterUpdate
• type Endpoint
• type EndpointHealthStatus
• type EndpointsUpdate
  • func ParseEDSRespProto(m *xdspb.ClusterLoadAssignment) (EndpointsUpdate, error)
  • func ParseEDSRespProtoForTesting(m *xdspb.ClusterLoadAssignment) EndpointsUpdate
• type ErrorType
  • func ErrType(e error) ErrorType
• type HeaderMatcher
• type Int64Range
• type Locality
• type Options
• type OverloadDropConfig
• type Route
• type ServiceUpdate

Functions

func NewErrorf

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.

Types

type AddLocalityOptions

type AddLocalityOptions struct {
	Health []corepb.HealthStatus
	Weight []uint32
}

AddLocalityOptions contains options when adding locality to the builder.

type Client

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.

A single client object will be shared by the xds resolver and balancer implementations. But the same client can only be shared by the same parent ClientConn.

func New

func New(opts Options) (*Client, error)

New returns a new xdsClient configured with opts.

func (*Client) Close

func (c *Client) Close()

Close closes the gRPC connection to the xDS server.

func (*Client) ReportLoad

func (c *Client) ReportLoad(server string, clusterName string, loadStore lrs.Store) func()

ReportLoad sends the load of the given clusterName from loadStore to the given server. If the server is not an empty string, and is different from the xds 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 function to cancel the load reporting stream. If server is different from xds server, the ClientConn will also be closed.

func (*Client) WatchCluster

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

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) WatchService

func (c *Client) WatchService(serviceName string, cb func(ServiceUpdate, error)) (cancel func())

WatchService uses LDS and RDS to discover information about the provided serviceName.

WatchService can only be called once. The second call will not start a watcher and the callback will get an error. It's this case because an xDS client is expected to be used only by one ClientConn.

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 ClusterLoadAssignmentBuilder

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

ClusterLoadAssignmentBuilder builds a ClusterLoadAssignment, aka EDS response.

func NewClusterLoadAssignmentBuilder

func NewClusterLoadAssignmentBuilder(clusterName string, dropPercents []uint32) *ClusterLoadAssignmentBuilder

NewClusterLoadAssignmentBuilder creates a ClusterLoadAssignmentBuilder.

func (*ClusterLoadAssignmentBuilder) AddLocality

func (clab *ClusterLoadAssignmentBuilder) AddLocality(subzone string, weight uint32, priority uint32, addrsWithPort []string, opts *AddLocalityOptions)

AddLocality adds a locality to the builder.

func (*ClusterLoadAssignmentBuilder) Build

func (clab *ClusterLoadAssignmentBuilder) Build() *xdspb.ClusterLoadAssignment

Build builds ClusterLoadAssignment.

type ClusterUpdate

type ClusterUpdate struct {
	// 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
}

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

type Endpoint

type Endpoint struct {
	Address      string
	HealthStatus EndpointHealthStatus
	Weight       uint32
}

Endpoint contains information of an endpoint.

type EndpointHealthStatus

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

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

EndpointsUpdate contains an EDS update.

func ParseEDSRespProto

func ParseEDSRespProto(m *xdspb.ClusterLoadAssignment) (EndpointsUpdate, error)

ParseEDSRespProto turns EDS response proto message to EndpointsUpdate.

This is temporarily exported to be used in eds balancer, before it switches to use xds client. TODO: unexport.

func ParseEDSRespProtoForTesting

func ParseEDSRespProtoForTesting(m *xdspb.ClusterLoadAssignment) EndpointsUpdate

ParseEDSRespProtoForTesting parses EDS response, and panic if parsing fails. This is used by EDS balancer tests.

TODO: delete this. The EDS balancer tests should build an EndpointsUpdate directly,

instead of building and parsing a proto message.

type ErrorType

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

func ErrType(e error) ErrorType

ErrType returns the error's type.

type HeaderMatcher

type HeaderMatcher struct {
	Name         string      `json:"name"`
	InvertMatch  *bool       `json:"invertMatch,omitempty"`
	ExactMatch   *string     `json:"exactMatch,omitempty"`
	RegexMatch   *string     `json:"regexMatch,omitempty"`
	PrefixMatch  *string     `json:"prefixMatch,omitempty"`
	SuffixMatch  *string     `json:"suffixMatch,omitempty"`
	RangeMatch   *Int64Range `json:"rangeMatch,omitempty"`
	PresentMatch *bool       `json:"presentMatch,omitempty"`
}

HeaderMatcher represents header matchers.

type Int64Range

type Int64Range struct {
	Start int64 `json:"start"`
	End   int64 `json:"end"`
}

Int64Range is a range for header range match.

type Locality

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

Locality contains information of a locality.

type Options

type Options struct {
	// Config contains a fully populated bootstrap config. It is the
	// responsibility of the caller to use some sane defaults here if the
	// bootstrap process returned with certain fields left unspecified.
	Config bootstrap.Config
	// DialOpts contains dial options to be used when dialing the xDS server.
	DialOpts []grpc.DialOption
	// TargetName is the target of the parent ClientConn.
	TargetName string
}

Options provides all parameters required for the creation of an xDS client.

type OverloadDropConfig

type OverloadDropConfig struct {
	Category    string
	Numerator   uint32
	Denominator uint32
}

OverloadDropConfig contains the config to drop overloads.

type Route

type Route struct {
	Path, Prefix, Regex *string
	Headers             []*HeaderMatcher
	Fraction            *uint32
	Action              map[string]uint32 // action is weighted clusters.
}

Route represents route with matchers and action.

type ServiceUpdate

type ServiceUpdate struct {
	// WeightedCluster is a map from cluster names (CDS resource to watch) to
	// their weights.
	//
	// This field is only set when routing is disabled (env variable
	// GRPC_XDS_EXPERIMENTAL_ROUTING is not true).
	WeightedCluster map[string]uint32

	// Routes
	Routes []*Route
}

ServiceUpdate contains update about the service.