resilicache

package module
v0.0.0-...-d0a8246 Latest Latest
Warning

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

 Go to latest Published: Aug 24, 2024 License: MIT Imports: 13 Imported by: 0

README

ResiliCache Go

ResiliCache Go is a robust and versatile caching package for Go, compatible with various caching systems, including Redis, RedisCluster, ValKey, KeyDB, DragonflyDB, and Kvrocks. It provides a comprehensive set of features to enhance the reliability and performance of your caching strategy.

Features

  • Eventual Consistency: Guarantees eventual consistency of cache data even under extreme conditions, ensuring that your application eventually reflects the most up-to-date information.

  • Strong Consistency: Offers strong consistency guarantees for cache access, making sure that your application always interacts with the most recent and reliable data.

  • Anti-Breakdown: Implements strategies to prevent cache breakdown, minimizing the risk of performance degradation during high traffic or system failures.

  • Anti-Penetration: Provides mechanisms to protect your cache from excessive load caused by cache penetration attacks, where requests bypass the cache and hit the database directly.

  • Anti-Avalanche: Uses techniques to prevent cache avalanches, which occur when many cache entries expire simultaneously, potentially overwhelming your backend systems.

  • Batch Query: Supports batch querying to efficiently handle multiple cache requests in a single operation, reducing the overhead and latency of individual cache accesses.

Installation

To install ResiliCache Go, use the following command:

go get github.com/driftdev/resilicache-go

Usage

Here's a basic examples of how to use ResiliCache Go.

package main

import (
	"context"
	"fmt"
	"github.com/driftdev/resilicache-go"
	"github.com/redis/go-redis/v9"
	"log"
	"time"
)

func main() {
	// Initialize Redis client
	rdb := redis.NewClient(&redis.Options{
		Addr:     "localhost:6379",
		Password: "",
		DB:       0,
	})

	// Flush the Redis database to start with a clean state
	if err := rdb.FlushDB(context.Background()).Err(); err != nil {
		log.Fatalf("Error flushing DB: %v", err)
	}

	// Initialize ResiliCache with Redis client and default options
	cache := resilicache.NewCache(rdb, resilicache.NewDefaultOptions())

	// Set a key-value pair in the cache with a TTL of 10 seconds
	err := cache.Set(context.Background(), "user:01J61BPPHMFH9VSF2T1R2ZXDA2", []byte("tester"), time.Second*10)
	if err != nil {
		log.Fatalf("Error setting key: %v", err)
	}

	// Retrieve the value for the key from the cache
	value, err := cache.Get(context.Background(), "user:01J61BPPHMFH9VSF2T1R2ZXDA2")
	if err != nil {
		log.Fatalf("Error getting key: %v", err)
	}
	if value == nil {
		log.Fatalf("Error: value not found")
	}
	fmt.Println("value: ", string(value))

	// Delete the key from the cache
	err = cache.Delete(context.Background(), "user:01J61BPPHMFH9VSF2T1R2ZXDA2")
	if err != nil {
		log.Fatalf("Error deleting key: %v", err)
	}

	// Fetch data for the key, caching it if it's not already present
	// If the key is not found in the cache, the provided function is called to get the data
	value, err = cache.FetchSingle(context.Background(), "user:01J61BPPHMFH9VSF2T1R2ZXDA2", time.Second*10, func() ([]byte, error) {
		// Fetch data from an external source (e.g., database)
		return []byte("tester"), nil
	})
	if err != nil {
		log.Fatalf("Error fetching key: %v", err)
	}
	fmt.Println("value: ", string(value))

	// Mark the key as deleted, indicating it should not be retrieved from the cache.
	// After being marked, the key is permanently deleted with a delay.
	err = cache.TagAsDeletedSingle(context.Background(), "user:01J61BPPHMFH9VSF2T1R2ZXDA2")
	if err != nil {
		log.Fatalf("Error tagging key as deleted: %v", err)
	}

	// Fetch data for multiple keys, caching them if they are not already present
	// If any keys are not found in the cache, the provided function is called to get the data
	values, err := cache.FetchBatch(context.Background(),
		[]string{
			"user:01J61C9MEMNXYKWJXNQ3ERQA1F",
			"user:01J61CH3XEVGKHGK3GKA7XJGF9",
			"user:01J61CHNPXZ65T9EZ3RSHJJDKV",
		},
		time.Second*10,
		func(idxs []int) (map[int][]byte, error) {
			// Fetch data from an external source for each key (e.g., database)
			values := make(map[int][]byte)
			for _, i := range idxs {
				values[i] = []byte(fmt.Sprintf("tester_%d", i))
			}
			return values, nil
		},
	)
	if err != nil {
		log.Fatalf("Error fetching keys: %v", err)
	}
	for _, v := range values {
		fmt.Println("value: ", string(v))
	}

	// Mark multiple keys as deleted, indicating they should not be retrieved from the cache.
	// After being marked, these keys are permanently deleted with a delay.
	err = cache.TagAsDeletedBatch(context.Background(),
		[]string{
			"user:01J61C9MEMNXYKWJXNQ3ERQA1F",
			"user:01J61CH3XEVGKHGK3GKA7XJGF9",
			"user:01J61CHNPXZ65T9EZ3RSHJJDKV",
		},
	)
	if err != nil {
		log.Fatalf("Error tagging keys as deleted: %v", err)
	}
}

