cache

go-cache

Two-level cache (local L1 + remote L2) with circuit breaker, Prometheus/OpenTelemetry metrics, and structured value support.

The remote layer is defined by the RemoteCache interface, so you can plug in Redis, Memcached, DynamoDB, or any other backend. A ready-to-use Redis adapter is included.

Install

go get github.com/treussart/go-cache

Architecture

Get request
    │
    ▼
┌────────┐  hit   ┌────────────┐
│ L1     │───────▶│ return     │
│ (local)│        └────────────┘
└───┬────┘
    │ miss
    ▼
┌─────────┐  hit   ┌────────────┐
│ L2      │───────▶│ write to L1│──▶ return
│ (remote)│        └────────────┘
└───┬─────┘
    │ miss
    ▼
ErrCacheMiss

Either layer is optional — you can use L1-only, L2-only, or both.

Usage

Cache instances are created with functional options:

import (
    cache "github.com/treussart/go-cache"
)

c, err := cache.New("my-service",
    cache.WithRedisConn(redisClient, 5*time.Minute),
    cache.WithLocalCacheTinyLFU(10000, time.Minute),
    cache.WithCBEnabled(true),
)

Using a custom remote cache

Implement the RemoteCache interface for any backend and pass it with WithRemoteCache:

c, err := cache.New("my-service",
    cache.WithRemoteCache(myMemcachedAdapter, 5*time.Minute),
    cache.WithLocalCacheTinyLFU(10000, time.Minute),
)

Raw bytes

err = c.Set(ctx, []byte("user:1"), []byte("data"))

val, err := c.Get(ctx, []byte("user:1"))

err = c.SetExp(ctx, []byte("user:1"), []byte("data"), 30*time.Second)

err = c.Del(ctx, []byte("user:1"))

Structured values

GetStruct / SetStruct / SetExStruct encode and decode values automatically using the configured Coder (MsgPack by default):

type User struct {
    Name string
    Age  int
}

err = c.SetStruct(ctx, "user:1", &User{Name: "Alice", Age: 30})

var u User
err = c.GetStruct(ctx, "user:1", &u)

err = c.SetExStruct(ctx, "user:1", &User{Name: "Alice"}, 30*time.Second)

Functional options

Interfaces

Cacher

type Cacher interface {
    Get(ctx context.Context, key []byte) ([]byte, error)
    Set(ctx context.Context, key, value []byte) error
    SetExp(ctx context.Context, key, value []byte, ttl time.Duration) error
    Del(ctx context.Context, key []byte) error
    DeleteFromLocalCache(key []byte)
    DeleteFromRemoteCache(ctx context.Context, key []byte) error
    Ready(ctx context.Context) error
    GetStruct(ctx context.Context, key string, dest any) error
    SetStruct(ctx context.Context, key string, value any) error
    SetExStruct(ctx context.Context, key string, value any, ttl time.Duration) error
}

A Mocked struct (testify mock) implementing Cacher is provided for unit tests.

RemoteCache

type RemoteCache interface {
    Get(ctx context.Context, key string) ([]byte, error)
    Set(ctx context.Context, key string, value []byte, ttl time.Duration) error
    Del(ctx context.Context, key string) error
    Ping(ctx context.Context) error
}

Get must return ErrCacheMiss when the key does not exist.

A RedisRemoteCache adapter implementing RemoteCache is included. Create one with NewRedisRemoteCache(client) or use the WithRedisConn convenience option.

LocalCache

type LocalCache interface {
    Set(key []byte, data []byte) error
    SetExp(key []byte, data []byte, ttl time.Duration) error
    Get(key []byte) ([]byte, error)
    Del(key []byte)
}

Built-in implementations: TinyLFU and FreeCache.

Circuit breaker

When enabled, all remote cache operations go through a gobreaker circuit breaker:

• Closed — requests flow normally to the remote cache.
• Open — remote calls are skipped. Get returns the error; Set/SetExp/Del silently fall back to L1.
• Half-open — a limited number of probe requests are sent to the remote cache.

ErrCacheMiss (cache miss) is treated as a success and does not count toward tripping.

Graceful degradation

When the remote cache goes down and the circuit breaker opens, Get normally returns an error for any key that is no longer in L1 (expired or evicted). With graceful degradation enabled, a stale cache (a separate in-memory TinyLFU with a longer TTL) is consulted before returning an error:

CB open + L1 miss
    │
    ▼
┌────────────┐  hit   ┌─────────────────┐
│ Stale cache│───────▶│ return stale data│
└───┬────────┘        └─────────────────┘
    │ miss
    ▼
