Documentation
¶
Overview ¶
Package cache provides caching abstractions and implementations.
Index ¶
- func SetDefaultRedisStore(s *RedisStore)
- type Cache
- func (c *Cache) Del(_ context.Context, key Key) error
- func (c *Cache) DelByPrefix(capType string)
- func (c *Cache) DelRaw(key string)
- func (c *Cache) Exists(_ context.Context, key Key) (bool, error)
- func (c *Cache) Expire(_ context.Context, key Key, ttl TTL) error
- func (c *Cache) Get(_ context.Context, key Key) (string, bool, error)
- func (c *Cache) GetBytes(key string) ([]byte, bool)
- func (c *Cache) GetRaw(key string) (any, bool)
- func (c *Cache) Set(_ context.Context, key Key, value string, ttl TTL) error
- func (c *Cache) SetNX(_ context.Context, key Key, value string, ttl TTL) (bool, error)
- func (c *Cache) SetRaw(key string, value any, cost int64) bool
- func (c *Cache) SetWithTTL(key string, value any, cost int64, ttl time.Duration) bool
- func (c *Cache) SetWithTTLCap(key string, value []byte, cost int64, ttl time.Duration, capType string) bool
- func (c *Cache) Wait()
- type IntCache
- type Key
- type ListCache
- type RedisStore
- func (s *RedisStore) Add(ctx context.Context, key Key, ttl TTL, members ...string) (int64, error)
- func (s *RedisStore) Clear(ctx context.Context, key Key) error
- func (s *RedisStore) Del(ctx context.Context, key Key) error
- func (s *RedisStore) Exists(ctx context.Context, key Key) (bool, error)
- func (s *RedisStore) ExistsRaw(ctx context.Context, key string) (bool, error)
- func (s *RedisStore) Expire(ctx context.Context, key Key, ttl TTL) error
- func (s *RedisStore) Get(ctx context.Context, key Key) (string, bool, error)
- func (s *RedisStore) GetInt64(ctx context.Context, key Key) (int64, error)
- func (s *RedisStore) GetMetricsInt64(key string) int64
- func (s *RedisStore) Incr(ctx context.Context, key Key) (int64, error)
- func (s *RedisStore) IncrWithTTL(ctx context.Context, key Key, ttl TTL) (int64, error)
- func (s *RedisStore) IsMember(ctx context.Context, key Key, member string) (bool, error)
- func (s *RedisStore) Len(ctx context.Context, key Key) (int64, error)
- func (s *RedisStore) Members(ctx context.Context, key Key) ([]string, error)
- func (s *RedisStore) Ping(ctx context.Context) (time.Duration, error)
- func (s *RedisStore) Push(ctx context.Context, key Key, values ...string) (int64, error)
- func (s *RedisStore) Range(ctx context.Context, key Key, start, stop int64) ([]string, error)
- func (s *RedisStore) Remove(ctx context.Context, key Key, members ...string) (int64, error)
- func (s *RedisStore) ScanKeys(ctx context.Context, pattern string, count int64) ([]string, error)
- func (s *RedisStore) Set(ctx context.Context, key Key, value string, ttl TTL) error
- func (s *RedisStore) SetInt64(ctx context.Context, key Key, value int64, ttl TTL) error
- func (s *RedisStore) SetMetricsInt64(key string, value int64)
- func (s *RedisStore) SetNX(ctx context.Context, key Key, value string, ttl TTL) (bool, error)
- type SetCache
- type StringCache
- type TTL
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func SetDefaultRedisStore ¶ added in v0.92.0
func SetDefaultRedisStore(s *RedisStore)
SetDefaultRedisStore sets the global Redis store for health checks and other cross-package access. Called once during server initialization.
Types ¶
type Cache ¶ added in v0.31.1
type Cache struct {
// contains filtered or unexported fields
}
var Instance *Cache
func (*Cache) DelByPrefix ¶ added in v0.92.0
DelByPrefix removes all cached keys registered under the given capability prefix. The prefix corresponds to a capability type string (e.g. "bookmark", "kanban"). If the prefix is empty, this is a no-op.
func (*Cache) Get ¶ added in v0.31.1
Get retrieves a string value from the cache. Returns false if the key is not found.
func (*Cache) GetBytes ¶ added in v0.92.0
GetBytes retrieves raw bytes from the cache. Returns false if the key is not found or the value is not a byte slice.
func (*Cache) SetNX ¶ added in v0.92.0
SetNX stores a value only if the key does not already exist. Returns true if the value was set.
func (*Cache) SetWithTTL ¶ added in v0.31.1
func (*Cache) SetWithTTLCap ¶ added in v0.92.0
func (c *Cache) SetWithTTLCap(key string, value []byte, cost int64, ttl time.Duration, capType string) bool
SetWithTTLCap stores a byte value with TTL and registers the key under the given capability prefix for later prefix-based invalidation via DelByPrefix.
type IntCache ¶ added in v0.92.0
type IntCache interface {
// GetInt64 retrieves the integer value for key.
GetInt64(ctx context.Context, key Key) (int64, error)
// SetInt64 stores an integer value with the given TTL.
SetInt64(ctx context.Context, key Key, value int64, ttl TTL) error
// Incr atomically increments the key and returns the new value.
Incr(ctx context.Context, key Key) (int64, error)
// IncrWithTTL atomically increments the key, sets the TTL if the key is new,
// and returns the new value.
IncrWithTTL(ctx context.Context, key Key, ttl TTL) (int64, error)
}
IntCache covers integer counters, backed by Redis. It provides atomic increment operations suitable for rate limiting, statistics, and gauges.
type Key ¶ added in v0.92.0
type Key struct {
// Prefix identifies the business domain (e.g. "online", "chat", "notify").
Prefix string
// Entity identifies the data purpose within the domain (e.g. "agent", "session", "throttle").
Entity string
// Identifier is the business primary key, which may contain additional colon-delimited segments.
Identifier string
}
Key represents a namespaced cache key following the format {prefix}:{entity}:{identifier}. It enforces consistent key naming across all cache operations.
type ListCache ¶ added in v0.92.0
type ListCache interface {
// Push appends values to the tail of the list. Returns the length after push.
Push(ctx context.Context, key Key, values ...string) (int64, error)
// Range returns elements from start to stop (inclusive, zero-indexed).
// Use -1 for stop to read to the end.
Range(ctx context.Context, key Key, start, stop int64) ([]string, error)
// Len returns the current length of the list.
Len(ctx context.Context, key Key) (int64, error)
// Clear removes all elements from the list.
Clear(ctx context.Context, key Key) error
}
ListCache covers list-based aggregation buffers, backed by Redis. It provides ordered insertion and ranged retrieval suitable for message queues and event buffers.
type RedisStore ¶ added in v0.92.0
type RedisStore struct {
// contains filtered or unexported fields
}
RedisStore wraps a Redis client to implement StringCache, IntCache, SetCache, and ListCache. All operations record cache hit/miss/eviction metrics via the helpers in metrics.go.
func DefaultRedisStore ¶ added in v0.92.0
func DefaultRedisStore() *RedisStore
DefaultRedisStore returns the global Redis store. May return nil before initialization.
func NewRedisStore ¶ added in v0.92.0
func NewRedisStore(client *redis.Client) *RedisStore
NewRedisStore creates a RedisStore backed by a Redis client.
func (*RedisStore) Add ¶ added in v0.92.0
Add adds members to a set. If the key is newly created, sets the TTL.
func (*RedisStore) Clear ¶ added in v0.92.0
func (s *RedisStore) Clear(ctx context.Context, key Key) error
Clear removes the entire set or list key.
func (*RedisStore) Del ¶ added in v0.92.0
func (s *RedisStore) Del(ctx context.Context, key Key) error
Del removes a key from the cache.
func (*RedisStore) ExistsRaw ¶ added in v0.92.0
ExistsRaw checks whether a raw key string exists in Redis. Used for scanning and other operations where a pre-formatted key string is available.
func (*RedisStore) Get ¶ added in v0.92.0
Get retrieves a string value by key. Returns false if the key is not found.
func (*RedisStore) GetInt64 ¶ added in v0.92.0
GetInt64 retrieves an int64 value. Returns 0 if the key is not found.
func (*RedisStore) GetMetricsInt64 ¶ added in v0.92.0
func (s *RedisStore) GetMetricsInt64(key string) int64
GetMetricsInt64 retrieves a named metric value.
func (*RedisStore) Incr ¶ added in v0.92.0
Incr atomically increments the integer at key by 1 and returns the new value.
func (*RedisStore) IncrWithTTL ¶ added in v0.92.0
IncrWithTTL atomically increments the integer at key by 1 and sets the TTL if the key was newly created (i.e., the new count is 1).
func (*RedisStore) Ping ¶ added in v0.92.0
Ping checks Redis connectivity and returns the round-trip latency.
func (*RedisStore) Push ¶ added in v0.92.0
Push appends values to the right end of a list. Returns the list length after the push.
func (*RedisStore) Range ¶ added in v0.92.0
Range returns a range of elements from the list. Use 0, -1 for all elements.
func (*RedisStore) ScanKeys ¶ added in v0.92.0
ScanKeys scans for keys matching a pattern, returning all matching keys.
func (*RedisStore) SetMetricsInt64 ¶ added in v0.92.0
func (s *RedisStore) SetMetricsInt64(key string, value int64)
SetMetricsInt64 stores a named metric value. Convenience wrapper around SetInt64.
type SetCache ¶ added in v0.92.0
type SetCache interface {
// Add adds one or more members to the set. Returns the number of members added.
Add(ctx context.Context, key Key, ttl TTL, members ...string) (int64, error)
// IsMember reports whether member is in the set.
IsMember(ctx context.Context, key Key, member string) (bool, error)
// Members returns all members of the set.
Members(ctx context.Context, key Key) ([]string, error)
// Remove removes one or more members from the set. Returns the number removed.
Remove(ctx context.Context, key Key, members ...string) (int64, error)
// Clear removes all members from the set.
Clear(ctx context.Context, key Key) error
}
SetCache covers set-based deduplication, backed by Redis. It manages unordered collections of unique members with O(1) membership tests.
type StringCache ¶ added in v0.92.0
type StringCache interface {
// Get retrieves the string value for key. Returns false if not present.
Get(ctx context.Context, key Key) (string, bool, error)
// Set stores a string value with the given TTL.
Set(ctx context.Context, key Key, value string, ttl TTL) error
// SetNX sets the value only if the key does not already exist.
// Returns true if the value was set.
SetNX(ctx context.Context, key Key, value string, ttl TTL) (bool, error)
// Del removes the key from the cache.
Del(ctx context.Context, key Key) error
// Exists returns whether the key is present in the cache.
Exists(ctx context.Context, key Key) (bool, error)
// Expire sets or updates the TTL on an existing key.
Expire(ctx context.Context, key Key, ttl TTL) error
}
StringCache covers raw string KV operations, backed by either Ristretto or Redis. It is the foundational interface that every backend must satisfy.
type TTL ¶ added in v0.92.0
TTL represents a cache time-to-live duration. It wraps time.Duration to provide named constants for common cache expiry policies.
const ( // TTLNone disables expiry — items persist until explicitly deleted or evicted. TTLNone TTL = 0 // TTLMinute is a 1-minute lifetime, suitable for transient locks or status flags. TTLMinute TTL = TTL(time.Minute) // TTLShort is a 2-minute lifetime, used for heartbeat and liveness signals. TTLShort TTL = TTL(2 * time.Minute) // TTLMedium is a 10-minute lifetime, used for temporary state with moderate freshness requirements. TTLMedium TTL = TTL(10 * time.Minute) // TTLLong is a 1-hour lifetime, used for cached data that can tolerate slight staleness. TTLLong TTL = TTL(1 * time.Hour) // TTLSession is a 24-hour lifetime, used for chat sessions and user presence. TTLSession TTL = TTL(24 * time.Hour) // TTLDay is a 24-hour lifetime, used for daily deduplication windows. TTLDay TTL = TTL(24 * time.Hour) // TTLWeek is a 7-day lifetime, used for medium-term deduplication. TTLWeek TTL = TTL(7 * 24 * time.Hour) // TTLMonth is a 30-day lifetime, used for long-term deduplication to prevent unbounded key growth. TTLMonth TTL = TTL(30 * 24 * time.Hour) )
Predefined TTL constants for standardized cache expiry policies.
Source Files