initial middleware with default LRU cache

Author: spdeepak

.github/workflows/go.yml

@@ -0,0 +1,31 @@
+name: Go
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Go
+      uses: actions/setup-go@v4
+      with:
+        go-version: '1.24'
+
+    - name: Build
+      run: go build -v ./...
+
+    - name: Test
+      run: go test -p 1 ./... -coverprofile=coverage.out
+
+    - name: Upload to Codecov
+      uses: codecov/codecov-action@v4
+      with:
+        token: ${{ secrets.CODECOV_TOKEN }}
+        files: coverage.out

.gitignore

@@ -28,5 +28,9 @@ go.work.sum
 .env
 
 # Editor/IDE
-# .idea/
-# .vscode/
+.idea/
+.vscode/
+*.xml
+*.iml
+vendor/
+*/vendor/

cache/cache.go

@@ -0,0 +1,43 @@
+package cache
+
+import (
+	"net/http"
+	"time"
+)
+
+// Store defines the contract for all storage backends.
+type Store interface {
+	Get(key string) (*ResponseCacheEntry, bool)
+	Set(key string, entry *ResponseCacheEntry) error
+	Delete(key string) error
+	Close() error // For graceful shutdown/cleanup
+}
+
+// ResponseCacheEntry holds the complete HTTP response data and caching metadata.
+type ResponseCacheEntry struct {
+	StatusCode int
+	Headers    http.Header
+	Body       []byte
+	CreatedAt  time.Time
+	TTL        time.Duration // Time-to-Live (Freshness)
+	SWR        time.Duration // Stale-While-Revalidate window
+}
+
+// Size returns the estimated memory footprint in bytes.
+func (e *ResponseCacheEntry) Size() int64 {
+	// Simple size estimation: Body length + headers map/string overhead
+	bodySize := int64(len(e.Body))
+	// Heuristic: ~30 bytes per header key/value pair overhead
+	headerSize := int64(len(e.Headers) * 30)
+	return bodySize + headerSize
+}
+
+// IsStale checks if the entry is past its TTL.
+func (e *ResponseCacheEntry) IsStale() bool {
+	return time.Since(e.CreatedAt) > e.TTL
+}
+
+// IsRotten checks if the entry is past its Stale-While-Revalidate window.
+func (e *ResponseCacheEntry) IsRotten() bool {
+	return time.Since(e.CreatedAt) > (e.TTL + e.SWR)
+}

cache/in_memory_quota_lru.go

@@ -0,0 +1,106 @@
+package cache
+
+import (
+	"container/list"
+	"sync"
+)
+
+// lruEntry links the cache key and the entry to the list element.
+type lruEntry struct {
+	key   string
+	size  int64
+	value *ResponseCacheEntry
+}
+
+// InMemoryQuotaLRU implements Store with a hard memory limit and LRU policy.
+type InMemoryQuotaLRU struct {
+	mutex sync.RWMutex
+	// Doubly linked list for LRU order
+	lru   *list.List
+	cache map[string]*list.Element
+	// Hard memory limit in bytes
+	maxBytes int64
+	// Current total size of all stored items
+	currentBytes int64
+}
+
+// NewInMemoryQuotaLRU creates a new InMemoryQuotaLRU cache.
+// maxMB is the memory limit in megabytes.
+func NewInMemoryQuotaLRU(maxMB int) Store {
+	return &InMemoryQuotaLRU{
+		lru:      list.New(),
+		cache:    make(map[string]*list.Element),
+		maxBytes: int64(maxMB) * 1024 * 1024,
+	}
+}
+
+// Get retrieves an entry and moves it to the front of the list (MRU).
+func (lru *InMemoryQuotaLRU) Get(key string) (*ResponseCacheEntry, bool) {
+	// Step 1: Read lock to check existence
+	lru.mutex.RLock()
+	element, ok := lru.cache[key]
+	lru.mutex.RUnlock()
+	if !ok {
+		return nil, false
+	}
+
+	// Step 2: Only lock for moving element to front
+	lru.mutex.Lock()
+	lru.lru.MoveToFront(element)
+	lru.mutex.Unlock()
+
+	return element.Value.(*lruEntry).value, true
+}
+
+// Set adds or updates an entry, triggering eviction if the hard memory limit is hit.
+func (lru *InMemoryQuotaLRU) Set(key string, entry *ResponseCacheEntry) error {
+	// compute before acquiring lock
+	itemSize := entry.Size()
+
+	lru.mutex.Lock()
+	defer lru.mutex.Unlock()
+
+	if element, ok := lru.cache[key]; ok {
+		oldEntry := element.Value.(*lruEntry)
+		lru.currentBytes -= oldEntry.size
+		oldEntry.size = itemSize
+		oldEntry.value = entry
+		lru.currentBytes += itemSize
+		lru.lru.MoveToFront(element)
+	} else {
+		newEntry := &lruEntry{key: key, size: itemSize, value: entry}
+		element := lru.lru.PushFront(newEntry)
+		lru.cache[key] = element
+		lru.currentBytes += itemSize
+	}
+
+	// Eviction
+	for lru.currentBytes > lru.maxBytes {
+		lruElement := lru.lru.Back()
+		if lruElement == nil {
+			break
+		}
+		evictedEntry := lru.lru.Remove(lruElement).(*lruEntry)
+		delete(lru.cache, evictedEntry.key)
+		lru.currentBytes -= evictedEntry.size
+	}
+	return nil
+}
+
+// Delete removes an entry from the cache.
+func (lru *InMemoryQuotaLRU) Delete(key string) error {
+	lru.mutex.Lock()
+	defer lru.mutex.Unlock()
+
+	if element, ok := lru.cache[key]; ok {
+		evictedEntry := lru.lru.Remove(element).(*lruEntry)
+		delete(lru.cache, evictedEntry.key)
+		lru.currentBytes -= evictedEntry.size
+	}
+	return nil
+}
+
+// Close is a no-op for in-memory, but required by the interface.
+func (lru *InMemoryQuotaLRU) Close() error {
+	return nil
+}