Here's a basic examples of how to use ResiliCache TypedCache. This leverages Go generics to enforce type safety, ensuring that only specified types are stored and retried.

package main

import (
	"context"
	"fmt"
	"github.com/driftdev/resilicache-go"
	"github.com/redis/go-redis/v9"
	"log"
	"time"
)

func main() {
	// Initialize Redis client
	rdb := redis.NewClient(&redis.Options{
		Addr:     "localhost:6379",
		Password: "",
		DB:       0,
	})

	// Flush the Redis database to start with a clean state
	if err := rdb.FlushDB(context.Background()).Err(); err != nil {
		log.Fatalf("Error flushing DB: %v", err)
	}

	// Initialize ResiliCache with Redis client and default options
	cache := resilicache.NewCache(rdb, resilicache.NewDefaultOptions())

	// Initialize a TypedCache instance with string as the value type
	// This enforces type safety, ensuring that only strings are stored and retrieved from the cache
	typedCache := resilicache.NewTypedCache[string](cache)

	// Set a key-value pair in the cache with a TTL of 10 seconds
	err := typedCache.Set(context.Background(), "user:01J61BPPHMFH9VSF2T1R2ZXDA2", "tester", time.Second*10)
	if err != nil {
		log.Fatalf("Error setting key: %v", err)
	}

	// Retrieve the value for the key from the cache
	// The retrieved value is already typed as a string
	value, err := typedCache.Get(context.Background(), "user:01J61BPPHMFH9VSF2T1R2ZXDA2")
	if err != nil {
		log.Fatalf("Error getting key: %v", err)
	}
	if value == "" {
		log.Fatalf("Error: value not found")
	}
	fmt.Println("value: ", value)

	// Delete the key from the cache
	err = typedCache.Delete(context.Background(), "user:01J61BPPHMFH9VSF2T1R2ZXDA2")
	if err != nil {
		log.Fatalf("Error deleting key: %v", err)
	}

	// Fetch data for the key, caching it if it's not already present
	// If the key is not found in the cache, the provided function is called to generate the data
	value, err = typedCache.FetchSingle(context.Background(), "user:01J61BPPHMFH9VSF2T1R2ZXDA2", time.Second*10, func() (string, error) {
		// Fetch or generate data (e.g., from a database)
		return "tester", nil
	})
	if err != nil {
		log.Fatalf("Error fetching key: %v", err)
	}
	fmt.Println("value: ", value)

	// Mark the key as deleted, so it should not be retrieved from the cache
	// The key is permanently deleted after a delay
	err = typedCache.TagAsDeletedSingle(context.Background(), "user:01J61BPPHMFH9VSF2T1R2ZXDA2")
	if err != nil {
		log.Fatalf("Error tagging key as deleted: %v", err)
	}

	// Fetch data for multiple keys, caching them if not already present
	// If any keys are missing from the cache, the provided function is called to generate the data
	values, err := typedCache.FetchBatch(context.Background(),
		[]string{
			"user:01J61C9MEMNXYKWJXNQ3ERQA1F",
			"user:01J61CH3XEVGKHGK3GKA7XJGF9",
			"user:01J61CHNPXZ65T9EZ3RSHJJDKV",
		},
		time.Second*10,
		func(idxs []int) (map[int]string, error) {
			// Fetch or generate data for each key (e.g., from a database)
			values := make(map[int]string)
			for _, i := range idxs {
				values[i] = fmt.Sprintf("tester_%d", i)
			}
			return values, nil
		},
	)
	if err != nil {
		log.Fatalf("Error fetching keys: %v", err)
	}
	for _, v := range values {
		fmt.Println("value: ", v)
	}

	// Mark multiple keys as deleted, so they should not be retrieved from the cache
	// The keys are permanently deleted after a delay
	err = typedCache.TagAsDeletedBatch(context.Background(),
		[]string{
			"user:01J61C9MEMNXYKWJXNQ3ERQA1F",
			"user:01J61CH3XEVGKHGK3GKA7XJGF9",
			"user:01J61CHNPXZ65T9EZ3RSHJJDKV",
		},
	)
	if err != nil {
		log.Fatalf("Error tagging keys as deleted: %v", err)
	}
}

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Cache 

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

