kvstore

type Conditional interface {
	GetEntry(ctx context.Context, key string) (Entry, bool, error)
	PutIf(ctx context.Context, key string, value []byte, w Write) (Result, error)
	DeleteIf(ctx context.Context, key string, version string) (Result, error)
}

type Entry struct {
	Value []byte
	// Version names this write of the key, an opaque hash (Version): every write gives the key another, and a restore
	// another timeline, so a version from before a restore names nothing after it. Callers compare versions for
	// equality only.
	Version string
	// ExpiresAt is the Unix second from which the key no longer exists; 0 is never.
	ExpiresAt uint64
}

type KV interface {
	// Get returns the value for key and whether it exists. A missing key is
	// (nil, false, nil) — not an error.
	Get(ctx context.Context, key string) (value []byte, found bool, err error)
	// Put stores value under key (overwriting any existing value).
	Put(ctx context.Context, key string, value []byte) error
	// Delete removes key; deleting a missing key is a no-op (no error).
	Delete(ctx context.Context, key string) error
	// List returns the keys that start with prefix.
	List(ctx context.Context, prefix string) (keys []string, err error)
}

type Result struct {
	Done    bool
	Version string
}

type Sweeper interface {
	Sweep(ctx context.Context, now time.Time, limit int, skip func(key string) bool) (swept []string, more bool, err error)
}

type Usager interface {
	Usage(ctx context.Context, prefix string) (int64, error)
}

type Write struct {
	// IfAbsent writes only when the key does not exist; an expired key does not.
	IfAbsent bool
	// IfVersion, when not "", writes or deletes only when the key exists at this version.
	IfVersion string
	// TTL, when not 0, makes the key expire once it has lived TTL, rounded up to the second.
	TTL time.Duration
	// ExpiresAt, when not 0, is the expiry itself, for a copy that keeps a key's own; never with TTL.
	ExpiresAt uint64
}