kvcache

package
v1.4.1 Latest Latest
Warning

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

Go to latest
Published: Nov 5, 2026 License: GPL-3.0 Imports: 10 Imported by: 0

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

Constants

This section is empty.

Variables

View Source
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

func (c *Cache[K, V]) Contains(key K) bool

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

func (c *Cache[K, V]) Get(ctx context.Context, key K) (V, bool)

Get returns the cached value for key. Tombstoned (negative) entries read as misses.

func (*Cache[K, V]) GetItem

func (c *Cache[K, V]) GetItem(ctx context.Context, key K) (Item[V], bool)

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

func (c *Cache[K, V]) GetRecheckKeys(ctx context.Context) []K

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

func (c *Cache[K, V]) Has(key K) bool

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

func (c *Cache[K, V]) Peek(key K) (V, bool)

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

func (c *Cache[K, V]) Refresh(ctx context.Context, key K) (V, error)

Refresh calls the refresh function for key and stores the result.

func (*Cache[K, V]) Reload

func (c *Cache[K, V]) Reload(ctx context.Context, key K) (V, error)

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

func (c *Cache[K, V]) Set(ctx context.Context, key K, value V) error

Set stores value in both tiers using the configured Recheck/Expires TTLs.

func (*Cache[K, V]) SetMissing

func (c *Cache[K, V]) SetMissing(ctx context.Context, key K) error

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.

func (*Cache[K, V]) Start

func (c *Cache[K, V]) Start(interval time.Duration)

Start launches a background goroutine that periodically reconciles with the shared tier and, when a refresh function is configured, refreshes due keys. Start is a no-op if already running. It panics on a non-positive interval, like time.NewTicker.

func (*Cache[K, V]) Stop

func (c *Cache[K, V]) Stop()

Stop halts the background goroutine and waits for an in-flight tick. The cache remains usable, and Start may be called again.

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

func (*MemoryStore) Get

func (s *MemoryStore) Get(ctx context.Context, key string) ([]byte, bool, error)

func (*MemoryStore) GetMulti

func (s *MemoryStore) GetMulti(ctx context.Context, keys []string) (map[string][]byte, error)

func (*MemoryStore) HGetAll

func (s *MemoryStore) HGetAll(ctx context.Context, key string) (map[string]string, error)

func (*MemoryStore) HSet

func (s *MemoryStore) HSet(ctx context.Context, key string, field string, value string) error

func (*MemoryStore) Set

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

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) Get

func (s *RedisStore) Get(ctx context.Context, key string) ([]byte, bool, error)

func (*RedisStore) GetMulti

func (s *RedisStore) GetMulti(ctx context.Context, keys []string) (map[string][]byte, error)

func (*RedisStore) HGetAll

func (s *RedisStore) HGetAll(ctx context.Context, key string) (map[string]string, error)

func (*RedisStore) HSet

func (s *RedisStore) HSet(ctx context.Context, key string, field string, value string) error

func (*RedisStore) Publish

func (s *RedisStore) Publish(ctx context.Context, channel string, payload []byte) error

func (*RedisStore) Set

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

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

type Subscription interface {
	Messages() <-chan []byte
	Close() error
}

Subscription is a live stream of published payloads for a single channel. Close releases the underlying backend connection.

Directories

Path Synopsis
Package storetest provides a conformance suite for kvcache.Store implementations.
Package storetest provides a conformance suite for kvcache.Store implementations.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL