cachex

package module
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 22, 2025 License: MIT Imports: 26 Imported by: 0

README ΒΆ

Go-CacheX

A production-grade, highly concurrent, async cache library for Go with multiple backend support and comprehensive observability features.

Go Report Card Go Version License Tests

πŸš€ Features

  • High Performance: Async I/O with non-blocking operations returning channels
  • Multiple Backends: Memory, Redis, Ristretto, and Layered store support
  • Thread-Safe: Comprehensive concurrency controls with race-free design
  • Type-Safe: Generic API with compile-time type safety
  • Observability: OpenTelemetry tracing, Prometheus metrics, structured logging
  • Caching Patterns: Read-Through, Write-Through, Write-Behind, Refresh-Ahead
  • Production Ready: Circuit breakers, retries, distributed locks
  • Flexible Configuration: YAML config files and environment variables

πŸ“¦ Installation

go get github.com/SeaSBee/go-cachex

🎯 Quick Start

Configuration Files

The library supports YAML configuration files for easy setup. Two configuration files are provided:

  • cachex-config-reference.yaml: Complete reference with all available options
  • cachex-config-example.yaml: Practical example you can copy and modify
// Load configuration from YAML file
cache, err := cachex.NewFromConfig[User]("cachex-config-example.yaml")
if err != nil {
    panic(err)
}
defer cache.Close()
Basic Usage with Memory Store
package main

import (
    "context"
    "fmt"
    "time"

    "github.com/SeaSBee/go-cachex"
)

type User struct {
    ID   string `json:"id"`
    Name string `json:"name"`
    Email string `json:"email"`
}

func main() {
    // Create memory store
    store, err := cachex.NewMemoryStore(cachex.DefaultMemoryConfig())
    if err != nil {
        panic(err)
    }
    defer store.Close()

    // Create cache instance
    cache, err := cachex.New[User](
        cachex.WithStore(store),
        cachex.WithDefaultTTL(5*time.Minute),
    )
    if err != nil {
        panic(err)
    }
    defer cache.Close()

    ctx := context.Background()
    user := User{ID: "123", Name: "John Doe", Email: "john@example.com"}

    // Set value (async operation)
    setResult := <-cache.Set(ctx, "user:123", user, 10*time.Minute)
    if setResult.Error != nil {
        panic(setResult.Error)
    }

    // Get value (async operation)
    getResult := <-cache.Get(ctx, "user:123")
    if getResult.Error != nil {
        panic(getResult.Error)
    }
    
    if getResult.Found {
        fmt.Printf("Found user: %+v\n", getResult.Value)
    } else {
        fmt.Println("User not found")
    }
}
Redis Store Usage
package main

import (
    "context"
    "fmt"
    "time"

    "github.com/SeaSBee/go-cachex"
)

func main() {
    // Create Redis store
    redisConfig := cachex.DefaultRedisConfig()
    redisConfig.Addr = "localhost:6379"
    
    store, err := cachex.NewRedisStore(redisConfig)
    if err != nil {
        panic(err)
    }
    defer store.Close()

    // Create cache with JSON codec
    cache, err := cachex.New[map[string]interface{}](
        cachex.WithStore(store),
        cachex.WithCodec(cachex.NewJSONCodec()),
        cachex.WithDefaultTTL(10*time.Minute),
    )
    if err != nil {
        panic(err)
    }
    defer cache.Close()

    ctx := context.Background()
    data := map[string]interface{}{
        "id":   "456",
        "name": "Jane Smith",
        "age":  30,
    }

    // Async operations
    setResult := <-cache.Set(ctx, "user:456", data, 15*time.Minute)
    if setResult.Error != nil {
        panic(setResult.Error)
    }

    getResult := <-cache.Get(ctx, "user:456")
    if getResult.Error != nil {
        panic(getResult.Error)
    }

    if getResult.Found {
        fmt.Printf("Retrieved: %+v\n", getResult.Value)
    }
}
Configuration-Based Setup
package main

import (
    "context"
    "fmt"

    "github.com/SeaSBee/go-cachex"
)

func main() {
    // Load from YAML configuration
    config, err := cachex.LoadConfig("config.yaml")
    if err != nil {
        panic(err)
    }

    // Create cache from configuration
    cache, err := cachex.NewFromConfig[string](config)
    if err != nil {
        panic(err)
    }
    defer cache.Close()

    ctx := context.Background()
    
    // Use the configured cache
    setResult := <-cache.Set(ctx, "key1", "value1", 0) // Uses default TTL from config
    if setResult.Error != nil {
        panic(setResult.Error)
    }

    getResult := <-cache.Get(ctx, "key1")
    if getResult.Error != nil {
        panic(getResult.Error)
    }

    if getResult.Found {
        fmt.Printf("Value: %s\n", getResult.Value)
    }
}

πŸ—οΈ Architecture

Core Interface (Async API)
type Cache[T any] interface {
    // Context management
    WithContext(ctx context.Context) Cache[T]

    // Basic operations (all non-blocking, return channels)
    Get(ctx context.Context, key string) <-chan AsyncCacheResult[T]
    Set(ctx context.Context, key string, val T, ttl time.Duration) <-chan AsyncCacheResult[T]
    MGet(ctx context.Context, keys ...string) <-chan AsyncCacheResult[T]
    MSet(ctx context.Context, items map[string]T, ttl time.Duration) <-chan AsyncCacheResult[T]
    Del(ctx context.Context, keys ...string) <-chan AsyncCacheResult[T]
    Exists(ctx context.Context, key string) <-chan AsyncCacheResult[T]
    TTL(ctx context.Context, key string) <-chan AsyncCacheResult[T]
    IncrBy(ctx context.Context, key string, delta int64, ttlIfCreate time.Duration) <-chan AsyncCacheResult[T]

    // Caching patterns
    ReadThrough(ctx context.Context, key string, ttl time.Duration, loader func(ctx context.Context) (T, error)) <-chan AsyncCacheResult[T]
    WriteThrough(ctx context.Context, key string, val T, ttl time.Duration, writer func(ctx context.Context) error) <-chan AsyncCacheResult[T]
    WriteBehind(ctx context.Context, key string, val T, ttl time.Duration, writer func(ctx context.Context) error) <-chan AsyncCacheResult[T]
    RefreshAhead(ctx context.Context, key string, refreshBefore time.Duration, loader func(ctx context.Context) (T, error)) <-chan AsyncCacheResult[T]

    // Tagging
    AddTags(ctx context.Context, key string, tags ...string) <-chan AsyncCacheResult[T]
    InvalidateByTag(ctx context.Context, tags ...string) <-chan AsyncCacheResult[T]

    // Distributed locks
    TryLock(ctx context.Context, key string, ttl time.Duration) <-chan AsyncLockResult

    // Statistics and lifecycle
    GetStats() map[string]any
    Close() error
}
Available Store Types
1. Memory Store (In-Memory)
// Default configuration
store, err := cachex.NewMemoryStore(cachex.DefaultMemoryConfig())

// Custom configuration
config := &cachex.MemoryConfig{
    MaxSize:         10000,
    MaxMemoryMB:     100,
    DefaultTTL:      5 * time.Minute,
    CleanupInterval: 1 * time.Minute,
    EvictionPolicy:  cachex.EvictionPolicyLRU, // LRU, LFU, TTL
    EnableStats:     true,
}
store, err := cachex.NewMemoryStore(config)
2. Redis Store (Distributed)
// Default configuration
store, err := cachex.NewRedisStore(cachex.DefaultRedisConfig())

// Custom configuration
config := &cachex.RedisConfig{
    Addr:             "localhost:6379",
    Password:         "",
    DB:               0,
    PoolSize:         10,
    MinIdleConns:     5,
    MaxRetries:       3,
    DialTimeout:      5 * time.Second,
    ReadTimeout:      3 * time.Second,
    WriteTimeout:     3 * time.Second,
    EnablePipelining: true,
    EnableMetrics:    true,
}
store, err := cachex.NewRedisStore(config)
3. Ristretto Store (High-Performance In-Memory)
// Default configuration
store, err := cachex.NewRistrettoStore(cachex.DefaultRistrettoConfig())

// Custom configuration
config := &cachex.RistrettoConfig{
    MaxItems:       10000,
    MaxMemoryBytes: 512 * 1024 * 1024, // 512MB
    DefaultTTL:     30 * time.Minute,
    NumCounters:    100000,
    BufferItems:    64,
    EnableMetrics:  true,
}
store, err := cachex.NewRistrettoStore(config)
4. Layered Store (Multi-Level Caching)
// Create L2 store (typically Redis)
l2Store, err := cachex.NewRedisStore(cachex.DefaultRedisConfig())

// Create layered store
config := cachex.DefaultLayeredConfig()
config.WritePolicy = cachex.WritePolicyThrough
config.ReadPolicy = cachex.ReadPolicyThrough

layeredStore, err := cachex.NewLayeredStore(l2Store, config)

βš™οΈ Configuration

YAML Configuration Example
# config.yaml
memory:
  max_size: 10000
  max_memory_mb: 100
  default_ttl: 5m
  cleanup_interval: 1m
  eviction_policy: "lru"
  enable_stats: true

# OR use Redis (only one store type allowed)
# redis:
#   addr: "localhost:6379"
#   password: ""
#   db: 0
#   pool_size: 10
#   dial_timeout: 5s

default_ttl: 10m
max_retries: 3
retry_delay: 100ms
codec: "json"  # or "msgpack"

