docs: deduplicate callKey KDoc across the context promotion chain#126
Merged
Conversation
RequestContext and ExchangeContext each restated, verbatim, the rationale for why the minted default callKey is collision-safe — the same explanation already documented in full on DispatchContext. Three copies of the same prose drift independently over time. Trim the two downstream types to state only what is local to them (the default is minted via DispatchContext.mintCallKey, and the resulting equality caveat) and defer the "why trace/span alone is not a safe key" reasoning to DispatchContext, the single canonical source. KDoc only; no behavior or API change.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
The minted, call-unique default
callKeyis documented in full onDispatchContext: why the baretraceId:spanIdpair is not a safeContextStorekey (the no-op context shares constant ids, an inbound W3C trace shares a trace id across spans, a tracer may reuse a span id across sibling calls) and why a process-unique counter is appended.RequestContextandExchangeContexteach restated that same rationale verbatim in their own KDoc. The explanation now lives in three places and will drift independently as it is edited.Change
Trim the two downstream types to document only what is local to them — that the default key is minted via
DispatchContext.mintCallKey, and the resulting equality caveat (two default-constructed instances are not structurally equal; pin an explicitcallKeyif you need equality) — and defer the underlying "why trace/span alone is not collision-safe" reasoning toDispatchContextas the single canonical source.KDoc only: no behavior, no signature, and no public-API change.
compileKotlinand ktlint pass.