cache

type Cache interface {
	ConfigWatcher
	ConfigFetcher
}

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

type ConfigWatcher interface {
	// CreateWatch returns a new open watch from a non-empty request.
	// This is the entrypoint to propagate configuration changes the
	// provided Response channel. State from the gRPC server is utilized
	// to make sure consuming cache implementations can see what the server has sent to clients.
	//
	// An individual consumer normally issues a single open watch by each type URL.
	//
	// The provided channel produces requested resources as responses, once they are available.
	//
	// Cancel is an optional function to release resources in the producer. If
	// provided, the consumer may call this function multiple times.
	CreateWatch(*Request, Subscription, chan Response) (cancel func(), err error)

	// CreateDeltaWatch returns a new open incremental xDS watch.
	// This is the entrypoint to propagate configuration changes the
	// provided DeltaResponse channel. State from the gRPC server is utilized
	// to make sure consuming cache implementations can see what the server has sent to clients.
	//
	// The provided channel produces requested resources as responses, or spontaneous updates in accordance
	// with the incremental xDS specification.
	//
	// Cancel is an optional function to release resources in the producer. If
	// provided, the consumer may call this function multiple times.
	CreateDeltaWatch(*DeltaRequest, Subscription, chan DeltaResponse) (cancel func(), err error)
}

type DeltaPassthroughResponse struct {
	// Request is the latest delta request on the stream
	DeltaRequest *discovery.DeltaDiscoveryRequest

	// NextVersionMap consists of updated version mappings after this response is applied
	NextVersionMap map[string]string

	// This discovery response that needs to be sent as is, without any marshaling transformations
	DeltaDiscoveryResponse *discovery.DeltaDiscoveryResponse
	// contains filtered or unexported fields
}

type DeltaRequest = discovery.DeltaDiscoveryRequest

type DeltaResponse interface {
	// GetDeltaDiscoveryResponse returns the constructed DeltaDiscoveryResponse.
	GetDeltaDiscoveryResponse() (*discovery.DeltaDiscoveryResponse, error)

	// GetDeltaRequest returns the request that created the watch that we're now responding to.
	// This is provided to allow the caller to correlate the response with a request.
	// Generally this will be the latest request seen on the stream for the specific type.
	GetDeltaRequest() *discovery.DeltaDiscoveryRequest

	// GetSystemVersion returns the version in the DeltaResponse.
	// The version in delta response is not indicative of the resources included,
	// but an internal property of the cache which can be used for debugging.
	// Deprecated: use GetResponseVersion instead
	GetSystemVersion() (string, error)

	// GetResponseVersion returns the version in the DeltaResponse.
	// The version in delta response is not indicative of the resources included,
	// but an internal property of the cache which can be used for debugging.
	GetResponseVersion() string

	// GetNextVersionMap provides the version map of the internal cache.
	// The version map consists of updated version mappings after this response is applied.
	// Deprecated: use GetReturnedResources instead
	GetNextVersionMap() map[string]string

	// GetReturnedResources provides the version map of the internal cache.
	// The version map consists of updated version mappings after this response is applied.
	GetReturnedResources() map[string]string

	// GetContext returns the context provided during response creation.
	GetContext() context.Context
}

type DeltaResponseWatch struct {
	// Request is the most recent delta request for the watch
	Request *DeltaRequest

	// Response is the channel to push the delta responses to
	Response chan DeltaResponse
	// contains filtered or unexported fields
}

type IDHash struct{}

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

type LinearCacheOption func(*LinearCache)

type MuxCache struct {
	// Classification functions.
	Classify      func(*Request) string
	ClassifyDelta func(*DeltaRequest) string
	// Muxed caches.
	Caches map[string]Cache
}

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

type PassthroughResponse struct {
	// Request is the original request.
	Request *discovery.DiscoveryRequest

	// The discovery response that needs to be sent as is, without any marshaling transformations.
	DiscoveryResponse *discovery.DiscoveryResponse

	// ReturnedResources tracks the resources returned for the subscription and the version when it was last returned,
	// including previously returned ones when using non-full state resources.
	// It allows the cache to know what the client knows. The server will transparently forward this
	// across requests, and the cache is responsible for its interpretation.
	ReturnedResources map[string]string
	// contains filtered or unexported fields
}

type RawDeltaResponse struct {
	// Request is the latest delta request on the stream.
	DeltaRequest *discovery.DeltaDiscoveryRequest

	// SystemVersionInfo holds the currently applied response system version and should be used for debugging purposes only.
	SystemVersionInfo string

	// Context provided at the time of response creation. This allows associating additional
	// information with a generated response.
	Ctx context.Context
	// contains filtered or unexported fields
}