Cache is a struct that represents a caching system utilizing a Redis client. It encapsulates the redis.UniversalClient, cache configuration Options, and a singleflight.Group for managing duplicate requests.

func NewCache 

func NewCache(cache redis.UniversalClient, options Options) *Cache

NewCache creates a new Cache instance with the provided Redis client and options. It initializes the Cache struct with the given Redis client and options, ensuring that critical fields such as Delay and LockExpire have valid (non-zero) values.

Parameters:

  • cache: A Redis client that implements the redis.UniversalClient interface, used to perform cache operations.
  • options: An Options struct that holds various cache configuration settings. If Delay or LockExpire is set to 0, the function will log a fatal error and terminate, advising to use NewDefaultOptions() to get default values for these fields.

Returns: - *Cache: A pointer to the newly created Cache instance.

Usage: To create a new cache instance, first configure the Options using either NewDefaultOptions() or by specifying custom values. Then, pass the Redis client and the options to NewCache:

Example: 

opts := NewDefaultOptions()
redisClient := redis.NewUniversalClient(...)
cache := NewCache(redisClient, opts)

If Delay or LockExpire is not properly set (i.e., is 0), the function will terminate with a fatal error, ensuring that these essential configuration values are provided.

func (*Cache) Delete 

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

Delete removes one or more keys from the cache. This method uses the Redis `DEL` command to delete the specified keys from the cache. If the operation fails, an error is returned.

Parameters:

  • ctx: The context to control cancellation and timeouts.
  • keys: A variadic parameter that allows passing one or more cache keys to delete.

Returns:

  • error: If the cache operation fails, an error is returned. Otherwise, it returns nil.

Example: 

err := Delete(ctx, "user_01J4YHWG45SC7VW684TZB2SZ7K", "user_01J4YJESQBVN1CPV9EPWJJFJ7V")
if err != nil {
    log.Fatalf("Failed to delete cache keys: %v", err)
} else {
    log.Println("Cache keys deleted successfully")
}

func (*Cache) FetchBatch 

func (c *Cache) FetchBatch(ctx context.Context, keys []string, expire time.Duration, fn func(idxs []int) (map[int][]byte, error)) (map[int][]byte, error)

FetchBatch retrieves multiple values from the cache, or if not present, computes them using the provided function `fn` and stores them in the cache. This method handles batch operations, allowing you to fetch or compute multiple values associated with the provided keys at once.

The method supports both strong and weak consistency modes, and the choice between them is controlled by the `Options.StrongConsistency` configuration. Additionally, cache reads can be disabled globally through the `Options.DisableCacheRead`.

The expiration time for the cache entry is adjusted using the configured `Options.Delay` and `Options.RandomExpireAdjustment` options to help mitigate issues like cache avalanches.

Parameters:

  • ctx: The context to control cancellation and timeouts.
  • keys: A slice of strings representing the unique identifiers for the cache entries (e.g., cache keys).
  • expire: The duration after which the cache entries will expire and be automatically deleted.
  • fn: A function that computes the values to be cached for the keys that are not already present in the cache. The function receives a slice of indexes corresponding to the keys that need to be computed and returns a map where the keys are the indexes from the input slice and the values are the computed byte slices.

Returns:

  • map[int][]byte: A map where the keys are the indexes of the input keys slice, and the values are the corresponding data retrieved from the cache or computed by the function `fn`.
  • error: If the cache operation or the function `fn` fails, an error is returned.

Example: 

// Define a function to compute the data for missing keys
fn := func(idxs []int) (map[int][]byte, error) {
    result := make(map[int][]byte)
    for _, idx := range idxs {
        data, err := fetchDataFromDatabase(keys[idx])
        if err != nil {
            return nil, err
        }
        result[idx] = data
    }
    return result, nil
}

// Fetch a batch of Data
batchData, err := FetchBatch(ctx, []string{"user_01J4YHWG45SC7VW684TZB2SZ7K", "user_01J4YJESQBVN1CPV9EPWJJFJ7V"}, 10*time.Minute, fn)
if err != nil {
    log.Fatalf("Failed to fetch batch data: %v", err)
}

for idx, val := range data {
    log.Printf("Fetched data for key[%d]: %s", idx, string(val))
}

func (*Cache) FetchSingle 

func (c *Cache) FetchSingle(ctx context.Context, key string, expire time.Duration, fn func() ([]byte, error)) ([]byte, error)

FetchSingle retrieves a value from the cache, or if not present, retrieves the value using the provided function `fn` and stores it in the cache. This method ensures that only one request for the given key is processed at a time (using the singleflight pattern) to avoid duplicate work.

The method supports both strong and weak consistency modes, and the choice between them is controlled by the `Options.StrongConsistency` configuration. Additionally, cache reads can be disabled globally through the `Options.DisableCacheRead`.

The expiration time for the cache entry is adjusted using the configured `Options.Delay` and `Options.RandomExpireAdjustment` options to help mitigate issues like cache avalanches.

