lcw

README

Loading Cache Wrapper

The library adds a thin layer on top of lru cache and internal implementation of expirable cache.

Cache name	Constructor	Defaults	Description
LruCache	lcw.NewLruCache	keys=1000	LRU cache with limits
ExpirableCache	lcw.NewExpirableCache	keys=1000, ttl=5m	TTL cache with limits
RedisCache	lcw.NewRedisCache	ttl=5m	Redis cache with limits
Nop	lcw.NewNopCache		Do-nothing cache

Main features:

• LoadingCache (guava style)
• Limit maximum cache size (in bytes)
• Limit maximum key size
• Limit maximum size of a value
• Limit number of keys
• TTL support (ExpirableCache and RedisCache)
• Callback on eviction event (not supported in RedisCache)
• Functional style invalidation
• Functional options
• Sane defaults

Install and update

go get -u github.com/go-pkgz/lcw

Usage

package main

import (
	"github.com/go-pkgz/lcw"
)

func main() {
	cache, err := lcw.NewLruCache(lcw.MaxKeys(500), lcw.MaxCacheSize(65536), lcw.MaxValSize(200), lcw.MaxKeySize(32))
	if err != nil {
		panic("failed to create cache")
	}
	defer cache.Close()

	val, err := cache.Get("key123", func() (interface{}, error) {
		res, err := getDataFromSomeSource(params) // returns string
		return res, err
	})

	if err != nil {
		panic("failed to get data")
	}

	s := val.(string) // cached value
}

Cache with URI

Cache can be created with URIs:

• mem://lru?max_key_size=10&max_val_size=1024&max_keys=50&max_cache_size=64000 - creates LRU cache with given limits
• mem://expirable?ttl=30s&max_key_size=10&max_val_size=1024&max_keys=50&max_cache_size=64000 - create expirable cache
• redis://10.0.0.1:1234?db=16&password=qwerty&network=tcp4&dial_timeout=1s&read_timeout=5s&write_timeout=3s - create redis cache
• nop:// - create Nop cache

Scoped cache

Scache provides a wrapper on top of all implementations of LoadingCache with a number of special features:

1. Key is not a string, but a composed type made from partition, key-id and list of scopes (tags).
2. Value type limited to []byte
3. Added Flush method for scoped/tagged invalidation of multiple records in a given partition
4. A simplified interface with Get, Stat, Flush and Close only.

Details

• In all cache types other than Redis (e.g. LRU and Expirable at the moment) values are stored as-is which means that mutable values can be changed outside of cache. ExampleLoadingCache_Mutability illustrates that.
• All byte-size limits (MaxCacheSize and MaxValSize) only work for values implementing lcw.Sizer interface.
• Negative limits (max options) rejected
• The implementation started as a part of remark42 and later on moved to go-pkgz/rest library and finally generalized to become lcw.

Documentation

Overview

Package lcw adds a thin layer on top of lru and expirable cache providing more limits and common interface. The primary method to get (and set) data to/from the cache is LoadingCache.Get returning stored data for a given key or call provided func to retrieve and store, similar to Guava loading cache. Limits allow max values for key size, number of keys, value size and total size of values in the cache. CacheStat gives general stats on cache performance. 3 flavors of cache provided - NoP (do-nothing cache), ExpirableCache (TTL based), and LruCache

Example (LoadingCacheMutability)

nolint:govet //false positive due to example name ExampleLoadingCacheMutability illustrates changing mutable stored item outside of cache, works only for non-Redis cache.

c, err := NewExpirableCache(MaxKeys(10), TTL(time.Minute*30)) // make expirable cache (30m TTL) with up to 10 keys
if err != nil {
	panic("can' make cache")
}
defer c.Close()

mutableSlice := []string{"key1", "key2"}

// put mutableSlice in "mutableSlice" cache key
_, _ = c.Get("mutableSlice", func() (interface{}, error) {
	return mutableSlice, nil
})

// get from cache, func won't run because mutableSlice is cached
// value is original now
v, _ := c.Get("mutableSlice", func() (interface{}, error) {
	return nil, nil
})
fmt.Printf("got %v slice from cache\n", v)

mutableSlice[0] = "another_key_1"
mutableSlice[1] = "another_key_2"

// get from cache, func won't run because mutableSlice is cached
// value is changed inside the cache now because mutableSlice stored as-is, in mutable state
v, _ = c.Get("mutableSlice", func() (interface{}, error) {
	return nil, nil
})
fmt.Printf("got %v slice from cache after it's change outside of cache\n", v)

