version

type CacheKey ¶

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

CacheKey is an canonical single-key identity generated by cascache. It is not a logical user key and must be treated as exact bytes.

func NewCacheKey(raw string) CacheKey

func (k CacheKey) String() string

type Fence ¶

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

Fence is the authoritative compare-only freshness token for one key.

Fence values are opaque. Callers and Store implementations may compare them for equality and may store/restore them through the canonical text or binary helpers below, but must not infer ordering or other semantics from the token contents.

For correctness, a live key must receive a fresh fence whenever authoritative state is created or bumped. This includes recreation after retention cleanup or TTL expiry so old cached values cannot become valid again through ABA.

func NewFence() (Fence, error)

func ParseFence(raw string) (Fence, error)

func ParseFenceBinary(b []byte) (Fence, error)

func (f Fence) AppendBinary(dst []byte) []byte

func (f Fence) AppendText(dst []byte) []byte

func (f Fence) Equal(other Fence) bool

func (f Fence) MarshalBinary() ([]byte, error)

func (f Fence) MarshalText() ([]byte, error)

func (f Fence) String() string

func (f *Fence) UnmarshalBinary(b []byte) error

func (f *Fence) UnmarshalText(text []byte) error

type LocalStore ¶

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

LocalStore keeps authoritative fence state in-process (no network I/O). Optionally starts a background cleanup goroutine that periodically prunes keys whose authoritative state hasn't changed for at least `retention` duration.

• Reads take a shared RLock (Snapshot, SnapshotMany).
• Advances take an exclusive Lock and are O(1).
• Cleanup takes an exclusive Lock and scans the map.

Ctx parameters are accepted to satisfy the Store interface, but are ignored because all operations are local and non-blocking.

func NewLocal() *LocalStore

func NewLocalWithCleanup(cleanupInterval, retention time.Duration) *LocalStore

func (s *LocalStore) Advance(_ context.Context, k CacheKey) (Snapshot, error)

func (s *LocalStore) Cleanup(retention time.Duration)

func (s *LocalStore) Close(_ context.Context) error

func (s *LocalStore) CreateIfMissing(_ context.Context, k CacheKey) (Snapshot, bool, error)

func (s *LocalStore) Snapshot(_ context.Context, k CacheKey) (Snapshot, error)

func (s *LocalStore) SnapshotMany(_ context.Context, ks []CacheKey) (map[CacheKey]Snapshot, error)

type Snapshot ¶

type Snapshot struct {
	Fence  Fence
	Exists bool
}

Snapshot is the authoritative per-key version state. Exists=false means the version store has no current record for the key.

type Store ¶

type Store interface {
	// Snapshot returns the current authoritative version state for a
	// canonical single-key identity.
	Snapshot(ctx context.Context, cacheKey CacheKey) (Snapshot, error)

	// SnapshotMany returns authoritative version state for many canonical
	// single-key identities. Missing keys must be represented as Exists=false.
	SnapshotMany(ctx context.Context, cacheKeys []CacheKey) (map[CacheKey]Snapshot, error)

	// CreateIfMissing creates explicit authoritative state only when the key is
	// currently missing. A created record starts with a fresh fence.
	CreateIfMissing(ctx context.Context, cacheKey CacheKey) (snap Snapshot, created bool, err error)

	// Advance moves authoritative state for a canonical single-key identity to a
	// fresh fence. It must replace any current live fence with a fresh unequal
	// fence. If the key is missing, it creates authoritative state with a fresh
	// fence.
	Advance(ctx context.Context, cacheKey CacheKey) (Snapshot, error)

	// Cleanup prunes old metadata if applicable (no-op for Redis).
	Cleanup(retention time.Duration)

	// Close releases resources (no-op ok).
	Close(context.Context) error
}

Store abstracts where authoritative fences live. Use LocalStore (default) for in-process version state, or redis.NewVersionStore for distributed version state.

CacheKey values are opaque canonical identities generated by cascache. Implementations must treat them as exact bytes and must not try to parse, normalize, or reconstruct them from logical user keys.