cache

Overview ¶

Package cache provides Redis-based caching for StreamSpace API.

This file implements the core Redis cache client with connection pooling.

Purpose: - Provide high-performance caching for frequently accessed data - Reduce database load for read-heavy operations - Enable distributed caching across multiple API instances - Support atomic operations and distributed locks

Features: - Connection pooling (25 max connections, 5 min idle) - Automatic retry with exponential backoff - Graceful fallback when Redis is unavailable (cache disabled mode) - JSON serialization/deserialization - TTL-based expiration - Pattern-based invalidation - Atomic counters and distributed locks (SetNX) - Statistics and monitoring (pool stats, hit/miss tracking)

Cache Strategy:

• Get: Retrieve value, deserialize JSON
• Set: Serialize to JSON, store with TTL
• Delete: Remove single or multiple keys
• DeletePattern: Bulk invalidation via pattern matching
• SetNX: Distributed lock acquisition

Implementation Details: - Uses go-redis client with connection pooling - Auto-reconnection on connection failures - 3 retry attempts with 8-512ms exponential backoff - 5-second dial timeout, 3-second read/write timeouts - Values stored as JSON for flexibility

Thread Safety: - Redis client is thread-safe - Safe for concurrent access across goroutines

Dependencies: - github.com/redis/go-redis/v9 for Redis client

Example Usage:

// Initialize cache
cache, err := cache.NewCache(cache.Config{
    Host:     "localhost",
    Port:     "6379",
    Password: "",
    DB:       0,
    Enabled:  true,
})
if err != nil {
    log.Fatal(err)
}
defer cache.Close()

// Store session in cache
err = cache.Set(ctx, cache.SessionKey("session-123"), session, 5*time.Minute)

// Retrieve from cache
var session Session
err = cache.Get(ctx, cache.SessionKey("session-123"), &session)

// Invalidate user's sessions
err = cache.DeletePattern(ctx, cache.UserPattern("user-123"))

Package cache provides Redis-based caching for StreamSpace API.

This file defines standardized cache key naming conventions and patterns.

Purpose: - Provide consistent cache key naming across all cache operations - Enable efficient cache invalidation via pattern matching - Organize cache keys by resource type - Support multi-level cache hierarchies

Features: - Resource-specific key prefixes (session, user, template, quota) - Hierarchical key structure (prefix:resource:identifier) - Pattern-based invalidation (session:*, user:123:*) - User-scoped keys for isolation - List and collection keys

Key Naming Convention:

• Format: {prefix}:{resource}:{identifier}
• Example: session:user1-firefox
• Example: user:username:alice
• Example: quota:user:user123

Key Patterns for Invalidation:

• session:* - All sessions
• *:user:123* - All user-specific caches
• template:category:browsers - Templates in category

Implementation Details: - Keys use colon (:) as separator for Redis best practices - Prefixes prevent key collisions across resource types - Patterns use wildcards (*) for bulk invalidation

Example Usage:

// Generate cache key for session
key := cache.SessionKey("user1-firefox")
// Result: "session:user1-firefox"

// Generate key for user by username
key := cache.UserByUsernameKey("alice")
// Result: "user:username:alice"

// Invalidate all user-related caches
pattern := cache.UserPattern("user123")
err := cache.DeletePattern(ctx, pattern)
// Deletes: user:user123, session:user:user123:list, quota:user:user123, etc.

Package cache provides Redis-based caching for StreamSpace API.

This file implements HTTP caching middleware for Gin framework.

Purpose: - Cache HTTP GET responses to reduce backend load - Automatically invalidate cache on mutations (POST, PUT, DELETE) - Add cache control headers for browser/CDN caching - Provide cache hit/miss transparency

Features: - Response caching for GET requests - Cache key generation from request URI (SHA-256 hash) - Automatic cache invalidation after mutations - X-Cache header (HIT/MISS) for debugging - Async cache operations (non-blocking) - Cache-Control headers for browser caching

Middleware Types:

• CacheMiddleware: Caches GET responses
• InvalidateCacheMiddleware: Clears cache after mutations
• CacheControl: Adds Cache-Control headers

Implementation Details: - Only caches successful responses (2xx status codes) - Response body captured via custom ResponseWriter - Cache operations run asynchronously to avoid blocking requests - Cache keys generated via SHA-256 hash of request URI - Gracefully handles cache unavailability (continues without caching)

Thread Safety: - Middleware is thread-safe (uses goroutines for async operations) - Safe for concurrent requests

Dependencies: - github.com/gin-gonic/gin for HTTP framework

Example Usage:

// Apply response caching middleware
router.Use(cache.CacheMiddleware(cacheClient, 5*time.Minute))

// Apply cache invalidation for mutations
router.POST("/sessions", cache.InvalidateCacheMiddleware(cacheClient, cache.SessionPattern()), handler)

// Add cache control headers
router.Use(cache.CacheControl(1*time.Hour))

// Result:
//   - GET /sessions: Cached for 5 minutes, X-Cache: HIT/MISS header added
//   - POST /sessions: Invalidates all session:* keys
//   - Response includes: Cache-Control: public, max-age=3600