observability:
  enable_metrics: true
  enable_tracing: true
  enable_logging: true
Environment Variables
# Store configuration
CACHEX_STORE_TYPE=memory  # memory, redis, ristretto
CACHEX_REDIS_ADDR=localhost:6379
CACHEX_REDIS_PASSWORD=your_password
CACHEX_REDIS_DB=0

# Cache settings
CACHEX_DEFAULT_TTL=5m
CACHEX_MAX_RETRIES=3
CACHEX_CODEC=json

# Observability
CACHEX_ENABLE_METRICS=true
CACHEX_ENABLE_TRACING=true
CACHEX_ENABLE_LOGGING=true

πŸ”„ Caching Patterns

1. Cache-Aside (Manual)
ctx := context.Background()

// Try to get from cache first
getResult := <-cache.Get(ctx, "user:123")
if getResult.Error != nil {
    // Handle error
    return
}

var user User
if getResult.Found {
    user = getResult.Value
} else {
    // Load from database
    user = loadUserFromDB("123")
    
    // Store in cache
    setResult := <-cache.Set(ctx, "user:123", user, 10*time.Minute)
    if setResult.Error != nil {
        // Handle cache set error (optional)
        log.Printf("Failed to cache user: %v", setResult.Error)
    }
}
2. Read-Through (Automatic Loading)
ctx := context.Background()

// Automatically loads from source if not in cache
result := <-cache.ReadThrough(ctx, "user:123", 10*time.Minute, func(ctx context.Context) (User, error) {
    return loadUserFromDB("123")
})

if result.Error != nil {
    // Handle error
    return
}

user := result.Value
3. Write-Behind (Async Persistence)
ctx := context.Background()

// Cache immediately, persist asynchronously
result := <-cache.WriteBehind(ctx, "user:123", user, 10*time.Minute, func(ctx context.Context) error {
    return saveUserToDB(user)
})

if result.Error != nil {
    // Handle error
    return
}
4. Refresh-Ahead (Proactive Refresh)
ctx := context.Background()

// Refresh cache before expiration
result := <-cache.RefreshAhead(ctx, "user:123", 1*time.Minute, func(ctx context.Context) (User, error) {
    return loadUserFromDB("123")
})

if result.Error != nil {
    // Handle error
    return
}

πŸ”’ Advanced Features

Batch Operations
ctx := context.Background()

// Batch set
items := map[string]User{
    "user:1": {ID: "1", Name: "Alice"},
    "user:2": {ID: "2", Name: "Bob"},
}
msetResult := <-cache.MSet(ctx, items, 10*time.Minute)

// Batch get
keys := []string{"user:1", "user:2"}
mgetResult := <-cache.MGet(ctx, keys...)
if mgetResult.Error == nil {
    for key, user := range mgetResult.Values {
        fmt.Printf("%s: %+v\n", key, user)
    }
}
Distributed Locking
ctx := context.Background()

// Try to acquire distributed lock
lockResult := <-cache.TryLock(ctx, "lock:critical-section", 30*time.Second)
if lockResult.Error != nil {
    // Handle error
    return
}

if lockResult.Acquired {
    defer func() {
        if err := lockResult.Unlock(); err != nil {
            log.Printf("Failed to unlock: %v", err)
        }
    }()
    
    // Critical section code here
    fmt.Println("Lock acquired, executing critical section")
} else {
    fmt.Println("Failed to acquire lock")
}
Tag-Based Invalidation
ctx := context.Background()

// Add tags to cached items
tagResult := <-cache.AddTags(ctx, "user:123", "users", "active", "premium")
if tagResult.Error != nil {
    // Handle error
}

// Invalidate all items with specific tags
invalidateResult := <-cache.InvalidateByTag(ctx, "premium")
if invalidateResult.Error != nil {
    // Handle error
}

πŸ“Š Observability

Built-in Metrics
  • cache_operations_total{operation, status} - Total cache operations
  • cache_operation_duration_seconds{operation} - Operation latencies
  • cache_hit_ratio - Cache hit ratio
  • cache_memory_usage_bytes - Memory usage (memory stores)
  • cache_evictions_total - Number of evictions
Structured Logging
// Enable logging in cache configuration
cache, err := cachex.New[string](
    cachex.WithStore(store),
    cachex.WithObservability(cachex.ObservabilityConfig{
        EnableLogging: true,
        EnableMetrics: true,
        EnableTracing: true,
    }),
)
OpenTelemetry Tracing

Automatic span creation for all cache operations with attributes:

  • cache.operation - Operation type (get, set, etc.)
  • cache.key - Cache key (redacted if configured)
  • cache.hit - Whether it was a cache hit
  • cache.ttl - TTL value
  • cache.size - Value size in bytes

πŸ§ͺ Testing

# Run all tests
go test ./... -race -v

# Run integration tests
go test ./tests/integration/ -v

# Run benchmarks
go test -bench=. ./tests/benchmark/

# Run with Redis (requires Redis running)
docker run -d -p 6379:6379 redis:alpine
go test ./tests/integration/ -v

# Linting
golangci-lint run

# Security checks
govulncheck ./...

πŸ“Š Performance & Test Results

πŸš€ Performance Benchmarks

The library is designed for high performance with async operations and efficient memory usage:

Memory Store Performance (Apple M3 Pro, 12 cores):

  • Set Operations: ~1.5ΞΌs per operation (784,498 ops/sec)
  • Get Operations: ~3.2ΞΌs per operation (378,142 ops/sec)
  • Batch Set (MSet): ~9.2ΞΌs per operation (239,446 ops/sec)
  • Batch Get (MGet): ~11.3ΞΌs per operation (105,052 ops/sec)

Memory Usage:

  • Set: 1,427 B/op (21 allocations)
  • Get: 2,713 B/op (32 allocations)
  • MSet: 6,796 B/op (68 allocations)
  • MGet: 7,582 B/op (107 allocations)
πŸ§ͺ Test Coverage & Quality

Comprehensive Test Suite:

  • Total Tests: 400+ tests across unit and integration suites
  • Test Results: 396 PASS, 4 SKIP (Redis-dependent tests)
  • Race Condition Testing: All tests run with -race flag
  • Concurrency Testing: Extensive concurrent access testing

Test Categories:

  • Unit Tests: 396 tests covering all components
  • Integration Tests: End-to-end functionality testing
  • Benchmark Tests: Performance measurement and regression testing
  • Security Tests: Validation, redaction, and authorization testing

Test Coverage Areas:

  • βœ… Core cache operations (Get, Set, MGet, MSet, Del, Exists, TTL, IncrBy)
  • βœ… Store implementations (Memory, Redis, Ristretto, Layered)
  • βœ… Codec implementations (JSON, MessagePack)
  • βœ… Security features (Validation, Redaction, Authorization)
  • βœ… Observability (Metrics, Tracing, Logging)
  • βœ… Tagging and invalidation
  • βœ… GORM integration
  • βœ… Refresh-ahead scheduling
  • βœ… Error handling and edge cases
  • βœ… Concurrency and race conditions
πŸ”’ Security Features

Built-in Security Components:

  • Key Validation: Pattern-based key validation with allow/block lists
  • Value Validation: Size limits and content validation
  • Data Redaction: Sensitive data masking in logs and traces
  • RBAC Authorization: Role-based access control for cache operations
  • Secrets Management: Secure secret retrieval and management
  • TLS Support: Encrypted connections for Redis and other stores

Security Best Practices:

  • Input validation and sanitization
  • Secure key generation with HMAC
  • Environment isolation
  • Audit logging and monitoring
  • Principle of least privilege

## πŸ“š Examples

Complete examples are available in the `examples/` directory:

- **[Single Service](examples/single-service/)** - Basic REST API integration
- **[Memory Store](examples/local-memory/)** - In-memory caching configurations  
- **[Redis Store](examples/redis/)** - Redis backend setup and usage
- **[Ristretto Store](examples/ristretto/)** - High-performance in-memory caching
- **[Configuration](examples/config-examples/)** - YAML and environment-based config
- **[GORM Integration](examples/gorm-integration/)** - Database integration patterns
- **[MessagePack](examples/msgpack/)** - MessagePack serialization
- **[Observability](examples/observability/)** - Metrics, tracing, and logging

## βš™οΈ Configuration

### Configuration Options

The library provides extensive configuration options through YAML files and environment variables:

#### Store Types
- **Memory Store**: In-memory caching with configurable size limits and eviction policies
- **Redis Store**: Distributed caching with connection pooling and TLS support
- **Ristretto Store**: High-performance in-memory caching with automatic eviction
- **Layered Store**: Multi-tier caching combining memory and persistent stores

#### Security Features
- **Input Validation**: Key pattern validation, value size limits, content filtering
- **Data Redaction**: Automatic masking of sensitive data in logs and traces
- **RBAC Authorization**: Role-based access control for cache operations
- **Secrets Management**: Secure retrieval of configuration secrets

#### Observability
- **Prometheus Metrics**: Cache hit/miss ratios, operation latencies, error rates
- **OpenTelemetry Tracing**: Distributed tracing for cache operations
- **Structured Logging**: Detailed operation logs with correlation IDs

#### Advanced Features
- **Tagging**: Logical grouping and bulk invalidation of cached items
- **Refresh-Ahead**: Automatic cache refresh before expiration
- **GORM Integration**: Automatic cache invalidation for database operations

### Environment Variables

All configuration options can be overridden using environment variables:

