cache

type Distributed interface {
	KV
	// HSet 设置 Hash 字段。
	HSet(ctx context.Context, key string, field string, value any) error
	// HGet 读取 Hash 字段；未命中时返回 ErrMiss。
	HGet(ctx context.Context, key string, field string, dest any) error
	// HGetAll 获取整个 Hash；当前仅支持 *map[string]T 目标类型。
	HGetAll(ctx context.Context, key string, destMap any) error
	// HDel 删除一个或多个 Hash 字段。
	HDel(ctx context.Context, key string, fields ...string) error
	// HIncrBy 原子递增整数类型字段。
	HIncrBy(ctx context.Context, key string, field string, increment int64) (int64, error)
	// ZAdd 向有序集合中写入成员。
	ZAdd(ctx context.Context, key string, score float64, member any) error
	// ZRem 从有序集合中删除成员。
	ZRem(ctx context.Context, key string, members ...any) error
	// ZScore 返回成员分数；未命中时返回 ErrMiss。
	ZScore(ctx context.Context, key string, member any) (float64, error)
	// ZRange 按分数升序返回指定区间内成员。
	ZRange(ctx context.Context, key string, start, stop int64, destSlice any) error
	// ZRevRange 按分数降序返回指定区间内成员。
	ZRevRange(ctx context.Context, key string, start, stop int64, destSlice any) error
	// ZRangeByScore 返回指定分数区间内成员。
	ZRangeByScore(ctx context.Context, key string, min, max float64, destSlice any) error
	// MGet 批量读取多个 key；目标必须是切片指针。
	MGet(ctx context.Context, keys []string, destSlice any) error
	// MSet 批量设置多个 key-value。
	MSet(ctx context.Context, items map[string]any, ttl time.Duration) error
	// RawClient 返回底层客户端，用于 Pipeline、Lua 脚本等高级场景。
	RawClient() any
}

type DistributedConfig struct {
	// Driver 后端类型，目前仅支持 redis。
	Driver DistributedDriverType `json:"driver" yaml:"driver"`

	// KeyPrefix 全局 Key 前缀。
	KeyPrefix string `json:"key_prefix" yaml:"key_prefix"`

	// Serializer 序列化器类型："json" | "msgpack"。
	Serializer string `json:"serializer" yaml:"serializer"`

	// DefaultTTL 默认 TTL，当 Set 或 Expire 传入 ttl<=0 时使用。默认 24 小时。
	DefaultTTL time.Duration `json:"default_ttl" yaml:"default_ttl"`
}

type DistributedDriverType string

type KV interface {
	// Set 设置缓存值。
	Set(ctx context.Context, key string, value any, ttl time.Duration) error
	// Get 读取缓存值；未命中时返回 ErrMiss。
	Get(ctx context.Context, key string, dest any) error
	// Delete 删除缓存值。
	Delete(ctx context.Context, key string) error
	// Has 判断 key 是否存在。
	Has(ctx context.Context, key string) (bool, error)
	// Expire 更新 key 的 TTL；ttl<=0 时使用组件配置的 DefaultTTL；bool=false 表示 key 不存在。
	Expire(ctx context.Context, key string, ttl time.Duration) (bool, error)
	// Close 释放缓存实例拥有的资源。
	Close() error
}

type Local interface {
	KV
}

type LocalConfig struct {
	// Driver 后端类型，目前仅支持 otter。
	Driver LocalDriverType `json:"driver" yaml:"driver"`

	// MaxEntries 缓存最大条目数。
	MaxEntries int `json:"max_entries" yaml:"max_entries"`

	// Serializer 序列化器类型："json" | "msgpack"。
	Serializer string `json:"serializer" yaml:"serializer"`

	// DefaultTTL 默认 TTL，当 Set 或 Expire 传入 ttl<=0 时使用。默认 1 小时。
	DefaultTTL time.Duration `json:"default_ttl" yaml:"default_ttl"`
}

type LocalDriverType string

type Multi interface {
	KV
}

type MultiConfig struct {
	// LocalTTL 写入本地缓存时使用的 TTL。0 表示跟随写入 TTL。
	LocalTTL time.Duration `json:"local_ttl" yaml:"local_ttl"`

	// BackfillTTL 远程回填本地缓存时使用的 TTL，默认 1 分钟。
	BackfillTTL time.Duration `json:"backfill_ttl" yaml:"backfill_ttl"`

	// FailOpenOnLocalError 本地缓存异常时是否继续访问远程缓存。默认 true。
	// 使用指针以区分"未设置"（nil）和"显式设置为 false"。
	FailOpenOnLocalError *bool `json:"fail_open_on_local_error" yaml:"fail_open_on_local_error"`
}

type Option func(*options)