cachestore

Documentation

Overview

Package cachestore is the caching (key->value) service abstraction layer

Index

• Constants
• Variables
• type CacheService
• type Client
  • func (c *Client) Close(ctx context.Context)
  • func (c *Client) Debug(on bool)
  • func (c *Client) Delete(ctx context.Context, key string) error
  • func (c *Client) EmptyCache(ctx context.Context) error
  • func (c *Client) Engine() Engine
  • func (c *Client) FreeCache() *freecache.Cache
  • func (c *Client) Get(ctx context.Context, key string) (string, error)
  • func (c *Client) GetModel(ctx context.Context, key string, model interface{}) error
  • func (c *Client) IsDebug() bool
  • func (c *Client) IsNewRelicEnabled() bool
  • func (c *Client) Redis() *cache.Client
  • func (c *Client) RedisConfig() *RedisConfig
  • func (c *Client) ReleaseLock(ctx context.Context, lockKey, secret string) (bool, error)
  • func (c *Client) Set(ctx context.Context, key string, value interface{}, dependencies ...string) error
  • func (c *Client) SetModel(ctx context.Context, key string, model interface{}, ttl time.Duration, ...) error
  • func (c *Client) WaitWriteLock(ctx context.Context, lockKey string, ttl, ttw int64) (string, error)
  • func (c *Client) WriteLock(ctx context.Context, lockKey string, ttl int64) (string, error)
• type ClientInterface
  • func NewClient(ctx context.Context, opts ...ClientOps) (ClientInterface, error)
• type ClientOps
  • func WithDebugging() ClientOps
  • func WithFreeCache() ClientOps
  • func WithFreeCacheConnection(client *freecache.Cache) ClientOps
  • func WithLogger(customLogger logger.Interface) ClientOps
  • func WithNewRelic() ClientOps
  • func WithRedis(redisConfig *RedisConfig) ClientOps
  • func WithRedisConnection(redisClient *cache.Client) ClientOps
• type Engine
  • func (e Engine) IsEmpty() bool
  • func (e Engine) String() string
• type LockService
• type RedisConfig

Constants

const (
	// DefaultRedisMaxIdleTimeout is the default max timeout on an idle connection
	DefaultRedisMaxIdleTimeout = 240 * time.Second

	// RedisPrefix is the prefix for URL based connections
	RedisPrefix = "redis://"
)

const (

	// DefaultCacheSize in bytes, where 1024 * 1024 represents a single Megabyte, and 100 * 1024*1024 represents 100 Megabytes.
	DefaultCacheSize = 100 * 1024 * 1024

	// DefaultGCPercent is the percentage when full it will run GC
	DefaultGCPercent = 20
)

Variables

var ErrInvalidRedisConfig = errors.New("invalid redis config")

ErrInvalidRedisConfig is when the redis config is missing or invalid

var ErrKeyNotFound = errors.New("key not found")

ErrKeyNotFound is returned when a record is not found for a given key

var ErrKeyRequired = errors.New("key is empty and required")

ErrKeyRequired is returned when the key is empty (key->value)

var ErrLockCreateFailed = errors.New("failed creating cache lock")

ErrLockCreateFailed is the error when creating a lock fails

var ErrLockExists = errors.New("lock already exists with a different secret")

ErrLockExists is the error when trying to create a lock fails due to an existing lock

var ErrNoEngine = errors.New("cachestore engine is empty: choose redis or memory (IE: WithRedis())")

ErrNoEngine is returned when there is no engine set (missing engine)

var ErrSecretGenerationFailed = errors.New("failed generating secret")

ErrSecretGenerationFailed is the error if the secret failed to generate

var ErrSecretRequired = errors.New("secret is empty and required")

ErrSecretRequired is returned when the secret is empty (value)

var ErrTTWCannotBeEmpty = errors.New("the TTW value cannot be empty")

ErrTTWCannotBeEmpty is when the TTW field is empty

Types

type CacheService

type CacheService interface {
	Delete(ctx context.Context, key string) error
	Get(ctx context.Context, key string) (string, error)
	GetModel(ctx context.Context, key string, model interface{}) error
	Set(ctx context.Context, key string, value interface{}, dependencies ...string) error
	SetModel(ctx context.Context, key string, model interface{}, ttl time.Duration, dependencies ...string) error
}

CacheService are the cache related methods

type Client

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

Client is the client (configuration)

func (*Client) Close

func (c *Client) Close(ctx context.Context)

Close will close the client and any open connections

func (*Client) Debug

func (c *Client) Debug(on bool)

Debug will set the debug flag

func (*Client) Delete

func (c *Client) Delete(ctx context.Context, key string) error

Delete will remove a key from the cache

func (*Client) EmptyCache

func (c *Client) EmptyCache(ctx context.Context) error

EmptyCache will empty the cache entirely

CAUTION: this will dump all the stored cache

func (*Client) Engine

func (c *Client) Engine() Engine

Engine will return the engine that is set

func (*Client) FreeCache

func (c *Client) FreeCache() *freecache.Cache

FreeCache will return the FreeCache client if found

func (*Client) Get

func (c *Client) Get(ctx context.Context, key string) (string, error)

Get will return a value from a given key

Redis will be an interface{} but really a string (empty string) mCache/ristretto will be an interface{} and usually a pointer (empty nil)

