Documentation
¶
Overview ¶
Package ctxcache provides a strongly-typed, context-scoped cache for request-scoped data.
ctxcache attaches a concurrency-safe, write-once key–value store to a context.Context, allowing values to be implicitly propagated across call boundaries without polluting function signatures.
Keys are identified by a combination of a string name and a Go type via generics, ensuring type safety and preventing collisions between values of different types—even if they share the same string identifier.
Each key may be assigned exactly once. After a value is set, it can be retrieved multiple times until the cache is cleared.
The cache lifecycle is explicitly controlled by a cancel function returned by Init. When the cancel function is called, all cached values are removed and the cache becomes permanently unusable.
ctxcache is not a general-purpose cache. It is designed for structured, short-lived, in-process data bound to a context's lifetime, such as authenticated users, permissions, trace metadata, or computed intermediates.
Typical usage:
- Initialize the cache at the request boundary (e.g. HTTP middleware).
- Set each value at most once using Set.
- Retrieve values using Get in downstream code.
- Defer the cancel function returned by Init to clean up request-scoped data.
Index ¶
Constants ¶
This section is empty.
Variables ¶
Functions ¶
func Get ¶
Get retrieves the value associated with the given key.
Returns an error if:
- the cache is not initialized,
- the cache has already been cleared, or
- no value has been set for the given key.
func Init ¶
Init attaches a Cache to the given context and returns the new context along with a cancel function.
Only one Cache may be attached to a context. Repeated calls to Init with the same context are safe: if a Cache already exists, Init returns the original context and the same cancel function created previously.
The returned cancel function should typically be deferred at the request boundary (e.g. in HTTP middleware) to ensure request-scoped data is cleaned up.
Only the first call to the cancel function performs actual cleanup. Subsequent calls are safe but have no effect.
Types ¶
type Cache ¶
type Cache struct {
// contains filtered or unexported fields
}
Cache holds context-scoped data associated with a context.Context.
Internally, Cache maintains a mutex-protected map keyed by strongly typed keys. The cache is propagated through the context without appearing in function signatures, making it suitable for passing data across modules.
A Cache is write-once per key: each key may be assigned a value exactly once. Values can be read multiple times until the cache is cleared.
Once cleared, the cache becomes permanently unusable; subsequent Get or Set operations will return ErrCacheAlreadyCleared.
func (*Cache) Clear ¶
func (cache *Cache) Clear()
Clear removes all cached values and marks the cache as cleared.
Clear is idempotent. Only the first call performs cleanup; subsequent calls have no effect.
After Clear is called, the cache is permanently unusable. All future Get or Set operations will return ErrCacheAlreadyCleared.
Source Files