cache

type Cache struct {
	// contains filtered or unexported fields
}

type DiskStorage struct {
	// contains filtered or unexported fields
}

type EntryWriter interface {
	io.Writer
	// Commit persists the streamed body with meta and admits it to the byte cap
	// (evicting LRU victims). A failure is fail-static: the entry is not cached.
	Commit(meta Meta) error
	// Abort discards the streamed body (e.g. truncated/over-cap/panicked fill).
	Abort()
}

type MemoryStorage struct {
	// contains filtered or unexported fields
}

type Meta struct {
	Status     int         `json:"status"`
	Header     http.Header `json:"header"`
	PrimaryHex string      `json:"primary"`        // primary key hash (host+method+scheme+uri)
	Host       string      `json:"host,omitempty"` // normalized host (lowercased, port-stripped); for out-of-band Range maintenance
	URI        string      `json:"uri,omitempty"`  // request-uri (path+query); for out-of-band Range maintenance
	Vary       []string    `json:"vary"`           // lowercased Vary header names
	Created    int64       `json:"created"`        // unix nanos
	FreshUntil int64       `json:"fresh"`          // unix nanos; entry is stale after this
	Size       int64       `json:"size"`           // body bytes (== eviction weight)
}

type Options struct {
	// InvalidatedAfter, when non-nil, is consulted on every cache hit to support
	// out-of-band invalidation (cache purge). It receives the request and the
	// stored entry's Meta and returns an invalidation epoch in unix nanos: a hit
	// whose Meta.Created is <= the returned epoch is treated as stale (reaped and
	// served as a miss), exactly like a passed FreshUntil. Return 0 (or any value
	// below the entry's Created) to keep the entry. It runs only on a hit, so it
	// costs nothing while the cache is idle; nil disables the check entirely (zero
	// overhead). The callee owns its own concurrency.
	InvalidatedAfter func(r *http.Request, m Meta) int64

	// MaxFileSize caps a cacheable response's body. A GET response larger than
	// this (by Content-Length, or mid-stream) is not cached but still served in
	// full. Defaults to 8 MiB when <= 0.
	MaxFileSize int64
}

type Storage interface {
	// Get returns the entry stored under key, or ok=false on a miss. A hit should
	// be counted as a recent use (LRU). The returned body must not be mutated by
	// the caller. Any internal error is reported as a miss (fail-static).
	Get(key string) (meta Meta, body []byte, ok bool)

	// Writer begins storing an entry under key. The caller streams the body to the
	// returned EntryWriter and then calls Commit (to persist) or Abort (to
	// discard). It returns an error if a writer can't be opened (then the entry is
	// simply not cached). The disk backend streams to a temp file so the body
	// never has to be buffered whole in RAM.
	Writer(key string) (EntryWriter, error)

	// Delete removes the entry under key (e.g. when the middleware finds it stale).
	Delete(key string)

	// Range calls fn for each currently-stored entry (key + its Meta), stopping
	// early if fn returns false. It is for out-of-band maintenance — e.g. a purge
	// reaper that physically deletes entries matching an external predicate — not
	// the serving path. Iteration order is unspecified, and the snapshot is
	// best-effort: fn may observe an entry that is concurrently deleted, and an
	// entry written during the walk may or may not be visited. fn MAY call
	// Delete(key) on this storage (a backend must not hold a lock across fn that
	// Delete would need). fn MUST NOT call Writer.
	Range(fn func(key string, m Meta) bool)
}