Capsule Cache

A lightweight, memory-quota-aware HTTP output cache middleware for Go web frameworks like Gin, Chi, and Fiber. This package addresses the challenge of safely deploying in-memory caches in containerized environments (like Kubernetes) by enforcing a strict memory limit.

---

Key Features

• Hard Memory Limit (Quota): Prevents Out-of-Memory (OOM) issues in containerized environments by evicting Least Recently Used (LRU) items when a configurable MB limit is hit. This ensures stability in memory-constrained setups.
• Framework Agnostic: Implemented as a standard net/http middleware, ensuring compatibility with all major Go routers (Gin, Chi, Fiber via their adapter methods).
• Stale-While-Revalidate (SWR): Serves stale content instantly while triggering a non-blocking background refresh to update the cache entry.
• Time-to-Live (TTL): Standard freshness control for cached entries.
• Pluggable Backend: Ships with a memory-safe LRU store and an interface for easy integration with external services like Redis.
• Flexible Key Strategy: Supports cache keys based on URL, headers, and request body hash for varied API use cases (e.g., translation services, API throttling).

---

Installation

go get github.com/spdeepak/capsulecache

---

Usage

The core of the package is the NewCacheMiddleware function, which requires a Store implementation and a Config.

1. Setup the Cache Store (In-Memory LRU with Quota)

The example below sets a hard memory limit of 100 Megabytes (MB).

package main
import (
"log""net/http""time""github.com/go-chi/chi/v5""github.com/spdeepak/capsulecache"
)
// Global store for access in other handlers (e.g., for manual invalidation)varstore cache.CacheStorefuncmain() {
// Initialize the In-Memory Cache Store with a hard limit of 100 MBconstmaxMemoryMB=100store=cache.NewInMemoryQuotaLRU(maxMemoryMB)
deferstore.Close()
// Configure the Middlewarecfg:=&cache.Config{
DefaultTTL: 1*time.Minute,
DefaultSWR: 15*time.Second, // Allow stale content for 15s while refreshing
}
// Initialize the MiddlewarecacheMiddleware:=cache.NewCacheMiddleware(store, cfg)
// Setup Chi Routerr:=chi.NewRouter()
// Apply the cache middleware to a specific route group or handlerr.Group(func(r chi.Router) {
r.Use(cacheMiddleware) // Apply cache to handlers in this groupr.Get("/api/products/{id}", productHandler)
r.Get("/public/data", publicDataHandler)
})
// Non-cached router.Post("/api/products", createProductHandler)
log.Println("Server starting on :8080")
http.ListenAndServe(":8080", r)
}
// Example HandlerfuncpublicDataHandler(w http.ResponseWriter, r*http.Request) {
// This expensive operation will only run once per cache TTLtime.Sleep(500*time.Millisecond) w.Write([]byte("Cached response: "+time.Now().Format(time.RFC3339)))
}

2. Integration with Frameworks

Framework	Integration Method	Example
Chi	Standard r.Use(middleware)	See example above (r.Use(cacheMiddleware))
Gin	Use gin.WrapH()	r.GET("/path", gin.WrapH(cacheMiddleware(http.HandlerFunc(myHandler))))
Fiber	Use the standard net/http adapter (e.g., adaptor.HTTPHandlerFunc)	app.Use(adaptor.HTTPHandlerFunc(cacheMiddleware(http.HandlerFunc(myHandler))))

---

Cache Invalidation

For compliance or immediate content updates, the Delete method on the CacheStore can be used to manually purge an entry.

// Example: Purging a cache entry after a POST requestfunccreateProductHandler(w http.ResponseWriter, r*http.Request) {
// ... logic to create product ...productID:="123"// Assume product ID is knownproductKey:="GET:/api/products/"+productID// Must match the KeyGenerator logic// Invalidate the cached GET response for the productiferr:=store.Delete(productKey); err!=nil {
log.Printf("Failed to purge cache for key %s: %v", productKey, err)
}
w.WriteHeader(http.StatusCreated)
}

---

Custom Cache Key Strategy

You can define a custom function to include specific headers (e.g., Accept-Language for translation services) in the cache key.

// Example: Caching based on URL AND Accept-Language headerfuncKeyWithLanguage(r*http.Request) string {
// Assuming DefaultKeyGenerator is also exported from capsulecache/cachebaseKey:=cache.DefaultKeyGenerator(r) lang:=r.Header.Get("Accept-Language")
iflang!="" {
// Simple extraction for the primary language tag (e.g., "en-US,en;q=0.9" -> "en-US")iflen(lang) >5 { lang=lang[:5] }
returnbaseKey+":lang="+lang
}
returnbaseKey
}
// In main():// cfg := &cache.Config{// DefaultTTL: 1 * time.Minute,// KeyGenerator: KeyWithLanguage,// }