ctxcache

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:

1. Initialize the cache at the request boundary (e.g. HTTP middleware).
2. Set each value at most once using Set.
3. Retrieve values using Get in downstream code.
4. Defer the cancel function returned by Init to clean up request-scoped data.

Index

• Variables
• func Get[T any](ctx context.Context, key string) (T, error)
• func Init(ctx context.Context) (_ context.Context, cancel func())
• func Set[T any](ctx context.Context, key string, value T) error
• type Cache
  • func (cache *Cache) Clear()
• type TypedKey
  • func (k TypedKey[T]) String() string

Variables

var (
	ErrCacheNotInitialized = errors.New("cache not initialized")
	ErrCacheAlreadyCleared = errors.New("cache already cleared")
	ErrKeyNotSet           = errors.New("key not set")
	ErrKeyAlreadySet       = errors.New("key already set")
)

Functions

func Get

func Get[T any](ctx context.Context, key string) (T, error)

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

func Init(ctx context.Context) (_ context.Context, cancel func())

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.

func Set

func Set[T any](ctx context.Context, key string, value T) error

Set assigns a value to the given key.

Each key may be assigned exactly once. Subsequent attempts to set the same key return ErrKeyAlreadySet.

Returns an error if:

• the cache is not initialized, or
• the cache has already been cleared.

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.

type TypedKey

type TypedKey[T any] struct {
	Key string
}

TypedKey represents a strongly typed cache key.

A TypedKey is defined by a string identifier and a Go type parameter. Keys with the same string but different type parameters are considered distinct and do not collide.

func (TypedKey[T]) String

func (k TypedKey[T]) String() string