cache package - github.com/fluxcd/pkg/cache

cache package - github.com/fluxcd/pkg/cache - Go Packages

Package cache provides a Store interface for a cache store, along with two implementations of this interface for expiring cache(Cache) and least recently used cache(LRU). Expirable defines an interface for cache with expiring items. This is also implemented by the expiring cache implementation, Cache. The Cache and LRU cache implementations are generic cache. The data type of the value stored in the cache has to be defined when creating the cache. For example, for storing string values in Cache create a string type Cache

cache, err := New[string](10)

The cache implementations are self-instrumenting and export metrics about the internal operations of the cache if it is configured with a metrics registerer.

cache, err := New[string](10, WithMetricsRegisterer(reg))

For recording cache hit/miss metrics associated with a Flux object for which the cache is used, the caller must explicitly record the cache event based on the result of the operation along with the object in the context

got, err := cache.Get("foo")
// Handle any error.
...

if err == ErrNotFound {
  cache.RecordCacheEvent(CacheEventTypeMiss, "GitRepository", "repoA", "testNS")
} else {
  cache.RecordCacheEvent(CacheEventTypeHit, "GitRepository", "repoA", "testNS")
}

When the Flux object associated with the cache metrics is deleted, the metrics can be deleted as follows

cache.DeleteCacheEvent(CacheEventTypeHit, "GitRepository", "repoA", "testNS")
cache.DeleteCacheEvent(CacheEventTypeMiss, "GitRepository", "repoA", "testNS")

View Source

const (
	
	CacheEventTypeMiss = "cache_miss"
	
	CacheEventTypeHit = "cache_hit"
	
	StatusSuccess = "success"
	
	StatusFailure = "failure"
)

TokenMaxDuration is the maximum duration that a token can have in the TokenCache. This is used to cap the duration of tokens to avoid storing tokens that are valid for too long.

View Source

var (
	ErrNotFound    = CacheErrorReason{"NotFound", "object not found"}
	ErrCacheClosed = CacheErrorReason{"CacheClosed", "cache is closed"}
	ErrCacheFull   = CacheErrorReason{"CacheFull", "cache is full"}
	ErrInvalidSize = CacheErrorReason{"InvalidSize", "invalid size"}
)

MustMakeMetrics registers the metrics collectors in the given registerer.

type Cache[T any] struct {
	
}

Cache[T] is a thread-safe in-memory key/value store. It can be used to store items with optional expiration.

New creates a new cache with the given configuration.

Clear all index from the cache. This reallocates the underlying array holding the index, so that the memory used by the index is reclaimed. A closed cache cannot be cleared.

Close closes the cache. It also stops the expiration eviction process.

