From 0621d7f12ef96041680db702102ad0f7827c6396 Mon Sep 17 00:00:00 2001 From: OmarAlJarrah Date: Wed, 17 Jun 2026 01:47:44 +0300 Subject: [PATCH] docs: deduplicate callKey KDoc across the context promotion chain MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- .../dexpace/sdk/core/http/context/ExchangeContext.kt | 11 ++++++----- .../dexpace/sdk/core/http/context/RequestContext.kt | 11 ++++++----- 2 files changed, 12 insertions(+), 10 deletions(-) diff --git a/sdk-core/src/main/kotlin/org/dexpace/sdk/core/http/context/ExchangeContext.kt b/sdk-core/src/main/kotlin/org/dexpace/sdk/core/http/context/ExchangeContext.kt index ccdcf30d..9155f3ef 100644 --- a/sdk-core/src/main/kotlin/org/dexpace/sdk/core/http/context/ExchangeContext.kt +++ b/sdk-core/src/main/kotlin/org/dexpace/sdk/core/http/context/ExchangeContext.kt @@ -19,11 +19,12 @@ import org.dexpace.sdk.core.instrumentation.InstrumentationContext * * As the terminal link this is the context whose [close] should be called to evict the * chain's [ContextStore] entry. In the normal flow the [callKey] is supplied by - * [RequestContext.toExchangeContext]. When this context is constructed directly off-chain, the - * [callKey] defaults to a freshly minted, call-unique key (`traceId:spanId:n`) — the same - * collision-safe derivation [DispatchContext] uses — so two directly-constructed contexts that - * share a trace/span id never collide in [ContextStore]. Two such default-constructed instances - * are therefore not structurally equal; pin an explicit [callKey] if you need equality. + * [RequestContext.toExchangeContext]. When this context is constructed directly off-chain it + * defaults to a freshly minted, call-unique key (`traceId:spanId:n`) via + * [DispatchContext.mintCallKey] — see [DispatchContext] for why the trace/span pair alone is not + * a collision-safe store key. One consequence of the minted default: two default-constructed + * instances are not structurally equal, since each mints a distinct key — pin an explicit + * [callKey] if you need equality. */ public data class ExchangeContext( override val instrumentationContext: InstrumentationContext, diff --git a/sdk-core/src/main/kotlin/org/dexpace/sdk/core/http/context/RequestContext.kt b/sdk-core/src/main/kotlin/org/dexpace/sdk/core/http/context/RequestContext.kt index 969ff74b..f255d2ba 100644 --- a/sdk-core/src/main/kotlin/org/dexpace/sdk/core/http/context/RequestContext.kt +++ b/sdk-core/src/main/kotlin/org/dexpace/sdk/core/http/context/RequestContext.kt @@ -18,11 +18,12 @@ import org.dexpace.sdk.core.instrumentation.InstrumentationContext * [DispatchContext] it was promoted from. * * In the normal flow the [callKey] is supplied by [DispatchContext.toRequestContext] so the - * whole chain shares one store slot. When this context is constructed directly off-chain, the - * [callKey] defaults to a freshly minted, call-unique key (`traceId:spanId:n`) — the same - * collision-safe derivation [DispatchContext] uses — so two directly-constructed contexts that - * share a trace/span id never collide in [ContextStore]. Two such default-constructed instances - * are therefore not structurally equal; pin an explicit [callKey] if you need equality. + * whole chain shares one store slot. When this context is constructed directly off-chain it + * defaults to a freshly minted, call-unique key (`traceId:spanId:n`) via + * [DispatchContext.mintCallKey] — see [DispatchContext] for why the trace/span pair alone is not + * a collision-safe store key. One consequence of the minted default: two default-constructed + * instances are not structurally equal, since each mints a distinct key — pin an explicit + * [callKey] if you need equality. */ public data class RequestContext( override val instrumentationContext: InstrumentationContext,