Output:

got [key1 key2] slice from cache
got [another_key_1 another_key_2] slice from cache after it's change outside of cache

Index

• Constants
• type CacheStat
  • func (s CacheStat) String() string
• type ExpirableCache
  • func NewExpirableCache(opts ...Option) (*ExpirableCache, error)
  • func (c *ExpirableCache) Close() error
  • func (c *ExpirableCache) Delete(key string)
  • func (c *ExpirableCache) Get(key string, fn func() (interface{}, error)) (data interface{}, err error)
  • func (c *ExpirableCache) Invalidate(fn func(key string) bool)
  • func (c *ExpirableCache) Keys() (res []string)
  • func (c *ExpirableCache) Peek(key string) (interface{}, bool)
  • func (c *ExpirableCache) Purge()
  • func (c *ExpirableCache) Stat() CacheStat
• type FlusherRequest
  • func Flusher(partition string) FlusherRequest
  • func (f FlusherRequest) Scopes(scopes ...string) FlusherRequest
• type Key
  • func NewKey(partition ...string) Key
  • func (k Key) ID(id string) Key
  • func (k Key) Scopes(scopes ...string) Key
  • func (k Key) String() string
• type LoadingCache
  • func New(uri string) (LoadingCache, error)
• type LruCache
  • func NewLruCache(opts ...Option) (*LruCache, error)
  • func (c *LruCache) Close() error
  • func (c *LruCache) Delete(key string)
  • func (c *LruCache) Get(key string, fn func() (interface{}, error)) (data interface{}, err error)
  • func (c *LruCache) Invalidate(fn func(key string) bool)
  • func (c *LruCache) Keys() (res []string)
  • func (c *LruCache) Peek(key string) (interface{}, bool)
  • func (c *LruCache) Purge()
  • func (c *LruCache) Stat() CacheStat
• type Nop
  • func NewNopCache() *Nop
  • func (n *Nop) Close() error
  • func (n *Nop) Delete(string)
  • func (n *Nop) Get(_ string, fn func() (interface{}, error)) (interface{}, error)
  • func (n *Nop) Invalidate(func(key string) bool)
  • func (n *Nop) Keys() []string
  • func (n *Nop) Peek(string) (interface{}, bool)
  • func (n *Nop) Purge()
  • func (n *Nop) Stat() CacheStat
• type Option
  • func EventBus(pubSub eventbus.PubSub) Option
  • func MaxCacheSize(max int64) Option
  • func MaxKeySize(max int) Option
  • func MaxKeys(max int) Option
  • func MaxValSize(max int) Option
  • func OnEvicted(fn func(key string, value interface{})) Option
  • func TTL(ttl time.Duration) Option
• type RedisCache
  • func NewRedisCache(backend *redis.Client, opts ...Option) (*RedisCache, error)
  • func (c *RedisCache) Close() error
  • func (c *RedisCache) Delete(key string)
  • func (c *RedisCache) Get(key string, fn func() (interface{}, error)) (data interface{}, err error)
  • func (c *RedisCache) Invalidate(fn func(key string) bool)
  • func (c *RedisCache) Keys() (res []string)
  • func (c *RedisCache) Peek(key string) (interface{}, bool)
  • func (c *RedisCache) Purge()
  • func (c *RedisCache) Stat() CacheStat
• type Scache
  • func NewScache(lc LoadingCache) *Scache
  • func (m *Scache) Close() error
  • func (m *Scache) Flush(req FlusherRequest)
  • func (m *Scache) Get(key Key, fn func() ([]byte, error)) (data []byte, err error)
  • func (m *Scache) Stat() CacheStat
• type Sizer

Examples

• Package (LoadingCacheMutability)
• LruCache
• Scache

Constants

const RedisValueSizeLimit = 512 * 1024 * 1024

RedisValueSizeLimit is maximum allowed value size in Redis

Types

type CacheStat

type CacheStat struct {
	Hits   int64
	Misses int64
	Keys   int
	Size   int64
	Errors int64
}

CacheStat represent stats values

func (CacheStat) String

func (s CacheStat) String() string

String formats cache stats

type ExpirableCache

type ExpirableCache struct {
	CacheStat
	// contains filtered or unexported fields
}

ExpirableCache implements LoadingCache with TTL.

func NewExpirableCache

