ads

package
v0.2.12 Latest Latest
Warning

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

 Go to latest Published: Apr 15, 2025 License: BSD-2-Clause Imports: 20 Imported by: 0

Documentation

Overview

Package ads provides a set of utilities and definitions around the Aggregated Discovery Service xDS protocol (ADS), such as convenient type aliases, constants and core definitions.

Index

Examples

Constants

View Source 
const (
	// WildcardSubscription is a special resource name that triggers a subscription to all resources of a
	// given type.
	WildcardSubscription = "*"
	// XDSTPScheme is the prefix for which all resource URNs (as defined in the [TP1 proposal]) start.
	//
	// [TP1 proposal]: https://github.com/cncf/xds/blob/main/proposals/TP1-xds-transport-next.md#uri-based-xds-resource-names
	XDSTPScheme = "xdstp://"
)

Variables

View Source 
var ErrInvalidGlobCollectionURI = errors.New("diderot: invalid glob collection URI")

ErrInvalidGlobCollectionURI is always returned by the various glob collection URL parsing functions.

View Source 
var StreamTypes = [...]StreamType{UnknownStreamType, DeltaStreamType, SotWStreamType}

StreamTypes is an array containing the valid StreamType values.

Functions

func ParseRemainingChunksFromNonce added in v0.0.3 

func ParseRemainingChunksFromNonce(nonce string) (remainingChunks int, err error)

ParseRemainingChunksFromNonce checks whether the Diderot server implementation chunked the delta responses because not all resources could fit in the same response without going over the default max gRPC message size of 4MB. A nonce from Diderot always starts with the 64-bit nanosecond timestamp of when the response was generated on the server. Then the number of remaining chunks as a 32-bit integer. The sequence of integers is binary encoded with binary.BigEndian then hex encoded. If the given nonce does not match the expected format, this function simply returns 0 along with an error describing why it does not match. If the error isn't nil, it means the nonce was not created by a Diderot server implementation, and therefore does not contain the expected information.

Example 
package main

import (
	"log"

	"github.com/linkedin/diderot/ads"
)

func main() {
	// Acquire a delta ADS client
	var client ads.DeltaClient

	var responses []*ads.DeltaDiscoveryResponse
	for {
		res, err := client.Recv()
		if err != nil {
			log.Panicf("Error receiving delta response: %v", err)
		}
		responses = append(responses, res)

		if remaining, _ := ads.ParseRemainingChunksFromNonce(res.Nonce); remaining == 0 {
			break
		}
	}

	log.Printf("All responses received: %+v", responses)
}

Output:

Types

type Cluster 

type Cluster = cluster.Cluster

These aliases mirror the constants declared in github.com/envoyproxy/go-control-plane/pkg/resource/v3

type DeltaClient 

type DeltaClient = discovery.AggregatedDiscoveryService_DeltaAggregatedResourcesClient

DeltaClient is an alias for the delta client type discovery.AggregatedDiscoveryService_DeltaAggregatedResourcesClient.

type DeltaDiscoveryRequest 

type DeltaDiscoveryRequest = discovery.DeltaDiscoveryRequest

DeltaDiscoveryRequest is an alias for the delta request type discovery.DeltaDiscoveryRequest.

type DeltaDiscoveryResponse 

type DeltaDiscoveryResponse = discovery.DeltaDiscoveryResponse

DeltaDiscoveryResponse is an alias for the delta response type discovery.DeltaDiscoveryResponse.

type DeltaStream 

type DeltaStream = discovery.AggregatedDiscoveryService_DeltaAggregatedResourcesServer

DeltaStream is an alias for the delta (also known as incremental) stream type for the server discovery.AggregatedDiscoveryService_DeltaAggregatedResourcesServer.

type Endpoint 

type Endpoint = endpoint.ClusterLoadAssignment

These aliases mirror the constants declared in github.com/envoyproxy/go-control-plane/pkg/resource/v3

type ExtensionConfig 

type ExtensionConfig = core.TypedExtensionConfig

These aliases mirror the constants declared in github.com/envoyproxy/go-control-plane/pkg/resource/v3

type GlobCollectionURL 

type GlobCollectionURL struct {
	// The URL's authority. Optional when URL of form "xdstp:///{ResourceType}/{Path}".
	Authority string
	// The type of the resources in the collection, without the "type.googleapis.com/" prefix.
	ResourceType string
	// The collection's path, without the trailing /*
	Path string
	// Optionally, the context parameters associated with the collection, always sorted by key name. If
	// present, starts with "?".
	ContextParameters string
}

GlobCollectionURL represents the individual elements of a glob collection URL. Please refer to the TP1 Proposal for additional context on each field. In summary, a glob collection URL has the following format: 

xdstp://{Authority}/{ResourceType}/{Path}{?ContextParameters}

func NewGlobCollectionURL added in v0.2.0 

func NewGlobCollectionURL[T proto.Message](authority, path string, contextParameters url.Values) GlobCollectionURL

NewGlobCollectionURL creates a new GlobCollectionURL for the given type, authority, path and context parameters.

func ParseGlobCollectionURL 

