caching

type Cache interface {
	// GetMany looks up every key and returns the ones it found, keyed by the
	// key they were asked for, with the SurrogateKeys they were stored with. A
	// miss is simply absent, never an error and never a zero Item.
	GetMany(ctx context.Context, keys []string) (map[string]Item, error)

	// SetMany stores every item, all of which must carry a positive TTL. When
	// items contains the same key twice, the last one wins. An error means an
	// unspecified subset of the items may already have been stored.
	// In case any of the passed ttls are invalid, SetMany should return
	// without saving any items that may have valid ttl values.
	SetMany(ctx context.Context, items []Item) error
}

type Digest [sha256.Size]byte

type Item struct {
	// Key is the key the entry is stored under, exactly as GetMany was asked
	// for it, so an Item carries enough to be acted on once it has been taken
	// out of the map it came in.
	Key string
	// Value is the cached bytes. An entry with an empty Value is still an
	// entry: GetMany omitting the key is the only thing that means a miss.
	Value []byte
	// TTL is how long the entry should live when passed to SetMany, and how
	// much of that life it has left when returned by GetMany, so the same key
	// comes back with less of it on every lookup. It is always positive in
	// both directions: SetMany refuses an item without a positive TTL, and
	// GetMany treats an entry with nothing left to live, or one it finds with
	// no expiry attached at all, as a miss rather than a hit.
	TTL time.Duration
	// Tags are the cache tags the entry was stored under, a secondary index
	// naming what the entry is about so it can later be found by something other
	// than its key for invalidation.
	Tags []string
	// Surrogate keys are what a client response carries so a CDN can purge by them.
	// Stored with the value and returned by GetMany.
	SurrogateKeys []string
	// Vary makes the entry a vary record rather than a body: the sets of
	// request headers responses at this key have varied on, newest first.
	// Each set's values select a variant stored under VariantKey. A record has
	// no Value and no SurrogateKeys.
	Vary [][]string
}

type SetManyError struct {
	// This depicts the known stored keys in a case of a partial write
	// this means that some more keys could have been written but there is no way to know
	// because the client did not receive a response
	KnownStoredKeys []string
	Err             error
}