Documentation
¶
Index ¶
- Variables
- type InstrumentedCache
- func (i *InstrumentedCache[T]) Close() error
- func (i *InstrumentedCache[T]) Delete(ctx context.Context, key string) error
- func (i *InstrumentedCache[T]) Get(ctx context.Context, key string) (T, error)
- func (i *InstrumentedCache[T]) GetWithFetch(ctx context.Context, key string, ttl time.Duration, ...) (T, error)
- func (i *InstrumentedCache[T]) Health(ctx context.Context) error
- func (i *InstrumentedCache[T]) Set(ctx context.Context, key string, value T, ttl time.Duration) error
- type MemoryCache
- func (m *MemoryCache[T]) Close() error
- func (m *MemoryCache[T]) Delete(ctx context.Context, key string) error
- func (m *MemoryCache[T]) Get(ctx context.Context, key string) (T, error)
- func (m *MemoryCache[T]) GetWithFetch(ctx context.Context, key string, ttl time.Duration, ...) (T, error)
- func (m *MemoryCache[T]) Health(ctx context.Context) error
- func (m *MemoryCache[T]) Len() int
- func (m *MemoryCache[T]) Set(ctx context.Context, key string, value T, ttl time.Duration) error
- type Metrics
- type NoopCache
- func (n *NoopCache[T]) Close() error
- func (n *NoopCache[T]) Delete(_ context.Context, _ string) error
- func (n *NoopCache[T]) Get(_ context.Context, _ string) (T, error)
- func (n *NoopCache[T]) GetWithFetch(ctx context.Context, key string, _ time.Duration, ...) (T, error)
- func (n *NoopCache[T]) Health(_ context.Context) error
- func (n *NoopCache[T]) Set(_ context.Context, _ string, _ T, _ time.Duration) error
- type RueidisAsideCache
- func (r *RueidisAsideCache) Close() error
- func (r *RueidisAsideCache) Delete(ctx context.Context, key string) error
- func (r *RueidisAsideCache[T]) Get(ctx context.Context, key string) (T, error)
- func (r *RueidisAsideCache[T]) GetWithFetch(ctx context.Context, key string, ttl time.Duration, ...) (T, error)
- func (r *RueidisAsideCache) Health(ctx context.Context) error
- func (r *RueidisAsideCache) Set(ctx context.Context, key string, value T, ttl time.Duration) error
- type RueidisCache
- func (r *RueidisCache) Close() error
- func (r *RueidisCache) Delete(ctx context.Context, key string) error
- func (r *RueidisCache[T]) Get(ctx context.Context, key string) (T, error)
- func (r *RueidisCache[T]) GetWithFetch(ctx context.Context, key string, ttl time.Duration, ...) (T, error)
- func (r *RueidisCache) Health(ctx context.Context) error
- func (r *RueidisCache) Set(ctx context.Context, key string, value T, ttl time.Duration) error
Constants ¶
This section is empty.
Variables ¶
var ( // ErrCacheMiss indicates the requested key was not found in cache ErrCacheMiss = errors.New("cache: key not found") ErrCacheUnavailable = errors.New("cache: backend unavailable") // ErrInvalidValue indicates the cached value cannot be parsed ErrInvalidValue = errors.New("cache: invalid value") )
Functions ¶
This section is empty.
Types ¶
type InstrumentedCache ¶ added in v0.25.0
type InstrumentedCache[T any] struct { // contains filtered or unexported fields }
InstrumentedCache wraps a Cache with Prometheus hit/miss/error counters.
func NewInstrumentedCache ¶ added in v0.25.0
func NewInstrumentedCache[T any](underlying core.Cache[T], cacheName string) *InstrumentedCache[T]
NewInstrumentedCache creates a new instrumented cache wrapper. cacheName is used as a Prometheus label to distinguish between different caches.
func (*InstrumentedCache[T]) Close ¶ added in v0.25.0
func (i *InstrumentedCache[T]) Close() error
func (*InstrumentedCache[T]) Delete ¶ added in v0.25.0
func (i *InstrumentedCache[T]) Delete(ctx context.Context, key string) error
func (*InstrumentedCache[T]) Get ¶ added in v0.25.0
func (i *InstrumentedCache[T]) Get(ctx context.Context, key string) (T, error)
func (*InstrumentedCache[T]) GetWithFetch ¶ added in v0.25.0
func (i *InstrumentedCache[T]) GetWithFetch( ctx context.Context, key string, ttl time.Duration, fetchFunc func(ctx context.Context, key string) (T, error), ) (T, error)
GetWithFetch implements the cache-aside pattern with metrics instrumentation. Wraps fetchFunc to detect whether it was called (miss) or not (hit), without calling underlying.Get() a second time. This preserves optimizations in the underlying implementation (e.g., stampede protection in RueidisAsideCache). Uses atomic.Bool because singleflight may set fetchCalled from a shared goroutine while the caller returns early on context cancellation.
type MemoryCache ¶
type MemoryCache[T any] struct { // contains filtered or unexported fields }
MemoryCache implements Cache interface with in-memory storage. Uses lazy expiration (checks expiry on Get) plus a background reaper that periodically evicts expired entries to prevent memory leaks. Suitable for single-instance deployments.
func NewMemoryCache ¶
func NewMemoryCache[T any](cleanupInterval ...time.Duration) *MemoryCache[T]
NewMemoryCache creates a new memory cache instance. An optional cleanup interval controls how often the background reaper evicts expired entries (default: 5 minutes). Pass a non-positive value to disable the reaper entirely and rely on lazy expiration in Get. When the reaper is enabled, callers must call Close to stop the background goroutine and release resources.
func (*MemoryCache[T]) Close ¶
func (m *MemoryCache[T]) Close() error
Close stops the background reaper and cleans up resources. Safe to call multiple times concurrently.
func (*MemoryCache[T]) Delete ¶
func (m *MemoryCache[T]) Delete(ctx context.Context, key string) error
Delete removes a key from cache.
func (*MemoryCache[T]) Get ¶
func (m *MemoryCache[T]) Get(ctx context.Context, key string) (T, error)
Get retrieves a value from cache.
func (*MemoryCache[T]) GetWithFetch ¶
func (m *MemoryCache[T]) GetWithFetch( ctx context.Context, key string, ttl time.Duration, fetchFunc func(ctx context.Context, key string) (T, error), ) (T, error)
GetWithFetch retrieves a value using the cache-aside pattern. On cache miss, fetchFunc is called and the result is stored in cache. Uses singleflight to deduplicate concurrent fetches for the same key.
func (*MemoryCache[T]) Health ¶
func (m *MemoryCache[T]) Health(ctx context.Context) error
Health checks if the cache is healthy (always true for memory cache).
func (*MemoryCache[T]) Len ¶ added in v0.25.0
func (m *MemoryCache[T]) Len() int
Len returns the number of items currently in the cache.
type Metrics ¶ added in v0.25.0
type Metrics struct {
// contains filtered or unexported fields
}
Metrics holds Prometheus counters for cache operations.
type NoopCache ¶ added in v0.24.0
type NoopCache[T any] struct{}
NoopCache implements Cache interface with no-op behavior. Used when caching is disabled.
func NewNoopCache ¶ added in v0.24.0
NewNoopCache creates a new no-op cache instance.
func (*NoopCache[T]) GetWithFetch ¶ added in v0.24.0
type RueidisAsideCache ¶
type RueidisAsideCache[T any] struct { // contains filtered or unexported fields }
RueidisAsideCache implements Cache interface using rueidisaside for cache-aside pattern. Uses rueidis' automatic client-side caching with RESP3 protocol for cache invalidation. Suitable for high-load multi-instance deployments (5+ pods).
func NewRueidisAsideCache ¶
func NewRueidisAsideCache[T any]( ctx context.Context, addr, password string, db int, keyPrefix string, clientTTL time.Duration, cacheSizeMB int, ) (*RueidisAsideCache[T], error)
NewRueidisAsideCache creates a new Redis cache with client-side caching using rueidisaside. clientTTL is the local cache TTL (e.g., 30s). Redis will automatically invalidate the local cache when keys change. cacheSizeMB is the client-side cache size per connection in megabytes. Note: Rueidis uses connection pooling (typically ~10 connections based on GOMAXPROCS), so total memory usage will be cacheSizeMB * number_of_connections.
func (*RueidisAsideCache) Close ¶
func (r *RueidisAsideCache) Close() error
Close closes the Redis connection.
func (*RueidisAsideCache[T]) Get ¶
func (r *RueidisAsideCache[T]) Get(ctx context.Context, key string) (T, error)
Get retrieves a value from Redis with client-side caching. Uses DoCache to leverage RESP3 client-side caching with automatic invalidation.
func (*RueidisAsideCache[T]) GetWithFetch ¶
func (r *RueidisAsideCache[T]) GetWithFetch( ctx context.Context, key string, ttl time.Duration, fetchFunc func(ctx context.Context, key string) (T, error), ) (T, error)
GetWithFetch retrieves a value using rueidisaside's cache-aside pattern. This is an enhanced method that leverages rueidisaside's automatic cache management. The fetchFunc is called automatically on cache miss to populate the cache.
type RueidisCache ¶
type RueidisCache[T any] struct { // contains filtered or unexported fields }
RueidisCache implements Cache interface using Redis via rueidis client. Suitable for multi-instance deployments where cache needs to be shared.
func NewRueidisCache ¶
func NewRueidisCache[T any]( ctx context.Context, addr, password string, db int, keyPrefix string, ) (*RueidisCache[T], error)
NewRueidisCache creates a new Redis cache instance using rueidis.
func (*RueidisCache) Close ¶
func (r *RueidisCache) Close() error
Close closes the Redis connection.
func (*RueidisCache[T]) Get ¶
func (r *RueidisCache[T]) Get(ctx context.Context, key string) (T, error)
Get retrieves a value from Redis.
func (*RueidisCache[T]) GetWithFetch ¶
func (r *RueidisCache[T]) GetWithFetch( ctx context.Context, key string, ttl time.Duration, fetchFunc func(ctx context.Context, key string) (T, error), ) (T, error)
GetWithFetch retrieves a value using the cache-aside pattern. On cache miss, fetchFunc is called and the result is stored in cache. Uses singleflight to deduplicate concurrent fetches for the same key.
Source Files