cache

cache

cache is a typed Go cache library with explicit hit, miss, stale, decode, and backend-failure semantics. It provides bounded cache-aside loading, versioned and hashed keys, strict codecs, a bounded memory backend, and native Redis and Valkey adapters. Valkey-backed caches can also publish a refresh only while a compatible distributed lease is still owned.

The semantic API does not expose Redis or Valkey client types. Backends keep their native clients and atomic behavior while applications share one portable contract.

Install

go get github.com/faustbrian/go-cache

Go 1.25 or newer is required.

Quickstart

package main

import (
	"context"
	"fmt"
	"time"

	cache "github.com/faustbrian/go-cache"
	"github.com/faustbrian/go-cache/backend/memory"
)

type User struct {
	ID   string `json:"id"`
	Name string `json:"name"`
}

func main() {
	ctx := context.Background()
	backend, err := memory.New(memory.Config{
		MaxEntries: 10_000,
		MaxBytes:   64 << 20,
		Clock:      cache.SystemClock{},
	})
	if err != nil {
		panic(err)
	}

	keys, err := cache.NewKeySpace("accounts", "user", 1,
		cache.StringKeyEncoder{}, 128)
	if err != nil {
		panic(err)
	}
	users, err := cache.New(cache.Config[string, User]{
		Backend:  backend,
		Keys:     keys,
		Codec:    cache.JSONCodec[User]{Version: 1},
		TTL:      cache.TTLPolicy{TTL: 5 * time.Minute},
		Clock:    cache.SystemClock{},
		MaxValue: 1 << 20,
		Load: cache.LoadPolicy{
			MaxConcurrent:    64,
			MaxWaitersPerKey: 256,
			NegativeTTL:      30 * time.Second,
		},
	})
	if err != nil {
		panic(err)
	}
	defer users.Close()

	result, err := users.GetOrLoad(ctx, "user-42",
		func(ctx context.Context, id string) (cache.LoadResult[User], error) {
			// Replace this with a context-aware source lookup.
			return cache.LoadResult[User]{Value: User{ID: id, Name: "Ada"}, Found: true}, nil
		})
	if err != nil {
		panic(err)
	}
	fmt.Println(result.State, result.Value.Name)
}

Always inspect Result.State; a stored zero value can be a Hit. A miss is not an error. Backend, decoding, schema, policy, limit, and loader failures remain errors and can be classified with errors.Is.

For distributed refreshes, acquire a Valkey lease through github.com/faustbrian/go-lease/valkey, derive its opaque guard with Store.Guard, and pass that guard to Cache.SetIfOwned or Cache.SetNegativeIfOwned. The cache record and active owner/token comparison occur in one Valkey script. Protected negative publication uses the configured NegativeTTL. The lease store and cache backend must use the same standalone Valkey deployment.

Choose a policy

• Use plain cache-aside for data where a source lookup is affordable.
• Add a short NegativeTTL only when source-level absence is authoritative.
• Use StaleWhileRevalidate when low latency is more important than returning the refresh error.
• Use StaleIfError when callers must see refresh failures but may also use the stale value. It returns both the stale Result and the error.
• Do not enable both stale policies; construction rejects ambiguous precedence.

See policy decisions and failure modes before enabling stale behavior.

Backends and observability

• Bounded memory, Redis, and Valkey setup
• OpenTelemetry and slog
• Shared backend conformance suite

Service lifecycle

cacheservice.New adapts an explicit concrete cache, Redis, or Valkey resource to service.Component. Startup validation and readiness are opt-in callbacks that receive the service context and the concrete resource. Callers add the readiness check to service.Plan only when cache availability is required to accept new work.

Omitting Shutdown keeps the resource shared and guarantees the adapter never closes it. Providing Shutdown explicitly transfers close ownership. The adapter performs no retries, closes a transferred resource once after draining later-declared components, and preserves startup and partial-cleanup failures.

Documentation

• API reference
• Semantic matrices and hardening audit
• Operations guide
• Key design and invalidation
• Codecs and schema evolution
• Stampede control and concurrency
• Adoption examples
• FAQ and troubleshooting
• Security, compatibility, migration, and performance

Development

make check
make integration
make fuzz
make benchmark

make check enforces formatting, vet, lint, unit tests, meaningful exact coverage, race safety, vulnerability scanning, GO-SAFETY-1, and docs compilation. Integration tests use Testcontainers and require Docker.

Status

The public API is being prepared for v1.0.0. Until that release, minor versions may change APIs. See CHANGELOG.md and the compatibility policy.

License

MIT. See LICENSE.

Ecosystem

Use the Golib documentation portal to choose companion packages, supported stacks, recipes, and operations guidance.