client

type Client interface {
	// Get returns the value held at key. found distinguishes a missing key from
	// a key holding an empty value: both are legal, the server answers them
	// differently, and a client that conflates them is wrong in a way its
	// caller cannot detect.
	//
	// The returned slice is read-only: do not modify it, and copy it before
	// keeping it past the call that produced it. Nothing enforces that, and the
	// current implementation allocates a fresh slice per reply, so breaking it
	// costs nothing today. It is stated as a contract because it is the one the
	// storage engine on the other end of the wire already keeps — handing a
	// reader an internal view rather than a copy is what makes GET
	// allocation-free there (ADR-0013) — and because a caller who honors it is
	// a caller this SDK can later stop copying for.
	//
	// Retried when the client was built with WithRetries.
	Get(ctx context.Context, key string) (value []byte, found bool, err error)

	// GetString is Get for callers whose values are text. The string is a copy,
	// so the read-only contract on Get's slice does not apply to it.
	GetString(ctx context.Context, key string) (value string, found bool, err error)

	// Set stores a value, with an expiry when ttl is positive and none when it
	// is zero. A negative ttl is an error rather than an immediate expiry.
	//
	// A ttl that is a whole number of seconds goes out as SET ... EX, and
	// anything finer as SET ... PX, so a 500ms entry is a 500ms entry rather
	// than a rounded one.
	//
	// The value is copied onto the wire before Set returns, so the caller may
	// reuse its buffer immediately.
	//
	// Retried when the client was built with WithRetries: repeating SET with a
	// fixed value leaves the same key holding the same bytes. Only the expiry
	// drifts, by however long the retry took.
	Set(ctx context.Context, key string, value []byte, ttl time.Duration) error

	// SetString is Set for callers whose values are text.
	SetString(ctx context.Context, key, value string, ttl time.Duration) error

	// SetNX stores a value only if the key is free, reporting whether it did.
	//
	// Never retried. A retry that answers 0 cannot be told apart from a key
	// that was already there, so a caller who won the race would be told it
	// lost — which is the one answer SETNX exists to give.
	SetNX(ctx context.Context, key string, value []byte) (stored bool, err error)

	// Del removes keys and reports how many it removed. Removing a key that is
	// not there is not an error; it is a zero in the count.
	//
	// Never retried. Deleting twice is harmless, but the second reply is 0, so
	// a retried DEL reports that it removed nothing when it removed the key on
	// the attempt whose reply was lost.
	Del(ctx context.Context, keys ...string) (removed int64, err error)

	// Exists counts how many of the given keys are present, counting a repeated
	// key once per mention — which is what the server does, and what callers
	// written against Redis expect.
	Exists(ctx context.Context, keys ...string) (count int64, err error)

	// Expire attaches an expiry to an existing key, reporting whether it found
	// one. A ttl that is zero or negative deletes the key, which is what the
	// server does with EXPIRE and what a caller written against Redis expects;
	// a positive ttl under a second is rounded up to one second rather than
	// down to zero, so it expires shortly rather than immediately.
	Expire(ctx context.Context, key string, ttl time.Duration) (applied bool, err error)

	// TTL reports the remaining life of a key, rounded to whole seconds by the
	// server, or [TTLNoExpiry] for a key that will not expire, or [TTLNoKey]
	// for a key that is not there. Neither sentinel is an error.
	TTL(ctx context.Context, key string) (time.Duration, error)

	// Keys returns every key matching a glob. It walks the whole keyspace and
	// holds a connection for the length of the walk, blocking the server for
	// the same period; Scan is what production code should use.
	Keys(ctx context.Context, pattern string) ([]string, error)

	// Scan returns one page of the keyspace and the cursor for the next.
	// An empty match means every key; a count of zero leaves the page size to
	// the server. Start at ScanStart and stop when [ScanResult.Done] is true:
	// an empty page means nothing on its own, because count bounds the work a
	// page does rather than the keys it finds.
	//
	// Never retried, and the reason is also a constraint on the caller: a scan
	// cursor is scoped to the connection that issued it (ADR-0017), so a page
	// fetched over a different connection is answered with an invalid-cursor
	// error. The SDK does not yet pin a connection for the length of a walk,
	// so a multi-page scan over a pool larger than one connection is correct
	// only by luck. ISSUE-0023 tracks the iterator that will carry the
	// constraint for the caller; until it lands, walk the keyspace on a client
	// built with WithPoolSize(1), or use Keys on a keyspace small enough to
	// block on.
	Scan(ctx context.Context, cursor, match string, count int) (ScanResult, error)

	// Ping checks that the server is answering.
	Ping(ctx context.Context) error

	// Echo returns its argument, unchanged and byte for byte.
	Echo(ctx context.Context, message []byte) ([]byte, error)

	// Info returns the server's INFO text, optionally narrowed to sections.
	Info(ctx context.Context, sections ...string) (string, error)

	// DBSize returns the number of keys in the keyspace.
	DBSize(ctx context.Context) (int64, error)

	// Stats returns the server's counters.
	Stats(ctx context.Context) (Stats, error)

	// Do sends an arbitrary command. It is the escape hatch that keeps SDK
	// releases decoupled from server releases; typed methods are preferred
	// wherever one exists.
	//
	// Arguments are rendered as wire bytes: []byte and string are passed
	// through byte for byte, the integer and float types are formatted, bool
	// becomes 1 or 0, and time.Duration becomes whole seconds. Anything else is
	// refused rather than formatted with %v, because a struct that reached the
	// wire as its Go formatting would be stored and only noticed much later.
	//
	// Do is never retried, whatever WithRetries was asked for. The SDK does not
	// know what command it is carrying — INCRBY and SET look alike from here —
	// and a silently repeated write is worse than a surfaced error (FEAT-0028).
	// A caller who knows their command is safe to repeat can retry it in their
	// own loop, which is the difference between a decision made and one guessed
	// at.
	Do(ctx context.Context, args ...any) (Reply, error)

	// WithRetries returns a view of this client that retries idempotent calls
	// up to n additional times on a network or timeout failure — the two
	// categories [Retryable] reports true for. A protocol error, a server
	// error, an authentication failure and a canceled context are surfaced on
	// the first attempt. A negative n is read as zero.
	//
	// Attempts are spaced by the same full-jitter backoff a reconnect uses, so
	// the delay before retry n is drawn from [0, min(base·2ⁿ, max)); see
	// [WithBackoff]. When every attempt fails the caller hears the last
	// failure, with its category intact, rather than a synthetic "gave up".
	//
	// The returned client shares this one's pool, so closing either closes
	// both, and a single client can be used both ways at once. Retry is opt-in
	// per call site rather than global because only the caller knows whether
	// repeating a command is safe — and the SDK will not guess on their behalf.
	WithRetries(n int) Client

	// Close releases every pooled connection and makes every later call return
	// [ErrClosed]. It is idempotent, and it always reports nil. Connections
	// checked out when it runs are closed as they are returned.
	Close() error
}