Parameters:

  • ctx: The context to control cancellation and timeouts.
  • key: The unique identifier for the cache entry (e.g., cache key).
  • expire: The duration after which the cache entry will expire and be automatically deleted.
  • fn: A function that computes the value to be cached if it is not already present. This function is called only if the cache miss occurs or if the cache read is disabled.

Returns:

  • []byte: The data retrieved from the cache or computed by the function `fn`, represented as a slice of bytes.
  • error: If the cache operation or the function `fn` fails, an error is returned.

Example: 

data, err := FetchSingle(ctx, "user_01J4YHWG45SC7VW684TZB2SZ7K", 10*time.Minute, func() ([]byte, error) {
    // Simulate data retrieval, e.g., from a database
    return fetchDataFromDatabase("user_01J4YHWG45SC7VW684TZB2SZ7K")
})
if err != nil {
    log.Fatalf("Failed to fetch data: %v", err)
}

log.Printf("Fetched data: %s", string(data))

func (*Cache) Get 

func (c *Cache) Get(ctx context.Context, key string) ([]byte, error)

Get retrieves a value from the cache using the specified key. This method uses the Redis `GET` command to fetch the data stored under the given key. If the key exists, the stored value is returned as a slice of bytes. If the key does not exist (i.e., a cache miss), the method returns `nil` for both the value and the error.

Parameters:

  • ctx: The context to control cancellation and timeouts.
  • key: The unique identifier for the cache entry (e.g., cache key).

Returns:

  • []byte: The data retrieved from the cache, represented as a slice of bytes. If the key does not exist, `nil` is returned.
  • error: If the cache operation fails, an error is returned. Otherwise, it returns nil.

Example: 

dataBytes, err := Get(ctx, "user_01J4YHWG45SC7VW684TZB2SZ7K")
if err != nil {
    log.Fatalf("Failed to get cache: %v", err)
}
if data == nil {
    log.Println("Cache miss for key: user_01J4YHWG45SC7VW684TZB2SZ7K")
} else {
    log.Printf("Cache hit: %s", string(dataBytes))
}

func (*Cache) LockForUpdate 

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

LockForUpdate attempts to acquire a lock on a cache entry for a specific owner, allowing the owner to perform updates without interference. The lock is implemented using a Lua script that sets a lock with a very high expiration time (`math.Pow10(10)`).

If the lock is already held by another owner, the method returns an error indicating the key is locked by someone else.

Parameters:

  • ctx: The context to control cancellation and timeouts.
  • key: The unique identifier for the cache entry (e.g., the Redis key to be locked).
  • owner: A string representing the entity (e.g., a unique identifier) that requests the lock.

Returns:

  • error: If an error occurs during the locking process or if the lock is already held by another owner, it is returned.

Example: 

err := LockForUpdate(ctx, "user_01J4YHWG45SC7VW684TZB2SZ7K", "service_01J4ZXVMKDFTSZGYKT5FXAZAB4")
if err != nil {
    log.Fatalf("Failed to lock cache key: %v", err)
}
log.Println("Cache key locked for update")

func (*Cache) RawGet 

func (c *Cache) RawGet(ctx context.Context, key string) ([]byte, error)

RawGet directly retrieves the value of a specific cache entry from a Redis hash by its key. This method bypasses any locking mechanisms, meaning it can read data that might currently be locked for updates.

Warning: Use caution when using `RawGet`, as it does not respect any locks that may be in place on the cache entry. This could lead to reading stale or inconsistent data if another process is currently updating the value.

Parameters:

  • ctx: The context to control cancellation and timeouts.
  • key: The unique identifier for the cache entry (e.g., the Redis hash key).

Returns:

  • string: The value associated with the given key in the Redis hash.
  • error: If an error occurs during the retrieval process, it is returned.

Example: 

value, err := RawGet(ctx, "user_01J4YHWG45SC7VW684TZB2SZ7K")
if err != nil {
    log.Fatalf("Failed to retrieve cache key: %v", err)
}
log.Printf("Retrieved value: %s", value)

func (*Cache) RawSet 

func (c *Cache) RawSet(ctx context.Context, key string, value []byte, expire time.Duration) error

RawSet directly stores a value in a specific cache entry in a Redis hash and sets an expiration time for the entry. This method bypasses any locking mechanisms, meaning it can overwrite data that might currently be locked for updates.

Warning: Use caution when using `RawSet`, as it does not respect any locks that may be in place on the cache entry. This could lead to race conditions or overwriting data that is currently being updated by another process.

Parameters:

  • ctx: The context to control cancellation and timeouts.
  • key: The unique identifier for the cache entry (e.g., the Redis hash key).
  • value: The value to be stored in the "value" field of the Redis hash.
  • expire: The duration after which the cache entry will expire and be automatically deleted.

