[Off-chain] feat: in-memory query cache(s)

pkg/client/interface.go

@@ -360,3 +360,23 @@ type BankQueryClient interface {
 	// GetBalance queries the chain for the uPOKT balance of the account provided
 	GetBalance(ctx context.Context, address string) (*cosmostypes.Coin, error)
 }
+
+// QueryCache is a key/value store style interface for a cache of a single type.
+// It is intended to be used to cache query responses (or derivatives thereof),
+// where each key uniquely indexes the most recent query response.
+type QueryCache[T any] interface {
+	Get(key string) (T, error)
+	Set(key string, value T) error
+	Delete(key string)
+	Clear()
+}
+
+// HistoricalQueryCache extends QueryCache to support getting and setting values
+// at multiple heights for a given key.
+type HistoricalQueryCache[T any] interface {
+	QueryCache[T]
+	// GetAtHeight retrieves the nearest value <= the specified height
+	GetAtHeight(key string, height int64) (T, error)
+	// SetAtHeight adds or updates a value at a specific height
+	SetAtHeight(key string, value T, height int64) error
+}

pkg/client/query/cache/config.go

@@ -0,0 +1,89 @@
+package cache
+
+import (
+	"time"
+)
+
+// EvictionPolicy determines which items are removed when number of keys in the cache reaches maxKeys.
+type EvictionPolicy int64
+
+const (
+	FirstInFirstOut = EvictionPolicy(iota)
+	LeastRecentlyUsed
+	LeastFrequentlyUsed
+)
+
+// queryCacheConfig is the configuration for query caches.
+// It is intended to be configured via QueryCacheOptionFn functions.
+type queryCacheConfig struct {
+	// maxKeys is the maximum number of items (key/value pairs) the cache can
+	// hold before it starts evicting.
+	maxKeys int64
+
+	// TODO_CONSIDERATION:
+	//
+	// maxValueSize is the maximum cumulative size of all values in the cache.
+	// maxValueSize int64
+	// maxCacheSize is the maximum cumulative size of all keys AND values in the cache.
+	// maxCacheSize int64
+
+	// evictionPolicy determines which items are removed when number of keys in the cache reaches maxKeys.
+	evictionPolicy EvictionPolicy
+	// ttl is how long items should remain in the cache. Items older than the ttl
+	// MAY NOT be evicted immediately, but are NEVER considered as cache hits.
+	ttl time.Duration
+	// historical determines whether each key will point to a single values (false)
+	// or a history (i.e. reverse chronological list) of values (true).
+	historical bool
+	// numHistoricalValues is the number of past blocks for which to keep historical
+	// values. If 0, no historical pruning is performed. It only applies when
+	// historical is true.
+	numHistoricalValues int64
+}
+
+// QueryCacheOptionFn is a function which receives a queryCacheConfig for configuration.
+type QueryCacheOptionFn func(*queryCacheConfig)
+
+// Validate ensures that the queryCacheConfig isn't configured with incompatible options.
+func (cfg *queryCacheConfig) Validate() error {
+	switch cfg.evictionPolicy {
+	case FirstInFirstOut:
+	// TODO_IMPROVE: support LeastRecentlyUsed and LeastFrequentlyUsed policies.
+	default:
+		return ErrQueryCacheConfigValidation.Wrapf("eviction policy %d not imlemented", cfg.evictionPolicy)
+	}
+
+	return nil
+}
+
+// WithHistoricalMode enables historical caching with the given numHistoricalValues
+// configuration; if 0, no historical pruning is performed.
+func WithHistoricalMode(numHistoricalBlocks int64) QueryCacheOptionFn {
+	return func(cfg *queryCacheConfig) {
+		cfg.historical = true
+		cfg.numHistoricalValues = numHistoricalBlocks
+	}
+}
+
+// WithMaxKeys sets the maximum number of distinct key/value pairs the cache will
+// hold before evicting according to the configured eviction policy.
+func WithMaxKeys(maxKeys int64) QueryCacheOptionFn {
+	return func(cfg *queryCacheConfig) {
+		cfg.maxKeys = maxKeys
+	}
+}
+
+// WithEvictionPolicy sets the eviction policy.
+func WithEvictionPolicy(policy EvictionPolicy) QueryCacheOptionFn {
+	return func(cfg *queryCacheConfig) {
+		cfg.evictionPolicy = policy
+	}
+}
+
+// WithTTL sets the time-to-live for cached items. Items older than the TTL
+// MAY NOT be evicted immediately, but are NEVER considered as cache hits.
+func WithTTL(ttl time.Duration) QueryCacheOptionFn {
+	return func(cfg *queryCacheConfig) {
+		cfg.ttl = ttl
+	}
+}

pkg/client/query/cache/errors.go

@@ -0,0 +1,12 @@
+package cache
+
+import "cosmossdk.io/errors"
+
+const codesace = "client/query/cache"
+
+var (
+	ErrCacheMiss                  = errors.Register(codesace, 1, "cache miss")
+	ErrHistoricalModeNotEnabled   = errors.Register(codesace, 2, "historical mode not enabled")
+	ErrQueryCacheConfigValidation = errors.Register(codesace, 3, "invalid query cache config")
+	ErrCacheInternal              = errors.Register(codesace, 4, "cache internal error")
+)