redigo

README

 

🔥 RediGo

A Redis client for GoLang featuring Tags with Gob & JSON encoding.

Why?

RediGo is a wrapper for the Redis V8 GoLang client that features tagging, expiration and automatic encoding and decoding using various encoders. It helps to unify various encoding techniques with a simple and easy to user interface.

Gob encoding performs drastically better in comparison to JSON which you can see from the benchmarks below.

Install

go get -u github.com/ainsleyclark/redigo

Quick Start

See below for a quick start to create a new Redis Client with an encoder. For more client methods see the Go Doc which includes all the client methods.

func ExampleClient() {
	ctx := context.Background()

	c := redigo.New(&redis.Options{}, redigo.NewGobEncoder())
	err := c.Ping(ctx)
	if err != nil {
		log.Fatalln(err)
	}

	err = c.Set(ctx, "my-key", "hello", redigo.Options{
		Expiration: time.Second * 100,
		Tags:       []string{"my-tag"},
	})
	if err != nil {
		log.Fatalln(err)
	}

	var val string
	err = c.Get(ctx, "my-key", &val) // Be sure to pass a reference!
	if err != nil {
		log.Fatalln(err)
	}

	err = c.Delete(ctx, "my-key")
	if err != nil {
		log.Fatalln(err)
	}
}

Encoders

JSON

c := redigo.New(&redis.Options{}, redigo.NewJSONEncoder())

Gob

c := redigo.New(&redis.Options{}, redigo.NewGobEncoder())

Message Pack

See github.com/vmihailenco/msgpack for more details.

c := redigo.New(&redis.Options{}, redigo.NewMessagePackEncoder())

Go JSON

See github.com/goccy/go-json for more details.

c := redigo.New(&redis.Options{}, redigo.NewMessagePackEncoder())

Custom

You can pass in custom encoders to the client constructor, that implement the Encode and Decode methods.

type MyEncoder struct{}

func (m MessagePack) Encode(value any) ([]byte, error) {
	// Marshal or encode value
	return []byte("hello"), nil
}

func (m MessagePack) Decode(data []byte, value any) error {
	// Unmarshal or decode value
	return nil
}

func ExampleCustom() {
	c := redigo.New(&redis.Options{}, &MyEncoder{})
}

Benchmarks

$ go version
go version go1.18.2 darwin/amd64

Encode

BenchmarkEncode/JSON-16                    54728             21813 ns/op            9294 B/op        206 allocs/op
BenchmarkEncode/Gob-16                    154272              7629 ns/op            4304 B/op        220 allocs/op
BenchmarkEncode/Message_Pack-16           113059             10468 ns/op            6820 B/op        208 allocs/op
BenchmarkEncode/Go_JSON-16                 92598             12768 ns/op             897 B/op          1 allocs/op

Graph representing ns/op.

Decode

BenchmarkDecode/JSON/-16                   39386             30318 ns/op            7246 B/op        302 allocs/op
BenchmarkDecode/Gob/-16                    57792             20742 ns/op           12733 B/op        193 allocs/op
BenchmarkDecode/Message_Pack/-16           57416             20626 ns/op            7217 B/op        220 allocs/op
BenchmarkDecode/Go_JSON/-16                95376             12186 ns/op            8068 B/op        220 allocs/op

Graph representing ns/op.

Contributing

Please feel free to make a pull request if you think something should be added to this package!

Credits

Shout out to the incredible Maria Letta for her excellent Gopher illustrations.

Licence

Code Copyright 2022 RediGo. Code released under the MIT Licence.

Documentation

Overview

Example

ctx := context.Background()

c := redigo.New(&redis.Options{}, redigo.NewGobEncoder())
err := c.Ping(ctx)
if err != nil {
	log.Fatalln(err)
}

err = c.Set(ctx, "my-key", "hello", redigo.Options{
	Expiration: time.Second * 100,
	Tags:       []string{"my-tag"},
})
if err != nil {
	log.Fatalln(err)
}