Returns:

  • error: If an error occurs during the storage or expiration process, it is returned.

Example: 

err := RawSet(ctx, "user_01J4YHWG45SC7VW684TZB2SZ7K", []byte("example_value"), 10*time.Minute)
if err != nil {
    log.Fatalf("Failed to set cache key: %v", err)
}
log.Println("Cache key set successfully")

func (*Cache) Set 

func (c *Cache) Set(ctx context.Context, key string, value []byte, expire time.Duration) error

Set stores a value in the cache under the specified key, with an associated expiration time. This method uses the Redis `SET` command to store the data, allowing it to expire after the given duration. If the operation fails, an error is returned.

Parameters:

  • ctx: The context to control cancellation and timeouts.
  • key: The unique identifier for the cache entry (e.g., cache key).
  • value: The data to be stored in the cache, represented as a slice of bytes.
  • expire: The duration after which the cache entry will expire and be automatically deleted.

Returns:

  • error: If the cache operation fails, an error is returned. Otherwise, it returns nil.

Example: 

err := Set(ctx, "user_01J4YHWG45SC7VW684TZB2SZ7K", []byte("example_value"), 10*time.Minute)
if err != nil {
    log.Fatalf("Failed to set cache: %v", err)
}

func (*Cache) TagAsDeletedBatch 

func (c *Cache) TagAsDeletedBatch(ctx context.Context, keys []string) error

TagAsDeletedBatch marks multiple cache entries as deleted by setting a delayed deletion in Redis. The actual deletion is performed using a Lua script that delays the removal by the duration specified in the `Options.Delay` field. This is useful for scenarios where you want to invalidate multiple cache entries without immediately removing them, allowing other systems to recognize the deletion and take appropriate action.

If cache deletion is disabled using `Options.DisableCacheDelete`, the method returns immediately without performing any operation.

The method also supports waiting for a specified number of replicas to acknowledge the operation using the Redis `WAIT` command, if `Options.WaitReplicas` is greater than 0. This ensures stronger consistency across distributed Redis instances.

Parameters:

  • ctx: The context to control cancellation and timeouts.
  • keys: A slice of strings representing the unique identifiers for the cache entries to be marked as deleted.

Returns:

  • error: If an error occurs during the execution of the Lua script, processing the `WAIT` command, or if the number of replicas acknowledging the operation is less than `WaitReplicas`, an error is returned. If cache deletion is disabled, it returns nil.

Example: 

err := cache.TagAsDeletedBatch(ctx, []string{"user_01J4YHWG45SC7VW684TZB2SZ7K", "user_01J4YJESQBVN1CPV9EPWJJFJ7V"})
if err != nil {
    log.Fatalf("Failed to tag cache keys as deleted: %v", err)
} else {
    log.Println("Cache keys tagged for delayed deletion successfully")
}

func (*Cache) TagAsDeletedSingle 

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

TagAsDeletedSingle marks a cache entry as deleted by setting a delayed deletion in Redis. The actual deletion is performed using a Lua script that delays the removal by the duration specified in the `Options.Delay` field. This is useful for scenarios where you want to invalidate a cache entry without immediately removing it, allowing other systems to recognize the deletion and take appropriate action.

If cache deletion is disabled using `Options.DisableCacheDelete`, the method returns immediately without performing any operation.

The method also supports waiting for a specified number of replicas to acknowledge the operation using the Redis `WAIT` command, if `Options.WaitReplicas` is greater than 0. This ensures stronger consistency across distributed Redis instances.

Parameters:

  • ctx: The context to control cancellation and timeouts.
  • key: The unique identifier for the cache entry to be marked as deleted.

Returns:

  • error: If an error occurs during the execution of the Lua script, processing the `WAIT` command, or if the number of replicas acknowledging the operation is less than `Options.WaitReplicas`, an error is returned. If cache deletion is disabled, it returns nil.

Example: 

err := TagAsDeletedSingle(ctx, "user_01J4YHWG45SC7VW684TZB2SZ7K")
if err != nil {
    log.Fatalf("Failed to tag cache key as deleted: %v", err)
} else {
    log.Println("Cache key tagged for delayed deletion successfully")
}

func (*Cache) UnlockForUpdate 

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

UnlockForUpdate releases a lock on a cache entry for a specific owner, allowing other entities to acquire the lock. The lock is removed using a Lua script that checks the ownership and then releases the lock if the owner matches.

Parameters:

  • ctx: The context to control cancellation and timeouts.
  • key: The unique identifier for the cache entry (e.g., the Redis key to be unlocked).
  • owner: A string representing the entity (e.g., a unique identifier) that currently holds the lock.

Returns:

  • error: If an error occurs during the unlocking process, it is returned.

Example: 

