natscache

Documentation

Overview

Package natscache provides a NATS JetStream KeyValue cache backend for entcache.

It implements both the entcache.Cache and entcache.StampedeLocker interfaces, providing distributed caching capabilities with robust Cache Stampede Protection.

When multiple concurrent requests attempt to fetch the same missing key, exactly one request acquires a lock and queries the database. The other requests wait seamlessly using NATS KV Watch capabilities until the data is populated, preventing database overload.

Requirements: NATS JetStream KV buckets must be created with LimitMarkerTTL enabled for the internal stampede locks to automatically expire in case of client failure.

Index

• type NatsKV
  • func New(kv jetstream.KeyValue) *NatsKV
  • func (n *NatsKV) Add(ctx context.Context, k entcache.Key, e *entcache.Entry, ttl time.Duration) error
  • func (n *NatsKV) Close()
  • func (n *NatsKV) Del(ctx context.Context, k entcache.Key) error
  • func (n *NatsKV) Get(ctx context.Context, k entcache.Key) (*entcache.Entry, error)
  • func (n *NatsKV) LockOrWait(ctx context.Context, k entcache.Key) (bool, func(context.Context) (*entcache.Entry, error), func(context.Context), ...)
  • func (n *NatsKV) WatchInvalidations(ctx context.Context, onInvalidate func(key entcache.Key)) error

Types

type NatsKV

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

NatsKV provides a remote cache backed by NATS JetStream KeyValue with built-in distributed stampede locking and real-time Watch invalidations.

func New

func New(kv jetstream.KeyValue) *NatsKV

New returns a new NATS JetStream KeyValue cache level.

func (*NatsKV) Add

func (n *NatsKV) Add(ctx context.Context, k entcache.Key, e *entcache.Entry, ttl time.Duration) error

Add adds the entry to the cache using Put or Create for per-key TTL.

func (*NatsKV) Close

func (n *NatsKV) Close()

Close gracefully tears down the heartbeat instance.

func (*NatsKV) Del

func (n *NatsKV) Del(ctx context.Context, k entcache.Key) error

Del deletes an entry from the cache.

func (*NatsKV) Get

func (n *NatsKV) Get(ctx context.Context, k entcache.Key) (*entcache.Entry, error)

Get gets an entry from the cache.

func (*NatsKV) LockOrWait

func (n *NatsKV) LockOrWait(ctx context.Context, k entcache.Key) (bool, func(context.Context) (*entcache.Entry, error), func(context.Context), error)

LockOrWait acquires a distributed lock on cache misses using NATS KV Create. If won == true, the caller executes the DB query and releases the lock. If won == false, wait() uses Watch to wait until the winner populates the cache.

func (*NatsKV) WatchInvalidations

func (n *NatsKV) WatchInvalidations(ctx context.Context, onInvalidate func(key entcache.Key)) error

WatchInvalidations listens to NATS KV key updates/deletions and triggers onInvalidate.