cache

Cache Package

A flexible caching solution for Go applications that supports both in-memory and Redis backends. Switch between drivers with just an environment variable - no code changes required.

Features

• Multiple Drivers: Built-in memory cache and Redis support
• Zero Code Changes: Switch drivers via environment variables
• Environment-First: Follows Beaver Kit's BEAVER_ prefix convention
• Connection Pooling: Optimized Redis connection management
• TTL Support: Set expiration times for cached values
• Namespace Isolation: Separate cache spaces with prefixes
• Health Checks: Built-in health monitoring
• Thread-Safe: Safe for concurrent use

Installation

go get github.com/gobeaver/beaver-kit/cache

Quick Start

Using Environment Variables

# For in-memory cache (default)
export BEAVER_CACHE_DRIVER=memory

# For Redis
export BEAVER_CACHE_DRIVER=redis
export BEAVER_CACHE_HOST=localhost
export BEAVER_CACHE_PORT=6379

package main

import (
    "context"
    "log"
    "time"
    
    "github.com/gobeaver/beaver-kit/cache"
)

func main() {
    // Initialize from environment
    if err := cache.Init(); err != nil {
        log.Fatal(err)
    }
    
    ctx := context.Background()
    
    // Store a value
    err := cache.Set(ctx, "user:123", []byte("John Doe"), 5*time.Minute)
    if err != nil {
        log.Fatal(err)
    }
    
    // Retrieve a value
    data, err := cache.Get(ctx, "user:123")
    if err != nil {
        log.Fatal(err)
    }
    
    log.Printf("User: %s", string(data))
}

Using Specific Configuration

// In-memory cache
memCache, err := cache.New(cache.Config{
    Driver:    "memory",
    MaxKeys:   10000,
    MaxSize:   100 * 1024 * 1024, // 100MB
    DefaultTTL: 10 * time.Minute,
})

// Redis cache
redisCache, err := cache.New(cache.Config{
    Driver:   "redis",
    Host:     "localhost",
    Port:     "6379",
    Database: 0,
    KeyPrefix: "myapp:",
})

Configuration

Environment Variables

Driver Features

Memory Driver

• Zero dependencies
• Fast for small datasets
• Automatic cleanup of expired items
• Memory and key count limits
• Best for: Development, small apps, temporary data

Redis Driver

• Distributed caching across servers
• Persistence options
• Pub/sub capabilities
• Clustering support
• Best for: Production, microservices, shared cache

API Reference

Core Operations

// Get retrieves a value by key
Get(ctx context.Context, key string) ([]byte, error)

// Set stores a value with optional TTL
Set(ctx context.Context, key string, value []byte, ttl time.Duration) error

// Delete removes a key
Delete(ctx context.Context, key string) error

// Exists checks if a key exists
Exists(ctx context.Context, key string) (bool, error)

// Clear removes all keys (with prefix if configured)
Clear(ctx context.Context) error

// Ping checks if cache is reachable
Ping(ctx context.Context) error

Global Functions

All operations are available as package-level functions after initialization:

cache.Init()
cache.Set(ctx, "key", data, ttl)
cache.Get(ctx, "key")
cache.Delete(ctx, "key")
cache.Exists(ctx, "key")
cache.Clear(ctx)
cache.IsHealthy()

Examples

Switching Drivers Without Code Changes

// Your code remains the same
func saveUserSession(userID string, session []byte) error {
    return cache.Set(context.Background(), 
        fmt.Sprintf("session:%s", userID), 
        session, 
        30*time.Minute)
}

// Switch driver via environment
// Development: BEAVER_CACHE_DRIVER=memory
// Production:  BEAVER_CACHE_DRIVER=redis

Using Namespaces

// Separate cache spaces for different services
userCache, _ := cache.New(cache.Config{
    Driver:    "redis",
    Namespace: "users",
})

orderCache, _ := cache.New(cache.Config{
    Driver:    "redis",
    Namespace: "orders",
})

// Keys are automatically prefixed: "users:123", "orders:456"

Connection URL

// Use Redis URL for cloud providers
cache.Init(cache.Config{
    Driver: "redis",
    URL:    "redis://user:pass@redis.example.com:6379/0",
})

Health Monitoring

// Check cache health
if !cache.IsHealthy() {
    log.Println("Cache is down!")
}

// Or with context
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
defer cancel()

if err := cache.Health(ctx); err != nil {
    log.Printf("Cache unhealthy: %v", err)
}

Testing

The package includes comprehensive tests for both drivers:

# Run all tests
go test ./cache/...

# Test with Redis (requires running Redis)
docker run -d -p 6379:6379 redis:alpine
go test ./cache/...

Performance Considerations

Memory Driver

• O(1) operations for get/set/delete
• Cleanup runs periodically (configurable)
• Best for <100MB of data
• Consider MaxKeys to prevent unbounded growth

Redis Driver

• Network latency considerations
• Use connection pooling settings
• Enable pipelining for batch operations
• Consider Redis persistence settings

Error Handling

data, err := cache.Get(ctx, "key")
if err != nil {
    if errors.Is(err, cache.ErrKeyNotFound) {
        // Key doesn't exist
    } else {
        // Other error (network, etc.)
    }
}

Thread Safety

Both drivers are safe for concurrent use. The memory driver uses fine-grained locking, while Redis handles concurrency at the server level.