err := UnlockForUpdate(ctx, "user_01J4YHWG45SC7VW684TZB2SZ7K", "service_01J4ZXVMKDFTSZGYKT5FXAZAB4")
if err != nil {
    log.Fatalf("Failed to unlock cache key: %v", err)
}
log.Println("Cache key unlocked for update")

type Options 

type Options struct {
	// Delay is the delay delete time for keys that are tag deleted. default is 10s
	Delay time.Duration
	// EmptyExpire is the expiry time for empty result. default is 60s
	EmptyExpire time.Duration
	// LockExpire is the expiry time for the lock which is allocated when updating cache. default is 3s
	// should be set to the max of the underling data calculating time.
	LockExpire time.Duration
	// LockSleep is the sleep interval time if try lock failed. default is 100ms
	LockSleep time.Duration
	// WaitReplicas is the number of replicas to wait for. default is 0
	// if WaitReplicas is > 0, it will use redis WAIT command to wait for TagAsDeleted synchronized.
	WaitReplicas int
	// WaitReplicasTimeout is the number of replicas to wait for. default is 3000ms
	// if WaitReplicas is > 0, WaitReplicasTimeout is the timeout for WAIT command.
	WaitReplicasTimeout time.Duration
	// RandomExpireAdjustment is the random adjustment for the expiry time. default 0.1
	// if the expiry time is set to 600s, and this value is set to 0.1, then the actual expire time will be 540s - 600s
	// solve the problem of cache avalanche.
	RandomExpireAdjustment float64
	// CacheReadDisabled is the flag to disable read cache. default is false
	// when redis is down, set this flat to downgrade.
	DisableCacheRead bool
	// CacheDeleteDisabled is the flag to disable delete cache. default is false
	// when redis is down, set this flat to downgrade.
	DisableCacheDelete bool
	// StrongConsistency is the flag to enable strong consistency. default is false
	// if enabled, the Fetch result will be consistent with the db result, but performance is bad.
	StrongConsistency bool
}

Options holds the configuration settings for the Cache.

func NewDefaultOptions 

func NewDefaultOptions() Options

NewDefaultOptions returns an Options struct initialized with default values for cache configuration settings. The default values are designed to provide a balanced configuration for typical caching scenarios. Each field in the Options struct is set to a default value, as documented below:

Defaults:

  • Delay: The time to delay the deletion of keys that are marked as deleted (tag deleted). Default is 10 seconds.

  • EmptyExpire: The expiration time for empty cache results (e.g., when a cache miss occurs and an empty result is cached). Default is 60 seconds.

  • LockExpire: The duration that a cache lock is held when updating the cache. This should be set to the maximum time it takes to compute the underlying data. Default is 3 seconds.

  • LockSleep: The interval to sleep between retry attempts if acquiring a cache lock fails. Default is 100 milliseconds.

  • RandomExpireAdjustment: The random adjustment factor for cache expiry times. For example, if the expiry time is set to 600 seconds and this value is set to 0.1, the actual expiry time will be between 540 seconds and 600 seconds. This helps mitigate cache avalanche issues. Default is 0.1 (i.e., 10% adjustment).

  • WaitReplicasTimeout: The maximum time to wait for replicas to synchronize when using the Redis WAIT command if WaitReplicas is greater than 0. Default is 3000 milliseconds (3 seconds).

type TypedCache 

type TypedCache[T any] struct {
	// contains filtered or unexported fields
}

TypedCache is a generic wrapper around the Cache struct, allowing strongly-typed cache operations. It provides a type-safe way to store and retrieve values in the cache by leveraging Go's generics.

This wrapper simplifies the process of storing and retrieving typed values by handling JSON serialization and deserialization internally. It delegates the actual caching operations to an underlying Cache instance.

Type Parameters:

  • T: The type of the values that will be cached.

func NewTypedCache 

func NewTypedCache[T any](cache *Cache) *TypedCache[T]

NewTypedCache creates a new instance of TypedCache for the specified type `T`. It initializes the TypedCache with the provided Cache instance, allowing for type-safe caching operations.

Parameters:

  • cache: A pointer to the Cache instance that will handle the underlying cache operations.

Type Parameters:

  • T: The type of the values that will be cached.

Returns:

  • *TypedCache[T]: A pointer to the newly created TypedCache instance.

This function is typically used to create a TypedCache for a specific type: Example: 

cache := NewCache(redisClient, opts)
typedCache := NewTypedCache[string](cache)

func (*TypedCache[T]) Delete 

func (tc *TypedCache[T]) Delete(ctx context.Context, key string) error

Delete removes a typed value from the cache using the specified key.

Parameters:

  • ctx: The context to control cancellation and timeouts.
  • key: The unique identifier for the cache entry to be deleted (e.g., cache key).

Returns:

  • error: If the cache operation fails, an error is returned. Otherwise, it returns nil.

Example: To delete a value from the cache: 