func ParseGlobCollectionURL[T proto.Message](name string) (GlobCollectionURL, error)

ParseGlobCollectionURL attempts to parse the given name as GlobCollectionURL, returning an error if the given name does not represent one. See the TP1 proposal for additional context on the exact definition of a glob collection.

func ParseGlobCollectionURN added in v0.2.0 

func ParseGlobCollectionURN[T proto.Message](name string) (GlobCollectionURL, string, error)

ParseGlobCollectionURN checks if the given name is a resource URN, and returns the corresponding GlobCollectionURL. The format of a resource URN is defined in the TP1 proposal, and looks like this: 

xdstp://[{authority}]/{resource type}/{id/*}?{context parameters}

For example: 

xdstp://some-authority/envoy.config.listener.v3.Listener/foo/bar/baz

In the above example, the URN belongs to this collection: 

xdstp://authority/envoy.config.listener.v3.Listener/foo/bar/*

Note that in the above example, the URN does _not_ belong to the following collection: 

xdstp://authority/envoy.config.listener.v3.Listener/foo/*

Glob collections are not recursive, and the {id/?} segment of the URN (after the type) should be opaque, and not interpreted any further than the trailing /*. More details on this matter can be found here.

This function returns an error if the given name is not a resource URN.

func RawNewGlobCollectionURL added in v0.2.4 

func RawNewGlobCollectionURL(authority, typeURL, path string, contextParameters url.Values) GlobCollectionURL

RawNewGlobCollectionURL is the untyped equivalent of NewGlobCollectionURL.

func RawParseGlobCollectionURL added in v0.2.4 

func RawParseGlobCollectionURL(typeURL, name string) (GlobCollectionURL, error)

RawParseGlobCollectionURL is the untyped equivalent of ParseGlobCollectionURL.

func RawParseGlobCollectionURN added in v0.2.4 

func RawParseGlobCollectionURN(typeURL, name string) (GlobCollectionURL, string, error)

RawParseGlobCollectionURN is the untyped equivalent of ParseGlobCollectionURN.

func (GlobCollectionURL) MemberURN added in v0.2.0 

func (u GlobCollectionURL) MemberURN(name string) string

func (GlobCollectionURL) String 

func (u GlobCollectionURL) String() string

type LbEndpoint 

type LbEndpoint = endpoint.LbEndpoint

These aliases mirror the constants declared in github.com/envoyproxy/go-control-plane/pkg/resource/v3

type Listener 

type Listener = listener.Listener

These aliases mirror the constants declared in github.com/envoyproxy/go-control-plane/pkg/resource/v3

type Node 

type Node = core.Node

Node is an alias for the client information included in both Delta and SotW requests core.Node.

type RawResource 

type RawResource = discovery.Resource

RawResource is a type alias for the core ADS type discovery.Resource. It is "raw" only in contrast to the *Resource type defined in this package, which preserves the underlying resource's type as a generic parameter.

type RawSubscriptionHandler 

type RawSubscriptionHandler interface {
	// Notify is the untyped equivalent of SubscriptionHandler.Notify.
	Notify(name string, r *RawResource, metadata SubscriptionMetadata)
	// ResourceMarshalError is invoked whenever a resource cannot be marshaled. This should be extremely
	// rare and requires immediate attention. When a resource cannot be marshaled, the notification will
	// be dropped and Notify will not be invoked.
	ResourceMarshalError(name string, resource proto.Message, err error)
}

RawSubscriptionHandler is the untyped equivalent of SubscriptionHandler.

type Resource 

type Resource[T proto.Message] struct {
	Name         string
	Version      string
	Resource     T
	Ttl          *durationpb.Duration
	CacheControl *discovery.Resource_CacheControl
	Metadata     *core.Metadata
	// contains filtered or unexported fields
}

Resource is the typed equivalent of RawResource in that it preserves the underlying resource's type at compile time. It defines the same fields as RawResource (except for unsupported fields such as ads.RawResource.Aliases), and can be trivially serialized to a RawResource with Marshal. It is undefined behavior to modify a Resource after creation.

func NewResource 

func NewResource[T proto.Message](name, version string, t T) *Resource[T]

NewResource is a convenience method for creating a new *Resource.

func UnmarshalRawResource 

func UnmarshalRawResource[T proto.Message](raw *RawResource) (*Resource[T], error)

UnmarshalRawResource unmarshals the given RawResource and returns a Resource of the corresponding type. Resource.Marshal on the returned Resource will return the given RawResource instead of re-serializing the resource.

func (*Resource[T]) Equals added in v0.2.0 

func (r *Resource[T]) Equals(other *Resource[T]) bool

func (*Resource[T]) Marshal 

func (r *Resource[T]) Marshal() (*RawResource, error)

Marshal returns the serialized version of this Resource. Note that this result is cached, and can be called repeatedly and from multiple goroutines.

func (*Resource[T]) TypeURL 

func (r *Resource[T]) TypeURL() string

TypeURL returns the underlying resource's type URL.

type Route 

type Route = route.RouteConfiguration

These aliases mirror the constants declared in github.com/envoyproxy/go-control-plane/pkg/resource/v3

type Runtime 

type Runtime = runtime.Runtime

These aliases mirror the constants declared in github.com/envoyproxy/go-control-plane/pkg/resource/v3

type ScopedRoute 

type ScopedRoute = route.ScopedRouteConfiguration

These aliases mirror the constants declared in github.com/envoyproxy/go-control-plane/pkg/resource/v3

type Secret 

type Secret = tls.Secret

These aliases mirror the constants declared in github.com/envoyproxy/go-control-plane/pkg/resource/v3

type Server 

type Server = discovery.AggregatedDiscoveryServiceServer

Server is the core interface that needs to be implemented by an xDS control plane. The "Aggregated" service (i.e. ADS, the name of this package) service is type agnostic, the desired type is specified in the request. This avoids the need for clients to open multiple streams when requesting different types, along with not needing new service definitions such as github.com/envoyproxy/go-control-plane/envoy/service/endpoint/v3.EndpointDiscoveryServiceServer.

type SotWClient 

type SotWClient = discovery.AggregatedDiscoveryService_StreamAggregatedResourcesClient

SotWClient is an alias for the state-of-the-world client type discovery.AggregatedDiscoveryService_StreamAggregatedResourcesClient.

type SotWDiscoveryRequest 

type SotWDiscoveryRequest = discovery.DiscoveryRequest

SotWDiscoveryRequest is an alias for the state-of-the-world request type discovery.DiscoveryRequest.

type SotWDiscoveryResponse 

type SotWDiscoveryResponse = discovery.DiscoveryResponse

SotWDiscoveryResponse is an alias for the state-of-the-world response type discovery.DiscoveryResponse.

type SotWStream 

type SotWStream = discovery.AggregatedDiscoveryService_StreamAggregatedResourcesServer

SotWStream is an alias for the state-of-the-world stream type for the server discovery.AggregatedDiscoveryService_StreamAggregatedResourcesServer.

type StreamType 

type StreamType int

StreamType is an enum representing the different possible ADS stream types, SotW and Delta. 

const (
	// UnknownStreamType is the 0-value, unknown stream type.
	UnknownStreamType StreamType = iota
	// DeltaStreamType is the delta/incremental variant of the ADS protocol.
	DeltaStreamType
	// SotWStreamType is the state-of-the-world variant of the ADS protocol.
	SotWStreamType
)

func LookupStreamTypeByRPCMethod 

func LookupStreamTypeByRPCMethod(rpcMethod string) (StreamType, bool)

LookupStreamTypeByRPCMethod checks whether the given RPC method string (usually acquired from google.golang.org/grpc.StreamServerInfo.FullMethod in the context of a server stream interceptor) is either SotWStreamType or DeltaStreamType. Returns (UnknownStreamType, false) if it is neither.

func (StreamType) String 

func (t StreamType) String() string

type SubscriptionHandler 

type SubscriptionHandler[T proto.Message] interface {
	// Notify is invoked when the given entry is modified. A deletion is denoted with a nil resource. The given time
	// parameters provides the time at which the client subscribed to the resource and the time at which the
	// modification happened respectively. Note that if an entry is modified repeatedly at a high rate, Notify will not
	// be invoked for all intermediate versions, though it will always *eventually* be invoked with the final version.
	Notify(name string, r *Resource[T], metadata SubscriptionMetadata)
}

A SubscriptionHandler will receive notifications for the cache entries it has subscribed to using RawCache.Subscribe. Note that it is imperative that implementations be hashable as it will be stored as the key to a map (unhashable types include slices and functions).

type SubscriptionMetadata 

type SubscriptionMetadata struct {
	// The time at which the resource was subscribed to
	SubscribedAt time.Time
	// The time at which the resource was modified (can be UnknownModifiedTime if the modification time is unknown)
	ModifiedAt time.Time
	// The time at which the update to the resource was received by the cache (i.e. when [Cache.Set] was
	// called, not strictly when the server actually received the update). If this is metadata is for a
	// subscription to a resource that does not yet exist, will be UnknownModifiedTime.
	CachedAt time.Time
	// The current priority index of the value. Will be 0 unless the backing cache was created with
	// [NewPrioritizedCache], [NewPrioritizedAggregateCache] or
	// [NewPrioritizedAggregateCachesByClientTypes]. If this metadata is for a subscription to a resource
	// that has been deleted (or does not yet exist), Priority will be the last valid index priority
	// index (because a resource is only considered deleted once it has been deleted from all cache
	// sources). For example, if the cache was created like this:
	//	NewPrioritizedCache(10)
	// Then the last valid index is 9, since the slice of cache objects returned is of length 10.
	Priority int
	// The glob collection this resource belongs to, empty if it does not belong to any collections.
	GlobCollectionURL string
}

SubscriptionMetadata contains metadata about the subscription that triggered the Notify call on the RawSubscriptionHandler or SubscriptionHandler.

type VirtualHost 

type VirtualHost = route.VirtualHost

These aliases mirror the constants declared in github.com/envoyproxy/go-control-plane/pkg/resource/v3

Source Files

View all Source files

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.