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 CachePolicy struct {
	Decision StoreDecision

	// TTL is how long the router may keep it: s-maxage, else max-age, else
	// Expires, else the fallback, net of Age.
	TTL time.Duration
	// ClientTTL is how long a client may keep it: max-age, else Expires, net
	// of Age, never over TTL. Zero when SharedOnly.
	ClientTTL time.Duration
	// SharedOnly is a shareable response with no max-age or Expires: s-maxage,
	// or public on the fallback. Clients get no lifetime from it. Without
	// public a fallback lifetime stays a max-age, as s-maxage would grant
	// sharing.
	SharedOnly bool

	// Public is the response's own public directive.
	Public bool
	// Private is stored per user only: private, or a request with
	// Authorization the response did not allow to be shared.
	Private bool
}

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 []SurrogateKey
	// 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
	// Public is whether the response said public, so a hit says it only then.
	Public bool
	// SharedOnly is CachePolicy.SharedOnly: a hit gives a client no max-age of
	// its own. Stored and returned with the value.
	SharedOnly bool
	// ClientTTL is CachePolicy.ClientTTL: how long a client may keep the
	// entry, never over TTL. Like TTL, GetMany returns what is left of it.
	ClientTTL time.Duration
	// FetchedAt is when the fetch behind the item started. A store drops the
	// item if one of its tags was invalidated since. Not stored.
	FetchedAt time.Time
}

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
}

type StoreDecision uint8

type SurrogateKey struct {
	Value string
	Tier  SurrogateKeyTier
}

type SurrogateKeyTier uint8