cache

Go Cache Library

A framework-agnostic, store-driven cache library for Go that unifies local and cloud cache stores behind a single generic interface. Built with Go 1.23+ generics for type safety and performance.

Features

• Type-Safe API — Generic Cache[T] interface eliminates casting and provides compile-time type safety
• Pluggable Stores — Unified interface for memory (Ristretto), Redis, SQLite, and PostgreSQL backends
• Multi-Layer Caching — Chain multiple cache layers (L1/L2/L3) with automatic backfill
• Batch Operations — Efficient GetMany/SetMany/DeleteMany reduce round-trips by 8-10x
• Loader Pattern — GetOrLoad with single-flight deduplication prevents thundering herd (99.9% load reduction)
• Flexible Serialization — Pluggable codecs (JSON, MessagePack, Gob) with custom codec support
• Performance Optimized — Sub-microsecond memory cache, ~40μs Redis, ~8μs SQLite
• Context-Aware — All operations respect context cancellation and timeouts
• Metrics Built-In — Optional hit/miss tracking with WithMetrics()
• Production Ready — Comprehensive tests, benchmarks, and battle-tested design patterns

Quick Start

package main

import (
    "context"
    "fmt"
    "time"

    "github.com/kaptinlin/cache"
    "github.com/kaptinlin/cache/store/memory"
)

type User struct {
    ID   string
    Name string
    Age  int
}

func main() {
    // Create in-memory store with 100MB capacity
    store, _ := memory.New(memory.Config{MaxCost: 100 << 20})
    defer store.Close()

    // Create type-safe cache with 5-minute default TTL
    userCache := cache.New[User](store, cache.WithTTL(5*time.Minute))
    defer userCache.Close()

    ctx := context.Background()

    // Set a user
    user := User{ID: "123", Name: "Alice", Age: 30}
    userCache.Set(ctx, "user:123", user, 0)

    // Get the user
    retrieved, _ := userCache.Get(ctx, "user:123")
    fmt.Printf("%s is %d years old\n", retrieved.Name, retrieved.Age)
    // Output: Alice is 30 years old
}

Installation

go get github.com/kaptinlin/cache

Optional Dependencies

Install store-specific dependencies as needed:

# Redis support
go get github.com/redis/rueidis

# PostgreSQL support
go get github.com/jackc/pgx/v5

# SQLite support (pure Go)
go get modernc.org/sqlite

# MessagePack codec (recommended for production)
go get github.com/vmihailenco/msgpack/v5

Usage Examples

Basic In-Memory Cache

store, _ := memory.New(memory.Config{MaxCost: 100 << 20}) // 100MB
cache := cache.New[User](store, cache.WithTTL(5*time.Minute))
defer cache.Close()

ctx := context.Background()
user := User{ID: "123", Name: "Alice", Age: 30}

// Set with default TTL (5 minutes)
cache.Set(ctx, "user:123", user, 0)

// Set with custom TTL (1 minute)
cache.Set(ctx, "user:456", user, 1*time.Minute)

// Get from cache
retrieved, err := cache.Get(ctx, "user:123")
if err != nil {
    // Handle cache miss or error
}

Redis Cache

import (
    "github.com/kaptinlin/cache/store/redis"
    "github.com/redis/rueidis"
)

// Create Redis client
client, _ := rueidis.NewClient(rueidis.ClientOption{
    InitAddress: []string{"localhost:6379"},
})

// Create Redis store
store := redis.New(client)
cache := cache.New[User](store, cache.WithTTL(10*time.Minute))
defer cache.Close()

// Use like any other cache
cache.Set(ctx, "user:123", user, 0)

SQLite Cache (Persistent Local Cache)

import "github.com/kaptinlin/cache/store/sqlite"

// Create SQLite store with file-based database
store, _ := sqlite.New(sqlite.Config{
    Path: "/var/cache/myapp.db",
})
defer store.Close()

cache := cache.New[User](store, cache.WithTTL(1*time.Hour))
defer cache.Close()

// Data persists across restarts
cache.Set(ctx, "user:123", user, 0)

PostgreSQL Cache (Distributed Persistent Cache)

import (
    "github.com/kaptinlin/cache/store/postgres"
    "github.com/jackc/pgx/v5/pgxpool"
)

// Create PostgreSQL connection pool
pool, _ := pgxpool.New(ctx, "postgres://user:pass@localhost/cache")
defer pool.Close()

