cache

type Bound struct {
	Score     float64
	Inclusive bool
	// Inf selects an unbounded endpoint: -1 for -inf, +1 for +inf, 0 to use
	// Score.
	Inf int8
}

type Browser interface {
	Tree(ctx context.Context, req TreeRequest) (TreeResponse, error)
	Key(ctx context.Context, key string) (KeyDetail, error)
	Search(ctx context.Context, req SearchRequest) (SearchResponse, error)
	Stats(ctx context.Context) (Stats, error)
	DeleteKey(ctx context.Context, key string) (DeleteResponse, error)
	DeletePrefix(ctx context.Context, prefix string) (DeleteResponse, error)
}

type DeleteResponse struct {
	Deleted int64 `json:"deleted"`
}

type KeyDetail struct {
	Key        string `json:"key"`
	Type       string `json:"type"`
	TTLSeconds int64  `json:"ttlSeconds"`
	// Bytes is MEMORY USAGE when supported, otherwise omitted.
	Bytes int64 `json:"bytes,omitempty"`
	// Length is the full value length: STRLEN, HLEN, LLEN, SCARD or ZCARD.
	Length  int64             `json:"length"`
	Value   string            `json:"value,omitempty"`
	Fields  map[string]string `json:"fields,omitempty"`
	Items   []string          `json:"items,omitempty"`
	Members []ScoredMember    `json:"members,omitempty"`
	// Truncated is set when the returned value was capped (string bytes or
	// collection items); Length still reports the full size.
	Truncated bool `json:"truncated,omitempty"`
}

type ScoredMember struct {
	Member string  `json:"member"`
	Score  float64 `json:"score"`
}

type SearchRequest struct {
	Query string
	// Limit caps the number of returned keys. Zero uses the backend default.
	Limit int
}

type SearchResponse struct {
	Keys      []TreeNode `json:"keys"`
	Truncated bool       `json:"truncated,omitempty"`
}

type Stats struct {
	Keys int64 `json:"keys"`
	// KeysTruncated is set when Keys was counted by a capped scan (namespaced
	// keyspaces) and is therefore a lower bound.
	KeysTruncated    bool   `json:"keysTruncated,omitempty"`
	UsedMemoryBytes  int64  `json:"usedMemoryBytes,omitempty"`
	MaxMemoryBytes   int64  `json:"maxMemoryBytes,omitempty"`
	Hits             int64  `json:"hits,omitempty"`
	Misses           int64  `json:"misses,omitempty"`
	EvictedKeys      int64  `json:"evictedKeys,omitempty"`
	ExpiredKeys      int64  `json:"expiredKeys,omitempty"`
	ConnectedClients int64  `json:"connectedClients,omitempty"`
	Version          string `json:"version,omitempty"`
	UptimeSeconds    int64  `json:"uptimeSeconds,omitempty"`
	InfoError        string `json:"infoError,omitempty"`
}

type Store interface {
	// Set writes value at key. A ttl <= 0 persists the key with no expiry; a
	// positive ttl sets an expiry, replacing any existing one.
	Set(ctx context.Context, key string, value []byte, ttl time.Duration) error
	// Get returns the value at key, or ErrKeyNotFound if the key is absent or
	// expired. Any other error is transient (backend unavailable, decode, …) and
	// must be distinguishable from a genuine miss — callers prune index entries
	// only on ErrKeyNotFound.
	Get(ctx context.Context, key string) ([]byte, error)
	// Del removes key (of any type). Removing a missing key is not an error.
	Del(ctx context.Context, key string) error
	// Expire sets a ttl on an existing key of any type; it does not change the
	// value. A missing key is a no-op.
	Expire(ctx context.Context, key string, ttl time.Duration) error

	// ZAdd inserts or updates member with score in the sorted set at key. It
	// does not affect any TTL already set on the key.
	ZAdd(ctx context.Context, key string, score float64, member string) error
	// ZRem removes member from the sorted set at key.
	ZRem(ctx context.Context, key, member string) error
	// ZRevRange returns members ranked by score high→low over the inclusive rank
	// range [start, stop]; negative indices count from the end (Redis
	// semantics). Used for newest-first indexes.
	ZRevRange(ctx context.Context, key string, start, stop int64) ([]string, error)
	// ZRangeByScore returns members whose score falls within [lower, upper],
	// ascending by score.
	ZRangeByScore(ctx context.Context, key string, lower, upper Bound) ([]string, error)
	// ZRemRangeByScore removes members whose score falls within [lower, upper].
	ZRemRangeByScore(ctx context.Context, key string, lower, upper Bound) error
	// ZRemRangeByRank removes members in the inclusive rank range [start, stop],
	// ranked by score low→high; negative indices count from the end. Trimming a
	// sorted set to its newest N members is ZRemRangeByRank(key, 0, -(N+1)).
	ZRemRangeByRank(ctx context.Context, key string, start, stop int64) error
}

type TreeNode struct {
	// Name is the display segment: the next path segment for groups, the
	// remaining key tail for leaves.
	Name string `json:"name"`
	// Prefix is set on group nodes only: the full logical prefix including
	// the trailing separator, ready to feed back into TreeRequest.Prefix.
	Prefix string `json:"prefix,omitempty"`
	// Key is set on leaf nodes only: the full logical key.
	Key string `json:"key,omitempty"`
	// Keys is the total number of keys under this node (1 for a leaf).
	Keys int `json:"keys"`
	// Children is the number of distinct child segments under a group node.
	Children int `json:"children,omitempty"`
	// Type is the value type of a leaf: string|hash|list|set|zset|stream.
	Type string `json:"type,omitempty"`
	// TTLSeconds is the leaf's remaining TTL; -1 means no expiry.
	TTLSeconds int64 `json:"ttlSeconds,omitempty"`
	// Bytes is the MEMORY USAGE of the node when the server supports it: the
	// leaf's own size, or for a group the aggregated size of every key
	// beneath it.
	Bytes int64 `json:"bytes,omitempty"`
}

type TreeRequest struct {
	// Prefix is the logical prefix to expand, e.g. "tx:". Empty expands the
	// root. It must include the trailing separator when pointing at a group.
	Prefix string
	// MaxChildren caps the number of nodes returned for the level. Zero uses
	// the backend default.
	MaxChildren int
}

type TreeResponse struct {
	Prefix string     `json:"prefix"`
	Nodes  []TreeNode `json:"nodes"`
	// Keys is the total number of keys scanned under Prefix, including keys
	// rolled up into group nodes.
	Keys int `json:"keys"`
	// Truncated is set when the node list or the underlying scan hit a cap;
	// counts are then lower bounds.
	Truncated bool `json:"truncated,omitempty"`
	// BytesSupported reports whether per-key byte sizes were available
	// (MEMORY USAGE); when false every Bytes field is absent, not zero.
	BytesSupported bool `json:"bytesSupported"`
}