CacheStore

The CacheStore interface in comby provides an abstraction for managing cached data efficiently. It supports essential operations such as adding, retrieving, updating, and deleting cache entries, making it suitable for scenarios requiring quick access to frequently used data. The interface is designed for extensibility, allowing users to implement custom cache storage backends or use built-in ones.

Interface

The CacheStore interface provides methods for initialization, cache management (retrieval, storage, updating, deletion, and listing), metadata utilities (e.g., total count, store info), and state management (e.g., resetting the cache). It also offers insights into configuration settings and a string representation for debugging or logging.

type CacheStore interface {
	// Init initializes the cache store with the provided options.
	Init(ctx context.Context, opts ...CacheStoreOption) error

	// Get retrieves a cache entry by its key.
	Get(ctx context.Context, opts ...CacheStoreGetOption) (*CacheModel, error)

	// Set adds or updates a cache entry with the specified key and value.
	Set(ctx context.Context, opts ...CacheStoreSetOption) error

	// List retrieves a list of cache entries based on the provided options.
	List(ctx context.Context, opts ...CacheStoreListOption) ([]*CacheModel, int64, error)

	// Delete removes a cache entry by its key.
	Delete(ctx context.Context, opts ...CacheStoreDeleteOption) error

	// Total returns the total number of items in the cache.
	Total(ctx context.Context) int64

	// Close closes the cache store connection.
	Close(ctx context.Context) error

	// Options returns the configuration options of the cache store.
	Options() CacheStoreOptions

	// String returns a string representation of the cache store.
	String() string

	// Info provides detailed information about the cache store.
	Info(ctx context.Context) (*CacheStoreInfoModel, error)

	// Reset clears all cache entries.
	Reset(ctx context.Context) error
}

Model

The CacheModel represents individual cache entries and includes the following fields:

type CacheModel struct {
	Key       string `json:"key"`                 // Unique key for the cache entry.
	Value     any    `json:"value"`               // Value associated with the key.
	ExpiredAt int64  `json:"expiredAt,omitempty"` // Expiration time of the cache entry (optional).
}

Options and Methods

Init

The Init method sets up the cache store with specific configurations, such as custom read-only or logging preferences.

Options	Description
CacheStoreOptionWithReadOnly(readOnly bool)	Specifies whether the cache store is read-only.
CacheStoreOptionWithLogLevel(logLevel string)	Sets the logging level for the cache store.
CacheStoreOptionWithAttribute(key string, value any)	Sets custom attributes for the cache store.
CacheStoreOptionWithCryptoService(cryptoService *comby.CryptoService)	Sets the crypto service for encrypting and decrypting cache values in the cache store.

Get

The Get method retrieves cache entries using unique keys. Returns cache entry of model CacheModel.

Options	Description
CacheStoreGetOptionWithKey(key string)	Specifies the key of the cache entry to retrieve.
CacheStoreGetOptionWithAttribute(key string, value any)	Sets custom attributes for the Get option.

Set

The Set method adds new entries or updates existing ones with specified keys, values, and optional expiration times.

Options	Description
CacheStoreSetOptionWithKeyValue(key string, value any)	Specifies the key and value of the cache entry to add or update.
CacheStoreSetOptionWithExpiration(expiration time.Duration)	Sets the expiration time for the cache entry.
CacheStoreSetOptionWithAttribute(key string, value any)	Sets custom attributes for the Set object.

List

The List method supports paginated retrieval of multiple cache entries, with sorting and filtering options. Returns list of cache entries of model CacheModel.

Options	Description
CacheStoreListOptionWithTenantUuid(tenantUuid string)	Sets the tenant UUID for filtering cache entries.
CacheStoreListOptionOffset(offset int64)	Sets the offset for pagination.
CacheStoreListOptionLimit(limit int64)	Sets the limit for the number of cache entries to retrieve.
CacheStoreListOptionOrderBy(orderBy string)	Sets the field to order the cache entries by.
CacheStoreListOptionAscending(ascending bool)	Sets the sorting order (ascending or descending).
CacheStoreListOptionWithAttribute(key string, value any)	Sets custom attributes for the List object.