type Error struct {
	// Category is one of the six sentinels above, or nil for a canceled call.
	Category error

	// Op is what was being attempted: a command name ("GET"), or a stage of
	// the connection's life ("dial", "handshake", "pool").
	Op string

	// Addr is the server the call was made against, when it is known.
	Addr string

	// Kind is the error kind a server reply carried — "ERR", "WRONGPASS",
	// "OOM", "NOPROTO". Empty for everything that did not come off the wire.
	Kind string

	// Message is the human-readable detail. For a server reply it is the
	// server's own text, kind included, verbatim.
	Message string

	// Err is the underlying cause, when there is one: a net.Error, an
	// os.ErrDeadlineExceeded, a context error. It is part of the Is/As chain.
	Err error
}

type Option func(*options) error

type Reply struct {
	// Type is the shape this reply arrived in, and it decides which of the
	// fields below carry anything.
	Type ReplyType

	// Str carries the bytes of a bulk string, the text of a status or error
	// reply, and the digits of a big number.
	Str []byte

	// Int carries an integer reply, and a boolean as 1 or 0.
	Int int64

	// Float carries a RESP3 double. Str holds the same value as the server
	// wrote it, for callers that must not round-trip through float64.
	Float float64

	// Kind is the error kind of an error reply — the first word, "ERR" or
	// "WRONGPASS" or "OOM" — with Str holding the whole line.
	Kind string

	// Arr holds the elements of an array, or the keys and values of a map
	// flattened into alternating pairs. Flattening is deliberate: RESP2 has no
	// map frame and renders one as exactly that array, so a caller reading
	// STATS sees the same thing from a RESP2 and a RESP3 server.
	Arr []Reply
}

type ReplyType uint8

type ScanResult struct {
	// Cursor is what to pass to the next Scan. The scan is finished when it is
	// ScanStart, and only then.
	Cursor string

	// Keys is this page. It may be empty on a page that is not the last.
	Keys []string
}

type Stats map[string]int64