err := Delete(ctx, "user_01J4YHWG45SC7VW684TZB2SZ7K")
if err != nil {
    log.Fatalf("Failed to delete cache key: %v", err)
}

func (*TypedCache[T]) FetchBatch 

func (tc *TypedCache[T]) FetchBatch(ctx context.Context, keys []string, expire time.Duration, fn func(idxs []int) (map[int]T, error)) (map[int]T, error)

FetchBatch retrieves multiple typed values from the cache using the specified keys. If some keys are not found, the provided function `fn` is called to generate the missing values, which are then stored in the cache then returned. This method deserializes the values to defined type on retrieval.

Parameters:

  • ctx: The context to control cancellation and timeouts.
  • keys: A slice of unique identifiers for the cache entries.
  • expire: The duration after which the cache entries will expire.
  • fn: A function that returns a map of missing index positions to their corresponding values to be cached.

Returns:

  • map[int]T: A map of index positions to the typed values retrieved from or stored in the cache.
  • error: If the cache operation, serialization, or deserialization fails, an error is returned.

Example: To fetch or generate multiple string values: 

values, err := FetchBatch(ctx, []string{"key1", "key2"}, 10*time.Minute, func(idxs []int) (map[int]string, error) {
    return map[int]string{
        indexes[0]: "generated_value1",
        indexes[1]: "generated_value2",
    }, nil
})
if err != nil {
    log.Fatalf("Failed to fetch batch cache: %v", err)
}
log.Printf("Fetched or generated values: %v", values)

func (*TypedCache[T]) FetchSingle 

func (tc *TypedCache[T]) FetchSingle(ctx context.Context, key string, expire time.Duration, fn func() (T, error)) (T, error)

FetchSingle retrieves a typed value from the cache using the specified key. If the key is not found, the provided function `fn` is called to generate the value, which is then stored in the cache then returned. This method deserializes the value to defined type on retrieval.

Parameters:

  • ctx: The context to control cancellation and timeouts.
  • key: The unique identifier for the cache entry.
  • expire: The duration after which the cache entry will expire.
  • fn: A function that returns the value to be cached if it is not already present.

Returns:

  • T: The typed value retrieved from or stored in the cache.
  • error: If the cache operation, serialization, or deserialization fails, an error is returned.

Example: To fetch or generate a string value: 

value, err := FetchSingle(ctx, "user_01J4YHWG45SC7VW684TZB2SZ7K", 10*time.Minute, func() (string, error) {
    return "generated_value", nil
})
if err != nil {
    log.Fatalf("Failed to fetch cache: %v", err)
}
log.Printf("Fetched or generated value: %s", value)

func (*TypedCache[T]) Get 

func (tc *TypedCache[T]) Get(ctx context.Context, key string) (T, error)

Get retrieves a typed value from the cache using the specified key. This method deserializes the value to defined type on retrieval.

Parameters:

  • ctx: The context to control cancellation and timeouts.
  • key: The unique identifier for the cache entry (e.g., cache key).

Returns:

  • T: The typed value retrieved from the cache. If the key does not exist, a zero value for the type `T` is returned.
  • error: If the cache operation or deserialization fails, an error is returned. Otherwise, it returns nil.

Example: To retrieve a string value from the cache: 

value, err := Get(ctx, "user_01J4YHWG45SC7VW684TZB2SZ7K")
if err != nil {
    log.Fatalf("Failed to get cache: %v", err)
}
log.Printf("Fetched value: %s", value)

func (*TypedCache[T]) LockForUpdate 

func (tc *TypedCache[T]) LockForUpdate(ctx context.Context, key string, owner string) error

LockForUpdate locks a cache entry for update, ensuring that only one operation can modify the entry at a time. The lock is associated with a specific owner, which must be provided to unlock the entry later.

Parameters:

  • ctx: The context to control cancellation and timeouts.
  • key: The unique identifier for the cache entry to be locked.
  • owner: The owner of the lock, used to identify the locking operation.

Returns:

  • error: If the cache operation fails, an error is returned.

Example: To lock a cache entry for update: 

err := LockForUpdate(ctx, "user_01J4YHWG45SC7VW684TZB2SZ7K", "service_01J4ZXVMKDFTSZGYKT5FXAZAB4")
if err != nil {
    log.Fatalf("Failed to lock cache key for update: %v", err)
}

func (*TypedCache[T]) RawGet 

func (tc *TypedCache[T]) RawGet(ctx context.Context, key string) (T, error)

RawGet retrieves a typed value from the cache using the specified key, without any additional logic. This method deserializes the values to defined type on retrieval.

Warning: Use caution when using `RawGet`, as it does not respect any locks that may be in place on the cache entry. This could lead to reading stale or inconsistent data if another process is currently updating the value.

Parameters:

  • ctx: The context to control cancellation and timeouts.
  • key: The unique identifier for the cache entry.

