cachecore

type BaseConfig struct {
	// DefaultTTL is used when an operation does not provide a positive TTL.
	DefaultTTL time.Duration
	// Prefix namespaces logical keys within a shared backend.
	Prefix string
	// Compression selects value compression when the constructing driver supports shaping.
	Compression CompressionCodec
	// MaxValueBytes limits value size; zero disables the limit and negative values are invalid.
	MaxValueBytes int
	// EncryptionKey enables AES-GCM value encryption when the constructing driver supports shaping.
	EncryptionKey []byte
}

type CacheEntry struct {
	// Key is the unprefixed logical cache key.
	Key string
	// SizeBytes is the stored value size reported by the backend.
	SizeBytes int
	// ExpiresAt is the Unix timestamp in milliseconds, or nil when unavailable or non-expiring.
	ExpiresAt *int64
}

type CompressionCodec string

type Driver string

type Inspector interface {
	Capabilities() InspectorCapabilities
	ListPage(ctx context.Context, opts ListPageOptions) (ListPageResult, error)
}

type InspectorCapabilities struct {
	// CanList reports whether the store can enumerate cache metadata.
	CanList bool
	// CanRead reports whether listed keys can be read through the Store contract.
	CanRead bool
	// CanDelete reports whether listed keys can be deleted through the Store contract.
	CanDelete bool
	// CanTTL reports whether entries include expiration metadata.
	CanTTL bool
}

type ListPageOptions struct {
	// Query filters entries by matching any part of the cache key.
	Query string
	// Prefix is retained as a backward-compatible alias for Query.
	Prefix string
	// Cursor is an opaque continuation value returned by a previous page.
	Cursor string
	// Limit bounds the page size; implementations normalize it to the supported range.
	Limit int
}

type ListPageResult struct {
	// Entries contains the current page in deterministic key order when the backend supports it.
	Entries []CacheEntry
	// NextCursor continues the listing when HasMore is true.
	NextCursor string
	// HasMore reports whether another page is available.
	HasMore bool
}

type Store interface {
	// Driver identifies the concrete backend.
	Driver() Driver
	// Ready verifies that the backend can serve operations.
	Ready(ctx context.Context) error
	// Get retrieves a value and distinguishes cache misses from backend errors.
	Get(ctx context.Context, key string) ([]byte, bool, error)
	// Set writes a value with the requested TTL.
	Set(ctx context.Context, key string, value []byte, ttl time.Duration) error
	// Add writes a value only when the key does not already exist.
	Add(ctx context.Context, key string, value []byte, ttl time.Duration) (bool, error)
	// Increment atomically adds delta to a numeric value when the backend supports its contract.
	Increment(ctx context.Context, key string, delta int64, ttl time.Duration) (int64, error)
	// Decrement atomically subtracts delta from a numeric value when the backend supports its contract.
	Decrement(ctx context.Context, key string, delta int64, ttl time.Duration) (int64, error)
	// Delete removes one key and succeeds when the key is absent.
	Delete(ctx context.Context, key string) error
	// DeleteMany removes the provided keys.
	DeleteMany(ctx context.Context, keys ...string) error
	// Flush removes all keys in the store's configured scope.
	Flush(ctx context.Context) error
}