Context Values

## What a context value actually is `context.WithValue(parent, key, val)` does not modify anything. It returns a **new** `context.Context` that wraps the parent and holds exactly one key/value pair. `ctx.Value(k)` compares `k` against the pair this node holds and, if it does not match, asks the parent — up the chain to the root, where a miss returns `nil`. The comparison is `==` between two `any` (interface) values. Interface equality compares **both** the dynamic type and the underlying data. That single fact explains the whole convention. ## Why a string key is dangerous There is no registry, no namespacing and no ownership. Every package in the process writes into the same flat key space of one context chain. If your package does: ```go ctx = context.WithValue(ctx, "userID", id) ``` then any other package that writes `"userID"` produces a key that is `==` to yours. Two things can go wrong, both silently: - **Shadowing.** A middleware deeper in the chain stores its own `"userID"` and your lookup now returns theirs — a different type, or the same type with the wrong meaning. - **Leaking.** Code you do not control can read a value you meant to be internal to your package, and start depending on it. Neither produces a compile error, a panic, or a log line. It shows up much later as a wrong value or a failed type assertion. ## The pattern Declare a type only your package can name: ```go type traceIDKey struct{} // zero-size, comparable // or: type ctxKey int; const traceIDKey ctxKey = iota ``` An empty struct is the common choice: it is comparable, allocates nothing, and `traceIDKey{}` written twice inside your package produces two equal keys. An unexported integer-constant type is equally fine and is handy when one package owns several keys. Because the type is unexported, no other package can even write the expression that would build the key, so collision is impossible **by construction** rather than by convention. ## Export accessors, not keys The key being unexported means callers need helpers: ```go func WithTraceID(ctx context.Context, id string) context.Context func TraceID(ctx context.Context) (string, bool) ``` This is a feature. The pair documents what type the value has, gives exactly one place where the value is written, and forces a decision about the missing case at the API level rather than at each call site. ## What `WithValue` requires of a key The key must be non-nil and **comparable**; `WithValue` panics immediately otherwise. A slice, a map or a function value as a key panics rather than failing later. Structs made only of comparable fields are fine. Pointer keys work too — the standard library uses that form, exporting pointer values such as `http.ServerContextKey` when it deliberately wants other packages to read the value — but prefer a pointer to a **non-empty** struct if you take that route, since distinct zero-size allocations are not guaranteed to have distinct addresses. ## Common confusions - *"A package-level `var userKey = \"userID\"` fixes it."* It does not. The value is still a `string`, and the comparison is by type and data, not by which variable it came from. - *"Making the key unique enough is fine."* Uniqueness by hope is not uniqueness. A type is checked by the compiler; a string prefix is checked by nobody. - *"A struct key makes `Value` return a typed result."* It does not. `Value` returns `any` whatever the key is; the caller still asserts. The key protects the namespace, not the value's type — which is exactly why the exported accessor that does the assertion once is worth writing.