dcache

README

* DCache
A full-featured 2-layer (mem-redis) cache implementation.
+ Cache penetration protection: empty values can also be cached.
+ Cache breakdown: single-query-in-flight.
+ Redis network IO pressure: memory cache with Redis queue events for invalidation.
+ Compression
+ Prometheus
+ OpenTelementry

** Versions

+ For `go-redis/v8` users, please use `v0.1.x`. 
+ For `go-redis/v9` users, use `v0.2.x`

Documentation

Index

• Variables
• func EnableRedisSingleFlightOption(c *DCache)
• func SetNowFunc(f func() time.Time)
• type CacheDuration
  • func (c CacheDuration) ToDuration() time.Duration
• type DCache
  • func NewDCache(appName string, primaryClient redis.UniversalClient, ...) (*DCache, error)
  • func (c *DCache) Close()
  • func (c *DCache) Get(ctx context.Context, key string, target any, expire time.Duration, ...) error
  • func (c *DCache) GetWithTtl(ctx context.Context, key string, target any, read ReadWithTtlFunc, ...) (err error)
  • func (c *DCache) Invalidate(ctx context.Context, key string) (err error)
  • func (c *DCache) Ping(ctx context.Context) error
  • func (c *DCache) Set(ctx context.Context, key string, val any, ttl time.Duration) (err error)
  • func (c *DCache) SetMemCacheMaxTTLSeconds(ttl int64) error
• type DacheOption
• type ReadFunc
• type ReadWithTtlFunc
• type ValueBytesExpiredAt

Variables

var (
	// ErrTimeout is timeout error
	ErrTimeout = errors.New("timeout")
	// ErrInternal should never happen
	ErrInternal = errors.New("internal")
	// ErrNotPointer value passed to get functions is not a pointer.
	ErrNotPointer = errors.New("value is not a pointer")
	// ErrTypeMismatch value passed to get functions is not a pointer.
	ErrTypeMismatch = errors.New("value type mismatches cached type")
)

Functions

func EnableRedisSingleFlightOption

func EnableRedisSingleFlightOption(c *DCache)

WithRedisSingleFlight enables single flight for Redis.

func SetNowFunc

func SetNowFunc(f func() time.Time)

SetNowFunc is a helper function to replace time.Now(), usually used for testing.

Types

type CacheDuration

type CacheDuration time.Duration

const (
	SuperFast           CacheDuration = CacheDuration(time.Second)
	VeryFast            CacheDuration = CacheDuration(time.Second * 2)
	Fast                CacheDuration = CacheDuration(time.Second * 5)
	Normal              CacheDuration = CacheDuration(time.Second * 10)
	Slow                CacheDuration = CacheDuration(time.Second * 30)
	VerySlow            CacheDuration = CacheDuration(time.Minute * 1)
	SuperSlow           CacheDuration = CacheDuration(time.Minute * 5)
	SuperDuperSlow      CacheDuration = CacheDuration(time.Hour * 1)
	SuperSuperDuperSlow CacheDuration = CacheDuration(time.Hour * 5)
	NeverExpire         CacheDuration = CacheDuration(0)
)

func (CacheDuration) ToDuration

func (c CacheDuration) ToDuration() time.Duration

type DCache

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

DCache implements cache.

func NewDCache

func NewDCache(
	appName string,
	primaryClient redis.UniversalClient,
	inMemCache *freecache.Cache,
	readInterval time.Duration,
	enableStats bool,
	enableTracer bool,
	options ...DacheOption,
) (*DCache, error)

NewDCache creates a new cache client with in-memory cache if not @p inMemCache not nil. Cache MUST be explicitly closed by calling Close(). It will also register several Prometheus metrics to the default register. @p readInterval specify the duration between each read per key.

func (*DCache) Close

func (c *DCache) Close()

Close terminates redis pubsub gracefully

func (*DCache) Get

func (c *DCache) Get(ctx context.Context, key string, target any, expire time.Duration, read ReadFunc, noCache bool, noStore bool) error

Get will read the value from cache if exists or call read() to retrieve the value and cache it in both the memory and Redis by @p ttl. Inputs: @p key: Key used in cache @p value: A pointer to the memory piece of the type of the value.

For example, if we are caching string, then target must be of type *string.
if we caching a null-able string, using *string to represent it, then the
target must be of type **string, i.e., pointer to the pointer of string.

@p ttl: Expiration of cache key @p read: Actual call that hits underlying data source. @p noCache: The response value will be fetched through @p read(). The new value will be

cached, unless @p noStore is specified.

@p noStore: The response value will not be saved into the cache.

func (*DCache) GetWithTtl

func (c *DCache) GetWithTtl(ctx context.Context, key string, target any, read ReadWithTtlFunc, noCache bool, noStore bool) (err error)

GetWithTtl will read the value from cache if exists or call @p read to retrieve the value and cache it in both the memory and Redis by the ttl returned in @p read. Inputs: @p key: Key used in cache @p value: A pointer to the memory piece of the type of the value.

For example, if we are caching string, then target must be of type *string.
if we caching a null-able string, using *string to represent it, then the
target must be of type **string, i.e., pointer to the pointer of string.

@p read: Actual call that hits underlying data source that also returns a ttl for cache. @p noCache: The response value will be fetched through @p read(). The new value will be

cached, unless @p noStore is specified.

@p noStore: The response value will not be saved into the cache.

func (*DCache) Invalidate

func (c *DCache) Invalidate(ctx context.Context, key string) (err error)

Invalidate explicitly invalidates a cache key Inputs: key - key to invalidate

func (*DCache) Ping

func (c *DCache) Ping(ctx context.Context) error

Ping checks if the underlying redis connection is alive

func (*DCache) Set

func (c *DCache) Set(ctx context.Context, key string, val any, ttl time.Duration) (err error)

Set explicitly set a cache key to a val Inputs: key - key to set val - val to set ttl - ttl of key

func (*DCache) SetMemCacheMaxTTLSeconds

func (c *DCache) SetMemCacheMaxTTLSeconds(ttl int64) error

type DacheOption

type DacheOption func(*DCache)

type ReadFunc

type ReadFunc = func() (any, error)

ReadFunc is the actual call to underlying data source

type ReadWithTtlFunc

type ReadWithTtlFunc = func() (any, time.Duration, error)

ReadWithTtlFunc is the actual call to underlying data source while returning a duration as expire timer

type ValueBytesExpiredAt

type ValueBytesExpiredAt struct {
	ValueBytes []byte `msgpack:"v,omitempty"`
	ExpiredAt  int64  `msgpack:"e,omitempty"` // UNIX timestamp in Milliseconds.
}

ValueBytesExpiredAt is how we store value and expiration time to Redis.