func NewExpirableCache(opts ...Option) (*ExpirableCache, error)

NewExpirableCache makes expirable LoadingCache implementation, 1000 max keys by default and 5m TTL

func (*ExpirableCache) Close

func (c *ExpirableCache) Close() error

Close kills cleanup goroutine

func (*ExpirableCache) Delete

func (c *ExpirableCache) Delete(key string)

Delete cache item by key

func (*ExpirableCache) Get

func (c *ExpirableCache) Get(key string, fn func() (interface{}, error)) (data interface{}, err error)

Get gets value by key or load with fn if not found in cache

func (*ExpirableCache) Invalidate

func (c *ExpirableCache) Invalidate(fn func(key string) bool)

Invalidate removes keys with passed predicate fn, i.e. fn(key) should be true to get evicted

func (*ExpirableCache) Keys

func (c *ExpirableCache) Keys() (res []string)

Keys returns cache keys

func (*ExpirableCache) Peek

func (c *ExpirableCache) Peek(key string) (interface{}, bool)

Peek returns the key value (or undefined if not found) without updating the "recently used"-ness of the key.

func (*ExpirableCache) Purge

func (c *ExpirableCache) Purge()

Purge clears the cache completely.

func (*ExpirableCache) Stat

func (c *ExpirableCache) Stat() CacheStat

Stat returns cache statistics

type FlusherRequest

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

FlusherRequest used as input for cache.Flush

func Flusher

func Flusher(partition string) FlusherRequest

Flusher makes new FlusherRequest with empty scopes

func (FlusherRequest) Scopes

func (f FlusherRequest) Scopes(scopes ...string) FlusherRequest

Scopes adds scopes to FlusherRequest

type Key

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

Key for scoped cache. Created foe given partition (can be empty) and set with ID and Scopes. example: k := NewKey("sys1").ID(postID).Scopes("last_posts", customer_id)

func NewKey

func NewKey(partition ...string) Key

NewKey makes base key for given partition. Partition can be omitted.

func (Key) ID

func (k Key) ID(id string) Key

ID sets key id

func (Key) Scopes

func (k Key) Scopes(scopes ...string) Key

Scopes of the key

func (Key) String

func (k Key) String() string

String makes full string key from primary key, partition and scopes key string made as <partition>@@<id>@@<scope1>$$<scope2>....

type LoadingCache

type LoadingCache interface {
	Get(key string, fn func() (interface{}, error)) (val interface{}, err error) // load or get from cache
	Peek(key string) (interface{}, bool)                                         // get from cache by key
	Invalidate(fn func(key string) bool)                                         // invalidate items for func(key) == true
	Delete(key string)                                                           // delete by key
	Purge()                                                                      // clear cache
	Stat() CacheStat                                                             // cache stats
	Keys() []string                                                              // list of all keys
	Close() error                                                                // close open connections
}

LoadingCache defines guava-like cache with Get method returning cached value ao retrieving it if not in cache

func New

func New(uri string) (LoadingCache, error)

New parses uri and makes any of supported caches supported URIs:

• redis://<ip>:<port>?db=123&max_keys=10
• mem://lru?max_keys=10&max_cache_size=1024
• mem://expirable?ttl=30s&max_val_size=100
• nop://

type LruCache

type LruCache struct {
	CacheStat
	// contains filtered or unexported fields
}

LruCache wraps lru.LruCache with loading cache Get and size limits

Example

LruCache illustrates the use of LRU loading cache

// set up test server for single response
var hitCount int
ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	if r.URL.String() == "/post/42" && hitCount == 0 {
		_, _ = w.Write([]byte("<html><body>test response</body></html>"))
		return
	}
	w.WriteHeader(404)
}))

// load page function
loadURL := func(url string) (string, error) {
	resp, err := http.Get(url) // nolint
	if err != nil {
		return "", err
	}
	b, err := io.ReadAll(resp.Body)
	_ = resp.Body.Close()
	if err != nil {
		return "", err
	}
	return string(b), nil
}

// fixed size LRU cache, 100 items, up to 10k in total size
cache, err := NewLruCache(MaxKeys(100), MaxCacheSize(10*1024))
if err != nil {
	log.Printf("can't make lru cache, %v", err)
}

// url not in cache, load data
url := ts.URL + "/post/42"
val, err := cache.Get(url, func() (val interface{}, err error) {
	return loadURL(url)
})
if err != nil {
	log.Fatalf("can't load url %s, %v", url, err)
}
fmt.Println(val.(string))