```bash
# Store type and basic settings
export CACHEX_STORE_TYPE=redis
export CACHEX_DEFAULT_TTL=10m
export CACHEX_CODEC=json

# Redis configuration
export CACHEX_REDIS_ADDR=localhost:6379
export CACHEX_REDIS_PASSWORD=your-password
export CACHEX_REDIS_POOL_SIZE=20

# Security settings
export CACHEX_SECURITY_MAX_KEY_LENGTH=256
export CACHEX_SECURITY_MAX_VALUE_SIZE=1048576

# Observability
export CACHEX_OBSERVABILITY_ENABLE_METRICS=true
export CACHEX_OBSERVABILITY_SERVICE_NAME=my-app

πŸš€ Best Practices

1. Choose the Right Store
  • Memory Store: Ultra-low latency, single-node applications
  • Redis Store: Distributed applications, data persistence
  • Ristretto Store: High-performance, memory-efficient caching
  • Layered Store: Multi-level caching for optimal performance
2. Handle Async Operations
// Always handle errors from async operations
result := <-cache.Get(ctx, key)
if result.Error != nil {
    // Log error and fallback to source
    log.Printf("Cache error: %v", result.Error)
    return loadFromSource(key)
}

if !result.Found {
    // Cache miss - load from source
    return loadFromSource(key)
}

return result.Value
3. Use Context for Cancellation
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

result := <-cache.Get(ctx, key)
// Operation will respect context timeout
4. Configure Appropriate TTLs
// Short TTL for frequently changing data
userProfile := <-cache.Set(ctx, "profile:123", profile, 5*time.Minute)

// Longer TTL for static data
config := <-cache.Set(ctx, "config:app", appConfig, 1*time.Hour)

// No TTL for permanent data (use 0)
constants := <-cache.Set(ctx, "constants", data, 0)

⚠️ Important Notes

  • Async API: All operations return channels and are non-blocking
  • Context: Always pass context for cancellation and timeouts
  • Error Handling: Check AsyncCacheResult.Error for operation errors
  • Resource Management: Always call Close() on caches and stores
  • Type Safety: Use generic types for compile-time safety

🀝 Contributing

Please read CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.

πŸ“„ License

This project is licensed under the MIT License - see the LICENSE file for details.

πŸ†˜ Support

Documentation ΒΆ

Index ΒΆ

Constants ΒΆ

This section is empty.

Variables ΒΆ

View Source 
var (
	ErrNotFound      = errors.New("cache: key not found")
	ErrTimeout       = errors.New("cache: operation timeout")
	ErrInvalidKey    = errors.New("cache: invalid key")
	ErrInvalidValue  = errors.New("cache: invalid value")
	ErrSerialization = errors.New("cache: serialization error")
	ErrEncryption    = errors.New("cache: encryption error")
	ErrDecryption    = errors.New("cache: decryption error")
	ErrLockFailed    = errors.New("cache: lock acquisition failed")
	ErrLockExpired   = errors.New("cache: lock expired")
	ErrStoreClosed   = errors.New("cache: store is closed")
)

Common cache errors

Functions ΒΆ

func IsLockExpired ΒΆ 

func IsLockExpired(err error) bool

IsLockExpired checks if the error is a lock expiration error

func IsLockFailed ΒΆ 

func IsLockFailed(err error) bool

IsLockFailed checks if the error is a lock failure error

func IsNotFound ΒΆ 

func IsNotFound(err error) bool

IsNotFound checks if the error is a not found error

func IsTimeout ΒΆ 

func IsTimeout(err error) bool

IsTimeout checks if the error is a timeout error

Types ΒΆ

type AnyCache ΒΆ 

type AnyCache interface {
	// WithContext returns a new cache instance with the given context
	WithContext(ctx context.Context) AnyCache

	// Non-blocking operations only
	Get(ctx context.Context, key string) <-chan AsyncAnyCacheResult
	Set(ctx context.Context, key string, val any, ttl time.Duration) <-chan AsyncAnyCacheResult
	MGet(ctx context.Context, keys ...string) <-chan AsyncAnyCacheResult
	MSet(ctx context.Context, items map[string]any, ttl time.Duration) <-chan AsyncAnyCacheResult
	Del(ctx context.Context, keys ...string) <-chan AsyncAnyCacheResult
	Exists(ctx context.Context, key string) <-chan AsyncAnyCacheResult
	TTL(ctx context.Context, key string) <-chan AsyncAnyCacheResult
	IncrBy(ctx context.Context, key string, delta int64, ttlIfCreate time.Duration) <-chan AsyncAnyCacheResult

	// Non-blocking caching patterns
	ReadThrough(ctx context.Context, key string, ttl time.Duration, loader func(ctx context.Context) (any, error)) <-chan AsyncAnyCacheResult
	WriteThrough(ctx context.Context, key string, val any, ttl time.Duration, writer func(ctx context.Context) error) <-chan AsyncAnyCacheResult
	WriteBehind(ctx context.Context, key string, val any, ttl time.Duration, writer func(ctx context.Context) error) <-chan AsyncAnyCacheResult
	RefreshAhead(ctx context.Context, key string, refreshBefore time.Duration, loader func(ctx context.Context) (any, error)) <-chan AsyncAnyCacheResult

	// Non-blocking Namespaces/Tags
	InvalidateByTag(ctx context.Context, tags ...string) <-chan AsyncAnyCacheResult
	AddTags(ctx context.Context, key string, tags ...string) <-chan AsyncAnyCacheResult

	// Non-blocking Distributed Locks
	TryLock(ctx context.Context, key string, ttl time.Duration) <-chan AsyncLockResult

	// Statistics
	GetStats() map[string]any

	// Close releases resources
	Close() error
}

AnyCache defines a cache that can work with any type using type assertions - Non-blocking Only

func NewAnyFromConfig ΒΆ 

func NewAnyFromConfig(config *CacheConfig) (AnyCache, error)

NewAnyFromConfig creates a new AnyCache instance from configuration

type AsyncAnyCacheResult ΒΆ 

type AsyncAnyCacheResult struct {
	Value  any
	Values map[string]any
	Found  bool
	Error  error
}

AsyncAnyCacheResult represents the result of an async any cache operation

type AsyncCacheResult ΒΆ 

type AsyncCacheResult[T any] struct {
	Value  T
	Values map[string]T
	Int    int64
	Found  bool
	TTL    time.Duration
	Error  error
}

AsyncCacheResult represents the result of an async cache operation

type AsyncLockResult ΒΆ 

type AsyncLockResult struct {
	Unlock func() error
	OK     bool
	Error  error
}

AsyncLockResult represents the result of an async lock operation

type AsyncResult ΒΆ 

type AsyncResult struct {
	Value  []byte
	Values map[string][]byte
	Result int64
	Exists bool
	TTL    time.Duration
	Error  error
}

AsyncResult represents the result of an async store operation

type AuthorizationContext ΒΆ 

type AuthorizationContext struct {
	UserID    string
	Roles     []string
	Resource  string
	Action    string
	Key       string
	Timestamp time.Time
}

AuthorizationContext holds authorization context

type AuthorizationResult ΒΆ 

type AuthorizationResult struct {
	Allowed bool
	Reason  string
}

AuthorizationResult holds authorization result

type Builder ΒΆ 

type Builder struct {
	// contains filtered or unexported fields
}

Builder implements the KeyBuilder interface with namespaced key generation

func NewBuilder ΒΆ 

func NewBuilder(appName, env string, secret string) *Builder

NewBuilder creates a new key builder

func (*Builder) Build ΒΆ 

func (b *Builder) Build(entity, id string) string

Build creates a namespaced entity key

func (*Builder) BuildComposite ΒΆ 

func (b *Builder) BuildComposite(entityA, idA, entityB, idB string) string

BuildComposite creates a composite key for related entities

func (*Builder) BuildList ΒΆ 

func (b *Builder) BuildList(entity string, filters map[string]any) string

BuildList creates a list key with hashed filters

func (*Builder) BuildOrder ΒΆ 

func (b *Builder) BuildOrder(orderID string) string

BuildOrder creates an order key

func (*Builder) BuildOrg ΒΆ 

func (b *Builder) BuildOrg(orgID string) string

BuildOrg creates an organization key

func (*Builder) BuildProduct ΒΆ 

func (b *Builder) BuildProduct(productID string) string

BuildProduct creates a product key

func (*Builder) BuildSession ΒΆ 

func (b *Builder) BuildSession(sid string) string

BuildSession creates a session key

func (*Builder) BuildUser ΒΆ 

func (b *Builder) BuildUser(userID string) string

BuildUser creates a user key

func (*Builder) IsValidKey ΒΆ 

func (b *Builder) IsValidKey(key string) bool

IsValidKey checks if a key follows the expected format

func (*Builder) ParseKey ΒΆ 

func (b *Builder) ParseKey(key string) (entity, id string, err error)

ParseKey parses a key and returns its components

type Cache ΒΆ 

type Cache[T any] interface {
	// WithContext returns a new cache instance with the given context
	WithContext(ctx context.Context) Cache[T]

	// Non-blocking operations only
	Get(ctx context.Context, key string) <-chan AsyncCacheResult[T]
	Set(ctx context.Context, key string, val T, ttl time.Duration) <-chan AsyncCacheResult[T]
	MGet(ctx context.Context, keys ...string) <-chan AsyncCacheResult[T]
	MSet(ctx context.Context, items map[string]T, ttl time.Duration) <-chan AsyncCacheResult[T]
	Del(ctx context.Context, keys ...string) <-chan AsyncCacheResult[T]
	Exists(ctx context.Context, key string) <-chan AsyncCacheResult[T]
	TTL(ctx context.Context, key string) <-chan AsyncCacheResult[T]
	IncrBy(ctx context.Context, key string, delta int64, ttlIfCreate time.Duration) <-chan AsyncCacheResult[T]

	// Non-blocking caching patterns
	ReadThrough(ctx context.Context, key string, ttl time.Duration, loader func(ctx context.Context) (T, error)) <-chan AsyncCacheResult[T]
	WriteThrough(ctx context.Context, key string, val T, ttl time.Duration, writer func(ctx context.Context) error) <-chan AsyncCacheResult[T]
	WriteBehind(ctx context.Context, key string, val T, ttl time.Duration, writer func(ctx context.Context) error) <-chan AsyncCacheResult[T]
	RefreshAhead(ctx context.Context, key string, refreshBefore time.Duration, loader func(ctx context.Context) (T, error)) <-chan AsyncCacheResult[T]

	// Non-blocking Namespaces/Tags
	InvalidateByTag(ctx context.Context, tags ...string) <-chan AsyncCacheResult[T]
	AddTags(ctx context.Context, key string, tags ...string) <-chan AsyncCacheResult[T]

	// Non-blocking Distributed Locks
	TryLock(ctx context.Context, key string, ttl time.Duration) <-chan AsyncLockResult

	// Statistics
	GetStats() map[string]any

	// Close releases resources
	Close() error
}

Cache defines the main interface for the cache layer - Non-blocking Only

func New ΒΆ 

func New[T any](opts ...Option) (Cache[T], error)

New creates a new cache instance

func NewFromConfig ΒΆ 

func NewFromConfig[T any](config *CacheConfig) (Cache[T], error)

NewFromConfig creates a new cache instance from configuration

type CacheConfig ΒΆ 

type CacheConfig struct {
	// Cache store configuration - only one can be active
	Memory    *MemoryConfig    `yaml:"memory" json:"memory"`
	Redis     *RedisConfig     `yaml:"redis" json:"redis"`
	Ristretto *RistrettoConfig `yaml:"ristretto" json:"ristretto"`
	Layered   *LayeredConfig   `yaml:"layered" json:"layered"`

	// General cache settings
	DefaultTTL time.Duration `yaml:"default_ttl" json:"default_ttl"`
	MaxRetries int           `yaml:"max_retries" json:"max_retries"`
	RetryDelay time.Duration `yaml:"retry_delay" json:"retry_delay"`

	// Codec settings
	Codec string `yaml:"codec" json:"codec"` // "json" or "msgpack"

	// Observability settings
	Observability *ObservabilityConfig `yaml:"observability" json:"observability"`

	// Security settings
	Security *SecurityConfig `yaml:"security" json:"security"`

	// Tagging settings
	Tagging *TagConfig `yaml:"tagging" json:"tagging"`

	// Refresh ahead settings
	RefreshAhead *RefreshAheadConfig `yaml:"refresh_ahead" json:"refresh_ahead"`

	// GORM integration settings
	GORM *GormConfig `yaml:"gorm" json:"gorm"`
}

CacheConfig represents the main configuration structure

func LoadConfig ΒΆ 

func LoadConfig(configPath string) (*CacheConfig, error)

LoadConfig loads configuration from environment variables and YAML file Environment variables take precedence over YAML file

type CacheError ΒΆ 

type CacheError struct {
	Op      string
	Key     string
	Message string
	Err     error
}

CacheError represents a cache-specific error with additional context

func NewCacheError ΒΆ 

func NewCacheError(op, key, message string, err error) *CacheError

NewCacheError creates a new cache error

func (*CacheError) Error ΒΆ 

func (e *CacheError) Error() string

Error implements the error interface

func (*CacheError) Unwrap ΒΆ 

func (e *CacheError) Unwrap() error

Unwrap returns the underlying error

type Codec ΒΆ 

type Codec interface {
	Encode(v any) ([]byte, error)
	Decode(data []byte, v any) error
}

Codec defines the interface for serialization/deserialization

func CreateCodecFromConfig ΒΆ 

func CreateCodecFromConfig(config *CacheConfig) Codec

CreateCodecFromConfig creates a codec instance based on the configuration

type Config ΒΆ 

type Config struct {
	MaxKeyLength    int      `yaml:"max_key_length" json:"max_key_length"`     // Maximum key length
	MaxValueSize    int      `yaml:"max_value_size" json:"max_value_size"`     // Maximum value size in bytes
	AllowedPatterns []string `yaml:"allowed_patterns" json:"allowed_patterns"` // Allowed key patterns (regex)
	BlockedPatterns []string `yaml:"blocked_patterns" json:"blocked_patterns"` // Blocked key patterns (regex)
}

Config holds validation configuration

type DistributedLockManager ΒΆ 

type DistributedLockManager struct {
	// contains filtered or unexported fields
}

DistributedLockManager manages distributed locks for refresh operations

func NewDistributedLockManager ΒΆ 

func NewDistributedLockManager(store Store) *DistributedLockManager

NewDistributedLockManager creates a new distributed lock manager

func (*DistributedLockManager) TryLock ΒΆ 

func (dlm *DistributedLockManager) TryLock(ctx context.Context, key string, ttl time.Duration) (func() error, bool, error)

TryLock attempts to acquire a distributed lock

type EvictionPolicy ΒΆ 

type EvictionPolicy string

EvictionPolicy defines how items are evicted when capacity is reached 

const (
	EvictionPolicyLRU EvictionPolicy = "lru" // Least Recently Used
	EvictionPolicyLFU EvictionPolicy = "lfu" // Least Frequently Used
	EvictionPolicyTTL EvictionPolicy = "ttl" // Time To Live (oldest first)
)

type GormConfig ΒΆ 

type GormConfig struct {
	// Enable automatic cache invalidation
	EnableInvalidation bool `yaml:"enable_invalidation" json:"enable_invalidation"`
	// Enable read-through caching
	EnableReadThrough bool `yaml:"enable_read_through" json:"enable_read_through"`
	// Default TTL for cached items
	DefaultTTL time.Duration `yaml:"default_ttl" json:"default_ttl"`
	// Enable query result caching
	EnableQueryCache bool `yaml:"enable_query_cache" json:"enable_query_cache"`
	// Cache key prefix
	KeyPrefix string `yaml:"key_prefix" json:"key_prefix"`
	// Enable debug logging
	EnableDebug bool `yaml:"enable_debug" json:"enable_debug"`
	// Batch invalidation size
	BatchSize int `yaml:"batch_size" json:"batch_size"`
}

Config holds GORM plugin configuration

func DefaultGormConfig ΒΆ 

func DefaultGormConfig() *GormConfig

DefaultGormConfig returns a default configuration

type JSONCodec ΒΆ 

type JSONCodec struct{}

JSONCodec implements the Codec interface using JSON serialization

func NewJSONCodec ΒΆ 

func NewJSONCodec() *JSONCodec

NewJSONCodec creates a new JSON codec

func (*JSONCodec) Decode ΒΆ 

func (c *JSONCodec) Decode(data []byte, v any) error

Decode deserializes JSON bytes to a value

func (*JSONCodec) Encode ΒΆ 

func (c *JSONCodec) Encode(v any) ([]byte, error)

Encode serializes a value to JSON bytes

func (*JSONCodec) Name ΒΆ 

func (c *JSONCodec) Name() string

Name returns the codec name

type KeyBuilder ΒΆ 

type KeyBuilder interface {
	Build(entity, id string) string
	BuildList(entity string, filters map[string]any) string
	BuildComposite(entityA, idA, entityB, idB string) string
	BuildSession(sid string) string
}

KeyBuilder defines the interface for key generation

type KeyHasher ΒΆ 

type KeyHasher interface {
	Hash(data string) string
}

KeyHasher defines the interface for key hashing

type LayeredConfig ΒΆ 

type LayeredConfig struct {
	// Memory store configuration
	MemoryConfig *MemoryConfig

	// Layering behavior
	WritePolicy  WritePolicy   // Write-through, write-behind, or write-around
	ReadPolicy   ReadPolicy    // Read-through, read-aside, or read-around
	SyncInterval time.Duration // How often to sync L1 with L2
	EnableStats  bool          // Enable detailed statistics

	// Performance tuning
	MaxConcurrentSync int // Maximum concurrent sync operations
}

LayeredConfig defines layered store configuration

func DefaultLayeredConfig ΒΆ 

func DefaultLayeredConfig() *LayeredConfig

DefaultLayeredConfig returns a default configuration

func HighPerfLayeredConfig ΒΆ 

func HighPerfLayeredConfig() *LayeredConfig

HighPerfLayeredConfig returns a configuration optimized for high throughput

func ResourceLayeredConfig ΒΆ 

func ResourceLayeredConfig() *LayeredConfig

ResourceLayeredConfig returns a configuration for resource-constrained environments

type LayeredStats ΒΆ 

type LayeredStats struct {
	L1Hits     int64
	L1Misses   int64
	L2Hits     int64
	L2Misses   int64
	SyncCount  int64
	SyncErrors int64
	// contains filtered or unexported fields
}

LayeredStats holds layered store statistics

type LayeredStore ΒΆ 

type LayeredStore struct {
	// contains filtered or unexported fields
}

LayeredStore implements a layered cache with memory as L1 and Redis as L2

func NewLayeredStore ΒΆ 

func NewLayeredStore(l2Store Store, config *LayeredConfig) (*LayeredStore, error)

NewLayeredStore creates a new layered store

func (*LayeredStore) Close ΒΆ 

func (s *LayeredStore) Close() error

Close closes the layered store and releases resources

func (*LayeredStore) Del ΒΆ 

func (s *LayeredStore) Del(ctx context.Context, keys ...string) <-chan AsyncResult

Del removes keys from the layered store (non-blocking)

func (*LayeredStore) Exists ΒΆ 

func (s *LayeredStore) Exists(ctx context.Context, key string) <-chan AsyncResult

Exists checks if a key exists in the layered store (non-blocking)

func (*LayeredStore) Get ΒΆ 

func (s *LayeredStore) Get(ctx context.Context, key string) <-chan AsyncResult

Get retrieves a value from the layered store (non-blocking)

func (*LayeredStore) GetStats ΒΆ 

func (s *LayeredStore) GetStats() *LayeredStats

GetStats returns current statistics

func (*LayeredStore) IncrBy ΒΆ 

func (s *LayeredStore) IncrBy(ctx context.Context, key string, delta int64, ttlIfCreate time.Duration) <-chan AsyncResult

IncrBy increments a key by the given delta (non-blocking)

func (*LayeredStore) MGet ΒΆ 

func (s *LayeredStore) MGet(ctx context.Context, keys ...string) <-chan AsyncResult

MGet retrieves multiple values from the layered store (non-blocking)

func (*LayeredStore) MSet ΒΆ 

func (s *LayeredStore) MSet(ctx context.Context, items map[string][]byte, ttl time.Duration) <-chan AsyncResult

MSet stores multiple values in the layered store (non-blocking)

func (*LayeredStore) Set ΒΆ 

func (s *LayeredStore) Set(ctx context.Context, key string, value []byte, ttl time.Duration) <-chan AsyncResult

Set stores a value in the layered store (non-blocking)

func (*LayeredStore) SyncL1ToL2 ΒΆ 

func (s *LayeredStore) SyncL1ToL2(ctx context.Context) error

SyncL1ToL2 synchronizes L1 cache to L2 (for write-behind mode)

func (*LayeredStore) TTL ΒΆ 

func (s *LayeredStore) TTL(ctx context.Context, key string) <-chan AsyncResult

TTL gets the time to live of a key (non-blocking)

type MemoryConfig ΒΆ 

type MemoryConfig struct {
	// Capacity limits
	MaxSize     int `yaml:"max_size" json:"max_size"`           // Maximum number of items
	MaxMemoryMB int `yaml:"max_memory_mb" json:"max_memory_mb"` // Maximum memory usage in MB (approximate)

	// TTL settings
	DefaultTTL      time.Duration `yaml:"default_ttl" json:"default_ttl"`           // Default TTL for items
	CleanupInterval time.Duration `yaml:"cleanup_interval" json:"cleanup_interval"` // How often to run cleanup

	// Eviction policy
	EvictionPolicy EvictionPolicy `yaml:"eviction_policy" json:"eviction_policy"` // LRU, LFU, or TTL-based

	// Performance tuning
	EnableStats bool `yaml:"enable_stats" json:"enable_stats"` // Enable detailed statistics
}

Config defines memory store configuration

func DefaultMemoryConfig ΒΆ 

func DefaultMemoryConfig() *MemoryConfig

DefaultMemoryConfig returns a default configuration

func HighPerformanceMemoryConfig ΒΆ 

func HighPerformanceMemoryConfig() *MemoryConfig

HighPerformanceMemoryConfig returns a configuration optimized for high throughput

func ResourceConstrainedMemoryConfig ΒΆ 

func ResourceConstrainedMemoryConfig() *MemoryConfig

ResourceConstrainedMemoryConfig returns a configuration optimized for resource-constrained environments

type MemoryStats ΒΆ 

type MemoryStats struct {
	Hits        int64
	Misses      int64
	Evictions   int64
	Expirations int64
	Size        int64
	MemoryUsage int64 // Approximate memory usage in bytes
	// contains filtered or unexported fields
}

Stats holds memory store statistics

type MemoryStore ΒΆ 

type MemoryStore struct {
	// contains filtered or unexported fields
}

Store implements the cache.Store interface using in-memory storage

func NewMemoryStore ΒΆ 

func NewMemoryStore(config *MemoryConfig) (*MemoryStore, error)

NewMemoryStore creates a new memory store

func (*MemoryStore) Clear ΒΆ 

func (s *MemoryStore) Clear()

Clear removes all items from the store

func (*MemoryStore) Close ΒΆ 

func (s *MemoryStore) Close() error

Close closes the memory store and releases resources

func (*MemoryStore) Del ΒΆ 

func (s *MemoryStore) Del(ctx context.Context, keys ...string) <-chan AsyncResult

Del removes keys from the memory store (non-blocking)

func (*MemoryStore) Exists ΒΆ 

func (s *MemoryStore) Exists(ctx context.Context, key string) <-chan AsyncResult

Exists checks if a key exists in the memory store (non-blocking)

func (*MemoryStore) Get ΒΆ 

func (s *MemoryStore) Get(ctx context.Context, key string) <-chan AsyncResult

Get retrieves a value from the memory store (non-blocking)

func (*MemoryStore) GetStats ΒΆ 

func (s *MemoryStore) GetStats() *MemoryStats

GetStats returns current statistics

func (*MemoryStore) IncrBy ΒΆ 

func (s *MemoryStore) IncrBy(ctx context.Context, key string, delta int64, ttlIfCreate time.Duration) <-chan AsyncResult

IncrBy increments a counter by the specified delta (non-blocking)

func (*MemoryStore) MGet ΒΆ 

func (s *MemoryStore) MGet(ctx context.Context, keys ...string) <-chan AsyncResult

MGet retrieves multiple values from the memory store (non-blocking)

func (*MemoryStore) MSet ΒΆ 

func (s *MemoryStore) MSet(ctx context.Context, items map[string][]byte, ttl time.Duration) <-chan AsyncResult

MSet stores multiple values in the memory store (non-blocking)

func (*MemoryStore) Set ΒΆ 

func (s *MemoryStore) Set(ctx context.Context, key string, value []byte, ttl time.Duration) <-chan AsyncResult

Set stores a value in the memory store (non-blocking)

func (*MemoryStore) TTL ΒΆ 

func (s *MemoryStore) TTL(ctx context.Context, key string) <-chan AsyncResult

TTL returns the time to live for a key (non-blocking)

type MessagePackCodec ΒΆ 

type MessagePackCodec struct {
	// contains filtered or unexported fields
}

MessagePackCodec implements the Codec interface using MessagePack serialization

func NewMessagePackCodec ΒΆ 

func NewMessagePackCodec() *MessagePackCodec

NewMessagePackCodec creates a new MessagePack codec with default settings

func NewMessagePackCodecWithOptions ΒΆ 

func NewMessagePackCodecWithOptions(useJSONTag bool) *MessagePackCodec

NewMessagePackCodecWithOptions creates a new MessagePack codec with custom options

func (*MessagePackCodec) Decode ΒΆ 

func (c *MessagePackCodec) Decode(data []byte, v any) error

Decode deserializes MessagePack bytes to a value

func (*MessagePackCodec) Encode ΒΆ 

func (c *MessagePackCodec) Encode(v any) ([]byte, error)

Encode serializes a value to MessagePack bytes

func (*MessagePackCodec) IsJSONTagEnabled ΒΆ 

func (c *MessagePackCodec) IsJSONTagEnabled() bool

IsJSONTagEnabled returns whether JSON tags are being used

func (*MessagePackCodec) Name ΒΆ 

func (c *MessagePackCodec) Name() string

Name returns the codec name

func (*MessagePackCodec) UseJSONTag ΒΆ 

func (c *MessagePackCodec) UseJSONTag(use bool)

UseJSONTag enables/disables JSON tag usage for field names

type Metrics ΒΆ 

type Metrics struct {
	// Operation counters
	OperationsTotal    *prometheus.CounterVec
	OperationsDuration *prometheus.HistogramVec

	// Cache performance metrics
	CacheHits   prometheus.Counter
	CacheMisses prometheus.Counter
	CacheSets   prometheus.Counter
	CacheDels   prometheus.Counter

	// Data transfer metrics
	BytesIn  prometheus.Counter
	BytesOut prometheus.Counter

	// Error metrics
	ErrorsTotal *prometheus.CounterVec

	// Circuit breaker metrics
	CircuitBreakerState     *prometheus.GaugeVec
	CircuitBreakerFailures  prometheus.Counter
	CircuitBreakerSuccesses prometheus.Counter

	// Worker pool metrics
	WorkerPoolActiveWorkers prometheus.Gauge
	WorkerPoolQueuedJobs    prometheus.Gauge
	WorkerPoolCompletedJobs prometheus.Counter
	WorkerPoolFailedJobs    prometheus.Counter

	// Dead letter queue metrics
	DLQFailedOperations    prometheus.Counter
	DLQRetriedOperations   prometheus.Counter
	DLQSucceededOperations prometheus.Counter
	DLQDroppedOperations   prometheus.Counter
	DLQCurrentQueueSize    prometheus.Gauge

	// Bloom filter metrics
	BloomFilterItems          prometheus.Gauge
	BloomFilterFalsePositives prometheus.Counter
	BloomFilterCapacity       prometheus.Gauge
}

Metrics holds all Prometheus metrics

type ModelConfig ΒΆ 

type ModelConfig struct {
	// Model name
	Name string
	// Cache TTL for this model
	TTL time.Duration
	// Enable caching for this model
	Enabled bool
	// Cache key template
	KeyTemplate string
	// Invalidation tags
	Tags []string
	// Enable read-through
	ReadThrough bool
	// Enable write-through
	WriteThrough bool
}

ModelConfig holds configuration for a specific model

type ObservabilityConfig ΒΆ 

type ObservabilityConfig struct {
	EnableMetrics bool `yaml:"enable_metrics" json:"enable_metrics"`
	EnableTracing bool `yaml:"enable_tracing" json:"enable_tracing"`
	EnableLogging bool `yaml:"enable_logging" json:"enable_logging"`
}

ObservabilityConfig defines observability settings

type ObservabilityManager ΒΆ 

type ObservabilityManager struct {
	// contains filtered or unexported fields
}

ObservabilityManager provides tracing, metrics, and logging capabilities

func NewObservability ΒΆ 

func NewObservability(config *ObservabilityManagerConfig) *ObservabilityManager

NewObservability creates a new observability instance

func (*ObservabilityManager) GetConfig ΒΆ 

func (o *ObservabilityManager) GetConfig() *ObservabilityManagerConfig

GetConfig returns the observability configuration

func (*ObservabilityManager) GetMetrics ΒΆ 

func (o *ObservabilityManager) GetMetrics() *Metrics

GetMetrics returns the metrics instance

func (*ObservabilityManager) LogOperation ΒΆ 

func (o *ObservabilityManager) LogOperation(level, operation, key, namespace string, ttl time.Duration, attempt int, duration time.Duration, err error, redactLogs bool)

LogOperation logs cache operations with enhanced fields

func (*ObservabilityManager) RecordBloomFilterStats ΒΆ 

func (o *ObservabilityManager) RecordBloomFilterStats(items, capacity uint64, falsePositives int64)

RecordBloomFilterStats records bloom filter statistics

func (*ObservabilityManager) RecordCircuitBreakerFailure ΒΆ 

func (o *ObservabilityManager) RecordCircuitBreakerFailure()

RecordCircuitBreakerFailure records circuit breaker failure

func (*ObservabilityManager) RecordCircuitBreakerState ΒΆ 

func (o *ObservabilityManager) RecordCircuitBreakerState(component string, state int)

RecordCircuitBreakerState records circuit breaker state

func (*ObservabilityManager) RecordCircuitBreakerSuccess ΒΆ 

func (o *ObservabilityManager) RecordCircuitBreakerSuccess()

RecordCircuitBreakerSuccess records circuit breaker success

func (*ObservabilityManager) RecordDLQStats ΒΆ 

func (o *ObservabilityManager) RecordDLQStats(failed, retried, succeeded, dropped int64, currentQueueSize int64)

RecordDLQStats records dead letter queue statistics

func (*ObservabilityManager) RecordError ΒΆ 

func (o *ObservabilityManager) RecordError(errorType, component string)

RecordError records error metrics

func (*ObservabilityManager) RecordOperation ΒΆ 

func (o *ObservabilityManager) RecordOperation(operation, status, component string, duration time.Duration, bytesIn, bytesOut int64)

RecordOperation records metrics for cache operations

func (*ObservabilityManager) RecordWorkerPoolStats ΒΆ 

func (o *ObservabilityManager) RecordWorkerPoolStats(activeWorkers, queuedJobs int32, completedJobs, failedJobs int64)

RecordWorkerPoolStats records worker pool statistics

func (*ObservabilityManager) TraceOperation ΒΆ 

func (o *ObservabilityManager) TraceOperation(ctx context.Context, operation, key, namespace string, ttl time.Duration, attempt int) (context.Context, trace.Span)

TraceOperation creates a span for cache operations

type ObservabilityManagerConfig ΒΆ 

type ObservabilityManagerConfig struct {
	EnableMetrics  bool   `yaml:"enable_metrics" json:"enable_metrics"`
	EnableTracing  bool   `yaml:"enable_tracing" json:"enable_tracing"`
	EnableLogging  bool   `yaml:"enable_logging" json:"enable_logging"`
	ServiceName    string `yaml:"service_name" json:"service_name"`
	ServiceVersion string `yaml:"service_version" json:"service_version"`
	Environment    string `yaml:"environment" json:"environment"`
}

ObservabilityManagerConfig holds observability configuration

type Option ΒΆ 

type Option func(*Options)

Option is a functional option for configuring the cache

func WithCodec ΒΆ 

func WithCodec(codec Codec) Option

WithCodec sets the serialization codec

func WithDefaultTTL ΒΆ 

func WithDefaultTTL(ttl time.Duration) Option

WithDefaultTTL sets the default TTL

func WithKeyBuilder ΒΆ 

func WithKeyBuilder(builder KeyBuilder) Option

WithKeyBuilder sets the key builder

func WithKeyHasher ΒΆ 

func WithKeyHasher(hasher KeyHasher) Option

WithKeyHasher sets the key hasher

func WithMaxRetries ΒΆ 

func WithMaxRetries(max int) Option

WithMaxRetries sets the maximum number of retries

func WithObservability ΒΆ 

func WithObservability(config ObservabilityConfig) Option

WithObservability sets observability configuration

func WithRetryDelay ΒΆ 

func WithRetryDelay(delay time.Duration) Option

WithRetryDelay sets the retry delay

func WithSecurity ΒΆ 

func WithSecurity(security *SecurityManager) Option

WithSecurity sets the security manager for input validation

func WithStore ΒΆ 

func WithStore(store Store) Option

WithStore sets the storage backend

type Options ΒΆ 

type Options struct {
	Store         Store
	Codec         Codec
	KeyBuilder    KeyBuilder
	KeyHasher     KeyHasher
	DefaultTTL    time.Duration
	MaxRetries    int
	RetryDelay    time.Duration
	Observability ObservabilityConfig
	Security      *SecurityManager
}

Options defines configuration options for the cache

type Plugin ΒΆ 

type Plugin struct {
	// contains filtered or unexported fields
}

Plugin provides GORM integration for automatic cache invalidation and read-through

func NewGormPlugin ΒΆ 

func NewGormPlugin(cache Cache[any], config *GormConfig) *Plugin

NewGormPlugin creates a new GORM plugin

func (*Plugin) CacheQueryResult ΒΆ 

func (p *Plugin) CacheQueryResult(modelName, id string, result any) error

CacheQueryResult caches query results

func (*Plugin) ClearCache ΒΆ 

func (p *Plugin) ClearCache() error

ClearCache clears all cached data for registered models

func (*Plugin) GetCache ΒΆ 

func (p *Plugin) GetCache() Cache[any]

GetCache returns the underlying cache instance

func (*Plugin) GetConfig ΒΆ 

func (p *Plugin) GetConfig() *GormConfig

GetConfig returns the plugin configuration

func (*Plugin) GetRegisteredModels ΒΆ 

func (p *Plugin) GetRegisteredModels() []string

GetRegisteredModels returns the list of registered models

func (*Plugin) Initialize ΒΆ 

func (p *Plugin) Initialize() error

Initialize initializes the plugin (placeholder for GORM integration)

func (*Plugin) InvalidateOnCreate ΒΆ 

func (p *Plugin) InvalidateOnCreate(model any) error

InvalidateOnCreate invalidates cache on model creation

func (*Plugin) InvalidateOnDelete ΒΆ 

func (p *Plugin) InvalidateOnDelete(model any) error

InvalidateOnDelete invalidates cache on model deletion

func (*Plugin) InvalidateOnUpdate ΒΆ 

func (p *Plugin) InvalidateOnUpdate(model any) error

InvalidateOnUpdate invalidates cache on model update

func (*Plugin) Name ΒΆ 

func (p *Plugin) Name() string

Name returns the plugin name

func (*Plugin) ReadThrough ΒΆ 

func (p *Plugin) ReadThrough(modelName, id string, dest any) (bool, error)

ReadThrough implements read-through caching for a model by ID

func (*Plugin) RegisterModel ΒΆ 

func (p *Plugin) RegisterModel(model any, config *ModelConfig) error

RegisterModel registers a model for caching

func (*Plugin) RegisterModelWithDefaults ΒΆ 

func (p *Plugin) RegisterModelWithDefaults(model any, ttl time.Duration, tags ...string) error

RegisterModel is a helper function to register a model with default configuration

func (*Plugin) WithContext ΒΆ 

func (p *Plugin) WithContext(ctx context.Context) *Plugin

WithContext sets the context for the plugin

type RBACAuthorizer ΒΆ 

type RBACAuthorizer struct {
}

RBACAuthorizer provides RBAC authorization hooks

func (*RBACAuthorizer) Authorize ΒΆ 

func (a *RBACAuthorizer) Authorize(ctx context.Context, authCtx *AuthorizationContext) *AuthorizationResult

Authorize checks if an operation is authorized

type ReadPolicy ΒΆ 

type ReadPolicy string

ReadPolicy defines how reads are handled across layers 

const (
	ReadPolicyThrough ReadPolicy = "through" // Read from L1, fallback to L2
	ReadPolicyAside   ReadPolicy = "aside"   // Read from L1 only, manual L2 sync
	ReadPolicyAround  ReadPolicy = "around"  // Read from L2 only, populate L1
)

type Redactor ΒΆ 

type Redactor struct {
	// contains filtered or unexported fields
}

Redactor provides log redaction utilities

func NewRedactor ΒΆ 

func NewRedactor(patterns []string, replacement string) (*Redactor, error)

NewRedactor creates a new redactor

func (*Redactor) Redact ΒΆ 

func (r *Redactor) Redact(input string) string

Redact redacts sensitive information from a string

type RedisConfig ΒΆ 

type RedisConfig struct {
	// Redis connection settings
	Addr     string `yaml:"addr" json:"addr"`
	Password string `yaml:"password" json:"password"`
	DB       int    `yaml:"db" json:"db"`

	// TLS configuration
	TLS *TLSConfig `yaml:"tls" json:"tls"`

	// Connection pool settings
	PoolSize     int `yaml:"pool_size" json:"pool_size"`
	MinIdleConns int `yaml:"min_idle_conns" json:"min_idle_conns"`
	MaxRetries   int `yaml:"max_retries" json:"max_retries"`

	// Timeout settings
	DialTimeout  time.Duration `yaml:"dial_timeout" json:"dial_timeout"`
	ReadTimeout  time.Duration `yaml:"read_timeout" json:"read_timeout"`
	WriteTimeout time.Duration `yaml:"write_timeout" json:"write_timeout"`

	// Performance settings
	EnablePipelining bool `yaml:"enable_pipelining" json:"enable_pipelining"`
	EnableMetrics    bool `yaml:"enable_metrics" json:"enable_metrics"`
}

Config holds Redis store configuration

func DefaultRedisConfig ΒΆ 

func DefaultRedisConfig() *RedisConfig

DefaultRedisConfig returns a default Redis configuration

func HighPerformanceRedisConfig ΒΆ 

func HighPerformanceRedisConfig() *RedisConfig

HighPerformanceRedisConfig returns a high-performance configuration

func ProductionRedisConfig ΒΆ 

func ProductionRedisConfig() *RedisConfig

ProductionRedisConfig returns a production configuration

type RedisStats ΒΆ 

type RedisStats struct {
	Hits     int64
	Misses   int64
	Sets     int64
	Dels     int64
	Errors   int64
	BytesIn  int64
	BytesOut int64
	// contains filtered or unexported fields
}

Stats holds Redis store statistics

type RedisStore ΒΆ 

type RedisStore struct {
	// contains filtered or unexported fields
}

Store implements the cache.Store interface using Redis

func NewRedisStore ΒΆ 

func NewRedisStore(config *RedisConfig) (*RedisStore, error)

NewRedisStore creates a new Redis store

func (*RedisStore) Close ΒΆ 

func (s *RedisStore) Close() error

Close closes the Redis store and releases resources

func (*RedisStore) Del ΒΆ 

func (s *RedisStore) Del(ctx context.Context, keys ...string) <-chan AsyncResult

Del removes keys from Redis (non-blocking)

func (*RedisStore) Exists ΒΆ 

func (s *RedisStore) Exists(ctx context.Context, key string) <-chan AsyncResult

Exists checks if a key exists in Redis (non-blocking)

func (*RedisStore) Get ΒΆ 

func (s *RedisStore) Get(ctx context.Context, key string) <-chan AsyncResult

Get retrieves a value from Redis (non-blocking)

func (*RedisStore) GetStats ΒΆ 

func (s *RedisStore) GetStats() *RedisStats

GetStats returns current statistics

func (*RedisStore) IncrBy ΒΆ 

func (s *RedisStore) IncrBy(ctx context.Context, key string, delta int64, ttlIfCreate time.Duration) <-chan AsyncResult

IncrBy increments a counter by the specified delta (non-blocking)

func (*RedisStore) MGet ΒΆ 

func (s *RedisStore) MGet(ctx context.Context, keys ...string) <-chan AsyncResult

MGet retrieves multiple values from Redis (non-blocking)

func (*RedisStore) MSet ΒΆ 

func (s *RedisStore) MSet(ctx context.Context, items map[string][]byte, ttl time.Duration) <-chan AsyncResult

MSet stores multiple values in Redis (non-blocking)

func (*RedisStore) Set ΒΆ 

func (s *RedisStore) Set(ctx context.Context, key string, value []byte, ttl time.Duration) <-chan AsyncResult

Set stores a value in Redis (non-blocking)

func (*RedisStore) TTL ΒΆ 

func (s *RedisStore) TTL(ctx context.Context, key string) <-chan AsyncResult

TTL returns the time to live for a key (non-blocking)

type RefreshAheadConfig ΒΆ 

type RefreshAheadConfig struct {
	// Enable refresh-ahead
	Enabled bool `yaml:"enabled" json:"enabled"`
	// Default refresh before TTL
	DefaultRefreshBefore time.Duration `yaml:"default_refresh_before" json:"default_refresh_before"`
	// Maximum concurrent refresh operations
	MaxConcurrentRefreshes int `yaml:"max_concurrent_refreshes" json:"max_concurrent_refreshes"`
	// Refresh interval for background scanning
	RefreshInterval time.Duration `yaml:"refresh_interval" json:"refresh_interval"`
	// Enable distributed locking
	EnableDistributedLock bool `yaml:"enable_distributed_lock" json:"enable_distributed_lock"`
	// Lock timeout for refresh operations
	LockTimeout time.Duration `yaml:"lock_timeout" json:"lock_timeout"`
	// Enable metrics
	EnableMetrics bool `yaml:"enable_metrics" json:"enable_metrics"`
}

RefreshAheadConfig holds refresh-ahead configuration

func DefaultRefreshAheadConfig ΒΆ 

func DefaultRefreshAheadConfig() *RefreshAheadConfig

DefaultRefreshAheadConfig returns a default configuration

type RefreshAheadScheduler ΒΆ 

type RefreshAheadScheduler struct {
	// contains filtered or unexported fields
}

RefreshAheadScheduler manages background refresh-ahead operations

func NewRefreshAheadScheduler ΒΆ 

func NewRefreshAheadScheduler(store Store, config *RefreshAheadConfig) *RefreshAheadScheduler

NewRefreshAheadScheduler creates a new refresh-ahead scheduler

func (*RefreshAheadScheduler) Close ΒΆ 

func (ras *RefreshAheadScheduler) Close() error

Close closes the refresh-ahead scheduler

func (*RefreshAheadScheduler) GetRefreshStats ΒΆ 

func (ras *RefreshAheadScheduler) GetRefreshStats() map[string]interface{}

GetRefreshStats returns refresh statistics

func (*RefreshAheadScheduler) ScheduleRefresh ΒΆ 

func (ras *RefreshAheadScheduler) ScheduleRefresh(key string, refreshBefore time.Duration, loader func(ctx context.Context) (interface{}, error)) error

ScheduleRefresh schedules a key for refresh-ahead

func (*RefreshAheadScheduler) UnscheduleRefresh ΒΆ 

func (ras *RefreshAheadScheduler) UnscheduleRefresh(key string) error

UnscheduleRefresh removes a key from refresh scheduling

type RefreshAheadStats ΒΆ 

type RefreshAheadStats struct {
	TotalTasks      int64
	TotalRefreshes  int64
	TotalErrors     int64
	LastRefreshTime time.Time
}

RefreshAheadStats holds refresh-ahead statistics

type RefreshTask ΒΆ 

type RefreshTask struct {
	Key           string
	RefreshBefore time.Duration
	Loader        func(ctx context.Context) (interface{}, error)
	LastRefresh   time.Time
	NextRefresh   time.Time
	RefreshCount  int64
	LastError     error
	TTL           time.Duration
	// contains filtered or unexported fields
}

RefreshTask represents a scheduled refresh task

type RistrettoConfig ΒΆ 

type RistrettoConfig struct {
	// Maximum number of items in cache
	MaxItems int64
	// Maximum memory usage in bytes
	MaxMemoryBytes int64
	// Default TTL for items
	DefaultTTL time.Duration
	// Number of counters (should be 10x the number of items)
	NumCounters int64
	// Buffer size for items
	BufferItems int64
	// Cost function for memory calculation
	CostFunction func(value interface{}) int64
	// Enable metrics
	EnableMetrics bool
	// Enable statistics
	EnableStats bool
}

Config holds Ristretto configuration

func DefaultRistrettoConfig ΒΆ 

func DefaultRistrettoConfig() *RistrettoConfig

DefaultRistrettoConfig returns a default Ristretto configuration

func HighPerformanceConfig ΒΆ 

func HighPerformanceConfig() *RistrettoConfig

HighPerformanceConfig returns a high-performance configuration

func ResourceConstrainedConfig ΒΆ 

func ResourceConstrainedConfig() *RistrettoConfig

ResourceConstrainedConfig returns a configuration for resource-constrained environments

type RistrettoStats ΒΆ 

type RistrettoStats struct {
	Hits        int64
	Misses      int64
	Evictions   int64
	Expirations int64
	Size        int64
	MemoryUsage int64
	// contains filtered or unexported fields
}

Stats holds Ristretto cache statistics

type RistrettoStore ΒΆ 

type RistrettoStore struct {
	// contains filtered or unexported fields
}

Store implements a Ristretto-based local hot cache

func NewRistrettoStore ΒΆ 

func NewRistrettoStore(config *RistrettoConfig) (*RistrettoStore, error)

NewRistrettoStore creates a new Ristretto store

func (*RistrettoStore) Close ΒΆ 

func (s *RistrettoStore) Close() error

Close closes the Ristretto store

func (*RistrettoStore) Del ΒΆ 

func (s *RistrettoStore) Del(ctx context.Context, keys ...string) <-chan AsyncResult

Del removes keys from the Ristretto cache (non-blocking)

func (*RistrettoStore) Exists ΒΆ 

func (s *RistrettoStore) Exists(ctx context.Context, key string) <-chan AsyncResult

Exists checks if a key exists in the Ristretto cache (non-blocking)

func (*RistrettoStore) Get ΒΆ 

func (s *RistrettoStore) Get(ctx context.Context, key string) <-chan AsyncResult

Get retrieves a value from the Ristretto cache (non-blocking)

func (*RistrettoStore) GetStats ΒΆ 

func (s *RistrettoStore) GetStats() *RistrettoStats

GetStats returns Ristretto cache statistics

func (*RistrettoStore) IncrBy ΒΆ 

func (s *RistrettoStore) IncrBy(ctx context.Context, key string, delta int64, ttlIfCreate time.Duration) <-chan AsyncResult

IncrBy increments a key by the given delta (non-blocking)

func (*RistrettoStore) MGet ΒΆ 

func (s *RistrettoStore) MGet(ctx context.Context, keys ...string) <-chan AsyncResult

MGet retrieves multiple values from the Ristretto cache (non-blocking)

func (*RistrettoStore) MSet ΒΆ 

func (s *RistrettoStore) MSet(ctx context.Context, items map[string][]byte, ttl time.Duration) <-chan AsyncResult

MSet stores multiple values in the Ristretto cache (non-blocking)

func (*RistrettoStore) Set ΒΆ 

func (s *RistrettoStore) Set(ctx context.Context, key string, value []byte, ttl time.Duration) <-chan AsyncResult

Set stores a value in the Ristretto cache (non-blocking)

func (*RistrettoStore) TTL ΒΆ 

func (s *RistrettoStore) TTL(ctx context.Context, key string) <-chan AsyncResult

TTL gets the time to live of a key (non-blocking) - Ristretto doesn't expose TTL

type SecretsManager ΒΆ 

type SecretsManager struct {
	// contains filtered or unexported fields
}

SecretsManager provides secrets management utilities

func NewSecretsManager ΒΆ 

func NewSecretsManager(envPrefix string) *SecretsManager

NewSecretsManager creates a new secrets manager

func (*SecretsManager) GetSecret ΒΆ 

func (sm *SecretsManager) GetSecret(name string) (string, error)

GetSecret retrieves a secret from environment variables

func (*SecretsManager) GetSecretOrDefault ΒΆ 

func (sm *SecretsManager) GetSecretOrDefault(name, defaultValue string) string

GetSecretOrDefault retrieves a secret with a default value

func (*SecretsManager) ListSecrets ΒΆ 

func (sm *SecretsManager) ListSecrets() []string

ListSecrets lists all available secrets

type SecurityConfig ΒΆ 

type SecurityConfig struct {
	Validation           *Config  `yaml:"validation" json:"validation"`
	RedactionPatterns    []string `yaml:"redaction_patterns" json:"redaction_patterns"`
	RedactionReplacement string   `yaml:"redaction_replacement" json:"redaction_replacement"`
	SecretsPrefix        string   `yaml:"secrets_prefix" json:"secrets_prefix"`
}

SecurityConfig holds comprehensive security configuration

func DefaultSecurityConfig ΒΆ 

func DefaultSecurityConfig() *SecurityConfig

DefaultSecurityConfig returns a default security configuration

type SecurityManager ΒΆ 

type SecurityManager struct {
	// contains filtered or unexported fields
}

SecurityManager provides comprehensive security management

func NewSecurityManager ΒΆ 

func NewSecurityManager(config *SecurityConfig) (*SecurityManager, error)

NewSecurityManager creates a new security manager

func (*SecurityManager) Authorize ΒΆ 

func (sm *SecurityManager) Authorize(ctx context.Context, authCtx *AuthorizationContext) *AuthorizationResult

Authorize checks authorization

func (*SecurityManager) GetSecret ΒΆ 

func (sm *SecurityManager) GetSecret(name string) (string, error)

GetSecret retrieves a secret

func (*SecurityManager) Redact ΒΆ 

func (sm *SecurityManager) Redact(input string) string

Redact redacts sensitive information

func (*SecurityManager) ValidateKey ΒΆ 

func (sm *SecurityManager) ValidateKey(key string) error

ValidateKey validates a cache key

func (*SecurityManager) ValidateValue ΒΆ 

func (sm *SecurityManager) ValidateValue(value []byte) error

ValidateValue validates a cache value

type Store ΒΆ 

type Store interface {
	Get(ctx context.Context, key string) <-chan AsyncResult
	Set(ctx context.Context, key string, value []byte, ttl time.Duration) <-chan AsyncResult
	MGet(ctx context.Context, keys ...string) <-chan AsyncResult
	MSet(ctx context.Context, items map[string][]byte, ttl time.Duration) <-chan AsyncResult
	Del(ctx context.Context, keys ...string) <-chan AsyncResult
	Exists(ctx context.Context, key string) <-chan AsyncResult
	TTL(ctx context.Context, key string) <-chan AsyncResult
	IncrBy(ctx context.Context, key string, delta int64, ttlIfCreate time.Duration) <-chan AsyncResult
	Close() error
}

Store defines the interface for cache storage backends - Non-blocking Only

func CreateStoreFromConfig ΒΆ 

func CreateStoreFromConfig(config *CacheConfig) (Store, error)

CreateStoreFromConfig creates a store instance based on the configuration

type TLSConfig ΒΆ 

type TLSConfig struct {
	Enabled            bool `yaml:"enabled" json:"enabled"`
	InsecureSkipVerify bool `yaml:"insecure_skip_verify" json:"insecure_skip_verify"`
}

TLSConfig holds TLS configuration

type TagConfig ΒΆ 

type TagConfig struct {
	// Enable persistence of tag mappings
	EnablePersistence bool `yaml:"enable_persistence" json:"enable_persistence"`
	// TTL for tag mappings
	TagMappingTTL time.Duration `yaml:"tag_mapping_ttl" json:"tag_mapping_ttl"`
	// Batch size for tag operations
	BatchSize int `yaml:"batch_size" json:"batch_size"`
	// Enable statistics
	EnableStats bool `yaml:"enable_stats" json:"enable_stats"`
}

TagConfig holds tagging configuration

func DefaultTagConfig ΒΆ 

func DefaultTagConfig() *TagConfig

DefaultTagConfig returns a default configuration

type TagManager ΒΆ 

type TagManager struct {
	// contains filtered or unexported fields
}

TagManager manages tag-to-keys and key-to-tags mappings

func NewTagManager ΒΆ 

func NewTagManager(store Store, config *TagConfig) *TagManager

NewTagManager creates a new tag manager

func (*TagManager) AddTags ΒΆ 

func (tm *TagManager) AddTags(ctx context.Context, key string, tags ...string) error

AddTags adds tags to a key

func (*TagManager) GetKeysByTag ΒΆ 

func (tm *TagManager) GetKeysByTag(ctx context.Context, tag string) ([]string, error)

GetKeysByTag returns all keys associated with a tag

func (*TagManager) GetStats ΒΆ 

func (tm *TagManager) GetStats() *TagStats

GetStats returns tagging statistics

func (*TagManager) GetTagsByKey ΒΆ 

func (tm *TagManager) GetTagsByKey(ctx context.Context, key string) ([]string, error)

GetTagsByKey returns all tags associated with a key

func (*TagManager) InvalidateByTag ΒΆ 

func (tm *TagManager) InvalidateByTag(ctx context.Context, keys []string) error

InvalidateByTag invalidates all keys associated with the given tags

func (*TagManager) RemoveKey ΒΆ 

func (tm *TagManager) RemoveKey(ctx context.Context, key string) error

RemoveKey removes a key and all its tag associations

func (*TagManager) RemoveTags ΒΆ 

func (tm *TagManager) RemoveTags(ctx context.Context, key string, tags ...string) error

RemoveTags removes tags from a key

type TagStats ΒΆ 

type TagStats struct {
	TotalTags     int64
	TotalKeys     int64
	TagOperations int64
}

TagStats holds tagging statistics

type Validator ΒΆ 

type Validator struct {
	// contains filtered or unexported fields
}

Validator provides input validation utilities

func NewValidator ΒΆ 

func NewValidator(config *Config) (*Validator, error)

NewValidator creates a new validator

func (*Validator) ValidateKey ΒΆ 

func (v *Validator) ValidateKey(key string) error

ValidateKey validates a cache key

func (*Validator) ValidateValue ΒΆ 

func (v *Validator) ValidateValue(value []byte) error

ValidateValue validates a cache value

type WritePolicy ΒΆ 

type WritePolicy string

WritePolicy defines how writes are handled across layers 

const (
	WritePolicyThrough WritePolicy = "through" // Write to both L1 and L2
	WritePolicyBehind  WritePolicy = "behind"  // Write to L1, async to L2
	WritePolicyAround  WritePolicy = "around"  // Write to L2, invalidate L1
)

Source Files ΒΆ

View all Source files

Directories ΒΆ

Path Synopsis
examples
config-examples command
config-integration command
configuration command
gorm-integration command
implementation-details command
key-generation command
local-memory command
msgpack command
observability command
pipeline command
redis command
resilience command
ristretto command
single-service command
worker-pool command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.