var val string
err = c.Get(ctx, "my-key", &val)
if err != nil {
	log.Fatalln(err)
}

err = c.Delete(ctx, "my-key")
if err != nil {
	log.Fatalln(err)
}

Index

• type Cache
  • func New(opts *redis.Options, enc Encoder) *Cache
  • func (c *Cache) Close() error
  • func (c *Cache) Delete(ctx context.Context, key string) error
  • func (c *Cache) Flush(ctx context.Context)
  • func (c *Cache) Get(ctx context.Context, key string, v any) error
  • func (c *Cache) Invalidate(ctx context.Context, tags []string)
  • func (c *Cache) Ping(ctx context.Context) error
  • func (c *Cache) Set(ctx context.Context, key string, value any, options Options) error
• type Encoder
  • func NewGoJSONEncoder() Encoder
  • func NewGobEncoder() Encoder
  • func NewJSONEncoder() Encoder
  • func NewMessagePackEncoder() Encoder
• type Options
• type Store

Examples

• Package

Types

type Cache

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

Cache defines the methods for interacting with the cache layer.

func New

func New(opts *redis.Options, enc Encoder) *Cache

New creates a new store to Redis instance(s).

func (*Cache) Close

func (c *Cache) Close() error

Close closes the client, releasing any open resources.

func (*Cache) Delete

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

Delete removes a singular item from the cache by a specific key.

func (*Cache) Flush

func (c *Cache) Flush(ctx context.Context)

Flush removes all items from the cache.

func (*Cache) Get

func (c *Cache) Get(ctx context.Context, key string, v any) error

Get retrieves a specific item from the cache by key. Values are automatically marshalled for use with Redis.

func (*Cache) Invalidate

func (c *Cache) Invalidate(ctx context.Context, tags []string)

Invalidate removes items from the cache from the tags passed.

func (*Cache) Ping

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

Ping pings the Redis cache to ensure its alive.

func (*Cache) Set

func (c *Cache) Set(ctx context.Context, key string, value any, options Options) error

Set stores a singular item in memory by key, value and options (tags and expiration time). Values are automatically marshalled for use with Redis & Memcache.

type Encoder

type Encoder interface {
	Encode(value any) ([]byte, error)
	Decode([]byte, any) error
}

Encoder defines methods for encoding and decoding buffers into the cache store.

func NewGoJSONEncoder

func NewGoJSONEncoder() Encoder

NewGoJSONEncoder returns a new Go JSON encoder for RediGo.

func NewGobEncoder

func NewGobEncoder() Encoder

NewGobEncoder returns a new Gob encoder for RediGo.

func NewJSONEncoder

func NewJSONEncoder() Encoder

NewJSONEncoder returns a new Gob encoder for RediGo.

func NewMessagePackEncoder

func NewMessagePackEncoder() Encoder

NewMessagePackEncoder returns a new Message Pack encoder for RediGo.

type Options

type Options struct {
	// Expiration allows to specify a global expiration
	// time hen setting a value.
	Expiration time.Duration
	// Tags allows specifying associated tags to the
	// current value.
	Tags []string
}

Options represents the cache store available options when using Set().

type Store

type Store interface {
	// Ping pings the Redis cache to ensure its alive.
	Ping(context.Context) error
	// Get retrieves a specific item from the cache by key. Values are
	// automatically marshalled for use with Redis.
	Get(context.Context, string, any) error
	// Set stores a singular item in memory by key, value
	// and options (tags and expiration time). Values are automatically
	// marshalled for use with Redis & Memcache.
	Set(context.Context, string, any, Options) error
	// Delete removes a singular item from the cache by
	// a specific key.
	Delete(context.Context, string) error
	// Invalidate removes items from the cache via the tags passed.
	Invalidate(context.Context, []string)
	// Flush removes all items from the cache.
	Flush(context.Context)
	// Closer closes the client, releasing any open resources.
	io.Closer
}

Store defines methods for interacting with the caching system.