cache

Documentation

Overview

Package cache implements durable on-disk cache with LRU expiration.

Index

• Constants
• func BlobIDCacheKey(id blob.ID) string
• func ContentIDCacheKey(contentID string) string
• type ContentCache
  • func NewContentCache(ctx context.Context, st blob.Storage, opt Options) (ContentCache, error)
• type Options
• type PersistentCache
  • func NewPersistentCache(ctx context.Context, description string, cacheStorage Storage, ...) (*PersistentCache, error)
  • func (c *PersistentCache) CacheStorage() Storage
  • func (c *PersistentCache) Close(ctx context.Context)
  • func (c *PersistentCache) GetFetchingMutex(key string) *sync.RWMutex
  • func (c *PersistentCache) GetFull(ctx context.Context, key string, output *gather.WriteBuffer) bool
  • func (c *PersistentCache) GetOrLoad(ctx context.Context, key string, fetch func(output *gather.WriteBuffer) error, ...) error
  • func (c *PersistentCache) GetPartial(ctx context.Context, key string, offset, length int64, ...) bool
  • func (c *PersistentCache) Put(ctx context.Context, key string, data gather.Bytes)
• type Storage
  • func NewStorageOrNil(ctx context.Context, cacheDir string, maxBytes int64, subdir string) (Storage, error)
• type StorageProtection
  • func AuthenticatedEncryptionProtection(key []byte) (StorageProtection, error)
  • func ChecksumProtection(key []byte) StorageProtection
  • func NoProtection() StorageProtection
• type SweepSettings

Constants

const (
	// DefaultSweepFrequency is how frequently the contents of cache are sweeped to remove excess data.
	DefaultSweepFrequency = 1 * time.Minute

	// DefaultTouchThreshold specifies the resolution of timestamps used to determine which cache items
	// to expire. This helps cache storage writes on frequently accessed items.
	DefaultTouchThreshold = 10 * time.Minute
)

const DirMode = 0o700

DirMode is the directory mode for all caches.

Functions

func BlobIDCacheKey

func BlobIDCacheKey(id blob.ID) string

BlobIDCacheKey computes the cache key for the provided blob ID.

func ContentIDCacheKey

func ContentIDCacheKey(contentID string) string

ContentIDCacheKey computes the cache key for the provided content ID.

Types

type ContentCache

type ContentCache interface {
	Close(ctx context.Context)
	GetContent(ctx context.Context, contentID string, blobID blob.ID, offset, length int64, output *gather.WriteBuffer) error
	PrefetchBlob(ctx context.Context, blobID blob.ID) error
	CacheStorage() Storage
}

ContentCache caches contents stored in pack blobs.

func NewContentCache

func NewContentCache(ctx context.Context, st blob.Storage, opt Options) (ContentCache, error)

NewContentCache creates new content cache for data contents.

type Options

type Options struct {
	BaseCacheDirectory string
	CacheSubDir        string
	Storage            Storage // force particular storage, used for testing
	HMACSecret         []byte
	FetchFullBlobs     bool
	Sweep              SweepSettings
}

Options encapsulates all content cache options.

type PersistentCache

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

PersistentCache provides persistent on-disk cache.

func NewPersistentCache

func NewPersistentCache(ctx context.Context, description string, cacheStorage Storage, storageProtection StorageProtection, sweep SweepSettings) (*PersistentCache, error)

NewPersistentCache creates the persistent cache in the provided storage.

func (*PersistentCache) CacheStorage

func (c *PersistentCache) CacheStorage() Storage

CacheStorage returns cache storage.

func (*PersistentCache) Close

func (c *PersistentCache) Close(ctx context.Context)

Close closes the instance of persistent cache possibly waiting for at least one sweep to complete.

func (*PersistentCache) GetFetchingMutex

func (c *PersistentCache) GetFetchingMutex(key string) *sync.RWMutex

GetFetchingMutex returns a RWMutex used to lock a blob or content during loading.

func (*PersistentCache) GetFull

func (c *PersistentCache) GetFull(ctx context.Context, key string, output *gather.WriteBuffer) bool

GetFull fetches the contents of a full blob. Returns false if not found.

func (*PersistentCache) GetOrLoad

func (c *PersistentCache) GetOrLoad(ctx context.Context, key string, fetch func(output *gather.WriteBuffer) error, output *gather.WriteBuffer) error

GetOrLoad is utility function gets the provided item from the cache or invokes the provided fetch function. The function also appends and verifies HMAC checksums using provided secret on all cached items to ensure data integrity.

func (*PersistentCache) GetPartial

func (c *PersistentCache) GetPartial(ctx context.Context, key string, offset, length int64, output *gather.WriteBuffer) bool

GetPartial fetches the contents of a cached blob when (length < 0) or a subset of it (when length >= 0). returns false if not found.

func (*PersistentCache) Put

func (c *PersistentCache) Put(ctx context.Context, key string, data gather.Bytes)

Put adds the provided key-value pair to the cache.

type Storage

type Storage interface {
	blob.Storage
	TouchBlob(ctx context.Context, contentID blob.ID, threshold time.Duration) error
}

Storage is the storage interface required by the cache and is implemented by the filesystem Storage.

func NewStorageOrNil

func NewStorageOrNil(ctx context.Context, cacheDir string, maxBytes int64, subdir string) (Storage, error)

NewStorageOrNil returns cache.Storage backed by the provided directory.

type StorageProtection

type StorageProtection interface {
	Protect(id string, input gather.Bytes, output *gather.WriteBuffer)
	Verify(id string, input gather.Bytes, output *gather.WriteBuffer) error
}

StorageProtection encapsulates protection (HMAC and/or encryption) applied to local cache items.

func AuthenticatedEncryptionProtection

func AuthenticatedEncryptionProtection(key []byte) (StorageProtection, error)

AuthenticatedEncryptionProtection returns StorageProtection that protects cached data using authenticated encryption.

func ChecksumProtection

func ChecksumProtection(key []byte) StorageProtection

ChecksumProtection returns StorageProtection that protects cached data using HMAC checksums without encryption.

func NoProtection

func NoProtection() StorageProtection

NoProtection returns implementation of StorageProtection that offers no protection.

type SweepSettings

type SweepSettings struct {
	MaxSizeBytes   int64
	SweepFrequency time.Duration
	MinSweepAge    time.Duration
	TouchThreshold time.Duration
}

SweepSettings encapsulates settings that impact cache item sweep/expiration.