Add pluggable persistence architecture

Author: Thomas Stromberg

Makefile

@@ -1,7 +1,8 @@
 .PHONY: test lint bench benchmark clean
 
 test:
-	go test -v -race -cover ./...
+	@echo "Running tests in all modules..."
+	@find . -name go.mod -execdir go test -v -race -cover ./... \;
 
 lint:
 	go vet ./...

README.md

@@ -8,7 +8,7 @@
 
 <br clear="right">
 
-Fast, persistent Go cache with S3-FIFO eviction - better hit rates than LRU, survives restarts with local files or Google Cloud Datastore, zero allocations.
+Fast, persistent Go cache with S3-FIFO eviction - better hit rates than LRU, survives restarts with pluggable persistence backends, zero allocations.
 
 ## Install
 
@@ -19,30 +19,42 @@ go get github.com/codeGROOVE-dev/bdcache
 ## Use
 
 ```go
+import (
+    "github.com/codeGROOVE-dev/bdcache"
+    "github.com/codeGROOVE-dev/bdcache/persist/localfs"
+)
+
 // Memory only
-cache, err := bdcache.New[string, int](ctx)
-if err != nil {
-    return err
-}
+cache, _ := bdcache.New[string, int](ctx)
 cache.Set(ctx, "answer", 42, 0)           // Synchronous: returns after persistence completes
 cache.SetAsync(ctx, "answer", 42, 0)      // Async: returns immediately, persists in background
-val, found, err := cache.Get(ctx, "answer")
-
-// With smart persistence (local files for dev, Google Cloud Datastore for Cloud Run)
-cache, err := bdcache.New[string, User](ctx, bdcache.WithBestStore("myapp"))
-
-// With Cloud Datastore persistence and automatic cleanup
-cache, err := bdcache.New[string, User](ctx,
-    bdcache.WithCloudDatastore("myapp"),
-    bdcache.WithCleanup(24*time.Hour), // Cleanup entries older than 24h
-)
+val, found, _ := cache.Get(ctx, "answer")
+
+// With local file persistence
+p, _ := localfs.New[string, User]("myapp", "")
+cache, _ := bdcache.New[string, User](ctx,
+    bdcache.WithPersistence(p))
+
+// With Valkey/Redis persistence
+p, _ := valkey.New[string, User](ctx, "myapp", "localhost:6379")
+cache, _ := bdcache.New[string, User](ctx,
+    bdcache.WithPersistence(p))
+
+// Cloud Run auto-detection (datastore in Cloud Run, localfs elsewhere)
+p, _ := cloudrun.New[string, User](ctx, "myapp")
+cache, _ := bdcache.New[string, User](ctx,
+    bdcache.WithPersistence(p))
 ```
 
 ## Features
 
 - **S3-FIFO eviction** - Better than LRU ([learn more](https://s3fifo.com/))
 - **Type safe** - Go generics
-- **Persistence** - Local files (gob) or Google Cloud Datastore (JSON)
+- **Pluggable persistence** - Bring your own database or use built-in backends:
+  - [`persist/localfs`](persist/localfs) - Local files (gob encoding, zero dependencies)
+  - [`persist/datastore`](persist/datastore) - Google Cloud Datastore
+  - [`persist/valkey`](persist/valkey) - Valkey/Redis
+  - [`persist/cloudrun`](persist/cloudrun) - Auto-detect Cloud Run
 - **Graceful degradation** - Cache works even if persistence fails
 - **Per-item TTL** - Optional expiration
 
@@ -73,64 +85,13 @@ Benchmarks on MacBook Pro M4 Max comparing memory-only Get operations:
 
 ### Competitive Analysis
 
-Independent benchmark using [scalalang2/go-cache-benchmark](https://github.com/scalalang2/go-cache-benchmark) (500K items, Zipfian distribution):
+Independent benchmark using [scalalang2/go-cache-benchmark](https://github.com/scalalang2/go-cache-benchmark) (500K items, Zipfian distribution) shows bdcache consistently ranks top 1-2 for hit rate across all cache sizes:
 
-**Hit Rate Leadership:**
-- **0.1% cache size**: bdcache **48.12%** vs SIEVE 47.42%, TinyLFU 47.37%, S3-FIFO 47.16%
-- **1% cache size**: bdcache **64.45%** vs TinyLFU 63.94%, Otter 63.60%, S3-FIFO 63.59%, SIEVE 63.33%
-- **10% cache size**: bdcache **80.39%** vs TinyLFU 80.43%, Otter 79.86%, S3-FIFO 79.84%
-
-Consistently ranks top 1-2 for hit rate across all cache sizes while maintaining competitive throughput (5-12M QPS). The S3-FIFO implementation prioritizes cache efficiency over raw speed, making bdcache ideal when hit rate matters.
-
-### Detailed Benchmarks
-
-Memory-only operations:
-```
-BenchmarkCache_Get_Hit-16      56M ops/sec    17.8 ns/op       0 B/op     0 allocs
-BenchmarkCache_Set-16          56M ops/sec    17.8 ns/op       0 B/op     0 allocs
-```
-
-With file persistence enabled:
-```
-BenchmarkCache_Get_PersistMemoryHit-16    85M ops/sec    11.8 ns/op       0 B/op     0 allocs
-BenchmarkCache_Get_PersistDiskRead-16     73K ops/sec    13.8 µs/op    7921 B/op   178 allocs
-BenchmarkCache_Set_WithPersistence-16      9K ops/sec   112.3 µs/op    2383 B/op    36 allocs
-```
-
-## Cloud Datastore TTL Setup
-
-When using Google Cloud Datastore persistence, configure native TTL policies for automatic expiration:
-
-### One-time Setup (per database)
-
-```bash
-# Enable TTL on the 'expiry' field for CacheEntry kind
-gcloud firestore fields ttls update expiry \
-  --collection-group=CacheEntry \
-  --enable-ttl \
-  --database=YOUR_CACHE_ID
-```
+- **0.1% cache size**: bdcache **48.12%** vs SIEVE 47.42%, TinyLFU 47.37%
+- **1% cache size**: bdcache **64.45%** vs TinyLFU 63.94%, Otter 63.60%
+- **10% cache size**: bdcache **80.39%** vs TinyLFU 80.43%, Otter 79.86%
 
-**Important:**
-- Replace `YOUR_CACHE_ID` with your cache ID (passed to `WithCloudDatastore()`)
-- This is a one-time setup per database
-- Datastore automatically deletes expired entries within 24 hours
-- No indexing needed on the expiry field (prevents hotspots)
-
-### Best Practices
-
-1. **Use Native TTL**: Let Datastore handle expiration automatically
-2. **Add Cleanup Fallback**: Use `WithCleanup()` as a safety net:
-   ```go
-   cache, err := bdcache.New[string, User](ctx,
-       bdcache.WithCloudDatastore("myapp"),
-       bdcache.WithCleanup(24*time.Hour), // Safety net for orphaned data
-   )
-   ```
-3. **Set Cleanup MaxAge**: Should match your longest TTL value
-4. **Monitor Costs**: TTL deletions count toward entity delete operations
-
-If native TTL is properly configured, `WithCleanup()` will find no entries (fast no-op).
+See [benchmarks/](benchmarks/) for detailed methodology and running instructions.
 
 ## License
 

benchmarks/README.md

@@ -71,6 +71,18 @@ Demonstrates S3-FIFO's scan resistance with a cherrypicked workload:
 
 This is a **best-case scenario for S3-FIFO**. Many real workloads won't see this dramatic of a difference.
 
+### Independent Hit Rate Benchmark
+
+Using [scalalang2/go-cache-benchmark](https://github.com/scalalang2/go-cache-benchmark) (500K items, Zipfian distribution):
+
+| Cache Size | bdcache | TinyLFU | Otter | S3-FIFO | SIEVE |
+|-----------|---------|---------|-------|---------|-------|
+| **0.1%** | **48.12%** | 47.37% | - | 47.16% | 47.42% |
+| **1%** | **64.45%** | 63.94% | 63.60% | 63.59% | 63.33% |
+| **10%** | **80.39%** | 80.43% | 79.86% | 79.84% | - |
+
+bdcache consistently ranks top 1-2 for hit rate while maintaining competitive throughput (5-12M QPS).
+
 ### Additional Tests
 
 ```bash

cache.go

@@ -3,6 +3,7 @@ package bdcache
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"log/slog"
 	"time"
@@ -17,7 +18,9 @@ type Cache[K comparable, V any] struct {
 
 // New creates a new cache with the given options.
 func New[K comparable, V any](ctx context.Context, options ...Option) (*Cache[K, V], error) {
-	opts := defaultOptions()
+	opts := &Options{
+		MemorySize: 10000,
+	}
 	for _, opt := range options {
 		opt(opts)
 	}
@@ -27,47 +30,45 @@ func New[K comparable, V any](ctx context.Context, options ...Option) (*Cache[K,
 		opts:   opts,
 	}
 
-	// Initialize persistence if configured
-	if opts.CacheID != "" {
-		var err error
-		if opts.UseDatastore {
-			cache.persist, err = newDatastorePersist[K, V](ctx, opts.CacheID)
+	// Set persistence from options
+	if opts.Persister != nil {
+		p, ok := opts.Persister.(PersistenceLayer[K, V])
+		if !ok {
+			return nil, errors.New("invalid persister type")
+		}
+		cache.persist = p
+		slog.Info("initialized cache with persistence")
+	}
+
+	// Run background cleanup if configured
+	if cache.persist != nil && opts.CleanupEnabled {
+		//nolint:contextcheck // Background cleanup uses detached context to complete independently
+		go func() {
+			// Create detached context with timeout - cleanup should complete independently
+			bgCtx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
+			defer cancel()
+
+			deleted, err := cache.persist.Cleanup(bgCtx, opts.CleanupMaxAge)
 			if err != nil {
-				slog.Warn("failed to initialize datastore persistence, continuing with memory-only cache",
-					"error", err, "cache_id", opts.CacheID)
-				cache.persist = nil
-			} else {
-				slog.Info("initialized cache with datastore persistence", "cache_id", opts.CacheID)
+				slog.Warn("error during cache cleanup", "error", err)
+				return
 			}
-		} else {
-			cache.persist, err = newFilePersist[K, V](opts.CacheID)
-			if err != nil {
-				slog.Warn("failed to initialize file persistence, continuing with memory-only cache",
-					"error", err, "cache_id", opts.CacheID)
-				cache.persist = nil
-			} else {
-				slog.Info("initialized cache with file persistence", "cache_id", opts.CacheID)
+			if deleted > 0 {
+				slog.Info("cache cleanup complete", "deleted", deleted)
 			}
-		}
+		}()
+	}
 
-		// Run background cleanup if configured
-		if cache.persist != nil && opts.CleanupEnabled {
-			go func() {
-				deleted, err := cache.persist.Cleanup(ctx, opts.CleanupMaxAge)
-				if err != nil {
-					slog.Warn("error during cache cleanup", "error", err)
-					return
-				}
-				if deleted > 0 {
-					slog.Info("cache cleanup complete", "deleted", deleted)
-				}
-			}()
-		}
+	// Warm up cache from persistence if configured
+	if cache.persist != nil && opts.WarmupLimit > 0 {
+		//nolint:contextcheck // Background warmup uses detached context to complete independently
+		go func() {
+			// Create detached context with timeout - warmup should complete independently
+			bgCtx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
+			defer cancel()
 
-		// Warm up cache from persistence if configured
-		if cache.persist != nil && opts.WarmupLimit > 0 {
-			go cache.warmup(ctx)
-		}
+			cache.warmup(bgCtx)
+		}()
 	}
 
 	return cache, nil
@@ -138,18 +139,24 @@ func (c *Cache[K, V]) Get(ctx context.Context, key K) (V, bool, error) {
 	return val, true, nil
 }
 
+// calculateExpiry returns the expiry time based on TTL and default TTL.
+func (c *Cache[K, V]) calculateExpiry(ttl time.Duration) time.Time {
+	if ttl > 0 {
+		return time.Now().Add(ttl)
+	}
+	if c.opts.DefaultTTL > 0 {
+		return time.Now().Add(c.opts.DefaultTTL)
+	}
+	return time.Time{}
+}
+
 // Set stores a value in the cache with an optional TTL.
 // A zero TTL means no expiration (or uses DefaultTTL if configured).
 // The value is ALWAYS stored in memory, even if persistence fails.
 // Returns an error if the key violates persistence constraints or if persistence fails.
 // Even when an error is returned, the value is cached in memory.
 func (c *Cache[K, V]) Set(ctx context.Context, key K, value V, ttl time.Duration) error {
-	var expiry time.Time
-	if ttl > 0 {
-		expiry = time.Now().Add(ttl)
-	} else if c.opts.DefaultTTL > 0 {
-		expiry = time.Now().Add(c.opts.DefaultTTL)
-	}
+	expiry := c.calculateExpiry(ttl)
 
 	// Validate key early if persistence is enabled
 	if c.persist != nil {
@@ -175,12 +182,7 @@ func (c *Cache[K, V]) Set(ctx context.Context, key K, value V, ttl time.Duration
 // Key validation and in-memory caching happen synchronously. Persistence errors are logged but not returned.
 // Returns an error only for validation failures (e.g., invalid key format).
 func (c *Cache[K, V]) SetAsync(ctx context.Context, key K, value V, ttl time.Duration) error {
-	var expiry time.Time
-	if ttl > 0 {
-		expiry = time.Now().Add(ttl)
-	} else if c.opts.DefaultTTL > 0 {
-		expiry = time.Now().Add(c.opts.DefaultTTL)
-	}
+	expiry := c.calculateExpiry(ttl)
 
 	// Validate key early if persistence is enabled (synchronous)
 	if c.persist != nil {
@@ -195,7 +197,11 @@ func (c *Cache[K, V]) SetAsync(ctx context.Context, key K, value V, ttl time.Dur
 	// Update persistence asynchronously if available
 	if c.persist != nil {
 		go func() {
-			if err := c.persist.Store(ctx, key, value, expiry); err != nil {
+			// Derive context with timeout to prevent hanging
+			storeCtx, cancel := context.WithTimeout(ctx, 30*time.Second)
+			defer cancel()
+
+			if err := c.persist.Store(storeCtx, key, value, expiry); err != nil {
 				slog.Warn("async persistence store failed", "error", err, "key", key)
 			}
 		}()