cache

package
v2.0.0-beta.6 Latest Latest
Warning

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

Go to latest
Published: Jul 17, 2026 License: MIT Imports: 9 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.

func Module

func Module() kernel.Component

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

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 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 Component

type Component struct {
	// contains filtered or unexported fields
}

Component owns the application-wide layered Cache.

func (*Component) Cache

func (c *Component) Cache() Cache

Cache returns the built cache, or nil when no layers are enabled.

func (*Component) Close

func (c *Component) Close(ctx context.Context) error

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.

func (*Component) Init

func (c *Component) Init(ctx context.Context, k kernel.Kernel) error

Init assembles the configured layers. Zero enabled layers is valid — the component stays up with a nil Cache ("cache disabled") so consumers can treat absence uniformly.

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

func (*Options) Validate

func (o *Options) Validate() error

Validate implements conf.Validatable.

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.

Jump to

Keyboard shortcuts

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