// Create PostgreSQL store
store, _ := postgres.New(postgres.Config{
    Pool:      pool,
    TableName: "cache_entries",
})
defer store.Close()

cache := cache.New[User](store, cache.WithTTL(24*time.Hour))
defer cache.Close()

Multi-Layer Cache (L1 + L2)

// L1: Fast in-memory cache (1MB, 1-minute TTL)
l1Store, _ := memory.New(memory.Config{MaxCost: 1 << 20})
l1Cache := cache.New[User](l1Store, cache.WithTTL(1*time.Minute))

// L2: Distributed Redis cache (10-minute TTL)
l2Store := redis.New(redisClient)
l2Cache := cache.New[User](l2Store, cache.WithTTL(10*time.Minute))

// Create chain cache (L1 -> L2)
chainCache := cache.NewChain[User](l1Cache, l2Cache)
defer chainCache.Close()

// Get checks L1 first, then L2, and backfills L1 on L2 hit
user, _ := chainCache.Get(ctx, "user:123")

Batch Operations

batchCache := cache.NewBatch[User](store, cache.WithTTL(5*time.Minute))
defer batchCache.Close()

// Set multiple users at once (8-10x faster than individual Sets)
users := map[string]User{
    "user:100": {ID: "100", Name: "Alice", Age: 30},
    "user:101": {ID: "101", Name: "Bob", Age: 25},
    "user:102": {ID: "102", Name: "Charlie", Age: 35},
}
batchCache.SetMany(ctx, users, 0)

// Get multiple users at once
keys := []string{"user:100", "user:101", "user:102"}
retrieved, _ := batchCache.GetMany(ctx, keys)

// Delete multiple keys at once
batchCache.DeleteMany(ctx, keys)

Loader Pattern (Cache-Aside)

loaderCache := cache.NewLoader[User](store, cache.WithTTL(5*time.Minute))
defer loaderCache.Close()

// Define loader function (e.g., database query)
loadUserFromDB := func(ctx context.Context, key string) (User, error) {
    // Query database, call API, etc.
    return db.GetUser(ctx, key)
}

// GetOrLoad checks cache first, then calls loader on miss
// Uses single-flight deduplication to prevent thundering herd
user, err := loaderCache.GetOrLoad(ctx, "user:123", loadUserFromDB)

Custom Codec (MessagePack)

import "github.com/kaptinlin/cache/codec"

// Use MessagePack for 15-63% faster serialization than JSON
cache := cache.New[User](
    store,
    cache.WithCodec(codec.MessagePackCodec{}),
    cache.WithTTL(5*time.Minute),
)
defer cache.Close()

Metrics Tracking

metrics := &cache.Metrics{}

cache := cache.New[User](
    store,
    cache.WithMetrics(metrics),
    cache.WithTTL(5*time.Minute),
)
defer cache.Close()

// Perform operations
cache.Set(ctx, "key1", user, 0)
cache.Get(ctx, "key1") // Hit
cache.Get(ctx, "key2") // Miss

// Check metrics
fmt.Printf("Hits: %d, Misses: %d, Hit Rate: %.2f%%\n",
    metrics.Hits.Load(),
    metrics.Misses.Load(),
    metrics.HitRate()*100,
)

Store Comparison

Store Features

⚠️ = Optional or limited support

Codec Comparison

Codec Features

Recommendation: Use MessagePack for production workloads, JSON for development/debugging.

Performance Benchmarks

Store Performance

MemoryStore:
  Get:    < 100 ns/op,  0 allocs/op
  Set:    < 150 ns/op,  2 allocs/op

RedisStore:
  Get:    39,854 ns/op,  1 allocs/op
  Set:    56,367 ns/op,  2 allocs/op
  Client-side caching: 172.7 ns/op (230x faster)

SQLiteStore:
  Get:    7,802 ns/op,  19 allocs/op
  Set:    14,646 ns/op, 11 allocs/op

PostgresStore:
  Get:    < 10 ms/op
  Set:    < 10 ms/op

Codec Performance

MessagePack:
  Encode: 371 ns/op   (15% faster than JSON)
  Decode: 496 ns/op   (63% faster than JSON)

JSON:
  Encode: 436 ns/op
  Decode: 1,348 ns/op

Gob:
  Encode: 4,955 ns/op  (11x slower than JSON)
  Decode: 44,384 ns/op (33x slower than JSON)

