Documentation
¶
Overview ¶
Package dryrun observes cache behaviour for a set of repositories without actually caching. Each observed request has its cache key recorded in a shadow store with the same sliding TTL the real cache uses, so metrics accurately report the hit / miss / coalesce rate the caching path would have produced. All requests are transparently proxied to upstream and no packfiles are written to disk. The dry-run allowlist reuses allowlist.Allowlist; the middleware's "enabled" check is `list.Bounded() && list.Contains(repo)`.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var (
ErrFailedToCreateShadow = errors.New("failed to create dry-run shadow cache")
)
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// MaxEntries caps the number of keys the shadow tracks. Well over the
// real cache's own MaxEntries so shadow evictions never fire before the
// real cache's would; that way "would-hit" isn't an under-count.
MaxEntries int64
// MaxIdleAge mirrors the real cache's sliding TTL.
MaxIdleAge time.Duration
// OnEviction, if set, receives "ttl" or "size" for each eviction.
OnEviction func(reason string)
// OnEvictSize, if set, receives the evicted entry's repository and
// size on every eviction, so a per-repo size gauge can be decremented
// symmetrically with the AddDryRunShadowSizeBytes call made at Put time.
OnEvictSize func(repo string, size int64)
}
Config configures a Shadow.
type Entry ¶ added in v1.46.0
Entry is the value stored per shadow key. It carries just enough metadata to attribute an eviction back to its repository so a per-repo size gauge stays balanced.
type Shadow ¶
type Shadow struct {
// contains filtered or unexported fields
}
Shadow is a byte-free stand-in for the real cache. It tracks whether a cache key would currently be a hit, applying the same sliding TTL policy the real cache uses so hit-rate metrics reflect real eviction behaviour. The stored value carries the observed response size and owning repository so evictions can decrement a per-repo size gauge; no packfile bytes are ever written to disk.
func (*Shadow) Has ¶
Has reports whether the key is currently tracked. On a hit it also refreshes the entry's sliding TTL, matching the real cache's Get behaviour. The refresh is fire-and-forget: waiting for Ristretto's write buffer to drain would add latency to every hit on the request path, and eventual visibility of the refreshed TTL is fine because the next Has for the same key comes from a fresh HTTP request that takes far longer than the buffer flush.
func (*Shadow) Put ¶
Put records the key with the configured sliding TTL and the observed entry metadata (repo + size). Waits for the Ristretto write to be observable so a follow-up Has call in the same request path (or a concurrent second request that arrives while the leader is finishing) sees the entry.
Source Files