func (*Client) GetModel

func (c *Client) GetModel(ctx context.Context, key string, model interface{}) error

GetModel will get a model (parsing JSON (bytes) -> Model)

Model needs to be a pointer to a struct

func (*Client) IsDebug

func (c *Client) IsDebug() bool

IsDebug will return if debugging is enabled

func (*Client) IsNewRelicEnabled

func (c *Client) IsNewRelicEnabled() bool

IsNewRelicEnabled will return if new relic is enabled

func (*Client) Redis

func (c *Client) Redis() *cache.Client

Redis will return the Redis client if found

func (*Client) RedisConfig

func (c *Client) RedisConfig() *RedisConfig

RedisConfig will return the Redis config client if found

func (*Client) ReleaseLock

func (c *Client) ReleaseLock(ctx context.Context, lockKey, secret string) (bool, error)

ReleaseLock will release a given lock key only if the secret matches

func (*Client) Set

func (c *Client) Set(ctx context.Context, key string, value interface{}, dependencies ...string) error

Set will set a key->value using the current engine

NOTE: redis only supports dependency keys at this time Value should be used as a string for best results

func (*Client) SetModel

func (c *Client) SetModel(ctx context.Context, key string, model interface{},
	ttl time.Duration, dependencies ...string) error

SetModel will set any model or struct (parsing Model->JSON (bytes))

Model needs to be a pointer to a struct NOTE: redis only supports dependency keys at this time

func (*Client) WaitWriteLock

func (c *Client) WaitWriteLock(ctx context.Context, lockKey string, ttl, ttw int64) (string, error)

WaitWriteLock will aggressively try to make a lock until the TTW (in seconds) is reached

func (*Client) WriteLock

func (c *Client) WriteLock(ctx context.Context, lockKey string, ttl int64) (string, error)

WriteLock will create a unique lock/secret with a TTL (seconds) to expire The lockKey is unique and should be deterministic The secret will be automatically generated and stored in the locked key (returned)

type ClientInterface

type ClientInterface interface {
	CacheService
	LockService
	Close(ctx context.Context)
	Debug(on bool)
	EmptyCache(ctx context.Context) error
	Engine() Engine
	FreeCache() *freecache.Cache
	IsDebug() bool
	IsNewRelicEnabled() bool
	Redis() *cache.Client
	RedisConfig() *RedisConfig
}

ClientInterface is the cachestore interface

func NewClient

func NewClient(ctx context.Context, opts ...ClientOps) (ClientInterface, error)

NewClient creates a new client for all CacheStore functionality

If no options are given, it will use the defaultClientOptions() ctx may contain a NewRelic txn (or one will be created)

type ClientOps

type ClientOps func(c *clientOptions)

ClientOps allow functional options to be supplied that overwrite default client options.

func WithDebugging

func WithDebugging() ClientOps

WithDebugging will enable debugging mode

func WithFreeCache

func WithFreeCache() ClientOps

WithFreeCache will set the cache to local memory using FreeCache

func WithFreeCacheConnection

func WithFreeCacheConnection(client *freecache.Cache) ClientOps

WithFreeCacheConnection will set the cache to use an existing FreeCache connection

func WithLogger

func WithLogger(customLogger logger.Interface) ClientOps

WithLogger will set the custom logger interface

func WithNewRelic

func WithNewRelic() ClientOps

WithNewRelic will enable the NewRelic wrapper

func WithRedis

func WithRedis(redisConfig *RedisConfig) ClientOps

WithRedis will set the redis configuration

func WithRedisConnection

func WithRedisConnection(redisClient *cache.Client) ClientOps

WithRedisConnection will set an existing redis connection (read & write)

type Engine

type Engine string

Engine is the different engines that are supported (key->value)

const (
	Empty     Engine = "empty"
	FreeCache Engine = "freecache"
	Redis     Engine = "redis"
)

Supported engines

func (Engine) IsEmpty

func (e Engine) IsEmpty() bool

IsEmpty will return true if the engine is not set

func (Engine) String

func (e Engine) String() string

String is the string version of engine

type LockService

type LockService interface {
	ReleaseLock(ctx context.Context, lockKey, secret string) (bool, error)
	WaitWriteLock(ctx context.Context, lockKey string, ttl, ttw int64) (string, error)
	WriteLock(ctx context.Context, lockKey string, ttl int64) (string, error)
}

LockService are the locking related methods

type RedisConfig

type RedisConfig struct {
	DependencyMode        bool          `json:"dependency_mode" mapstructure:"dependency_mode"`                 // false for digital ocean (not supported)
	MaxActiveConnections  int           `json:"max_active_connections" mapstructure:"max_active_connections"`   // 0
	MaxConnectionLifetime time.Duration `json:"max_connection_lifetime" mapstructure:"max_connection_lifetime"` // 0
	MaxIdleConnections    int           `json:"max_idle_connections" mapstructure:"max_idle_connections"`       // 10
	MaxIdleTimeout        time.Duration `json:"max_idle_timeout" mapstructure:"max_idle_timeout"`               // 240 * time.Second
	URL                   string        `json:"url" mapstructure:"url"`                                         // redis://localhost:6379
	UseTLS                bool          `json:"use_tls" mapstructure:"use_tls"`                                 // true for digital ocean (required)
}

RedisConfig is the configuration for the cache client (redis)