return error

Enable it with:

c, err := cache.New("my-service",
    cache.WithRedisConn(redisClient, 5*time.Minute),
    cache.WithLocalCacheTinyLFU(10000, time.Minute),
    cache.WithCBEnabled(true),
    cache.WithGracefulDegradation(1*time.Hour), // stale TTL
)

• The stale cache is written on every Set/SetExp/SetStruct/SetExStruct, not only during degradation.
• The stale cache is consulted on any remote cache error (connection failure, timeout, CB open/too-many-requests). Only ErrCacheMiss (genuine cache miss) is not covered.
• Del clears both the primary L1 and the stale cache to maintain consistency.
• A cache_stale_hit_total metric is emitted on each stale hit (both Prometheus and OpenTelemetry).
• A staleTTL of 0 means entries never expire (they are only evicted when the cache is full).
• Stale eviction — the stale TinyLFU holds 10k items by default (override with the optional second argument, e.g. WithGracefulDegradation(0, 50000)). If you write more distinct keys than the configured size, the LFU eviction policy may evict the preloaded fallback.

Cache preloading

Warm up L1 on startup so the first requests hit the local cache instead of going to the remote cache:

data := map[string][]byte{
    "config:feature-flags": flagsJSON,
    "config:rate-limits":   limitsJSON,
}

c, err := cache.New("my-service",
    cache.WithLocalCacheTinyLFU(10000, time.Minute),
    cache.WithRedisConn(redisClient, 5*time.Minute),
    cache.WithPreload(data),
)

• Data is written to L1 (and the stale cache if WithGracefulDegradation is also enabled).
• The remote cache is not touched — preloading is strictly for the local layer.
• Keys are subject to the configured prefix, just like regular Set calls.

Maximum resiliency example

Combine circuit breaker, graceful degradation with a never-expiring stale cache, and preloading with a fallback value to guarantee that Get always returns data — even if the remote cache has never been reachable:

// A sensible default that is returned when both L1 and remote are unavailable
// and no real value has ever been written for this key.
fallback := map[string][]byte{
    "config": []byte(`{"feature_x":false}`),
}

c, err := cache.New("my-service",
    cache.WithRedisConn(redisClient, 5*time.Minute),
    cache.WithLocalCacheTinyLFU(10000, time.Minute),
    cache.WithCBEnabled(true),
    cache.WithGracefulDegradation(0),  // stale entries never expire
    cache.WithPreload(fallback),       // warm L1 + stale cache on startup
)

What happens at runtime:

1. Normal operation — Get("config") hits L1 or the remote cache as usual.
2. L1 expires, remote healthy — value is fetched from the remote cache and written back to L1.
3. Remote goes down, L1 still fresh — L1 hit, no error.
4. Remote down, L1 expired — circuit breaker is open, stale cache returns the last known value.
5. Remote has never been reachable — the preloaded fallback is still in the stale cache (TTL = 0, never expires) and is returned.

This makes the cache behave as a best-effort data source that degrades gracefully rather than failing.

Coders

The Coder interface controls serialization for GetStruct/SetStruct/SetExStruct:

Implement the Coder interface for custom serialization:

type Coder interface {
    Encode(value any) ([]byte, error)
    Decode(data []byte, value any) error
}

Observability

Prometheus

c, _ := cache.New("my-cache",
    cache.WithStatsProm(cache.GetStatsProm("namespace", "subsystem")),
    // ...
)

OpenTelemetry

stats, _ := cache.GetStatsOTEL("my-cache")
c, _ := cache.New("my-cache",
    cache.WithStatsOTEL(stats),
    // ...
)

Exposed metrics: cache_local_hit_total, cache_local_miss_total, cache_remote_hit_total, cache_remote_miss_total, cache_stale_hit_total, cache_local_set_total, cache_remote_set_total, cache_set_total, cache_cb_open_total, cache_cb_too_many_requests_total, cache_cb_state, cache_duration_seconds.

All metrics are labelled with cache_name.

Benchmarks

Run with go test -bench=. -benchmem ./...

Apple M1 Pro — Go 1.26 — arm64

Coder (serialization only)

Cache operations (L1 only, raw bytes)

### Cache operations with graceful degradation (L1 + stale cache, raw bytes)

Set pays for the extra TinyLFU write into the stale cache. Get paths are unaffected because the stale cache is only consulted when the circuit breaker rejects a request.

Cache operations (L1 only, struct roundtrip)