cache

Documentation

Overview

Package cache defines a configuration cache for the server.

Index

• Variables
• func IndexResourcesByName(items []Resource) map[string]Resource
• func NewStatusInfo(node *envoy_config_core_v3.Node) *statusInfo
• func Superset(names map[string]bool, resources map[string]Resource) error
• type Cache
• type ConfigWatcher
• type GenericSnapshot
  • func NewEasyGenericSnapshot(version string, resources ...[]Resource) *GenericSnapshot
  • func NewGenericSnapshot(resources TypedResources) *GenericSnapshot
  • func (s *GenericSnapshot) Clone() Snapshot
  • func (s *GenericSnapshot) Combine(a *GenericSnapshot) (*GenericSnapshot, error)
  • func (s *GenericSnapshot) Consistent() error
  • func (s *GenericSnapshot) GetResources(typ string) Resources
  • func (s *GenericSnapshot) Merge(newSnap *GenericSnapshot) (*GenericSnapshot, error)
• type NilSnapshot
  • func (NilSnapshot) Clone() Snapshot
  • func (NilSnapshot) Consistent() error
  • func (NilSnapshot) GetResources(typ string) Resources
• type NodeHash
• type Request
• type Resource
• type ResourceProto
• type Resources
  • func NewResources(version string, items []Resource) Resources
• type Response
• type ResponseWatch
• type Snapshot
• type SnapshotCache
  • func NewSnapshotCache(ads bool, hash NodeHash, logger log.Logger) SnapshotCache
• type StatusInfo
• type TypedResources
• type XdsResourceReference

Variables

var (
	MResponses = stats.Int64("xds/responses", "The responses for envoy", "1")

	KeyType = tag.MustNewKey("type")

	ResponsesView = &view.View{
		Name:        "xds/responses",
		Measure:     MResponses,
		Description: "The times gloo responded to xds request",
		Aggregation: view.Count(),
		TagKeys: []tag.Key{
			KeyType,
		},
	}

	VersionUpToDateError = errors.New("skip fetch: version up to date")
)

Functions

func IndexResourcesByName

func IndexResourcesByName(items []Resource) map[string]Resource

IndexResourcesByName creates a map from the resource name to the resource.

func NewStatusInfo

func NewStatusInfo(node *envoy_config_core_v3.Node) *statusInfo

NewStatusInfo initializes a status info data structure.

func Superset

func Superset(names map[string]bool, resources map[string]Resource) error

Superset checks that all resources are listed in the names set.

Types

type Cache

type Cache interface {
	ConfigWatcher

	// Fetch implements the polling method of the config cache using a non-empty request.
	Fetch(context.Context, Request) (*Response, error)

	// GetStatusInfo retrieves status information for a node ID.
	GetStatusInfo(string) StatusInfo
	//
	// // GetStatusKeys retrieves node IDs for all statuses.
	GetStatusKeys() []string
}

Cache is a generic config cache with a watcher.

type ConfigWatcher

type ConfigWatcher interface {
	// CreateWatch returns a new open watch from a non-empty request.
	//
	// Value channel produces requested resources, once they are available.  If
	// the channel is closed prior to cancellation of the watch, an unrecoverable
	// error has occurred in the producer, and the consumer should close the
	// corresponding stream.
	//
	// Cancel is an optional function to release resources in the producer. If
	// provided, the consumer may call this function multiple times.
	CreateWatch(Request) (value chan Response, cancel func())
}

ConfigWatcher requests watches for configuration resources by a node, last applied version identifier, and resource names hint. The watch should send the responses when they are ready. The watch can be cancelled by the consumer, in effect terminating the watch for the request. ConfigWatcher implementation must be thread-safe.

type GenericSnapshot

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

func NewEasyGenericSnapshot

func NewEasyGenericSnapshot(version string, resources ...[]Resource) *GenericSnapshot

func NewGenericSnapshot

func NewGenericSnapshot(resources TypedResources) *GenericSnapshot

NewSnapshot creates a snapshot from response types and a version.

func (*GenericSnapshot) Clone

func (s *GenericSnapshot) Clone() Snapshot

func (*GenericSnapshot) Combine

func (s *GenericSnapshot) Combine(a *GenericSnapshot) (*GenericSnapshot, error)

Combine snapshots with distinct types to one.

func (*GenericSnapshot) Consistent

func (s *GenericSnapshot) Consistent() error

func (*GenericSnapshot) GetResources

