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 {
	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
	Tags       []string    `json:"tags,omitempty"` // surrogate keys from the response Cache-Tag header; for out-of-band tag-scoped Range maintenance
	Created    int64       `json:"created"`        // unix nanos
	FreshUntil int64       `json:"fresh"`          // unix nanos; entry is stale after this
	// StaleWhileRevalidate and StaleIfError are RFC 5861 windows in nanoseconds
	// PAST FreshUntil: within StaleWhileRevalidate a stale entry may be served
	// while it is revalidated in the background; within StaleIfError a stale entry
	// may be served when revalidation fails. 0 means the window is not offered.
	StaleWhileRevalidate int64 `json:"swr,omitempty"`
	StaleIfError         int64 `json:"sie,omitempty"`
	Size                 int64 `json:"size"` // body bytes (== eviction weight)
	Status               int   `json:"status"`
}

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

	// Cacheable, when non-nil, is called for each GET/HEAD request; returning false
	// excludes the request from the cache entirely (served straight from the origin,
	// untagged), exactly as if it were uncacheable. Use it to restrict caching to
	// vetted paths, or to refuse requests carrying headers an origin might reflect
	// into the body without declaring them in Vary (an unkeyed-input poisoning
	// vector — see the package doc). nil caches everything otherwise cacheable.
	Cacheable func(r *http.Request) bool

	// Override, when non-nil, may return a forced caching policy that overrides the
	// origin's Cache-Control — letting you cache an origin that sends no (or
	// unwanted) cache headers. It is called on each GET/HEAD fill with the request
	// and the origin's response status and headers (before the body), so the
	// decision can key on anything in the request (host, path, extension) AND the
	// response (Content-Type, Content-Length, status). Return nil to honor the
	// origin for that response (the default). header is a copy of the response
	// headers, so reading it is safe and mutating it has no effect.
	//
	// The forced policy is baked into the stored entry only, so the served
	// Cache-Control stays the origin's and does not propagate downstream. How far
	// the override reaches is set per request by Override.Mode; safety refusals
	// (see Override) still apply.
	//
	// It runs on every fill, including background stale-while-revalidate refreshes,
	// and is re-evaluated against the fresh response each time (so a response-shape
	// change can change the policy). Don't key on wall-clock or random state.
	// Changing the hook does not re-policy already-stored entries.
	//
	// Forcing trusts you to target cacheable paths: the cache key ignores the
	// request's Cookie/Authorization, so do not force per-user paths (see the
	// per-mode safety notes on OverrideMode). Cacheable returning false takes
	// precedence — an excluded request is never forced.
	Override func(r *http.Request, status int, header http.Header) *Override

	// OnResult, when non-nil, is called once per request the cache serves, after it
	// decides how it was served, with the request and a ResultInfo (the outcome —
	// HIT/MISS/STALE/STALE_ERROR/BYPASS — and, on a fill, its duration). It makes
	// the cache observable without changing behavior: see prom.Cache for Prometheus
	// metrics and cache.LogResult for a structured-log field, or compose your own
	// ResultFunc. It runs synchronously on the foreground serving path only, never
	// from the background stale-while-revalidate goroutine; a panic unwinding from
	// the origin handler during a fill is not reported. nil disables it (zero
	// overhead). The callee owns its own concurrency.
	OnResult ResultFunc

	// 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

	// LockTimeout bounds how long a concurrent miss (a "follower") waits for the
	// in-flight leader to populate the cache before giving up and fetching the
	// origin itself. The leader holds the fill lock for the WHOLE time it streams
	// the response to its own client and (on the disk backend) fsyncs the committed
	// entry, so a slow leader client or a saturated disk can hold followers for up
	// to this long before they fall back to the origin. Raise it to wait through a
	// slow fill (fewer origin fetches, higher follower latency); lower it to fail
	// fast (more origin fetches under load). Defaults to 2s when <= 0.
	LockTimeout time.Duration

	// RevalidateTimeout bounds a background stale-while-revalidate fetch (RFC
	// 5861): the detached request to the origin is cancelled after this long so a
	// hung origin can't pin the single-flight lock or leak a goroutine. It does
	// not apply to a normal (foreground) fill. Defaults to 30s when <= 0.
	RevalidateTimeout time.Duration

	// DefaultStaleWhileRevalidate and DefaultStaleIfError force RFC 5861 stale
	// serving for a cacheable response that does not carry the matching directive,
	// so an origin you don't control still gets stale-while-revalidate /
	// stale-if-error behavior. An explicit directive on the response wins; a
	// response marked must-revalidate / proxy-revalidate is never served stale,
	// regardless of these. Unlike injecting the directive with a headers
	// middleware, these stay private to this cache: the served Cache-Control is
	// the origin's, so the policy does not propagate to downstream clients/caches.
	// Zero (the default) forces nothing. Each is clamped to ~10y.
	DefaultStaleWhileRevalidate time.Duration
	DefaultStaleIfError         time.Duration

	// DecoupleFill, when true, stops a slow leader client (or a slow disk) from
	// holding the fill lock — and thus stalling waiting followers — while its response
	// streams to that client. It engages only when the fill is CONTENDED, i.e. at
	// least one follower is already blocked waiting for it (the stampede case
	// single-flight exists for); an uncontended fill has nothing to isolate and
	// streams to the client in lockstep with no added latency.
	//
	// When it engages, the cacheable body is read from the origin at origin speed —
	// the leader's client receives nothing until the fill is done — while it is
	// streamed to storage and also buffered in memory for the leader (so the leader's
	// response never depends on the stored entry, which may expire, be evicted, or be
	// purged). The entry is then committed, the fill lock released (waiting followers
	// immediately hit the cache), and only then is the leader's own client served from
	// the buffered body. This trades the leader's time-to-first-byte (it waits for the
	// whole fill) and an extra in-memory copy of the leader's body (bounded by
	// MaxFileSize, per in-flight decoupled fill) for follower isolation, and serves
	// the leader the sanitized response headers (hop-by-hop stripped, no Age) rather
	// than the raw origin headers. A handler that relies on incremental flushing is
	// unaffected (a Flush during a decoupled fill is ignored). When false (default),
	// the leader always streams in lockstep and holds the fill lock until that stream
	// and the commit finish (see LockTimeout).
	DecoupleFill bool
}

type Override struct {
	TTL                  time.Duration
	StaleWhileRevalidate time.Duration
	StaleIfError         time.Duration
	Mode                 OverrideMode
}

type OverrideMode int

type Result string

type ResultFunc func(r *http.Request, info ResultInfo)

type ResultInfo struct {
	// Result is the cache decision (HIT, MISS, STALE, STALE_ERROR, BYPASS).
	Result Result

	// FillDuration is how long the foreground origin fetch took, set only when this
	// request actually contacted the origin on the serving path: a MISS fill and a
	// stale-if-error revalidation attempt. It is zero for a HIT, for a
	// stale-while-revalidate STALE (served from cache; the background refresh runs
	// detached and is never reported), and for a BYPASS.
	FillDuration time.Duration
}

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 Meta (including its Header map
	// and Vary slice) must be independent of stored state — safe for the caller to
	// read or modify without affecting the cache; the returned body must not be
	// mutated. 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. The Meta passed to
	// fn is independent of stored state (see Get), so fn may freely read or modify
	// it. 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)
}