cache

Documentation

Index

• Variables
• type Cache
• type MemoryCache
  • func NewMemoryCache[T any]() *MemoryCache[T]
  • 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]) MGet(ctx context.Context, keys []string) (map[string]T, error)
  • func (m *MemoryCache[T]) MSet(ctx context.Context, values map[string]T, ttl time.Duration) error
  • func (m *MemoryCache[T]) Set(ctx context.Context, key string, value T, ttl time.Duration) error
• type RueidisAsideCache
  • func NewRueidisAsideCache[T any](ctx context.Context, addr, password string, db int, keyPrefix string, ...) (*RueidisAsideCache[T], error)
  • func (r *RueidisAsideCache[T]) Close() error
  • func (r *RueidisAsideCache[T]) 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[T]) Health(ctx context.Context) error
  • func (r *RueidisAsideCache[T]) MGet(ctx context.Context, keys []string) (map[string]T, error)
  • func (r *RueidisAsideCache[T]) MSet(ctx context.Context, values map[string]T, ttl time.Duration) error
  • func (r *RueidisAsideCache[T]) Set(ctx context.Context, key string, value T, ttl time.Duration) error
• type RueidisCache
  • func NewRueidisCache[T any](ctx context.Context, addr, password string, db int, keyPrefix string) (*RueidisCache[T], error)
  • func (r *RueidisCache[T]) Close() error
  • func (r *RueidisCache[T]) 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[T]) Health(ctx context.Context) error
  • func (r *RueidisCache[T]) MGet(ctx context.Context, keys []string) (map[string]T, error)
  • func (r *RueidisCache[T]) MSet(ctx context.Context, values map[string]T, ttl time.Duration) error
  • func (r *RueidisCache[T]) Set(ctx context.Context, key string, value T, ttl time.Duration) error

Variables

var (
	// ErrCacheMiss indicates the requested key was not found in cache
	ErrCacheMiss = errors.New("cache: key not found")

	// ErrCacheUnavailable indicates the cache backend is unavailable
	ErrCacheUnavailable = errors.New("cache: backend unavailable")

	// ErrInvalidValue indicates the cached value cannot be parsed
	ErrInvalidValue = errors.New("cache: invalid value")
)

Types

type Cache

type Cache[T any] interface {
	// Get retrieves a single value from cache.
	// Returns ErrCacheMiss if the key does not exist or has expired.
	Get(ctx context.Context, key string) (T, error)

	// Set stores a single value in cache with TTL
	Set(ctx context.Context, key string, value T, ttl time.Duration) error

	// MGet retrieves multiple values from cache.
	// Returns a map of key->value for keys that exist and have not expired.
	MGet(ctx context.Context, keys []string) (map[string]T, error)

	// MSet stores multiple values in cache with TTL
	MSet(ctx context.Context, values map[string]T, ttl time.Duration) error

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

	// Close closes the cache connection
	Close() error

	// Health checks if the cache is healthy
	Health(ctx context.Context) error

	// GetWithFetch retrieves a value using the cache-aside pattern.
	// On cache miss, fetchFunc is called and the result is stored in cache.
	// Implementations may provide stampede protection (e.g. RueidisAsideCache).
	GetWithFetch(
		ctx context.Context,
		key string,
		ttl time.Duration,
		fetchFunc func(ctx context.Context, key string) (T, error),
	) (T, error)
}

Cache defines the primitive operations for a key-value cache. T is the type of value stored in the cache (e.g. int64, string, or a struct).

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). Suitable for single-instance deployments.

func NewMemoryCache

func NewMemoryCache[T any]() *MemoryCache[T]

NewMemoryCache creates a new memory cache instance.

func (*MemoryCache[T]) Close

func (m *MemoryCache[T]) Close() error

Close cleans up resources.

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. No stampede protection is provided (single-instance memory cache).

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]) MGet

func (m *MemoryCache[T]) MGet(ctx context.Context, keys []string) (map[string]T, error)

MGet retrieves multiple values from cache.

func (*MemoryCache[T]) MSet

func (m *MemoryCache[T]) MSet(ctx context.Context, values map[string]T, ttl time.Duration) error

MSet stores multiple values in cache with TTL.

func (*MemoryCache[T]) Set

func (m *MemoryCache[T]) Set(ctx context.Context, key string, value T, ttl time.Duration) error

Set stores a value in cache with TTL.

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[T]) Close

func (r *RueidisAsideCache[T]) Close() error

Close closes the Redis connection.

func (*RueidisAsideCache[T]) Delete

func (r *RueidisAsideCache[T]) Delete(ctx context.Context, key string) error

Delete removes a key from Redis.

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.

func (*RueidisAsideCache[T]) Health

func (r *RueidisAsideCache[T]) Health(ctx context.Context) error

Health checks if Redis is reachable.

func (*RueidisAsideCache[T]) MGet

func (r *RueidisAsideCache[T]) MGet(ctx context.Context, keys []string) (map[string]T, error)

MGet retrieves multiple values from Redis with client-side caching.

func (*RueidisAsideCache[T]) MSet

func (r *RueidisAsideCache[T]) MSet(
	ctx context.Context,
	values map[string]T,
	ttl time.Duration,
) error

MSet stores multiple values in Redis with TTL.

func (*RueidisAsideCache[T]) Set

func (r *RueidisAsideCache[T]) Set(
	ctx context.Context,
	key string,
	value T,
	ttl time.Duration,
) error

Set stores a value in Redis with TTL.

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[T]) Close

func (r *RueidisCache[T]) Close() error

Close closes the Redis connection.

func (*RueidisCache[T]) Delete

func (r *RueidisCache[T]) Delete(ctx context.Context, key string) error

Delete removes a key from Redis.

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. No stampede protection is provided.

func (*RueidisCache[T]) Health

func (r *RueidisCache[T]) Health(ctx context.Context) error

Health checks if Redis is reachable.

func (*RueidisCache[T]) MGet

func (r *RueidisCache[T]) MGet(ctx context.Context, keys []string) (map[string]T, error)

MGet retrieves multiple values from Redis.

func (*RueidisCache[T]) MSet

func (r *RueidisCache[T]) MSet(ctx context.Context, values map[string]T, ttl time.Duration) error

MSet stores multiple values in Redis with TTL.

func (*RueidisCache[T]) Set

func (r *RueidisCache[T]) Set(ctx context.Context, key string, value T, ttl time.Duration) error

Set stores a value in Redis with TTL.