Batch Operations

RedisStore GetMany (10 keys):  ~50 μs  (8x faster than 10 individual Gets)
RedisStore SetMany (10 keys):  ~70 μs  (8x faster than 10 individual Sets)

Multi-Layer Caching

L1 Hit Rate: 90% (served from memory at ~100 ns)
L2 Hit Rate: 9%  (served from Redis at ~40 μs)
L3 Miss Rate: 1% (load from source at ~100 ms)

Network Call Reduction: 90% (L1 cache eliminates Redis calls)

See BENCHMARKS.md for comprehensive performance analysis.

API Reference

Core Interfaces

// Cache provides type-safe cache operations
type Cache[T any] interface {
    Get(ctx context.Context, key string) (T, error)
    Set(ctx context.Context, key string, value T, ttl time.Duration) error
    Delete(ctx context.Context, key string) error
    Clear(ctx context.Context) error
    Close() error
}

// BatchCache adds batch operations
type BatchCache[T any] interface {
    Cache[T]
    GetMany(ctx context.Context, keys []string) (map[string]T, error)
    SetMany(ctx context.Context, items map[string]T, ttl time.Duration) error
    DeleteMany(ctx context.Context, keys []string) error
}

// LoaderCache adds loader pattern with single-flight deduplication
type LoaderCache[T any] interface {
    BatchCache[T]
    GetOrLoad(ctx context.Context, key string, loader LoaderFunc[T]) (T, error)
}

Configuration Options

// WithTTL sets default TTL for cache entries
cache.WithTTL(5 * time.Minute)

// WithCodec sets custom serialization codec
cache.WithCodec(codec.MessagePackCodec{})

// WithMetrics enables metrics collection
cache.WithMetrics(&cache.Metrics{})

// WithSingleFlight enables single-flight deduplication (default: enabled)
cache.WithSingleFlight(true)

Store Constructors

// In-memory store (Ristretto)
memory.New(memory.Config{MaxCost: 100 << 20})

// Redis store (Rueidis)
redis.New(client, redis.WithKeyPrefix("myapp:"))

// SQLite store
sqlite.New(sqlite.Config{Path: "/var/cache/app.db"})

// PostgreSQL store
postgres.New(postgres.Config{Pool: pool, TableName: "cache"})

Full API documentation: pkg.go.dev/github.com/kaptinlin/cache

Architecture

cache/
├── cache.go           # Generic Cache[T] interface and implementation
├── store.go           # Store interface (byte-oriented)
├── codec.go           # Codec interface for serialization
├── chain.go           # Multi-layer cache implementation
├── loader.go          # Loader pattern with single-flight
├── codec/
│   ├── json.go        # JSON codec (default)
│   ├── msgpack.go     # MessagePack codec (recommended)
│   └── gob.go         # Gob codec (Go-specific)
└── store/
    ├── memory/        # MemoryStore using Ristretto
    ├── redis/         # RedisStore using Rueidis
    ├── sqlite/        # SQLiteStore implementation
    └── postgres/      # PostgresStore implementation

Design Patterns

• Store Abstraction — Pluggable backends implement Store interface
• Generic Cache Wrapper — Cache[T] wraps Store with type-safe API
• Functional Options — Configuration via WithTTL(), WithCodec(), etc.
• Single-Flight Deduplication — GetOrLoad prevents thundering herd
• Multi-Layer Caching — ChainCache supports L1/L2/L3 with automatic backfill

Testing

# Run all tests with race detection
go test -race ./...

# Run specific package tests
go test -race ./store/memory/
go test -race ./store/redis/

# Run benchmarks
go test -bench=. -benchmem ./...

# Run with coverage
go test -cover ./...

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Development Setup

# Clone repository
git clone https://github.com/kaptinlin/cache.git
cd cache

# Install dependencies
go mod download

# Run tests
go test -race ./...

# Run linting
golangci-lint run

License

MIT License - see LICENSE for details.

Acknowledgments

This library draws inspiration from:

• Ristretto — High-performance in-memory cache
• Rueidis — Modern Redis client with auto-pipelining
• Otter — Generic cache interface design
• golang-lru — Simple LRU cache patterns

Support

• Documentation: pkg.go.dev/github.com/kaptinlin/cache
• Issues: GitHub Issues
• Discussions: GitHub Discussions