cache

type Action = types.Action

type Cache interface {
	// Get retrieves a value from the cache.
	// Returns the value and true if found, nil and false otherwise.
	Get(ctx context.Context, key string) (any, bool)

	// Set stores a value in the cache and propagates it to other pods.
	// The value is stored in both local and remote storage, and other pods
	// receive the value directly to update their local caches.
	Set(ctx context.Context, key string, value any) error

	// SetWithInvalidate stores a value in the cache and invalidates it on other pods.
	// The value is stored in both local and remote storage, but other pods
	// only receive an invalidation event and must fetch from Redis if needed.
	SetWithInvalidate(ctx context.Context, key string, value any) error

	// Delete removes a value from the cache.
	// The value is removed from both local and remote storage.
	Delete(ctx context.Context, key string) error

	// Clear removes all values from the cache.
	Clear(ctx context.Context) error

	// Close closes the cache and releases all resources.
	Close() error

	// Stats returns cache statistics.
	Stats() Stats
}

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

type InvalidationEvent = types.InvalidationEvent

type JSONMarshaller struct{}

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

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

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

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

type LocalCache interface {
	// Get retrieves a value from the local cache.
	Get(key string) (any, bool)

	// Set stores a value in the local cache.
	Set(key string, value any, cost int64) bool

	// Delete removes a value from the local cache.
	Delete(key string)

	// Clear removes all values from the local cache.
	Clear()

	// Close closes the local cache.
	Close()

	// Metrics returns cache metrics.
	Metrics() LocalCacheMetrics
}

type LocalCacheConfig struct {
	// NumCounters is the number of counters for the cache (Ristretto only).
	// Recommended: 10 * MaxItems
	NumCounters int64

	// MaxCost is the maximum cost of items in the cache (Ristretto only).
	// Recommended: 1GB = 1 << 30
	MaxCost int64

	// BufferItems is the number of items to buffer before eviction (Ristretto only).
	// Recommended: 64
	BufferItems int64

	// IgnoreInternalCost ignores the internal cost of items (Ristretto only).
	IgnoreInternalCost bool

	// MaxSize is the maximum number of items in the cache (LRU only).
	MaxSize int
}

type LocalCacheFactory interface {
	// Create creates a new local cache instance.
	Create() (LocalCache, error)
}

type LocalCacheMetrics struct {
	Hits      int64
	Misses    int64
	Evictions int64
	Size      int64
}

type Logger interface {
	// Debug logs a debug message.
	Debug(msg string, args ...any)

	// Info logs an info message.
	Info(msg string, args ...any)

	// Warn logs a warning message.
	Warn(msg string, args ...any)

	// Error logs an error message.
	Error(msg string, args ...any)
}

type Marshaller interface {
	// Marshal serializes a value to bytes.
	Marshal(v any) ([]byte, error)

	// Unmarshal deserializes a value from bytes.
	Unmarshal(data []byte, v any) error
}

type NoOpLogger struct{}

type Options struct {
	// PodID is the unique identifier for this pod/instance.
	// Used to avoid self-invalidation in pub/sub.
	PodID string

	// LocalCacheConfig configures the local Ristretto cache.
	LocalCacheConfig LocalCacheConfig

	// LocalCacheFactory is the factory for creating local cache instances.
	// If nil, defaults to Ristretto factory.
	LocalCacheFactory LocalCacheFactory

	// RedisAddr is the Redis server address (e.g., "localhost:6379").
	RedisAddr string

	// RedisPassword is the optional Redis password.
	RedisPassword string

	// RedisDB is the Redis database number.
	RedisDB int

	// InvalidationChannel is the Redis pub/sub channel for cache invalidation.
	InvalidationChannel string

	// SerializationFormat specifies how values are serialized ("json" or "msgpack").
	SerializationFormat string

	// Marshaller is the marshaller for serialization.
	// If nil, defaults to JSON marshaller.
	Marshaller Marshaller

	// Logger is the logger for debug logging.
	// If nil, defaults to no-op logger.
	Logger Logger

	// DebugMode enables debug logging.
	DebugMode bool

	// ContextTimeout is the default timeout for cache operations.
	ContextTimeout time.Duration

	// EnableMetrics enables metrics collection.
	EnableMetrics bool

	// OnError is called when an error occurs in background operations.
	OnError func(error)

	// ReaderCanSetToRedis controls whether reader nodes are allowed to write data to Redis.
	// When false (default), reader nodes will only update local cache but NOT write to Redis.
	// When true, reader nodes can write data to Redis.
	// This prevents stale data from readers overwriting fresh data in Redis.
	ReaderCanSetToRedis bool

	// OnSetLocalCache is a callback for custom processing of data before storing in local cache.
	// This callback is invoked when an invalidation event with action "set" is received.
	// The callback receives the invalidation event and returns the value to store in local cache.
	// When nil (default), the default behavior is used: unmarshal the value and store in local cache.
	//
	// Use cases:
	// - Return raw bytes directly without unmarshaling for reader nodes that serve cached bytes
	// - Parse and transform event data into a pre-processed wrapper struct for zero-cost reads
	// - Extract structured metadata (hash, timestamp, data) from events for custom handling
	OnSetLocalCache func(event InvalidationEvent) any
}

type Stats struct {
	LocalHits     int64
	LocalMisses   int64
	RemoteHits    int64
	RemoteMisses  int64
	LocalSize     int64
	RemoteSize    int64
	Invalidations int64
}

type Store interface {
	// Get retrieves a value from the store.
	Get(ctx context.Context, key string) ([]byte, error)

	// Set stores a value in the store.
	Set(ctx context.Context, key string, value []byte) error

	// Delete removes a value from the store.
	Delete(ctx context.Context, key string) error

	// Clear removes all values from the store.
	Clear(ctx context.Context) error

	// Close closes the store connection.
	Close() error
}

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

type Synchronizer interface {
	// Subscribe starts listening for invalidation events.
	Subscribe(ctx context.Context) error

	// Publish publishes an invalidation event.
	Publish(ctx context.Context, event types.InvalidationEvent) error

	// OnInvalidate registers a callback for invalidation events.
	OnInvalidate(callback func(event types.InvalidationEvent))

	// Close closes the synchronizer.
	Close() error
}