cache

type CBORCodec[T any] struct{}

type Cache[T any] interface {
	Get(ctx context.Context, key string) (*T, error)
	// GetMany fetches multiple keys in as few round trips as possible.
	// Missing keys are omitted from the returned map, so a key's absence
	// from the result is a cache miss.
	GetMany(ctx context.Context, keys []string) (map[string]*T, error)
	Set(ctx context.Context, key string, value *T, opts ...WriteOption) error
	// SetIfPresent overwrites key only if it currently holds a value,
	// reporting ErrNotFound without writing when it does not. It is the
	// conditional half of Set, and it resolves WriteOptions the same way.
	//
	// It exists because "update what is there, and do not create it" is not
	// expressible as a read followed by a Set. Between those two calls the
	// entry can be deleted, and the Set then puts it back — which for a
	// caller whose deletes mean something (a revoked session, a released
	// claim) undoes the delete rather than losing a race harmlessly. This
	// is one operation and cannot be interleaved with one.
	//
	// It is not a compare-and-swap: it tests existence, not the value. A
	// caller that must not overwrite a *changed* value wants a lock — see
	// distributedlock — and the two compose, since this narrows what the
	// lock has to cover rather than replacing it.
	//
	// Providers that store nothing report ErrNotFound always, because
	// nothing is ever present in them. That makes a noop cache visibly
	// unable to serve a caller who needs this, which is the honest answer:
	// reporting success would claim a conditional write happened against a
	// store that holds no conditions.
	SetIfPresent(ctx context.Context, key string, value *T, opts ...WriteOption) error
	// SetMany stores multiple values at once. WriteOptions apply to the
	// whole batch: every item gets the same expiry resolution as a single
	// Set call would.
	SetMany(ctx context.Context, items map[string]*T, opts ...WriteOption) error
	Delete(ctx context.Context, key string) error
	// DeleteMany removes multiple keys in as few round trips as possible.
	// Keys that are already absent are not an error.
	DeleteMany(ctx context.Context, keys []string) error
	// DeleteByPrefix removes every entry whose key begins with prefix.
	// Providers on shared backing stores that have no configured
	// namespace reject an empty prefix with ErrNamespaceRequired, since
	// that would delete entries they cannot prove they own.
	DeleteByPrefix(ctx context.Context, prefix string) error
	// Flush removes every entry this cache owns. Providers whose backing
	// store may be shared (redis) require a configured namespace to know
	// what they own and return ErrNamespaceRequired without one;
	// providers that wholly own their store (memory) always succeed.
	Flush(ctx context.Context) error
	Ping(ctx context.Context) error
	// Close releases the resources the cache holds — a connection pool, a
	// background sweep — and is safe to call more than once. It does not
	// evict anything: entries in a shared backing store outlive the handle
	// that wrote them. After Close the cache must not be used again.
	Close() error
}

type Codec[T any] interface {
	Encode(value *T) ([]byte, error)
	Decode(data []byte) (*T, error)
}

type GobCodec[T any] struct{}

type WriteConfig struct {
	// Expiry holds the caller's requested expiry: zero for "use the
	// cache's default", NoExpiry (or any negative value) for "never
	// expire", or a positive duration.
	Expiry time.Duration
}

type WriteOption func(*WriteConfig)