zcache

README

zcache Package

Overview

The zcache package provides an abstraction layer over Redis, allowing easy integration of caching mechanisms into Go applications. It simplifies interacting with Redis by offering a common interface for various caching operations.

Table of Contents

1. Features
2. Installation
3. Usage
4. Configuration
5. Mocking Support

Features

• Unified Caching Interface: Offers a consistent API for common caching operations, abstracting the complexity of direct Redis interactions.
• Distributed Mutex Locks: Supports distributed synchronization using Redis-based mutex locks, crucial for concurrent operations.
• Extensibility: Easy to extend with additional methods for more Redis operations.
• Serialization and Deserialization: Automatically handles the conversion of Go data structures to and from Redis storage formats.
• Mocking for Testing: Includes mock implementations for easy unit testing without a live Redis instance.
• Connection Pool Management: Efficiently handles Redis connection pooling.
• Supported Operations: Includes a variety of caching operations like Set, Get, Delete, as well as more advanced operations like Incr, Decr, and others.

---

Installation

go get github.com/zondax/golem/pkg/zcache

---

Usage Remote cache - Redis

import (
    "github.com/zondax/golem/pkg/zcache"
    "context"
    "time"
)

func main() {
    config := zcache.RemoteConfig{Addr: "localhost:6379"}
    cache := zcache.NewRemoteCache(config)
    ctx := context.Background()

    // Set a value
    cache.Set(ctx, "key1", "value1", 10*time.Minute)

    // Get a value
    if value, err := cache.Get(ctx, "key1"); err == nil {
        fmt.Println("Retrieved value:", value)
    }

    // Delete a value
    cache.Delete(ctx, "key1")
}

Usage Local cache - BigCache

func main() {
    config := zcache.LocalConfig{Eviction: 12}
    cache, err := zcache.NewLocalCache(config)
    if err != nil {
        // Handle error
    }
    
    ctx := context.Background()
    
    cache.Set(ctx, "key1", "value1", 10*time.Minute)
    if value, err := cache.Get(ctx, "key1"); err == nil {
    fmt.Println("Retrieved value:", value)
    }
    cache.Delete(ctx, "key1")
}

---

Configuration

Configure zcache using the Config struct, which includes network settings, server address, timeouts, and other connection parameters. This struct allows you to customize the behavior of your cache and mutex instances to fit your application's needs.

type Config struct {
    Addr               string        // Redis server address
    Password           string        // Redis server password
    DB                 int           // Redis database
    DialTimeout        time.Duration // Timeout for connecting to Redis
    ReadTimeout        time.Duration // Timeout for reading from Redis
    WriteTimeout       time.Duration // Timeout for writing to Redis
    PoolSize           int           // Number of connections in the pool
    MinIdleConns       int           // Minimum number of idle connections
    IdleTimeout        time.Duration // Timeout for idle connections
}

---

Working with mutex

func main() {
    cache := zcache.NewCache(zcache.Config{Addr: "localhost:6379"})
    mutex := cache.NewMutex("mutex_name", 2*time.Minute)

    // Acquire lock
    if err := mutex.Lock(); err != nil {
        log.Fatalf("Failed to acquire mutex: %v", err)
    }

    // Perform operations under lock
    // ...

    // Release lock
    if ok, err := mutex.Unlock(); !ok || err != nil {
        log.Fatalf("Failed to release mutex: %v", err)
    }
}

---

Mocking support

Use MockZCache and MockZMutex for unit testing.

func TestCacheOperation(t *testing.T) {
    mockCache := new(zcache.MockZCache)
    mockCache.On("Get", mock.Anything, "key1").Return("value1", nil)
    // Use mockCache in your tests
}

func TestSomeFunctionWithMutex(t *testing.T) {
    mockMutex := new(zcache.MockZMutex)
    mockMutex.On("Lock").Return(nil)
    mockMutex.On("Unlock").Return(true, nil)
    mockMutex.On("Name").Return("myMutex")
    
    result, err := SomeFunctionThatUsesMutex(mockMutex)
    assert.NoError(t, err)
    assert.Equal(t, expectedResult, result)
    
    mockMutex.AssertExpectations(t)
}

Documentation

Index

• type LocalCache
  • func NewLocalCache(config *LocalConfig) (LocalCache, error)
• type LocalConfig
  • func (c *LocalConfig) ToBigCacheConfig() bigcache.Config
• type MockZCache
  • func (m *MockZCache) Decr(ctx context.Context, key string) (int64, error)
  • func (m *MockZCache) Delete(ctx context.Context, key string) error
  • func (m *MockZCache) Exists(ctx context.Context, keys ...string) (int64, error)
  • func (m *MockZCache) FlushAll(ctx context.Context) error
  • func (m *MockZCache) Get(ctx context.Context, key string, data interface{}) error
  • func (m *MockZCache) HGet(ctx context.Context, key, field string) (string, error)
  • func (m *MockZCache) HSet(ctx context.Context, key string, values ...interface{}) (int64, error)
  • func (m *MockZCache) Incr(ctx context.Context, key string) (int64, error)
  • func (m *MockZCache) LPush(ctx context.Context, key string, values ...interface{}) (int64, error)
  • func (m *MockZCache) RPush(ctx context.Context, key string, values ...interface{}) (int64, error)
  • func (m *MockZCache) SAdd(ctx context.Context, key string, members ...interface{}) (int64, error)
  • func (m *MockZCache) SMembers(ctx context.Context, key string) ([]string, error)
  • func (m *MockZCache) Set(ctx context.Context, key string, value interface{}, expiration time.Duration) error