Delete

The Delete method removes cache entries based on their keys.

Options	Description
CacheStoreDeleteOptionWithKey(key string)	Specifies the key of the cache entry to delete.
CacheStoreDeleteOptionWithAttribute(key string, value any)	Sets custom attributes for the Delete object.

Total

Provides the total number of entries in the cache store.

Close

Closes the cache store connection.

Options

Returns the configuration settings of the cache store.

String

Returns a string representation of the cache store.

Info

Provides detailed information about the cache store. Details are returned in the following structure:

type CacheStoreInfoModel struct {
	StoreType      string `json:"storeType"`      // Type of the cache store.
	NumItems       int64  `json:"numItems"`       // Number of items in the cache.
	ConnectionInfo string `json:"connectionInfo"` // Connection details of the cache store.
}

Reset

Clears all entries in the cache store.

Store Synchronization

Comby provides built-in synchronization capabilities to copy data between store instances. This is particularly useful for:

• Migration scenarios: Moving data from one storage backend to another (e.g., in-memory to Redis)
• Cache warm-up: Populating a new cache instance with existing data
• Backup and replication: Creating copies of store data for redundancy
• Multi-region deployment: Synchronizing data across different geographical locations

Synchronization Function

The SyncCacheStore function copies all cache entries from a source CacheStore to a destination CacheStore:

func SyncCacheStore(ctx context.Context, source, destination CacheStore, opts ...CacheStoreSyncOption) error

Synchronization Options

Option	Description
CacheStoreSyncOptionWithTenantUuid(tenantUuid string)	Filter cache entries to synchronize by tenant UUID.
CacheStoreSyncOptionWithProgressFunc(progressFunc func(copied, total int64))	Callback function for tracking synchronization progress.
CacheStoreSyncOptionWithSkipOnError(skip bool)	Continue synchronization even if individual entries fail to copy.
CacheStoreSyncOptionWithDryRun(dryRun bool)	Preview synchronization without making actual changes.

Usage Example

import redisStore "github.com/gradientzero/comby-store-redis"

// Create source and destination cache stores
sourceCache := comby.NewCacheStoreMemory(...)
destCache := redisStore.NewCacheStoreRedis(...)

// Initialize both stores (CacheStoreOptionWithCryptoService can be passed here if needed)
sourceCache.Init(ctx)
destCache.Init(ctx)

// Synchronize with progress reporting
err := comby.SyncCacheStore(ctx, sourceCache, destCache,
    comby.CacheStoreSyncOptionWithProgressFunc(func(copied, total int64) {
        fmt.Printf("Progress: %d/%d entries copied\n", copied, total)
    }),
    comby.CacheStoreSyncOptionWithSkipOnError(true),
)

Important Notes

• Expiration Preservation: The sync function preserves expiration times by calculating the remaining TTL (Time To Live) for each cache entry.
• Ephemeral Nature: Cache data is typically ephemeral and temporary. Synchronization is most useful for warm-up scenarios rather than long-term data persistence.
• No Resume Capability: Unlike EventStore and CommandStore, CacheStore synchronization does not support resumable operations, as cache data is not time-ordered.

Extensibility and Implementation

comby provides the following default implementations of the CacheStore interface:

• In-Memory Store: Useful for testing and development, offering fast and transient cache storage. Used by default if no specific store is configured.
• Redis Store: A distributed cache system that supports high-performance caching and data persistence. Ideal for production environments with large-scale caching requirements. Link: https://github.com/gradientzero/comby-store-redis

Users can implement the CacheStore interface to integrate with alternative storage systems, such as:

• Distributed caching systems (e.g., Memcached).
• Database-backed caching.
• Specialized file-based cache systems.

To create a custom cache store, implement all methods in the interface, adhering to the specified contracts for behavior and parameters.