// url not in cache, load data
val, err = cache.Get(url, func() (val interface{}, err error) {
	return loadURL(url)
})
if err != nil {
	log.Fatalf("can't load url %s, %v", url, err)
}
fmt.Println(val.(string))

// url cached, skip load and get from the cache
val, err = cache.Get(url, func() (val interface{}, err error) {
	return loadURL(url)
})
if err != nil {
	log.Fatalf("can't load url %s, %v", url, err)
}
fmt.Println(val.(string))

// get cache stats
stats := cache.Stat()
fmt.Printf("%+v\n", stats)

// close test HTTP server after all log.Fatalf are passed
ts.Close()

Output:

<html><body>test response</body></html>
<html><body>test response</body></html>
<html><body>test response</body></html>
{hits:2, misses:1, ratio:0.67, keys:1, size:0, errors:0}

func NewLruCache

func NewLruCache(opts ...Option) (*LruCache, error)

NewLruCache makes LRU LoadingCache implementation, 1000 max keys by default

func (*LruCache) Close

func (c *LruCache) Close() error

Close does nothing for this type of cache

func (*LruCache) Delete

func (c *LruCache) Delete(key string)

Delete cache item by key

func (*LruCache) Get

func (c *LruCache) Get(key string, fn func() (interface{}, error)) (data interface{}, err error)

Get gets value by key or load with fn if not found in cache

func (*LruCache) Invalidate

func (c *LruCache) Invalidate(fn func(key string) bool)

Invalidate removes keys with passed predicate fn, i.e. fn(key) should be true to get evicted

func (*LruCache) Keys

func (c *LruCache) Keys() (res []string)

Keys returns cache keys

func (*LruCache) Peek

func (c *LruCache) Peek(key string) (interface{}, bool)

Peek returns the key value (or undefined if not found) without updating the "recently used"-ness of the key.

func (*LruCache) Purge

func (c *LruCache) Purge()

Purge clears the cache completely.

func (*LruCache) Stat

func (c *LruCache) Stat() CacheStat

Stat returns cache statistics

type Nop

type Nop struct{}

Nop is do-nothing implementation of LoadingCache

func NewNopCache

func NewNopCache() *Nop

NewNopCache makes new do-nothing cache

func (*Nop) Close

func (n *Nop) Close() error

Close does nothing for nop cache

func (*Nop) Delete

func (n *Nop) Delete(string)

Delete does nothing for nop cache

func (*Nop) Get

func (n *Nop) Get(_ string, fn func() (interface{}, error)) (interface{}, error)

Get calls fn without any caching

func (*Nop) Invalidate

func (n *Nop) Invalidate(func(key string) bool)

Invalidate does nothing for nop cache

func (*Nop) Keys

func (n *Nop) Keys() []string

Keys does nothing for nop cache

func (*Nop) Peek

func (n *Nop) Peek(string) (interface{}, bool)

Peek does nothing and always returns false

func (*Nop) Purge

func (n *Nop) Purge()

Purge does nothing for nop cache

func (*Nop) Stat

func (n *Nop) Stat() CacheStat

Stat always 0s for nop cache

type Option

type Option func(o *options) error

Option func type

func EventBus

func EventBus(pubSub eventbus.PubSub) Option

EventBus sets PubSub for distributed cache invalidation

func MaxCacheSize

func MaxCacheSize(max int64) Option

MaxCacheSize functional option defines the total size of cached data. By default it is 0, which means unlimited.

func MaxKeySize

func MaxKeySize(max int) Option

MaxKeySize functional option defines the largest key's size allowed to be used in cache By default it is 0, which means unlimited.

func MaxKeys

func MaxKeys(max int) Option

MaxKeys functional option defines how many keys to keep. By default it is 0, which means unlimited.

func MaxValSize

func MaxValSize(max int) Option

MaxValSize functional option defines the largest value's size allowed to be cached By default it is 0, which means unlimited.

func OnEvicted

func OnEvicted(fn func(key string, value interface{})) Option

OnEvicted sets callback on invalidation event

func TTL

func TTL(ttl time.Duration) Option

TTL functional option defines duration. Works for ExpirableCache only

type RedisCache

type RedisCache struct {
	CacheStat
	// contains filtered or unexported fields
}

RedisCache implements LoadingCache for Redis.

func NewRedisCache

