cache

type Config struct {
	// Provider specifies the cache provider: redis|memory
	Provider string `json:"provider" yaml:"provider"`
	// Redis holds the Redis connection settings when Provider is "redis".
	Redis *RedisConfig `json:"redis" yaml:"redis"`
}

type Provider interface {
	// Set stores v (JSON encoded, or raw for string/[]byte on Redis) under
	// key. ttl == 0 applies the provider default, KeepTTL disables expiry.
	Set(ctx context.Context, key string, v any, ttl time.Duration) error
	// Get decodes the value stored under key into v, which must be a
	// non-nil pointer. It returns ErrNotFound for a missing or expired key.
	Get(ctx context.Context, key string, v any) error
	// Delete removes the keys; missing keys are not an error.
	Delete(ctx context.Context, keys ...string) error
	// CleanExpired removes expired entries from the memory provider;
	// it is a no-op for Redis, which expires keys itself.
	CleanExpired(ctx context.Context)
	// Close closes the client, releasing any open resources. The memory
	// and Redis providers close their live subscriptions first, so a
	// pending ReceiveMessage returns ErrClosed and queued messages are
	// discarded; a Subscribe that runs during or after Close returns a
	// failed subscription that reports ErrClosed.
	// It is rare to Close a Client, as the Client is meant to be long-lived and shared between many goroutines.
	Close() error
	// Keys returns the unexpired keys, relative to the provider, that
	// match the Redis glob pattern ('*' and '?' also match '/'), which is
	// relative to the provider and cleaned like a key; the prefix matches
	// literally. Only keys that Get can read are listed, and the key ""
	// only for an empty pattern. The memory provider matches as Redis KEYS
	// does (ranges with bytes >= 0x80 compare unsigned).
	// It scans the whole keyspace and is meant for tests.
	Keys(ctx context.Context, pattern string) ([]string, error)

	// IsLocal returns true when the cache lives in this process only.
	IsLocal() bool

	// Publish sends message to every current subscriber of channel. It
	// never waits for a subscriber: a memory subscriber whose buffer of
	// 100 undelivered messages is full misses the message,
	// and a Redis subscriber is subject to the go-redis channel policy
	// (delivery waits up to one minute, then the message is dropped). A
	// Redis Publish also fails when ctx is done or the server is unreachable.
	Publish(ctx context.Context, channel, message string) error
	// Subscribe registers a subscriber for channel; call Close on the result
	// when done. A message published after Subscribe returns is delivered
	// to the new subscriber (Redis confirms the subscription with the
	// server before returning; the wait ends when ctx is done, returning
	// ctx.Err() through ReceiveMessage; otherwise connecting is bounded by
	// the go-redis dial timeout and the confirmation by 10 seconds).
	// Subscribe never returns nil: when the subscription could not be
	// established, or the provider is closed, the returned
	// Subscription reports the error from ReceiveMessage and its Close is
	// a no-op.
	Subscribe(ctx context.Context, channel string) Subscription
}

type RedisConfig struct {
	// Server is the redis:// or rediss:// URL.
	Server string `json:"server,omitempty" yaml:"server,omitempty"`
	// TTL is the expiry applied when Set is called with ttl == 0; default 1h.
	TTL time.Duration `json:"ttl,omitempty" yaml:"ttl,omitempty"`
	// ClientTLS describes the TLS certs used to connect to the cluster
	ClientTLS *gserver.TLSInfo `json:"client_tls,omitempty" yaml:"client_tls,omitempty"`
	// User is the ACL user name; only applied when Password is set.
	User string `json:"user,omitempty" yaml:"user,omitempty"`
	// Password overrides the credentials embedded in Server.
	Password string `json:"password,omitempty" yaml:"password,omitempty"`
}

type Subscription interface {
	// Close unregisters the subscription and releases its resources,
	// discarding buffered messages. It is idempotent, and it unblocks a
	// pending ReceiveMessage, which then returns ErrClosed. Closing the
	// provider closes its subscriptions; calling Close on them afterwards
	// is harmless. During an outage Close may wait for an
	// in-flight go-redis redial.
	Close() error
	// ReceiveMessage returns the next buffered message, or blocks until a
	// message arrives, ctx is done (returning ctx.Err()) or the
	// subscription is closed (returning ErrClosed). It returns promptly in
	// the last two cases and may be called from one goroutine at a time.
	// A Subscription that Subscribe could not establish returns the
	// subscribe error from every ReceiveMessage call. A Redis subscription
	// does not report connection loss: go-redis reconnects and resubscribes
	// in the background, and messages published meanwhile are lost.
	ReceiveMessage(ctx context.Context) (string, error)
}