• type MockZMutex
  • func (m *MockZMutex) Lock() error
  • func (m *MockZMutex) Name() string
  • func (m *MockZMutex) Unlock() (bool, error)
• type RemoteCache
  • func NewRemoteCache(config *RemoteConfig) (RemoteCache, error)
• type RemoteConfig
  • func (c *RemoteConfig) ToRedisConfig() *redis.Options
• type ZCache
• type ZMutex

Types

type LocalCache

type LocalCache interface {
	ZCache
}

func NewLocalCache

func NewLocalCache(config *LocalConfig) (LocalCache, error)

type LocalConfig

type LocalConfig struct {
	EvictionInSeconds int
}

func (*LocalConfig) ToBigCacheConfig

func (c *LocalConfig) ToBigCacheConfig() bigcache.Config

type MockZCache

type MockZCache struct {
	mock.Mock
}

func (*MockZCache) Decr

func (m *MockZCache) Decr(ctx context.Context, key string) (int64, error)

func (*MockZCache) Delete

func (m *MockZCache) Delete(ctx context.Context, key string) error

func (*MockZCache) Exists

func (m *MockZCache) Exists(ctx context.Context, keys ...string) (int64, error)

func (*MockZCache) FlushAll

func (m *MockZCache) FlushAll(ctx context.Context) error

func (*MockZCache) Get

func (m *MockZCache) Get(ctx context.Context, key string, data interface{}) error

func (*MockZCache) HGet

func (m *MockZCache) HGet(ctx context.Context, key, field string) (string, error)

func (*MockZCache) HSet

func (m *MockZCache) HSet(ctx context.Context, key string, values ...interface{}) (int64, error)

func (*MockZCache) Incr

func (m *MockZCache) Incr(ctx context.Context, key string) (int64, error)

func (*MockZCache) LPush

func (m *MockZCache) LPush(ctx context.Context, key string, values ...interface{}) (int64, error)

func (*MockZCache) RPush

func (m *MockZCache) RPush(ctx context.Context, key string, values ...interface{}) (int64, error)

func (*MockZCache) SAdd

func (m *MockZCache) SAdd(ctx context.Context, key string, members ...interface{}) (int64, error)

func (*MockZCache) SMembers

func (m *MockZCache) SMembers(ctx context.Context, key string) ([]string, error)

func (*MockZCache) Set

func (m *MockZCache) Set(ctx context.Context, key string, value interface{}, expiration time.Duration) error

type MockZMutex

type MockZMutex struct {
	mock.Mock
}

func (*MockZMutex) Lock

func (m *MockZMutex) Lock() error

func (*MockZMutex) Name

func (m *MockZMutex) Name() string

func (*MockZMutex) Unlock

func (m *MockZMutex) Unlock() (bool, error)

type RemoteCache

type RemoteCache interface {
	ZCache
	Incr(ctx context.Context, key string) (int64, error)
	Decr(ctx context.Context, key string) (int64, error)
	LPush(ctx context.Context, key string, values ...interface{}) (int64, error)
	RPush(ctx context.Context, key string, values ...interface{}) (int64, error)
	SMembers(ctx context.Context, key string) ([]string, error)
	SAdd(ctx context.Context, key string, members ...interface{}) (int64, error)
	HSet(ctx context.Context, key string, values ...interface{}) (int64, error)
	HGet(ctx context.Context, key, field string) (string, error)
	FlushAll(ctx context.Context) error
	Exists(ctx context.Context, keys ...string) (int64, error)
}

func NewRemoteCache

func NewRemoteCache(config *RemoteConfig) (RemoteCache, error)

type RemoteConfig

type RemoteConfig struct {
	Network            string
	Addr               string
	Password           string
	DB                 int
	DialTimeout        time.Duration
	ReadTimeout        time.Duration
	WriteTimeout       time.Duration
	PoolSize           int
	MinIdleConns       int
	MaxConnAge         time.Duration
	PoolTimeout        time.Duration
	IdleTimeout        time.Duration
	IdleCheckFrequency time.Duration
}

func (*RemoteConfig) ToRedisConfig

func (c *RemoteConfig) ToRedisConfig() *redis.Options

type ZCache

type ZCache interface {
	Set(ctx context.Context, key string, value interface{}, expiration time.Duration) error
	Get(ctx context.Context, key string, data interface{}) error
	Delete(ctx context.Context, key string) error
}

type ZMutex

type ZMutex interface {
	Lock() error
	Unlock() (bool, error)
	Name() string
}