zcache

package
v0.19.1 Latest Latest
Warning

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

 Go to latest Published: Oct 29, 2024 License: Apache-2.0 Imports: 14 Imported by: 2

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

The LocalConfig for zcache not only allows you to specify a CleanupInterval that determines how often the expired keys cleanup process will run but also includes configurations for BatchSize and ThrottleTime to optimize the cleanup process. If CleanupInterval is not set, a default value of 12 hours will be used. Both BatchSize and ThrottleTime also have default values (200 and 1 second respectively) if not explicitly set. It's important to note that MetricServer is a mandatory configuration field in LocalConfig to facilitate the monitoring of cache operations and errors.

func main() {
    config := zcache.LocalConfig{
        // CleanupInterval is optional; if omitted, a default value of 12 hours will be used
        CleanupProcess:  CleanupProcess{
            Interval: 30 * time.Minute,
        },
        MetricServer:    metricServer,
    }
    
    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")
}

Usage Combined cache - Local and Remote

func main() {
    localConfig := zcache.LocalConfig{
        MetricServer:    metricServer, // Mandatory
    }
    remoteConfig := zcache.RemoteConfig{Addr: "localhost:6379"}
	config := zcache.CombinedConfig{Local: localConfig, Remote: remoteConfig, isRemoteBestEffort: false}
    cache, err := zcache.NewCombinedCache(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

Constants

View Source 
const KeySplitter = "/"

Variables

This section is empty.

Functions

This section is empty.

Types

type CacheItem added in v0.14.0 

type CacheItem struct {
	Value     []byte `json:"value"`
	ExpiresAt int64  `json:"expires_at"`
}

func NewCacheItem added in v0.14.0 

func NewCacheItem(value []byte, ttl time.Duration) CacheItem

func (CacheItem) IsExpired added in v0.14.0 

func (item CacheItem) IsExpired() bool

type CleanupProcess added in v0.17.1 

type CleanupProcess struct {
	Interval     time.Duration
	BatchSize    int
	ThrottleTime time.Duration
}

type CombinedCache added in v0.11.0 

type CombinedCache interface {
	ZCache
}

func NewCombinedCache added in v0.11.0 

func NewCombinedCache(combinedConfig *CombinedConfig) (CombinedCache, error)

type CombinedConfig added in v0.11.0 

type CombinedConfig struct {
	Local              *LocalConfig
	Remote             *RemoteConfig
	GlobalLogger       *logger.Logger
	GlobalPrefix       string
	GlobalMetricServer metrics.TaskMetrics
	GlobalStatsMetrics StatsMetrics
	IsRemoteBestEffort bool
}

type CustomZ added in v0.17.0 

type CustomZ struct {
	Score  float64
	Member interface{}
}

type LocalCache added in v0.10.1 

type LocalCache interface {
	ZCache
}

func NewLocalCache added in v0.10.1 

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

type LocalConfig added in v0.10.1 

type LocalConfig struct {
	Prefix         string
	Logger         *logger.Logger
	MetricServer   metrics.TaskMetrics
	StatsMetrics   StatsMetrics
	CleanupProcess CleanupProcess
}

func (*LocalConfig) ToBigCacheConfig added in v0.10.1 

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) Expire added in v0.17.0 

func (m *MockZCache) Expire(ctx context.Context, key string, ttl time.Duration) (bool, 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) GetStats added in v0.14.2 

func (m *MockZCache) GetStats() ZCacheStats

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) IsNotFoundError added in v0.14.2 

func (m *MockZCache) IsNotFoundError(err error) bool

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{}, ttl time.Duration) error

func (*MockZCache) SetupAndMonitorMetrics added in v0.14.2 

func (m *MockZCache) SetupAndMonitorMetrics(appName string, metricsServer metrics.TaskMetrics, updateInterval time.Duration) []error

func (*MockZCache) TTL added in v0.15.4 

func (m *MockZCache) TTL(ctx context.Context, key string) (time.Duration, error)

func (*MockZCache) ZIncrBy added in v0.17.0 

func (m *MockZCache) ZIncrBy(ctx context.Context, key string, member string, increment float64) (float64, error)

func (*MockZCache) ZRevRangeWithScores added in v0.17.0 

func (m *MockZCache) ZRevRangeWithScores(ctx context.Context, key string, start, stop int64) ([]CustomZ, 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 RedisStats added in v0.11.0 

type RedisStats struct {
	Pool *redis.PoolStats
}

type RemoteCache added in v0.10.1 

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)
	ZIncrBy(ctx context.Context, key string, member string, increment float64) (float64, error)
	ZRevRangeWithScores(ctx context.Context, key string, start, stop int64) ([]CustomZ, error)
	FlushAll(ctx context.Context) error
	Exists(ctx context.Context, keys ...string) (int64, error)
	Expire(ctx context.Context, key string, ttl time.Duration) (bool, error)
	TTL(ctx context.Context, key string) (time.Duration, error)
}

func NewRemoteCache added in v0.10.1 

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

type RemoteConfig added in v0.10.1 

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
	Prefix             string
	Logger             *logger.Logger
	MetricServer       metrics.TaskMetrics
	StatsMetrics       StatsMetrics
}

func (*RemoteConfig) ToRedisConfig added in v0.10.1 

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

type StatsMetrics added in v0.17.1 

type StatsMetrics struct {
	Enable         bool
	UpdateInterval time.Duration
}

type ZCache 

type ZCache interface {
	Set(ctx context.Context, key string, value interface{}, ttl time.Duration) error
	Get(ctx context.Context, key string, data interface{}) error
	Delete(ctx context.Context, key string) error
	GetStats() ZCacheStats
	IsNotFoundError(err error) bool
}

type ZCacheStats added in v0.11.0 

type ZCacheStats struct {
	Local  *bigcache.Stats
	Remote *RedisStats
}

type ZMutex 

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

Source Files

View all Source files

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.