func (s *GenericSnapshot) GetResources(typ string) Resources

GetResources selects snapshot resources by type.

func (*GenericSnapshot) Merge

func (s *GenericSnapshot) Merge(newSnap *GenericSnapshot) (*GenericSnapshot, error)

Combine snapshots with distinct types to one.

type NilSnapshot

type NilSnapshot struct{}

func (NilSnapshot) Clone

func (NilSnapshot) Clone() Snapshot

func (NilSnapshot) Consistent

func (NilSnapshot) Consistent() error

func (NilSnapshot) GetResources

func (NilSnapshot) GetResources(typ string) Resources

type NodeHash

type NodeHash interface {
	// ID function defines a unique string identifier for the remote Envoy node.
	ID(node *envoy_config_core_v3.Node) string
}

NodeHash computes string identifiers for Envoy nodes.

type Request

type Request = envoy_service_discovery_v3.DiscoveryRequest

Request is an alias for the discovery request type.

type Resource

type Resource interface {
	Self() XdsResourceReference
	ResourceProto() ResourceProto
	References() []XdsResourceReference
}

type ResourceProto

type ResourceProto = proto.Message

type Resources

type Resources struct {
	// Version information.
	Version string

	// Items in the group.
	Items map[string]Resource
}

Resources is a versioned group of resources.

func NewResources

func NewResources(version string, items []Resource) Resources

NewResources creates a new resource group.

type Response

type Response struct {
	// Request is the original request.
	Request envoy_service_discovery_v3.DiscoveryRequest

	// Version of the resources as tracked by the cache for the given type.
	// Proxy responds with this version as an acknowledgement.
	Version string

	// Resources to be included in the response.
	Resources []Resource
}

Response is a pre-serialized xDS response.

type ResponseWatch

type ResponseWatch struct {
	// Request is the original request for the watch.
	Request Request

	// Response is the channel to push response to.
	Response chan Response
}

ResponseWatch is a watch record keeping both the request and an open channel for the response.

type Snapshot

type Snapshot interface {
	Consistent() error
	GetResources(typ string) Resources
	Clone() Snapshot
}

type SnapshotCache

type SnapshotCache interface {
	Cache

	// SetSnapshot sets a response snapshot for a node. For ADS, the snapshots
	// should have distinct versions and be internally consistent (e.g. all
	// referenced resources must be included in the snapshot).
	//
	// This method will cause the server to respond to all open watches, for which
	// the version differs from the snapshot version.
	SetSnapshot(node string, snapshot Snapshot) error

	// GetSnapshots gets the snapshot for a node.
	GetSnapshot(node string) (Snapshot, error)

	// ClearSnapshot removes all status and snapshot information associated with a node.
	ClearSnapshot(node string)
}

SnapshotCache is a snapshot-based cache that maintains a single versioned snapshot of responses per node. SnapshotCache consistently replies with the latest snapshot. For the protocol to work correctly in ADS mode, EDS/RDS requests are responded only when all resources in the snapshot xDS response are named as part of the request. It is expected that the CDS response names all EDS clusters, and the LDS response names all RDS routes in a snapshot, to ensure that Envoy makes the request for all EDS clusters or RDS routes eventually.

SnapshotCache can operate as a REST or regular xDS backend. The snapshot can be partial, e.g. only include RDS or EDS resources.

func NewSnapshotCache

func NewSnapshotCache(ads bool, hash NodeHash, logger log.Logger) SnapshotCache

NewSnapshotCache initializes a simple cache.

ADS flag forces a delay in responding to streaming requests until all resources are explicitly named in the request. This avoids the problem of a partial request over a single stream for a subset of resources which would require generating a fresh version for acknowledgement. ADS flag requires snapshot consistency. For non-ADS case (and fetch), mutliple partial requests are sent across multiple streams and re-using the snapshot version is OK.

Logger is optional.

type StatusInfo

type StatusInfo interface {
	// GetNode returns the node metadata.
	GetNode() *envoy_config_core_v3.Node

	// GetNumWatches returns the number of open watches.
	GetNumWatches() int

	// GetLastWatchRequestTime returns the timestamp of the last discovery watch request.
	GetLastWatchRequestTime() time.Time
}

StatusInfo tracks the server state for the remote Envoy node. Not all fields are used by all cache implementations.

type TypedResources

type TypedResources map[string]Resources

type XdsResourceReference

type XdsResourceReference struct {
	Type string
	Name string
}