Documentation
¶
Overview ¶
Package cache provides a pluggable caching layer with memory, file, and Redis backends. Backends can be composed into a multi-level chain via Chain.
Index ¶
- func GetOrLoad(ctx context.Context, c Cache, key string, loader Loader, ttl time.Duration) ([]byte, error)
- type BreakerOptions
- type BuildOptions
- type Cache
- func Build(opts BuildOptions) (Cache, error)
- func Chain(caches ...Cache) Cache
- func NewFile(opts *FileOptions, logger ...log.Logger) (Cache, error)
- func NewMemory(opts *MemoryOptions) (Cache, error)
- func NewRedis(client *redis.Client) Cache
- func NewRedisWithTTL(client *redis.Client, defaultTTL time.Duration) Cache
- func WithBreaker(c Cache, opts BreakerOptions) Cache
- type FileOptions
- type Loader
- type MemoryOptions
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func GetOrLoad ¶
func GetOrLoad(ctx context.Context, c Cache, key string, loader Loader, ttl time.Duration) ([]byte, error)
GetOrLoad retrieves a value by key from the cache. On miss, calls loader to populate the cache, using singleflight to ensure only one concurrent loader runs per key (preventing cache stampede / thundering herd). The result is stored with the given TTL.
This is a standalone function rather than an interface method so that existing Cache implementations don't need updating. It works with any Cache.
Types ¶
type BreakerOptions ¶
type BreakerOptions struct {
// Threshold is the number of consecutive failures before the circuit
// opens. Default: 5.
Threshold int
// ResetTimeout is how long the circuit stays open before switching to
// half-open and allowing a single probe request. Default: 30s.
ResetTimeout time.Duration
// HalfOpenSuccesses is the number of consecutive successful probes
// required to close the breaker from half-open. A flapping backend
// can otherwise oscillate (a single lucky probe closes the circuit,
// the next real request fails and re-opens it). Default: 3, chosen
// to dampen single-probe coincidences without delaying recovery
// when the backend is genuinely healthy.
HalfOpenSuccesses int
// ProbeTimeout bounds the half-open probe independently of the
// triggering request's context. Without this decoupling, a probe
// inherits the request's possibly-exhausted deadline and fails with
// context.DeadlineExceeded, which record() would treat as a backend
// failure and re-open the breaker — keeping the circuit open even
// though the backend may be healthy. Default: 2s, capped at
// ResetTimeout.
ProbeTimeout time.Duration
}
BreakerOptions configures the circuit breaker wrapping a Cache backend.
type BuildOptions ¶
type BuildOptions struct {
Memory *MemoryOptions // nil = skip memory layer
File *FileOptions // nil = skip file layer
Redis *redis.Client // nil = skip Redis layer
Breaker *BreakerOptions // nil = no circuit breaker on Redis layer
Logger log.Logger // optional, used for file cache (badger) logging
}
BuildOptions configures which cache layers to create. Nil or zero-value options skip that layer.
type Cache ¶
type Cache interface {
// Get retrieves a value by key. Returns (nil, false, nil) on cache miss.
Get(ctx context.Context, key string) ([]byte, bool, error)
// Set stores a value with the given TTL. TTL=0 means "use the backend's
// configured default TTL" (from MemoryOptions.TTL, FileOptions.TTL, etc.).
Set(ctx context.Context, key string, value []byte, ttl time.Duration) error
// Delete removes a key. Missing keys are a no-op (not an error).
Delete(ctx context.Context, key string) error
// Close releases resources. Idempotent.
Close() error
}
Cache is the unified caching interface. All implementations are safe for concurrent use.
func Build ¶
func Build(opts BuildOptions) (Cache, error)
Build creates a multi-level Cache from the given options. Layers are added in order: memory → file → Redis. Only enabled layers (non-nil options) are included. Returns nil if no layers are configured.
func Chain ¶
Chain composes multiple caches into a multi-level chain.
Get: tries L0, L1, ... in order. On first hit at layer N, backfills layers 0..N-1 (with TTL=0, relying on each layer's own eviction policy).
Set/Delete: applied to all layers.
An empty chain (no layers) is valid: Get always misses, Set/Delete are no-ops.
func NewFile ¶
func NewFile(opts *FileOptions, logger ...log.Logger) (Cache, error)
NewFile creates a file-based cache backed by badger. logger is optional; if nil, badger logs are discarded.
func NewMemory ¶
func NewMemory(opts *MemoryOptions) (Cache, error)
NewMemory creates an in-memory cache backed by otter.
func NewRedis ¶
NewRedis creates a Redis-backed cache. The client lifecycle is managed externally (e.g. via chok.App.AddCleanup); Close() on this cache is a no-op.
func NewRedisWithTTL ¶
NewRedisWithTTL creates a Redis-backed cache with a custom default TTL applied when callers pass TTL=0. This prevents go-redis from setting keys with no expiration.
func WithBreaker ¶
func WithBreaker(c Cache, opts BreakerOptions) Cache
WithBreaker wraps a Cache backend with a circuit breaker. Suitable for network-dependent backends (Redis) where sustained failures should not cascade latency to every request.
When the circuit is open, the wrapped cache behaves as if every key is a miss — this lets a Chain cache fall through to lower tiers transparently.
type FileOptions ¶
type FileOptions struct {
Path string // directory path for badger data files
TTL time.Duration // default TTL for entries
}
FileOptions configures the file-based cache (badger).
type Loader ¶
Loader is called by GetOrLoad on a cache miss. It returns the value to cache and an error. Concurrent calls for the same key share a single loader invocation (singleflight).
type MemoryOptions ¶
type MemoryOptions struct {
Capacity int // maximum number of entries
TTL time.Duration // default TTL for entries
}
MemoryOptions configures the in-memory cache (otter).