cache

Documentation

Overview

Package cache implements an caches for objects.

Index

• Variables
• type Cacher
  • func CacherFor(ctx context.Context, c *Config, keyFunc KeyFunc) (Cacher, error)
  • func NewInMemory(i *InMemoryConfig) (Cacher, error)
  • func NewNoop() (Cacher, error)
  • func NewRedis(i *RedisConfig) (Cacher, error)
• type CacherType
• type Config
• type FetchFunc
• type InMemoryConfig
• type Key
  • func (k *Key) Compute(f KeyFunc) (string, error)
• type KeyFunc
  • func HMACKeyFunc(hasher func() hash.Hash, key []byte) KeyFunc
  • func HashKeyFunc(hasher func() hash.Hash) KeyFunc
  • func MultiKeyFunc(fns ...KeyFunc) KeyFunc
• type RedisConfig

Variables

var (
	ErrMissingFetchFunc = fmt.Errorf("missing fetch function")
	ErrNotFound         = fmt.Errorf("key not found")
	ErrStopped          = fmt.Errorf("cacher is stopped")
)

Types

type Cacher

type Cacher interface {
	// Closer closes the cache, cleaning up any stale entries. A closed cache is
	// no longer valid and attempts to call methods should return an error or
	// (less preferred) panic.
	io.Closer

	// Fetch retrieves the named item from the cache. If the item does not exist,
	// it calls FetchFunc to create the item. If FetchFunc returns an error, the
	// error is bubbled up the stack and no value is cached. If FetchFunc
	// succeeds, the value is cached for the provided TTL.
	Fetch(context.Context, *Key, interface{}, time.Duration, FetchFunc) error

	// Read gets an item from the cache and reads it into the provided interface.
	// If it does not exist, it returns ErrNotFound.
	Read(context.Context, *Key, interface{}) error

	// Write adds an item to the cache, overwriting if it already exists, caching
	// for TTL. It returns any errors that occur on writing.
	Write(context.Context, *Key, interface{}, time.Duration) error

	// Delete removes an item from the cache, returning any errors that occur.
	Delete(context.Context, *Key) error

	// DeletePrefix removes all items from the cache that begin with the given
	// value.
	DeletePrefix(context.Context, string) error
}

Cacher is an interface that defines caching.

func CacherFor

func CacherFor(ctx context.Context, c *Config, keyFunc KeyFunc) (Cacher, error)

func NewInMemory

func NewInMemory(i *InMemoryConfig) (Cacher, error)

NewInMemory creates a new in-memory cache.

func NewNoop

func NewNoop() (Cacher, error)

NewNoop creates a new noop cache.

func NewRedis

func NewRedis(i *RedisConfig) (Cacher, error)

NewRedis creates a new in-memory cache.

type CacherType

type CacherType string

CacherType represents a type of cacher.

const (
	TypeNoop     CacherType = "NOOP"
	TypeInMemory CacherType = "IN_MEMORY"
	TypeRedis    CacherType = "REDIS"
)

type Config

type Config struct {
	Type CacherType `env:"CACHE_TYPE, default=IN_MEMORY"`

	// HMACKey is the hash key to use when for keys in the cacher.
	HMACKey envconfig.Base64Bytes `env:"CACHE_HMAC_KEY, required"`

	// Redis configuration
	Redis redis.Config `env:", prefix=CACHE_"`
}

Config represents configuration for a cacher.

type FetchFunc

type FetchFunc func() (interface{}, error)

FetchFunc is a function used to Fetch in a cacher.

type InMemoryConfig

type InMemoryConfig struct {
	// KeyFunc is the key function.
	KeyFunc KeyFunc

	// GCInterval is how frequently to purge stale entries from the cache.
	GCInterval time.Duration
}

type Key

type Key struct {
	Namespace string
	Key       string
}

Key is a cache key. It has an optional Namespace. Any KeyFunc are applied to the Key, but not the Namespace.

func (*Key) Compute

func (k *Key) Compute(f KeyFunc) (string, error)

Compute builds the final value of the key. If f is not nil, it is called on the value of Key. If Namespace is not "", the result is prefixed with Namespace + ":".

type KeyFunc

type KeyFunc func(string) (string, error)

KeyFunc is a function that mutates the provided cache key before storing it in Redis. This can be used to hash or HMAC values to prevent their plaintext from appearing in Redis. A good example might be an API key lookup that you HMAC before passing along.

The KeyFunc can also be used to add a prefix or namespace to keys in multi-tenant systems.

func HMACKeyFunc

func HMACKeyFunc(hasher func() hash.Hash, key []byte) KeyFunc

HMACKeyFunc returns a KeyFunc that HMACs the provided key before passing it to the cacher for storage.

func HashKeyFunc

func HashKeyFunc(hasher func() hash.Hash) KeyFunc

HashKeyFunc returns a KeyFunc that hashes the provided key before passing it to the cacher for storage.

func MultiKeyFunc

func MultiKeyFunc(fns ...KeyFunc) KeyFunc

MultiKeyFunc returns a KeyFunc that calls the provided KeyFuncs in order, with the previous value passed to the next.

type RedisConfig

type RedisConfig struct {
	// Address is the redis address and port. The default value is 127.0.0.1:6379.
	Address string

	// Username and Password are used for authentication.
	Username, Password string

	// IdleTimeout, MaxIdle, and MaxActive control connection handling.
	IdleTimeout time.Duration
	MaxIdle     int
	MaxActive   int

	// KeyFunc is the key function.
	KeyFunc KeyFunc

	// WaitTimeout is the maximum amount of time to wait for a connection to
	// become available.
	WaitTimeout time.Duration
}