func NewRedisCache(backend *redis.Client, opts ...Option) (*RedisCache, error)

NewRedisCache makes Redis LoadingCache implementation.

func (*RedisCache) Close

func (c *RedisCache) Close() error

Close closes underlying connections

func (*RedisCache) Delete

func (c *RedisCache) Delete(key string)

Delete cache item by key

func (*RedisCache) Get

func (c *RedisCache) Get(key string, fn func() (interface{}, error)) (data interface{}, err error)

Get gets value by key or load with fn if not found in cache

func (*RedisCache) Invalidate

func (c *RedisCache) Invalidate(fn func(key string) bool)

Invalidate removes keys with passed predicate fn, i.e. fn(key) should be true to get evicted

func (*RedisCache) Keys

func (c *RedisCache) Keys() (res []string)

Keys gets all keys for the cache

func (*RedisCache) Peek

func (c *RedisCache) Peek(key string) (interface{}, bool)

Peek returns the key value (or undefined if not found) without updating the "recently used"-ness of the key.

func (*RedisCache) Purge

func (c *RedisCache) Purge()

Purge clears the cache completely.

func (*RedisCache) Stat

func (c *RedisCache) Stat() CacheStat

Stat returns cache statistics

type Scache

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

Scache wraps LoadingCache with partitions (sub-system), and scopes. Simplified interface with just 4 funcs - Get, Flush, Stats and Close

Example

LruCache illustrates the use of LRU loading cache

// set up test server for single response
var hitCount int
ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	if r.URL.String() == "/post/42" && hitCount == 0 {
		_, _ = w.Write([]byte("<html><body>test response</body></html>"))
		return
	}
	w.WriteHeader(404)
}))

// load page function
loadURL := func(url string) ([]byte, error) {
	resp, err := http.Get(url) // nolint
	if err != nil {
		return nil, err
	}
	b, err := io.ReadAll(resp.Body)
	_ = resp.Body.Close()
	if err != nil {
		return nil, err
	}
	return b, nil
}

// fixed size LRU cache, 100 items, up to 10k in total size
backend, err := NewLruCache(MaxKeys(100), MaxCacheSize(10*1024))
if err != nil {
	log.Fatalf("can't make lru cache, %v", err)
}

cache := NewScache(backend)

// url not in cache, load data
url := ts.URL + "/post/42"
key := NewKey().ID(url).Scopes("test")
val, err := cache.Get(key, func() (val []byte, err error) {
	return loadURL(url)
})
if err != nil {
	log.Fatalf("can't load url %s, %v", url, err)
}
fmt.Println(string(val))

// url not in cache, load data
key = NewKey().ID(url).Scopes("test")
val, err = cache.Get(key, func() (val []byte, err error) {
	return loadURL(url)
})
if err != nil {
	log.Fatalf("can't load url %s, %v", url, err)
}
fmt.Println(string(val))

// url cached, skip load and get from the cache
key = NewKey().ID(url).Scopes("test")
val, err = cache.Get(key, func() (val []byte, err error) {
	return loadURL(url)
})
if err != nil {
	log.Fatalf("can't load url %s, %v", url, err)
}
fmt.Println(string(val))

// get cache stats
stats := cache.Stat()
fmt.Printf("%+v\n", stats)

// close cache and test HTTP server after all log.Fatalf are passed
ts.Close()
err = cache.Close()
if err != nil {
	log.Fatalf("can't close cache %v", err)
}

Output:

<html><body>test response</body></html>
<html><body>test response</body></html>
<html><body>test response</body></html>
{hits:2, misses:1, ratio:0.67, keys:1, size:0, errors:0}

func NewScache

func NewScache(lc LoadingCache) *Scache

NewScache creates Scache on top of LoadingCache

func (*Scache) Close

func (m *Scache) Close() error

Close calls Close function of the underlying cache

func (*Scache) Flush

func (m *Scache) Flush(req FlusherRequest)

Flush clears cache and calls postFlushFn async

func (*Scache) Get

func (m *Scache) Get(key Key, fn func() ([]byte, error)) (data []byte, err error)

Get retrieves a key from underlying backend

func (*Scache) Stat

func (m *Scache) Stat() CacheStat

Stat delegates the call to the underlying cache backend

type Sizer

type Sizer interface {
	Size() int
}

Sizer allows to perform size-based restrictions, optional. If not defined both maxValueSize and maxCacheSize checks will be ignored