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)
- func Module() kernel.Component
- type BreakerLayerOptions
- type BreakerOptions
- type BuildOptions
- type Cache
- type Component
- type Loader
- type MemoryLayerOptions
- type MemoryOptions
- type Options
- type RedisLayerOptions
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.
func Module ¶
Module returns the cache component for chok.Use. Consumers take the built cache through the accessor:
cc, ok := chok.Get[*cache.Component](k, "cache") c := cc.Cache() // may be nil: "no layers configured" is a valid mode
The redis layer rides the redis module's shared client (soft dependency); enabling cache.redis without assembling the redis module is a fail-fast startup error.
Types ¶
type BreakerLayerOptions ¶
type BreakerLayerOptions struct {
Enabled bool `mapstructure:"enabled" default:"false"`
Threshold int `mapstructure:"threshold" default:"5"`
ResetTimeout time.Duration `mapstructure:"reset_timeout" default:"30s"`
HalfOpenSuccesses int `mapstructure:"half_open_successes" default:"3"`
ProbeTimeout time.Duration `mapstructure:"probe_timeout" default:"2s"`
}
BreakerLayerOptions wraps the redis layer in a circuit breaker so a down Redis degrades to cache misses instead of stretching every request to the client timeout.
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
Redis *redis.Client // nil = skip Redis layer
RedisTTL time.Duration // 0 = the redis layer's default (10m)
Breaker *BreakerOptions // nil = no circuit breaker on Redis layer
}
BuildOptions configures which cache layers to create. Nil or zero-value options skip that layer.
The badger file layer was removed in v2 (SPEC §2.4): the layer composition below (memory → Redis, chained) is the extension slot — a future persistent layer slots back in as another Cache in the chain, without a heavyweight dependency riding every build.
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, the redis layer default, 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 → 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 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 Component ¶
type Component struct {
// contains filtered or unexported fields
}
Component owns the application-wide layered Cache.
func (*Component) Close ¶
Close releases cache resources (chain broadcast). The redis layer's Close is a no-op by design — the shared client belongs to the redis module.
func (*Component) Describe ¶
func (c *Component) Describe() kernel.Descriptor
Describe implements kernel.Component.
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 MemoryLayerOptions ¶
type MemoryLayerOptions struct {
Enabled bool `mapstructure:"enabled" default:"false"`
Capacity int `mapstructure:"capacity" default:"10000"`
TTL time.Duration `mapstructure:"ttl" default:"5m"`
}
MemoryLayerOptions configures the in-process otter layer.
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).
type Options ¶
type Options struct {
Enabled bool `mapstructure:"enabled" default:"true"`
Memory MemoryLayerOptions `mapstructure:"memory"`
Redis RedisLayerOptions `mapstructure:"redis"`
Breaker BreakerLayerOptions `mapstructure:"breaker"`
}
Options is the "cache" yaml section. Layer topology cannot be re-plumbed under live traffic, so every field is restart-only (untagged = restart, the conservative conf default).
v1 note: the memory/file layers lived in separate cache.memory / cache.file sections and the redis layer attached implicitly whenever a redis component existed. v2 folds everything into one section, drops the badger file layer (SPEC §2.4) and makes the redis layer an explicit switch — configuration drives behaviour, and an enabled redis layer with no redis module is a fail-fast assembly error, not a silent downgrade.
type RedisLayerOptions ¶
type RedisLayerOptions struct {
Enabled bool `mapstructure:"enabled" default:"false"`
TTL time.Duration `mapstructure:"ttl" default:"10m"`
}
RedisLayerOptions configures the shared-redis layer. Enabling it requires the redis module in the assembly.