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 a no-op cancel function.
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.
When a Cache is newly created, the cancel function clears the Cache. Calling the cancel function multiple times is safe.
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