cache

Documentation

Overview

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

Index

• Constants
• Variables
• type PersistentCache
  • func NewPersistentCache(ctx context.Context, description string, cacheStorage Storage, ...) (*PersistentCache, error)
  • func (c *PersistentCache) Close(ctx context.Context)
  • func (c *PersistentCache) Get(ctx context.Context, key string, offset, length int64, ...) bool
  • func (c *PersistentCache) GetOrLoad(ctx context.Context, key string, fetch func(output *gather.WriteBuffer) error, ...) error
  • 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

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.

Variables

var (
	MetricHitCount = stats.Int64(
		"kopia/content/cache/hit_count",
		"Number of time content was retrieved from the cache",
		stats.UnitDimensionless,
	)

	MetricHitBytes = stats.Int64(
		"kopia/content/cache/hit_bytes",
		"Number of bytes retrieved from the cache",
		stats.UnitBytes,
	)

	MetricMissCount = stats.Int64(
		"kopia/content/cache/miss_count",
		"Number of time content was not found in the cache and fetched from the storage",
		stats.UnitDimensionless,
	)

	MetricMalformedCacheDataCount = stats.Int64(
		"kopia/content/cache/malformed",
		"Number of times malformed content was read from the cache",
		stats.UnitDimensionless,
	)

	MetricMissBytes = stats.Int64(
		"kopia/content/cache/missed_bytes",
		"Number of bytes retrieved from the underlying storage",
		stats.UnitBytes,
	)

	MetricMissErrors = stats.Int64(
		"kopia/content/cache/miss_error_count",
		"Number of time content could not be found in the underlying storage",
		stats.UnitDimensionless,
	)

	MetricStoreErrors = stats.Int64(
		"kopia/content/cache/store_error_count",
		"Number of time content could not be saved in the cache",
		stats.UnitDimensionless,
	)
)

cache metrics.

Types

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, maxSizeBytes int64, touchThreshold, sweepFrequency time.Duration) (*PersistentCache, error)

NewPersistentCache creates the persistent cache in the provided 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) Get

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

Get fetches the contents of a cached blob when (length < 0) or a subset of it (when length >= 0). returns nil 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) 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 {
	SupportsPartial() bool
	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.