type RawResponse struct {
	// Request is the original request.
	Request *discovery.DiscoveryRequest

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

	// Whether this is a heartbeat response. For xDS versions that support TTL, this
	// will be converted into a response that doesn't contain the actual resource protobuf.
	// This allows for more lightweight updates that server only to update the TTL timer.
	Heartbeat bool

	// Context provided at the time of response creation. This allows associating additional
	// information with a generated response.
	Ctx context.Context
	// contains filtered or unexported fields
}

type Request = discovery.DiscoveryRequest

type ResourceSnapshot interface {
	// GetVersion should return the current version of the resource indicated
	// by typeURL. The version string that is returned is opaque and should
	// only be compared for equality.
	GetVersion(typeURL string) string

	// GetResourcesAndTTL returns all resources of the type indicted by
	// typeURL, together with their TTL.
	GetResourcesAndTTL(typeURL string) map[string]types.ResourceWithTTL

	// GetResources returns all resources of the type indicted by
	// typeURL. This is identical to GetResourcesAndTTL, except that
	// the TTL is omitted.
	GetResources(typeURL string) map[string]types.Resource

	// ConstructVersionMap is a hint that a delta watch will soon make a
	// call to GetVersionMap. The snapshot should construct an internal
	// opaque version string for each collection of resource types.
	ConstructVersionMap() error

	// GetVersionMap returns a map of resource name to resource version for
	// all the resources of type indicated by typeURL.
	GetVersionMap(typeURL string) map[string]string
}

type Resources struct {
	// Version information.
	Version string

	// Items in the group indexed by name.
	Items map[string]types.ResourceWithTTL
}

type Response interface {
	// GetDiscoveryResponse returns the Constructed DiscoveryResponse.
	GetDiscoveryResponse() (*discovery.DiscoveryResponse, error)

	// GetRequest returns the request that created the watch that we're now responding to.
	// This is provided to allow the caller to correlate the response with a request.
	// Generally this will be the latest request seen on the stream for the specific type.
	GetRequest() *discovery.DiscoveryRequest

	// GetVersion returns the version in the Response.
	// The version can be a property of the resources, allowing for optimizations in subsequent calls,
	// or simply an internal property of the cache which can be used for debugging.
	// The cache implementation should be able to determine if it can provide such optimization.
	// Deprecated: use GetResponseVersion instead
	GetVersion() (string, error)

	// GetResponseVersion returns the version in the Response.
	// The version can be a property of the resources, allowing for optimizations in subsequent calls,
	// or simply an internal property of the cache which can be used for debugging.
	// The cache implementation should be able to determine if it can provide such optimization.
	GetResponseVersion() string

	// GetReturnedResources returns the map of resources and their versions returned in the subscription.
	// It may include more resources than directly set in the response to consider the full state of the client.
	// The caller is expected to provide this unchanged to the next call to CreateWatch as part of the subscription.
	GetReturnedResources() map[string]string

	// GetContext returns the context provided during response creation.
	GetContext() context.Context
}

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

	// Response is the channel to push responses to.
	Response chan Response
	// contains filtered or unexported fields
}

type Snapshot struct {
	Resources [types.UnknownType]Resources

	// VersionMap holds the current hash map of all resources in the snapshot.
	// This field should remain nil until it is used, at which point should be
	// instantiated by calling ConstructVersionMap().
	// VersionMap is only to be used with delta xDS.
	VersionMap map[string]map[string]string
}

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(ctx context.Context, node string, snapshot ResourceSnapshot) error

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

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

	// GetStatusInfo retrieves status information for a node ID.
	GetStatusInfo(string) StatusInfo

	// GetStatusKeys retrieves node IDs for all statuses.
	GetStatusKeys() []string
}

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

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

	// GetNumDeltaWatches returns the number of open delta watches.
	GetNumDeltaWatches() int

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

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

type Subscription interface {
	// ReturnedResources returns the list of resources the client currently knows and their associated versions.
	// The versions are:
	//  - delta protocol: version of the specific resource set in the response.
	//  - sotw protocol: version of the global response when the resource was last sent.
	// The returned map must not be altered by the Cache.
	ReturnedResources() map[string]string

	// SubscribedResources returns the list of resources currently subscribed to by the client for the type.
	// For delta it keeps track of subscription updates across requests
	// For sotw it is a normalized view of the last request resources
	// The returned map must not be altered by the Cache.
	SubscribedResources() map[string]struct{}

	// IsWildcard returns whether the client has a wildcard watch.
	// This considers subtleties related to the current migration of wildcard definitions within the protocol.
	// More details on the behavior of wildcard are present at https://www.envoyproxy.io/docs/envoy/latest/api-docs/xds_protocol#how-the-client-specifies-what-resources-to-return
	IsWildcard() bool
}

type WatchResponse interface {
	GetReturnedResources() map[string]string
	GetResponseVersion() string
}