cache

type BulkFetcher ¶ added in v0.27.0

type BulkFetcher[V any] interface {
	// FetchMany returns the values of the keys the store holds, and no entry for
	// a key it does not. It mutates the store as Fetch does. Duplicate keys
	// are read once.
	FetchMany(ctx context.Context, keys []string) (map[string]V, error)
}

BulkFetcher is the sibling that reads many keys in one call (ADR 0039, #840): one lock acquisition per stripe on a memory store, one pass per tier on a chain, one round trip on a remote tier — where N calls of Fetch pay N.

type BulkSetter ¶ added in v0.27.0

type BulkSetter[V any] interface {
	// SetMany stores every entry under its key. Every entry is validated before
	// any is stored: one a store refuses — an empty key or tag, a TTL Set would
	// refuse — fails the call with [CacheEntryRejected] and stores nothing.
	SetMany(ctx context.Context, entries map[string]EntryValue[V]) error
}

BulkSetter is the sibling that stores many entries in one call (ADR 0039, #840).

type EntryFetcher ¶

type EntryFetcher[V any] interface {
	// FetchEntry is [Store.Fetch] returning the stored entry — value, remaining
	// TTL and tags. It mutates the store for the same reasons Fetch does.
	//
	// The TTL it reports is the REMAINING time, not the one originally
	// supplied: promoting an entry with its original TTL would extend its life
	// every time it moved between tiers.
	FetchEntry(ctx context.Context, key string) (EntryValue[V], bool, error)
}

EntryFetcher is the sibling that returns the whole entry rather than only its value (ADR 0039). It exists because promotion between tiers has to carry TTL and tags: a value promoted into a near tier without its tags is a value that Tagger.InvalidateTag can no longer reach, and an invalidation that silently misses one copy is worse than one that is not offered at all.

type EntryValue ¶

type EntryValue[V any] struct {
	// Value is the payload.
	Value V
	// TTL is how long the entry stays fetchable.
	//
	//   > 0        this exact lifetime
	//   0          the store's configured default
	//   [NoExpiry] no deadline at all
	//
	// Any other negative value is a mistake, not a third meaning, and is
	// refused with [CacheEntryRejected] rather than reinterpreted.
	TTL time.Duration
	// Tags label the entry for bulk invalidation. Order is not significant and
	// duplicates are collapsed. An empty tag is refused: it names a set nobody
	// can ask for, so accepting it would index the entry under a key that can
	// only ever be reached by accident.
	//
	// Tags cost memory in the store's reverse index — see
	// internal/service/data/cache/CLAUDE.md, which states the per-pair cost and
	// measures it.
	Tags []string
}

EntryValue is what a caller stores: the value, how long it should live, and the tags by which it can later be invalidated in bulk.

It is a VALUE — a store copies what it needs and never retains the slice the caller passed, so a caller may reuse or mutate its Tags slice afterwards.

type Expirer ¶ added in v0.27.0

type Expirer interface {
	// Expire removes every entry whose deadline has passed and reports how many
	// it removed. A chain sweeps every tier that can, far to near, and reports
	// the total of removals, as InvalidateTag counts them.
	Expire(ctx context.Context) (removed int, err error)
}

Expirer is the sibling for stores that can remove their expired entries on demand (ADR 0039, #1059). Expiry is otherwise lazy: an entry past its TTL is reaped by a read of its own key or by an eviction, and until then it holds capacity, a place in the tag index and — for a value that must not outlive its TTL — memory. The store starts no goroutine: the caller sweeps on its own ticker or scheduler, which is the cadence ADR 0049 left to it.

type Fill ¶

type Fill[V any] func(ctx context.Context) (EntryValue[V], error)

Fill computes the entry for a key that the cache does not hold. It is the caller's code: a database query, an HTTP call, a derivation.

It is a FUNC port rather than a one-method interface, the shape internal/core already admits for resilience.Operation, scheduler.Job and validation.Constraint — and, per ADR 0039, a func type satisfies the no-widening rule structurally, because it cannot grow a method at all.

type Leaser ¶ added in v0.27.0

type Leaser[V any] interface {
	// LoadLeased is Load with a lease named "cache:" + key taken from locker
	// on a miss, after the in-process collapse. The holder reads the store
	// again, fills, stores and releases. A process that finds the lease held
	// fills nothing: it reads the store again every poll step of the store's
	// clock until the holder's value lands or its own ctx ends — or until the
	// lease comes free without a value (the holder failed, died, or let a lease
	// that can expire lapse), when it takes the lease and reads once more
	// before filling. A nil locker makes it Load. A locker that cannot answer
	// fails the call with [CacheLeaseFailed]. A lease that can expire is not
	// renewed during the fill: its lifetime must outlast the fill.
	LoadLeased(ctx context.Context, key string, fill Fill[V], locker lock.Locker) (V, error)
}

Leaser is the sibling that carries stampede protection across PROCESSES (ADR 0039, #830). Loader.Load collapses concurrent misses within one process; LoadLeased also takes a named lease, on a miss, from a lock.Locker the processes share — the lock domain's file locker on one machine, whose lease dies with the process holding it — so that one process at a time fills a key.

What the others then get depends on what they share. A chain whose far tier every process reaches answers the waiting ones with the value the holder stored: the origin sees ONE fill. A memory store alone shares no value: the lease then only takes turns — one fill at a time, never two at once, each process filling its own copy once the holder has finished.

type Loader ¶

type Loader[V any] interface {
	// Load returns the value for key, calling fill exactly once across all
	// concurrent callers of this key in this process if the cache does not
	// hold it. A fill that fails stores nothing and returns
	// [CacheFillFailed] — unless the failure already carries an SDK code, in
	// which case it propagates untouched (ADR 0005 §origin wins).
	//
	// fill does NOT receive ctx. It receives the shared call's context: the
	// first caller's values with every deadline removed, cancelled only once
	// every waiting caller has gone. A caller whose own ctx ends while it
	// waits gets its own ctx.Err() and leaves the fill running for the others.
	Load(ctx context.Context, key string, fill Fill[V]) (V, error)
}

Loader is the sibling for stores that can fill a miss while ensuring that concurrent misses on ONE key run the fill ONCE (ADR 0039).

What it protects against, and what it does not ¶

A cache stampede is what happens when a hot key expires: every request that was being served from it misses at the same instant and every one of them calls the origin. The origin sees, in one moment, the traffic the cache was hiding — which is the load the cache was bought to prevent, arriving when the system is least able to absorb it.

Loader.Load collapses those calls into one WITHIN ONE PROCESS. It does NOT coordinate across replicas: N instances of a service each running this still produce N concurrent fills. Cross-process collapsing needs a shared lease, which is a distributed system and not something a cache port can promise. A reader who takes "stampede protection" to mean "my origin sees one request" would be wrong by a factor of N, so the limit is stated here, in the port, and again in every document that mentions the feature. Leaser is the sibling that takes such a lease, from a lock.Locker the processes share, and says what it can and cannot promise.

type Refresher ¶ added in v0.27.0

type Refresher[V any] interface {
	// LoadRefreshing is Load, except on a hit whose remaining lifetime is below
	// before: the value is returned at once and ONE background fill per key
	// starts, on the caller's context values without its cancellation, bounded
	// by the entry's remaining lifetime; what it returns replaces the entry, and
	// a failure leaves the entry to expire. A hit outside that window starts
	// nothing. A before that is not positive is refused with
	// [CacheMisconfigured].
	LoadRefreshing(ctx context.Context, key string, fill Fill[V], before time.Duration) (V, error)
}

Refresher is the sibling that refreshes a hot entry BEFORE it expires (ADR 0039, #838): stale-while-revalidate. A Load collapses the stampede at expiry; it does not hide the latency, since every reader of that instant waits for the origin. LoadRefreshing answers from the cache and refills in the background while the entry is still valid.

type Store ¶

type Store[V any] interface {
	// Fetch returns the value stored under key and whether it was present and
	// unexpired. It MUTATES the store — recency, counters, lazy expiry — which
	// is why it is not called Get. A miss is (zero, false, nil), never an
	// error: a cache that does not hold something has done nothing wrong.
	Fetch(ctx context.Context, key string) (V, bool, error)
	// Set stores entry under key, replacing whatever was there. An empty key,
	// an empty tag, or a negative TTL that is not [NoExpiry] is refused with
	// [CacheEntryRejected] rather than stored.
	Set(ctx context.Context, key string, entry EntryValue[V]) error
	// Delete removes key. It is idempotent: deleting a key that names nothing
	// reports nil, because a caller who wanted it gone has got what they asked
	// for.
	Delete(ctx context.Context, key string) error
}

Store is the cache port. Implementations MUST be safe for concurrent use.

The method set is deliberately three operations wide and is FROZEN: pkg/v1 aliases this interface, so under ADR 0039 a fourth method would break every downstream implementer at compile time with no deprecation window. New capabilities arrive as SIBLING interfaces discovered by type assertion — EntryFetcher, Tagger and Loader are the three that ship, and the model is codec's Appender (ADR 0037).

IFACE-PLUGIN: the concrete stores stay unexported behind their constructors in internal/service/data/cache.

type Tagger ¶

type Tagger interface {
	// InvalidateTag removes every entry carrying tag and reports how many it
	// removed. A tag that names nothing removes zero and reports nil.
	//
	// The cost is proportional to the number of entries carrying the tag, NOT
	// to the size of the store — see internal/service/data/cache/BENCH.md, which
	// measures it at two store sizes for exactly this claim.
	InvalidateTag(ctx context.Context, tag string) (removed int, err error)
}

Tagger is the sibling for stores that index entries by tag (ADR 0039).

Tagging exists because the thing a caller wants to invalidate is usually not a key. "Every entry derived from user 42" is a set whose members are known to the writer and not to the invalidator, and without a tag the invalidator's only options are to guess the key shape or to purge everything.