cachestore

package module
v0.3.10 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 29, 2024 License: MIT Imports: 17 Imported by: 9

README

go-cachestore

Simple cache access & storage layer using Redis or FreeCache

Release Build Status Report codecov Mergify Status Go
Gitpod Ready-to-Code standard-readme compliant Makefile Included Sponsor Donate


Table of Contents


Installation

go-cachestore requires a supported release of Go.

go get -u github.com/mrz1836/go-cachestore

Documentation

View the generated documentation

GoDoc


Repository Features

This repository was created using MrZ's go-template

Built-in Features
Package Dependencies
Library Deployment

Releases are automatically created when you create a new git tag!

If you want to manually make releases, please install GoReleaser:

goreleaser for easy binary or library deployment to GitHub and can be installed:

  • using make: make install-releaser
  • using brew: brew install goreleaser

The .goreleaser.yml file is used to configure goreleaser.


Automatic releases via GitHub Actions from creating a new tag:

make tag version=1.2.3

Manual Releases (optional)

Use make release-snap to create a snapshot version of the release, and finally make release to ship to production (manually).


Makefile Commands

View all makefile commands

make help

List of all current commands:

all                           Runs multiple commands
clean                         Remove previous builds and any cached data
clean-mods                    Remove all the Go mod cache
coverage                      Shows the test coverage
diff                          Show the git diff
generate                      Runs the go generate command in the base of the repo
godocs                        Sync the latest tag with GoDocs
help                          Show this help message
install                       Install the application
install-all-contributors      Installs all contributors locally
install-go                    Install the application (Using Native Go)
install-releaser              Install the GoReleaser application
lint                          Run the golangci-lint application (install if not found)
release                       Full production release (creates release in GitHub)
release                       Runs common.release then runs godocs
release-snap                  Test the full release (build binaries)
release-test                  Full production test release (everything except deploy)
replace-version               Replaces the version in HTML/JS (pre-deploy)
tag                           Generate a new tag and push (tag version=0.0.0)
tag-remove                    Remove a tag if found (tag-remove version=0.0.0)
tag-update                    Update an existing tag to current commit (tag-update version=0.0.0)
test                          Runs lint and ALL tests
test-ci                       Runs all tests via CI (exports coverage)
test-ci-no-race               Runs all tests via CI (no race) (exports coverage)
test-ci-short                 Runs unit tests via CI (exports coverage)
test-no-lint                  Runs just tests
test-short                    Runs vet, lint and tests (excludes integration tests)
test-unit                     Runs tests and outputs coverage
uninstall                     Uninstall the application (and remove files)
update-contributors           Regenerates the contributors html/list
update-linter                 Update the golangci-lint package (macOS only)
vet                           Run the Go vet application

Examples & Tests

All unit tests and examples run via GitHub Actions and uses Go version 1.19.x. View the configuration file.


Run all tests

make test

Run tests (excluding integration tests)

make test-short

Benchmarks

Run the Go benchmarks:

make bench

Code Standards

Read more about this Go project's code standards.


Usage

Checkout all the examples!


Contributing

View the contributing guidelines and follow the code of conduct.


How can I help?

All kinds of contributions are welcome 🙌! The most basic way to show your support is to star 🌟 the project, or to raise issues 💬. You can also support this project by becoming a sponsor on GitHub 👏 or by making a bitcoin donation to ensure this journey continues indefinitely! 🚀

Stars


Contributors ✨

Thank you to these wonderful people (emoji key):


Mr. Z
🚇 💻 🚧 🛡️

This project follows the all-contributors specification.


License

License

Documentation

Overview

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

Index

Constants

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

	// DefaultRedisPort is the default Redis port
	DefaultRedisPort = "6379"

	// RedisPrefix is the prefix for URL based connections
	RedisPrefix = "redis://"
)
View Source 
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

View Source 
var ErrAppNameRequired = errors.New("app name is required")

ErrAppNameRequired is when the app name is required

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

ErrInvalidRedisConfig is when the redis config is missing or invalid

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

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

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

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

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

ErrLockCreateFailed is the error when creating a lock fails

View Source 
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

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

ErrSecretGenerationFailed is the error if the secret failed to generate

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

ErrSecretRequired is returned when the secret is empty (value)

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

ErrTTWCannotBeEmpty is when the TTW field is empty

Functions

func RandomHex 

func RandomHex(n int) (string, error)

RandomHex returns a random hex string and error

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)

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)

func (*Client) WriteLockWithSecret added in v0.1.2 

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

WriteLockWithSecret will create a lock with the given secret with a TTL (seconds) to expire The lockKey is unique and should be deterministic The secret should be unique per instance/process that wants to acquire the lock

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 zLogger.GormLoggerInterface) 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 for the cachestore 

const (
	Empty     Engine = "empty"     // No engine set
	FreeCache Engine = "freecache" // FreeCache (in-memory cache)
	Redis     Engine = "redis"     // 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)
	WriteLockWithSecret(ctx context.Context, lockKey, secret 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)

Source Files

View all Source files

Directories

Path Synopsis
examples
debugging
new_client
new_relic
with_freecache
with_redis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.