Documentation
¶
Overview ¶
Package cache provides cache for arbritrary records. Data stored in Store implementations that are mounted on specific paths of the storage engine.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( ErrNotFound = errors.New("cache record not found") ErrNoMounts = errors.New("no mounts specified") ErrLockFailed = errors.New("failed to lock storage") ErrNoMatchingMount = errors.New("no storage mounted for path") ErrInvalidMount = errors.New("invalid mount") ErrOverlappingMount = errors.New("overlapping mount") )
Common errors when working with the cache package:.
Functions ¶
This section is empty.
Types ¶
type Cache ¶
type Cache interface {
// Write stores data under key. The cache package does not make any assumptions
// about the data stored in the cache. Callers must make sure to not modify data
// after calling write as the underlying cache store might keep a reference to
// the slice (like the in-memory store). Callers should rather create a copy
// of the data if later modifications of the slice are likely to happen.
Write(ctx context.Context, key string, data []byte, opts ...Option) error
// Read returns the data and associated metadata stored under key.
// If callers want to manipulate the data returned they are advised
// to create a copy as the underlying cache store (like the in-memory store)
// might keep a reference to the returned byte slice. It is safe to
// manipulate the returned Metadata though.
Read(ctx context.Context, key string) ([]byte, *Metadata, error)
// Delete deletes any data stored under key. It returns ErrNotFound
// if the cache entry to be deleted does not exist.
Delete(ctx context.Context, key string) error
// List returns a list of keys matching prefix. Note that List does not
// remove cache entries that used WithBurnAfterReading(). List will hide
// any cache items that are not valid anymore (i.e. exceeded their end-of-
// live).
List(ctx context.Context, prefix string) ([]string, error)
}
type Metadata ¶
type Metadata struct {
// NotValidAfter may hold the time at which the cache entry
// expires and must not be used anymore.
NotValidAfter *time.Time
// CreatedAt holds the timestamp the cache entry has been
// created.
CreatedAt time.Time
// BurnAfterReading is set to true if the cache entry should
// be evicted/expired as soon as a call to Read() happened.
// Note that List()ing cache keys does not burn a cache item.
BurnAfterReading bool
}
Metadata holds additional metadata for a cache entry.
type Mount ¶
type Mount struct {
// Store is the actual store that keeps track of all cache records
// under Path.
Store
// Path describes the base path of the mount. All items prefixed with
// this path will be stored in Store.
Path string
}
Mount describes a store being "mounted" on a given path. All cache items stored as children of that path will be passed to the mounted store.
type Option ¶
Option can be applied during cache writes and alternate various storage options.
func WithBurnAfterReading ¶
func WithBurnAfterReading() Option
WithBurnAfterReading marks the cache entry as one-time read. Once the cache entry is read it will be automatically deleted from the backing store.
func WithEOL ¶
WithEOL is like WithTTL but allows to specify a time instead of a duration. For more information please refer to the documentation of WithTTL.
type Record ¶
type Record struct {
// Metadata holds additional metadata for the cache record
Metadata
// Data is the actual payload of the cache record. The cache package
// does not make any assumptions about the content stored here.
Data []byte
}
Record represents a cache record stored under a certain key. Users of Cache should not care about the Record struct as it' mainly exported for Store interface implementers.
type Store ¶
type Store interface {
// Lock should lock the storage and return a method
// to unlock.
Lock(ctx context.Context) (UnlockFunc, bool)
// Put stores r under key.
Put(ctx context.Context, r KeyRecord) error
// Get returns the record stored under key. It should
// not care about records TTLs or other records metadata.
Get(ctx context.Context, key string) (*KeyRecord, error)
// List should list all records that start with prefix. If a prefix
// search is not supported by the underlying storage List can also
// return all records. The caller of List must expect to receive records
// with keys that are not prefixed with prefix.
List(ctx context.Context, prefix string) ([]*KeyRecord, error)
// Delete should returns any record stored under key.
Delete(ctx context.Context, key string) error
}
Store is used to store cache entries. It should only care about the actual storage of records but about record metadata, garbage collection or EOL handling. Store should not consider record data and act as if they are opaque data.
func NewMemoryStore ¶
func NewMemoryStore() Store
NewMemoryStore returns a new cache.Store that keeps all records in memory. Only use for really ephemeral data!
Source Files