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 LR
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. - 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.method.go: get/set operations and LRU maintenance.metrics.go: telemetry producer for cache metrics.
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.
Documentation
¶
Index ¶
- func SecondsToNextRescan(lastRescan time.Time, interval time.Duration, now time.Time) time.Duration
- 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 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 ¶
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 cache observable metrics in meter. A nil meter is a no-op. One callback reads Stats per pass; the cache lives for the process lifetime, so registration is not stored.
Source Files