Returns:

  • T: The typed value retrieved from the cache. If the key does not exist, a zero value for the type `T` is returned.
  • error: If the cache operation or deserialization fails, an error is returned.

Example: To directly retrieve a string value: 

value, err := RawGet(ctx, "user_01J4YHWG45SC7VW684TZB2SZ7K")
if err != nil {
    log.Fatalf("Failed to get cache: %v", err)
}
log.Printf("Fetched value: %s", value)

func (*TypedCache[T]) RawSet 

func (tc *TypedCache[T]) RawSet(ctx context.Context, key string, value T, expire time.Duration) error

RawSet stores a typed value in the cache under the specified key, with an associated expiration time. This method directly serializes the value to JSON and stores it using the underlying Cache instance's RawSet method.

Warning: Use caution when using `RawSet`, as it does not respect any locks that may be in place on the cache entry. This could lead to race conditions or overwriting data that is currently being updated by another process.

Parameters:

  • ctx: The context to control cancellation and timeouts.
  • key: The unique identifier for the cache entry.
  • value: The typed value to be stored in the cache, which will be serialized to JSON.
  • expire: The duration after which the cache entry will expire and be automatically deleted.

Returns:

  • error: If the serialization or cache operation fails, an error is returned.

Example: To directly store a string value in the cache: 

err := RawSet(ctx, "user_01J4YHWG45SC7VW684TZB2SZ7K", "example_value", 10*time.Minute)
if err != nil {
    log.Fatalf("Failed to set cache: %v", err)
}

func (*TypedCache[T]) Set 

func (tc *TypedCache[T]) Set(ctx context.Context, key string, value T, expire time.Duration) error

Set stores a typed value in the cache under the specified key, with an associated expiration time. This method serializes the value to JSON before storing.

Parameters:

  • ctx: The context to control cancellation and timeouts.
  • key: The unique identifier for the cache entry (e.g., cache key).
  • value: The typed value to be stored in the cache, which will be serialized to JSON.
  • expire: The duration after which the cache entry will expire and be automatically deleted.

Returns:

  • error: If the serialization or cache operation fails, an error is returned. Otherwise, it returns nil.

Example: To store a string value in the cache: 

err := Set(ctx, "user_01J4YHWG45SC7VW684TZB2SZ7K", "example_value", 10*time.Minute)
if err != nil {
    log.Fatalf("Failed to set cache: %v", err)
}

func (*TypedCache[T]) TagAsDeletedBatch 

func (tc *TypedCache[T]) TagAsDeletedBatch(ctx context.Context, keys []string) error

TagAsDeletedBatch marks multiple cache entries as deleted for the given keys. This method does not remove the entries immediately but tags them as deleted for delayed deletion.

Parameters:

  • ctx: The context to control cancellation and timeouts.
  • keys: A slice of unique identifiers for the cache entries to be marked as deleted.

Returns:

  • error: If the cache operation fails, an error is returned.

Example: To mark multiple cache entries as deleted: 

err := TagAsDeletedBatch(ctx, []string{"key1", "key2"})
if err != nil {
    log.Fatalf("Failed to mark cache keys as deleted: %v", err)
}

func (*TypedCache[T]) TagAsDeletedSingle 

func (tc *TypedCache[T]) TagAsDeletedSingle(ctx context.Context, key string) error

TagAsDeletedSingle marks a single cache entry as deleted for the given key. This method does not remove the entry immediately but tags it as deleted for delayed deletion.

Parameters:

  • ctx: The context to control cancellation and timeouts.
  • key: The unique identifier for the cache entry to be marked as deleted.

Returns:

  • error: If the cache operation fails, an error is returned.

Example: To mark a cache entry as deleted: 

err := TagAsDeletedSingle(ctx, "user_01J4YHWG45SC7VW684TZB2SZ7K")
if err != nil {
    log.Fatalf("Failed to mark cache key as deleted: %v", err)
}

func (*TypedCache[T]) UnlockForUpdate 

func (tc *TypedCache[T]) UnlockForUpdate(ctx context.Context, key string, owner string) error

UnlockForUpdate unlocks a cache entry that was previously locked for update, allowing other operations to modify the entry. The owner of the lock must be provided to successfully unlock the entry.

Parameters:

  • ctx: The context to control cancellation and timeouts.
  • key: The unique identifier for the cache entry to be unlocked.
  • owner: The owner of the lock, which was used to lock the entry.

Returns:

  • error: If the cache operation fails, an error is returned.

Example: To unlock a cache entry after an update: 

err := UnlockForUpdate(ctx, "user_01J4YHWG45SC7VW684TZB2SZ7K", "service_01J4ZXVMKDFTSZGYKT5FXAZAB4")
if err != nil {
    log.Fatalf("Failed to unlock cache key after update: %v", err)
}

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.