config.go

@@ -0,0 +1,94 @@
+package capsulecache
+
+import (
+	"bytes"
+	"crypto/sha256"
+	"encoding/hex"
+	"io"
+	"net/http"
+	"strings"
+	"time"
+)
+
+// Config holds the middleware settings.
+type Config struct {
+	// DefaultTTL is how long a cached entry is considered fresh.
+	DefaultTTL time.Duration
+	// DefaultSWR is the stale-while-revalidate window.
+	DefaultSWR   time.Duration
+	KeyGenerator func(*http.Request) string
+	// ShouldCache decides whether a response with given status code should be cached.
+	ShouldCache func(statusCode int) bool
+	// MaxBodyBytes - do not cache bodies larger than this.
+	MaxBodyBytes int64
+	// StripHeaders removes headers before storing (hop-by-hop etc).
+	StripHeaders func(http.Header) http.Header
+}
+
+// DefaultConfig provides defaults.
+var DefaultConfig = &Config{
+	DefaultTTL:   5 * time.Minute,
+	DefaultSWR:   1 * time.Minute,
+	KeyGenerator: DefaultKeyGenerator,
+	ShouldCache: func(statusCode int) bool {
+		// Only cache successful responses by default
+		return statusCode >= http.StatusOK && statusCode < http.StatusMultipleChoices
+	},
+	StripHeaders: stripHopByHop,
+}
+
+// DefaultKeyGenerator creates a simple cache key (Method:Path).
+func DefaultKeyGenerator(r *http.Request) string {
+	return "cache:" + r.Method + ":" + r.URL.Path
+}
+
+// AdvancedKeyGenerator includes specified headers and body hash (for POST/PUT).
+func AdvancedKeyGenerator(r *http.Request, headersToInclude []string) string {
+	// 1. Base Key
+	key := r.Method + ":" + r.URL.Path
+
+	// 2. Add Headers
+	for _, header := range headersToInclude {
+		if val := r.Header.Get(header); val != "" {
+			key += ":" + header + "=" + val
+		}
+	}
+
+	// 3. Add Body Hash (for safe caching of idempotent requests like POST to a search endpoint)
+	if r.ContentLength > 0 && (r.Method == http.MethodPost || r.Method == http.MethodPut) {
+		var buf bytes.Buffer
+		// TeeReader allows reading the body while writing it to buf
+		tee := io.TeeReader(r.Body, &buf)
+		bodyBytes, _ := io.ReadAll(tee)
+		r.Body.Close()
+		r.Body = io.NopCloser(&buf) // restore body for downstream
+
+		hash := sha256.Sum256(bodyBytes)
+		key += ":body_hash=" + hex.EncodeToString(hash[:])
+	}
+
+	return key
+}
+
+func stripHopByHop(header http.Header) http.Header {
+	// Clone so caller can mutate safely.
+	headerClone := header.Clone()
+
+	for _, k := range []string{
+		"Connection", "Proxy-Connection", "Keep-Alive",
+		"Proxy-Authenticate", "Proxy-Authorization", "TE",
+		"Trailer", "Transfer-Encoding", "Upgrade",
+	} {
+		headerClone.Del(k)
+	}
+	// Also remove hop-by-hop values referenced by Connection header
+	if conn := header.Get("Connection"); conn != "" {
+		for _, token := range strings.Split(conn, ",") {
+			token = strings.TrimSpace(token)
+			if token != "" {
+				headerClone.Del(token)
+			}
+		}
+	}
+	return headerClone
+}

go.mod

@@ -0,0 +1,7 @@
+module github.com/spdeepak/capsulecache
+
+go 1.24.0
+
+toolchain go1.24.7
+
+require golang.org/x/sync v0.18.0

go.sum

@@ -0,0 +1,2 @@
+golang.org/x/sync v0.18.0 h1:kr88TuHDroi+UVf+0hZnirlk8o8T+4MrK6mr60WkH/I=
+golang.org/x/sync v0.18.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=