README
¶
mod/cache
mod/cache is a bounded in-memory byte cache for small generated responses. It is used for metadata payloads and
HTML/API bodies where rebuilding is more expensive than storing a short byte slice. It is not used for large archives;
those are served from storage hot files.
Place in the runtime
flowchart TB
handler["server handler"] --> key["cache key"]
key --> cache["mod/cache"]
cache --> hit["cached bytes"]
cache --> miss["builder callback"]
miss --> cache
Responsibilities
- Store immutable byte slices under caller-defined keys.
- Bound memory use by total byte size.
- Evict least-recently-used entries when the budget is exceeded.
- Expose low-cardinality counters for hits, misses, inserts, evictions, and bytes.
- Keep cache policy separate from the domain builders that produce the bytes.
Contracts
- Callers must include all freshness inputs in the key or surrounding ETag logic.
- Values are copied before storage so later caller mutation cannot corrupt cached bytes.
- The cache is process-local and disposable. Durable state belongs in
mod/storage. - Detached cache builds share
cache.build_max_parallelwith the server typed-object cache. - This package does not know HTTP semantics;
Cache-Control,ETag, andIf-None-Matchare handled inmod/server.
Important files
obj.go: cache object, configuration, entry accounting.cache.go: get, set, and build operations.shard.go: shard-local LRU maintenance.metrics.go: telemetry producer for cache metrics.gate.go: shared admission gate for detached byte-cache and server typed-cache builds.
Operational notes
Use this cache only for small responses. Large artifact bytes would displace useful metadata and duplicate hot-file storage in RAM. The configured size should cover the working set of catalog, version, Composer, Go proxy, and HTML metadata responses.
The server's typed object cache is separate and lives in mod/server/objcache.go; it shares the build gate but is not
part of this byte cache.
Set cache.build_max_parallel low on small nodes and high on read-heavy nodes with enough CPU and storage IO. The gate
caps concurrent cold builds across cache keys; it does not limit already-cached response serving.
Documentation
¶
Index ¶
- func SecondsToNextRescan(lastRescan time.Time, interval time.Duration, now time.Time) time.Duration
- type BuildGateObj
- type EntryObj
- type Obj
- func (obj *Obj) Clear()
- func (obj *Obj) Get(key string) (EntryObj, bool)
- func (obj *Obj) GetOrBuild(ctx context.Context, key string, ttl time.Duration, ...) (EntryObj, bool, error)
- func (obj *Obj) RegisterMetrics(meterObj metric.Meter) error
- func (obj *Obj) Set(key string, value EntryObj, ttl time.Duration)
- func (obj *Obj) Stats() StatsObj
- type StatsObj
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func SecondsToNextRescan ¶
SecondsToNextRescan returns time left until the next rescan. It is the shared source for metadata TTL and server `Cache-Control: max-age`; 0 means unknown, invalid, or already expired.
Types ¶
type BuildGateObj ¶ added in v0.4.0
type BuildGateObj struct {
// contains filtered or unexported fields
}
BuildGateObj limits detached builds shared by the byte-cache and the obj-cache.
func NewBuildGate ¶ added in v0.4.0
func NewBuildGate(maxParallel uint) *BuildGateObj
func (*BuildGateObj) Acquire ¶ added in v0.4.0
func (obj *BuildGateObj) Acquire(ctx context.Context) error
func (*BuildGateObj) Release ¶ added in v0.4.0
func (obj *BuildGateObj) Release()
type EntryObj ¶
EntryObj is a cached value: payload bytes plus the ETag validator for server-side 304 handling.
type Obj ¶
type Obj struct {
// contains filtered or unexported fields
}
Obj is the cache: shards, global atomic byte budget, singleflight, and metric counters.
func New ¶
func New(cacheCfgObj stconf.CacheObj, gateArr ...*BuildGateObj) *Obj
New builds a cache with the byte budget from cache.metadata_max_size, validated in config.
func (*Obj) Clear ¶
func (obj *Obj) Clear()
Clear removes all cache entries for lifecycle or restart invalidation.
func (*Obj) GetOrBuild ¶
func (obj *Obj) GetOrBuild(ctx context.Context, key string, ttl time.Duration, buildFn func(context.Context) (EntryObj, error)) (EntryObj, bool, error)
GetOrBuild does lookup, builds exactly once through singleflight on miss, stores the result, and returns it to all waiters. Build errors are not cached. hit=true only means a fast-path cache hit.
func (*Obj) RegisterMetrics ¶
RegisterMetrics registers the cache snapshot through a single observable callback.
Source Files