cache

package
v0.1.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 3, 2026 License: MIT Imports: 10 Imported by: 0

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

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

func Chain(caches ...Cache) Cache

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

func NewRedis(client *redis.Client) Cache

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

func NewRedisWithTTL(client *redis.Client, defaultTTL time.Duration) Cache

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

type Loader func(ctx context.Context) ([]byte, error)

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).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL