Documentation
¶
Overview ¶
Package kvcache provides a generic two-tier cache: a per-process local tier in front of a shared Store such as Redis. It replaced the removed ecache and rcache packages; their storage key prefix and envelope are retained as the wire format.
Index ¶
- Variables
- type Cache
- func (c *Cache[K, V]) Contains(key K) bool
- func (c *Cache[K, V]) Get(ctx context.Context, key K) (V, bool)
- func (c *Cache[K, V]) GetItem(ctx context.Context, key K) (Item[V], bool)
- func (c *Cache[K, V]) GetRecheckKeys(ctx context.Context) []K
- func (c *Cache[K, V]) Has(key K) bool
- func (c *Cache[K, V]) LocalKeys() []K
- func (c *Cache[K, V]) Peek(key K) (V, bool)
- func (c *Cache[K, V]) Refresh(ctx context.Context, key K) (V, error)
- func (c *Cache[K, V]) Reload(ctx context.Context, key K) (V, error)
- func (c *Cache[K, V]) Set(ctx context.Context, key K, value V) error
- func (c *Cache[K, V]) SetMissing(ctx context.Context, key K) error
- func (c *Cache[K, V]) SetTTL(ctx context.Context, key K, value V, recheckTTL time.Duration, ...) error
- func (c *Cache[K, V]) Start(interval time.Duration)
- func (c *Cache[K, V]) Stop()
- type HashStore
- type Item
- type MemoryStore
- func (s *MemoryStore) Get(ctx context.Context, key string) ([]byte, bool, error)
- func (s *MemoryStore) GetMulti(ctx context.Context, keys []string) (map[string][]byte, error)
- func (s *MemoryStore) HGetAll(ctx context.Context, key string) (map[string]string, error)
- func (s *MemoryStore) HSet(ctx context.Context, key string, field string, value string) error
- func (s *MemoryStore) Set(ctx context.Context, key string, value []byte, ttl time.Duration) error
- type PubSubStore
- type RedisStore
- func (s *RedisStore) Get(ctx context.Context, key string) ([]byte, bool, error)
- func (s *RedisStore) GetMulti(ctx context.Context, keys []string) (map[string][]byte, error)
- func (s *RedisStore) HGetAll(ctx context.Context, key string) (map[string]string, error)
- func (s *RedisStore) HSet(ctx context.Context, key string, field string, value string) error
- func (s *RedisStore) Publish(ctx context.Context, channel string, payload []byte) error
- func (s *RedisStore) Set(ctx context.Context, key string, value []byte, ttl time.Duration) error
- func (s *RedisStore) Subscribe(ctx context.Context, channel string) (Subscription, error)
- type Store
- type Subscription
Constants ¶
This section is empty.
Variables ¶
var ErrNotFound = errors.New("not found")
ErrNotFound is returned by refresh functions to indicate a key is authoritatively absent; with NegativeTTL configured, the absence is cached as a tombstone.
Functions ¶
This section is empty.
Types ¶
type Cache ¶
type Cache[K comparable, V any] struct { // Recheck and Expires are the TTLs applied by Set and Refresh // (defaults 1h / 1h). Recheck time.Duration Expires time.Duration // RefreshTimeout bounds each refresh function call (default 1s). RefreshTimeout time.Duration // NegativeTTL enables tombstone caching of authoritatively absent // keys — via SetMissing or a refresh function returning ErrNotFound // (default off). Legacy ecache/rcache readers do not understand // tombstones and see them as zero-value hits; do not enable shared // tombstones on a topic until all legacy readers are retired. NegativeTTL time.Duration // KeyPrefix namespaces storage keys as "<prefix>:<topic>:<key>". The // default "ecache" preserves the legacy wire format. KeyPrefix string // Clock overrides time.Now, for tests. Clock func() time.Time // contains filtered or unexported fields }
Cache is a generic two-tier cache: a per-process local map in front of an optional shared Store. Entries carry a soft recheck time and a hard expiry; expired entries are never served from either tier.
func NewCache ¶
func NewCache[K comparable, V any](store Store, topic string) *Cache[K, V]
NewCache returns a two-tier cache; store may be nil for local-only use.
func NewRefreshCache ¶
func NewRefreshCache[K comparable, V any](store Store, topic string, refreshFn func(context.Context, K) (V, error)) *Cache[K, V]
NewRefreshCache returns a cache that populates values read-through on miss and in the background via Start.
func (*Cache[K, V]) Contains ¶
Contains reports whether the local tier has any record of key — a live value, a tombstone, or an expired entry not yet pruned. It consults neither the shared tier nor the refresh function.
func (*Cache[K, V]) Get ¶
Get returns the cached value for key. Tombstoned (negative) entries read as misses.
func (*Cache[K, V]) GetItem ¶
GetItem returns the full envelope for key; ok is true when a valid envelope is known, including negative tombstones (check Missing).
func (*Cache[K, V]) GetRecheckKeys ¶
GetRecheckKeys reconciles the local tier against the shared tier in a single multi-get — adopting entries refreshed by other processes and pruning expired ones — and returns the keys still due for refresh.
func (*Cache[K, V]) Has ¶
Has reports whether the local tier holds a live value for key: true exactly when Peek would return one.
func (*Cache[K, V]) LocalKeys ¶
func (c *Cache[K, V]) LocalKeys() []K
LocalKeys returns a snapshot of locally known keys.
func (*Cache[K, V]) Peek ¶
Peek returns the live local value for key: exactly what Get would return without loading. Tombstoned keys are not held. It consults neither the shared tier nor the refresh function.
func (*Cache[K, V]) Reload ¶
Reload re-runs the refresh function for key and installs the value it returns. Unlike Refresh, a key that turns out absent or unreadable leaves whatever is held in place: reloading is for a key already known to have changed, so a failure is a failure to observe that change rather than evidence the key is gone.
The call is bounded by RefreshTimeout and by the caller's own context, since unlike a flight leader's refresh its result is nobody else's. Installs go through installLocal: whatever landed mid-reload — a Set, a flight, or another Reload — saw the key later than this reload read it and is kept, and the returned value is the one actually held.
func (*Cache[K, V]) SetMissing ¶
SetMissing stores a negative tombstone for key in both tiers for NegativeTTL, suppressing lookups until it lapses. See NegativeTTL for the legacy-reader caveat.
func (*Cache[K, V]) SetTTL ¶
func (c *Cache[K, V]) SetTTL(ctx context.Context, key K, value V, recheckTTL time.Duration, expireTTL time.Duration) error
SetTTL stores value in both tiers. The local tier serves it until expireTTL; the shared tier additionally applies expireTTL as its backend TTL. Storage writes are best-effort: the local tier is always updated.
type HashStore ¶
type HashStore interface {
HSet(ctx context.Context, key string, field string, value string) error
HGetAll(ctx context.Context, key string) (map[string]string, error)
}
HashStore is an optional Store capability providing field-addressable hash maps, used for small secondary text indexes such as the GBFS bbox index.
type Item ¶
type Item[V any] struct { Value V ExpiresAt time.Time RecheckAt time.Time Missing bool `json:",omitempty"` }
Item is the stored envelope for a cached value. The JSON encoding is wire-compatible with the ecache/rcache envelope.
type MemoryStore ¶
type MemoryStore struct {
// contains filtered or unexported fields
}
MemoryStore is an in-process Store for tests and single-process use. Two Caches sharing one MemoryStore emulate cross-process behavior. It also implements the HashStore capability.
func NewMemoryStore ¶
func NewMemoryStore() *MemoryStore
type PubSubStore ¶
type PubSubStore interface {
// Publish sends payload to channel. Keep payloads small (a key or
// topic, not the value it points at).
Publish(ctx context.Context, channel string, payload []byte) error
// Subscribe streams messages published to channel until the returned
// Subscription is closed or ctx is canceled.
Subscribe(ctx context.Context, channel string) (Subscription, error)
}
PubSubStore is an optional Store capability providing publish/subscribe over named channels, used by the realtime store to fan feed updates out to every process.
Payloads are pointers, not data: a message names a key whose value the receiver re-reads from the Store. This keeps messages small enough for backends with tight limits (Postgres NOTIFY caps payloads at ~8KB).
type RedisStore ¶
type RedisStore struct {
// Timeout bounds each Redis operation (default 1s).
Timeout time.Duration
// contains filtered or unexported fields
}
RedisStore adapts a *redis.Client to Store. A nil client is a no-op store: all reads miss and writes are discarded, preserving the historical nil-client local-only mode.
func NewRedisStore ¶
func NewRedisStore(client *redis.Client) *RedisStore
func (*RedisStore) Subscribe ¶
func (s *RedisStore) Subscribe(ctx context.Context, channel string) (Subscription, error)
type Store ¶
type Store interface {
// Get returns the value for key. ok is false on a normal miss; err
// reports a backend failure. Callers treat errors as misses.
Get(ctx context.Context, key string) (value []byte, ok bool, err error)
// GetMulti returns values for the subset of keys that are present.
GetMulti(ctx context.Context, keys []string) (map[string][]byte, error)
// Set stores value. The backend may evict the entry after ttl; a ttl
// of zero or less means no backend-enforced expiry.
Set(ctx context.Context, key string, value []byte, ttl time.Duration) error
}
Store is a shared key-value tier for a Cache. Keys arrive fully namespaced; values are opaque byte envelopes. Implementations must be safe for concurrent use.
Store is intentionally minimal. Additional backend capabilities arrive as optional sibling interfaces (PubSubStore, HashStore) discovered by type assertion, never as new methods on Store.
type Subscription ¶
Subscription is a live stream of published payloads for a single channel. Close releases the underlying backend connection.