Delete an item from the cache. Does nothing if the key is not in the cache. It actually sets the item expiration to `now“, so that it will be deleted at the cleanup.

func (c *Cache[T]) DeleteCacheEvent(event, kind, name, namespace, operation string)

DeleteCacheEvent deletes the cache event (cache_miss or cache_hit) metric for the associated object being reconciled, given their kind, name and namespace.

Get returns an item in the cache for the given key. If no item is found, an error is returned. The caller can record cache hit or miss based on the result with Cache.RecordCacheEvent().

GetExpiration returns the expiration for the given key. Returns zero if the key is not in the cache or the item has already expired.

HasExpired returns true if the item has expired.

ListKeys returns a slice of the keys in the cache.

func (c *Cache[T]) RecordCacheEvent(event, kind, name, namespace, operation string)

RecordCacheEvent records a cache event (cache_miss or cache_hit) with kind, name and namespace of the associated object being reconciled.

Resize resizes the cache and returns the number of index removed. Size must be greater than zero.

Set an item in the cache, existing index will be overwritten. If the cache is full, an error is returned.

SetExpiration sets the expiration for the given key.

type CacheError struct {
	Reason CacheErrorReason
	Err    error
}

Error returns Err as a string, prefixed with the Reason to provide context.

Is returns true if the Reason or Err equals target. It can be used to programmatically place an arbitrary Err in the context of the Cache:

err := &CacheError{Reason: ErrCacheFull, Err: errors.New("arbitrary resize error")}
errors.Is(err, ErrCacheFull)

Unwrap returns the underlying Err.

type CacheErrorReason struct {
	
}

CacheErrorReason is a type that represents the reason for a cache error.

Error gives a human-readable description of the error.

Expirable is an interface for a cache store that supports expiration.

type LRU[T any] struct {
	
}

LRU is a thread-safe in-memory key/value store. All methods are safe for concurrent use. All operations are O(1). The hash map lookup is O(1) and so is the doubly linked list insertion/deletion.

The LRU is implemented as a doubly linked list, where the most recently accessed item is at the front of the list and the least recently accessed item is at the back. When an item is accessed, it is moved to the front of the list. When the cache is full, the least recently accessed item is removed from the back of the list.

                                  Cache
           ┌───────────────────────────────────────────────────┐
           │                                                   │
  empty    │     obj         obj          obj          obj     │    empty
┌───────┐  │  ┌───────┐   ┌───────┐     ┌───────┐   ┌───────┐  │  ┌───────┐
│       │  │  │       │   │       │ ... │       │   │       │  │  │       │
│ HEAD  │◄─┼─►│       │◄─►│       │◄───►│       │◄─►│       │◄─┼─►│ TAIL  │
│       │  │  │       │   │       │     │       │   │       │  │  │       │
└───────┘  │  └───────┘   └───────┘     └───────┘   └───────┘  │  └───────┘
           │                                                   │
           │                                                   │
           └───────────────────────────────────────────────────┘

Use the NewLRU function to create a new cache that is ready to use.

NewLRU creates a new LRU cache with the given capacity.

Delete removes a node from the list

func (c *LRU[T]) DeleteCacheEvent(event, kind, name, namespace, operation string)

DeleteCacheEvent deletes the cache event (cache_miss or cache_hit) metric for the associated object being reconciled, given their kind, name and namespace.

Get returns an item in the cache for the given key. If no item is found, an error is returned. The caller can record cache hit or miss based on the result with LRU.RecordCacheEvent().

GetIfOrSet returns an item in the cache for the given key if present and if the condition is satisfied, or calls the fetch function to get a new item and stores it in the cache. The operation is thread-safe and atomic. The boolean return value indicates whether the item was retrieved from the cache.

ListKeys returns a list of keys in the cache.

func (c *LRU[T]) RecordCacheEvent(event, kind, name, namespace, operation string)

RecordCacheEvent records a cache event (cache_miss or cache_hit) with kind, name and namespace of the associated object being reconciled.

Resize resizes the cache and returns the number of items removed.

Set an item in the cache, existing index will be overwritten.

type Options func(*storeOptions) error

Options is a function that sets the store options.

WithCleanupInterval sets the interval for the cache cleanup.

func WithEventNamespaceLabel(label string) Options

WithEventNamespaceLabel sets the namespace label for the cache events.

func WithInvolvedObject(kind, name, namespace, operation string) Options

WithInvolvedObject sets the involved object for the cache metrics.

WithMaxDuration sets the maximum duration for the cache items.

func WithMetricsPrefix(prefix string) Options

WithMetricsPrefix sets the metrics prefix for the cache metrics.

WithMetricsRegisterer sets the Prometheus registerer for the cache metrics.

Store is an interface for a cache store.

Token is an interface that represents an access token that can be used to authenticate with a cloud provider. The only common method is to get the duration of the token, because different providers may have different ways to represent the token. For example, Azure and GCP use an opaque string token, while AWS uses the pair of access key id and secret access key. Consumers of this token should know what type to cast this interface to.

type TokenCache struct {
	
}

TokenCache is a thread-safe cache specialized in storing and retrieving access tokens. It uses an LRU cache as the underlying storage and takes care of expiring tokens in a pessimistic way by storing both a timestamp with a monotonic clock (the Go default) and an absolute timestamp created from the Unix timestamp of when the token was created. The token is considered expired when either timestamps are older than the current time. This strategy ensures that expired tokens aren't kept in the cache for longer than their expiration time. Also, tokens expire on 80% of their lifetime, which is the same strategy used by kubelet for rotating ServiceAccount tokens.

func NewTokenCache(capacity int, opts ...Options) (*TokenCache, error)

NewTokenCache returns a new TokenCache with the given capacity.

func (c *TokenCache) DeleteEventsForObject(kind, name, namespace, operation string)

DeleteEventsForObject deletes all cache events (cache_miss and cache_hit) for the associated object being deleted, given its kind, name and namespace.

GetOrSet returns the token for the given key if present and not expired, or calls the newToken function to get a new token and stores it in the cache. The operation is thread-safe and atomic. The boolean return value indicates whether the token was retrieved from the cache.

TokenFlags contains the CLI flags that can be used to configure the TokenCache.