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.

The published v1 module is a stable member of Golib's Persistence and durability family. The current source is the v2.0.0 release candidate with protected-error and bounded-shutdown contracts. For ecosystem-wide selection and ownership guidance, see the versioned Golib ecosystem index and its Persistence and durability family.

Install

go get github.com/faustbrian/go-cache

Go 1.27.0 or newer is required.

Quickstart

package main

import (
	"context"
	"fmt"
	"time"

	cache "github.com/faustbrian/go-cache"
	cachememory "github.com/faustbrian/go-cache/adapters/memory"
)

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

func main() {
	ctx := context.Background()
	backend, err := cachememory.New(cachememory.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)
}

V2 adoption

Confirm that the /v2 v2.0.0 tag resolves publicly before changing production dependencies. Consumers can migrate with the guide in docs/migration.md and, after publication, install it with:

go get github.com/faustbrian/go-cache/v2@v2.0.0

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

Use the root package for portable cache policy and result semantics. Select a package under adapters/ only for its named integration, cachetest only for backend conformance tests, and an observability adapter only when the corresponding integration is required. Do not use this module as durable authoritative storage, a distributed-lock implementation, or an application-wide retry owner.

Service lifecycle

adapters/service.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.

The former backend/*, cacheservice, and observability/* import paths are deprecated compatibility facades. New code should use the corresponding adapters/* package; existing callers can migrate imports without changing configuration or runtime semantics.

Documentation

Use the documentation index for behavior, backends, operations, adoption, compatibility, and security guidance.

Development and verification guidance is in CONTRIBUTING.md.

License

MIT. See LICENSE.