dlru

The dlru package implements a distributed LRU cache that is shared among all peer replicas of a microservice. Each key is owned by exactly one replica, chosen by rendezvous hashing over the current peer set, so Get, Set and Delete are each a single addressed call to that owner. The broadcast channel carries only the control plane — peer discovery, join and leave, and the cluster-wide Clear, Weight and Len aggregates.

By default, a DLRU is created and assigned for each microservice and made available using svc.DistribCache().

var obj MyObject
ok, err := svc.DistribCache().Get(ctx, cacheKey, &obj)
if err != nil {
	return errors.Trace(err)
}
if !ok {
	obj, err = svc.loadObjectFromDatabase(ctx, objKey)
	if err != nil {
		return errors.Trace(err)
	}
	err = svc.DistribCache().Set(ctx, cacheKey, obj)
	if err != nil {
		return errors.Trace(err)
	}
}

Additional DLRU caches can be created manually. The constructor requires a microservice in order to be able to communicate with NATS, and the path of the NATS subscription to use for synchronization among peers. The cache’s capacity and TTL can be configured as well.

myCache, err := dlru.NewCache(ctx, svc, ":444/my-cache")
if err != nil {
	return errors.Trace(err)
}
myCache.SetMaxMemoryMB(5)
myCache.SetMaxAge(time.Hour)

SetOffloadDuration bounds how long a departing replica spends shipping its keys to their new owners during Close, and the same value defines the window in which two replicas may hold different views of the peer set. The connector clamps it to fit inside its shutdown budget.

Two Store and Load options are accepted for API compatibility but do nothing under single-owner routing. ConsistencyCheck is moot — with one owner there is no second copy to disagree with. Replicate (write to all) contradicts the single-owner model and the capacity scaling that follows from it, so it is ignored rather than silently changing where a key lands. Compress, and the load options Bump, NoBump and MaxAge, are honored and threaded through to the owner’s local LRU.