cistern

cistern

A Go library for two-level cache-aside caching — an in-process L1 and a shared Redis L2 — with load coalescing, negative caching, and invalidation by key, by tag and by event.

The name is the reservoir inside the fortress: you drink from it instead of going to the river, and it keeps serving when the river is slow or under siege.

Status: unreleased (phase C8 next). The library is feature-complete for v0.1: two levels, coalescing, negative caching, tag invalidation, a cross-instance Bus, hooks, and the examples module. What remains is validation under load with sapper, a clean-session audit and the release — see Roadmap. No version is tagged yet, and the API may still change.

Why this exists

A cache that makes the happy path faster is easy. The work is in what happens around it: a hot key expiring under load and sending every request to the database at once; a key built without the user id serving one user's data to another; a Redis outage turning a performance optimization into an application outage; a decoded value from Redis that nobody validated.

cistern takes positions on those and writes down the reasoning:

• REQUIREMENTS.md — traceable RF-/RS-/RNF- ids, architecture, phases
• docs/THREAT-MODEL.md — fourteen threats, their mitigations, and what is left over
• docs/adr/ — the decision record
• CONTRIBUTING.md — git flow, commit convention, and the documentation rules CI enforces
• RELEASING.md — why the tag order is not optional
• SECURITY.md — reporting, and how to operate Redis for it

Quick start

client := redis.NewClient(&redis.Options{
	Addr:                  "redis:6379",
	ContextTimeoutEnabled: true, // required: see redisstore/README.md
})
l2, _ := redisstore.New(client, redisstore.WithTimeout(50*time.Millisecond))
b, _ := redisstore.NewBus(client)
l1, _ := memory.New(memory.WithMaxEntries(10_000))

// The owner goes in the key and in the tag (RS-02, ADR-0005).
lists, err := cistern.New[int, []Task]("tasks",
	func(owner int) string { return fmt.Sprintf("user:%d:lists", owner) },
	cistern.WithL1(l1), cistern.WithL2(l2), cistern.WithBus(b),
	cistern.WithTTL(5*time.Minute), cistern.WithL1TTL(5*time.Second),
	cistern.WithTags(func(owner int) []string { return []string{fmt.Sprintf("user:%d:lists", owner)} }),
	cistern.WithNegativeTTL(10*time.Second),
	cistern.WithHooks(hooks), // see examples/crierhooks
)
defer lists.Close()

// Reads: concurrent misses share one load; Redis down means the loader
// answers, never an error.
tasks, err := lists.GetOrLoad(ctx, 42, func(ctx context.Context) ([]Task, error) {
	return repo.ListByOwner(ctx, 42)
})

// Writes: change the source of truth, then invalidate — every replica.
err = lists.InvalidateTag(ctx, "user:42:lists")

examples/ holds runnable versions: the task-api Repository Decorator, a bastion circuit breaker around Redis, hooks exported to crier, and how to keep moat secrets out of the cache.

Properties

And what it will not do

• Be a source of truth. Nothing may depend on the cache for correctness.
• Close the cache-aside race for untagged keys. Tag invalidation closes it; an untagged Delete racing a load can leave a stale value for up to its TTL (ADR-0011).
• Protect you from a key and a tag that both omit the owner. cistern forces a namespace; your key and tag functions have to encode the user.
• Protect you from whoever can write your Redis. Values are validated, not signed.
• HTTP caching, write-behind, Redis Cluster — out of scope for v0.x.

Operating it

• Redis: a dedicated ACL user with the tested minimum, TLS outside development, maxmemory-policy allkeys-lru, and never an instance shared with moat's rate limiter or cairn's link store (a logical database is not enough) — redisstore/README.md has the exact lines.
• Staleness between replicas is at most the L1 TTL when a Bus event is lost; keep it short (seconds).
• Wire OnError. Fail-open means a Redis outage returns no errors to your code; the hook is where it shows.

Security model in brief

The full model is docs/THREAT-MODEL.md.

Design shape

cistern/             core — Cache[K,V], options, GetOrLoad, tags, hooks  (stdlib only)
├── memory/          L1: LRU over bytes, entry and byte limits, TTL, eviction hook
├── codec/           Codec interface + JSON
├── bus/             Bus interface, in-process bus, event codec
├── cisterntest/     conformance suites for Store, TagStore and Bus
└── internal/        envelope, singleflight

cistern/redisstore/  separate module — Redis L2, tag generations, Pub/Sub Bus
cistern/examples/    not published — task-api decorator, bastion, crier, moat secrets

Roadmap

In parallel from C7, the task-api track: T0 baseline with sapper → T1 endpoint choice → T2 CachedTaskRepository → T3 re-measure and release.

Ecosystem

License

MIT.