entitycache

package
v0.57.1-rc.1 Latest Latest
Warning

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

Go to latest
Published: Nov 20, 2026 License: Apache-2.0 Imports: 7 Imported by: 0

Documentation

Overview

Package entitycache implements a revisioned cache for partially acquired normalized entities.

Entity data is acquired progressively (ADR 0147): several clients may fetch additional fields or history for the same entity concurrently. The cache retains the current partial entity for each canonical entity ID together with a revision, and updates it only through an atomic compare-and-swap so concurrent clients cannot silently overwrite each other's updates.

Merging is deliberately outside the cache API. After a conflict, a caller fetches the latest snapshot with Cache.Get, merges its newly retrieved data, and retries Cache.Put with the snapshot's revision.

The cached value is a normentity.Document, the typed normalized-entity v1 model. It represents unknown markers, nulls, absent members, and each collection's coverage, and the cache never rewrites them, so the contract's distinctions between absent, not loaded, unsupported, unknown, failed, and incomplete data survive a round trip.

See docs/ADRs/0147-evaluate-entity-cel-over-selectively-acquired-data.md and docs/normative/normalized-entity/v1/README.md.

Index

Constants

View Source
const (
	// DefaultMaxEntries is the number of live entities a [Memory] retains when
	// [MemoryOptions.MaxEntries] is zero.
	DefaultMaxEntries = 1024
	// DefaultTTL is how long a [Memory] retains an entity after its last
	// successful Put when [MemoryOptions.TTL] is zero.
	DefaultTTL = 5 * time.Minute
)

Variables

View Source
var (
	// ErrInvalidID reports an entity ID that is not in canonical form.
	ErrInvalidID = errors.New("entitycache: invalid entity ID")
	// ErrInvalidEntity reports a missing document, one whose identity is
	// inconsistent (see [normentity.Document.Validate]), or one whose
	// entity.id is not the given entity ID.
	ErrInvalidEntity = errors.New("entitycache: invalid entity document")
	// ErrConflict reports a Put whose expected revision is not the entity's
	// current revision. The caller should Get the latest snapshot, merge its
	// data into it, and retry.
	ErrConflict = errors.New("entitycache: revision conflict")
)

Errors returned by Cache methods.

View Source
var ErrInvalidOptions = errors.New("entitycache: invalid memory options")

ErrInvalidOptions reports MemoryOptions with a negative value.

Functions

This section is empty.

Types

type Cache

type Cache interface {
	// Get returns a private copy of the cached document for id and its
	// current revision. On a miss it returns ok false together with the
	// current revision, which a caller passes to Put to create the entry. An
	// invalid id misses with revision 0.
	Get(id normentity.ID) (doc *normentity.Document, rev Revision, ok bool)
	// Put atomically replaces the cached document for id when expected equals
	// the current revision, and returns the new revision. Otherwise it stores
	// nothing and returns the current revision with [ErrConflict]. It returns
	// [ErrInvalidID] or [ErrInvalidEntity] for invalid input.
	Put(id normentity.ID, doc *normentity.Document, expected Revision) (Revision, error)
	// Invalidate removes any cached document for id and advances its revision,
	// so a Put based on any earlier snapshot, including a miss, conflicts.
	// It returns the new revision, or [ErrInvalidID]. A cache that bounds
	// retention applies the same rule when it expires or evicts an entity.
	Invalidate(id normentity.ID) (Revision, error)
}

Cache retains partially acquired normalized entities keyed by canonical entity ID.

Implementations must be safe for concurrent use, must copy documents on the way in and out so callers cannot mutate cached state outside Put, and must store documents exactly as given. An implementation may drop an entity to bound its retention, but it must then advance the entity's revision exactly as Invalidate does, so a Put based on a snapshot taken before the removal conflicts instead of restoring stale data.

type Memory

type Memory struct {
	// contains filtered or unexported fields
}

Memory is a thread-safe, process-local Cache with bounded retention.

An entity is retained until it is invalidated, expires TTL after its last successful Put, or is evicted as the least recently used entity to make room for a new one. Successful Gets and Puts mark an entity as recently used. Expired entities are treated as misses and are reclaimed by the next cache operation; no background goroutine runs.

Revisions come from a single counter shared by every entity, so an entity's revision never repeats. An absent entity's revision is its tombstone revision when it was invalidated, expired, or evicted, and otherwise the shared absent revision. Tombstones keep a Put based on a pre-removal snapshot from restoring stale data. To bound memory, once the tombstone count reaches its limit every tombstone is dropped and the shared absent revision advances past all revisions issued so far; absent entities then report that new revision, so earlier snapshots of them still conflict. The cost is that a pending miss-time Put for an unrelated absent entity may also conflict and retry.

func NewMemory

func NewMemory(opts MemoryOptions) (*Memory, error)

NewMemory returns an empty in-memory cache. It returns ErrInvalidOptions when opts has a negative value.

func (*Memory) Get

Get implements Cache. An expired entity is a miss. A stored record that cannot be decoded is reported as a miss at its current revision, so the caller can replace it with Put; Put only stores documents that encode, so this does not occur in practice.

func (*Memory) Invalidate

func (m *Memory) Invalidate(id normentity.ID) (Revision, error)

Invalidate implements Cache.

func (*Memory) Put

func (m *Memory) Put(id normentity.ID, doc *normentity.Document, expected Revision) (Revision, error)

Put implements Cache. A successful Put restarts the entity's TTL and marks it as most recently used. Replacing an existing entity never evicts another. Inserting a new entity into a full cache reclaims expired entities first and then evicts the least recently used one. A failed Put changes neither recency nor expiry.

type MemoryOptions

type MemoryOptions struct {
	// MaxEntries is the most live entities retained. Inserting a new entity
	// beyond it evicts the least recently used one. Zero selects
	// [DefaultMaxEntries]; a negative value is invalid.
	MaxEntries int
	// TTL is how long an entity is retained after its last successful Put.
	// The expiry is absolute: Get does not extend it. Zero selects
	// [DefaultTTL]; a negative value is invalid.
	TTL time.Duration
}

MemoryOptions configures the retention of a Memory. The zero value selects the defaults.

type Revision

type Revision uint64

Revision identifies a version of one entity's cache state. Revisions for a given entity ID strictly increase with every successful Put and every removal of the entity (Invalidate, expiry, or eviction), and are never reused, so equal revisions imply no intervening change. Revisions are comparable only for the same entity ID. An entity ID the cache has never seen has revision 0.

Jump to

Keyboard shortcuts

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