Pass dd_debugger source as an explicit override

Previously, the Debugger SDK set `source: 'dd_debugger'` on its init
configuration so it would flow into the `ddsource` URL parameter, which
forced `validateAndBuildConfiguration` to convert it back to 'browser'
via a `toSdkSource` helper before storing on `Configuration.source`
(used as the SDK source on RUM events). The round-trip was confusing
because the same field was playing two roles: URL routing source and
RUM event SDK source.

Split them apart:

- `InitConfiguration.source` no longer accepts 'dd_debugger'.
- `computeTransportConfiguration` takes an optional `sourceOverride`
  parameter (typed `TransportSource`, includes 'dd_debugger') used only
  for URL building. The Debugger SDK passes 'dd_debugger' there.
- Function overloads narrow the return type when no override is given,
  so `Configuration.source` is `SdkSource` without a runtime conversion.
- `toSdkSource` is removed.

Wire behavior is unchanged: URLs still go out with
`?ddsource=dd_debugger&...&dd-evp-origin=browser`, RUM events still
carry a valid `SdkSource`, and downstream `source:dd_debugger` queries
keep working.

Author: watson

packages/core/src/domain/configuration/configuration.ts

@@ -276,7 +276,7 @@ export interface InitConfiguration {
    *
    * @internal
    */
-  source?: 'browser' | 'flutter' | 'unity' | 'dd_debugger' | undefined
+  source?: 'browser' | 'flutter' | 'unity' | undefined
 
   /**
    * [Internal option] Additional configuration for the SDK.
@@ -337,10 +337,6 @@ export interface Configuration extends TransportConfiguration {
   variant: string | undefined
 }
 
-function toSdkSource(source: TransportConfiguration['source']): SdkSource {
-  return source === 'dd_debugger' ? 'browser' : source
-}
-
 function isString(tag: unknown, tagName: string): tag is string | undefined | null {
   if (tag !== undefined && tag !== null && typeof tag !== 'string') {
     display.error(`${tagName} must be defined as a string`)
@@ -404,8 +400,6 @@ export function validateAndBuildConfiguration(
     return
   }
 
-  const transportConfiguration = computeTransportConfiguration(initConfiguration)
-
   return {
     beforeSend:
       initConfiguration.beforeSend && catchUserErrors(initConfiguration.beforeSend, 'beforeSend threw an error:'),
@@ -431,8 +425,7 @@ export function validateAndBuildConfiguration(
     variant: initConfiguration.variant,
     sdkVersion: initConfiguration.sdkVersion,
 
-    ...transportConfiguration,
-    source: toSdkSource(transportConfiguration.source),
+    ...computeTransportConfiguration(initConfiguration),
   }
 }
 

packages/core/src/domain/configuration/endpointBuilder.ts

@@ -16,10 +16,26 @@ export type ApiType =
   // a Node.js script).
   | 'manual'
 
+/**
+ * Source values supported by the transport layer for the `ddsource` URL parameter.
+ *
+ * `'dd_debugger'` is internal to the Live Debugger SDK and is not part of
+ * `InitConfiguration.source`. It can only be supplied by passing it as the
+ * `sourceOverride` argument of `computeTransportConfiguration`.
+ */
+export type TransportSource = 'browser' | 'flutter' | 'unity' | 'dd_debugger'
+
+// Internal: the endpoint builder accepts a wider `source` than the public
+// `InitConfiguration.source` so that `computeTransportConfiguration` can pass
+// the validated/overridden transport source through to URL building.
+type EndpointBuilderInitConfiguration = Omit<InitConfiguration, 'source'> & {
+  source?: TransportSource
+}
+
 export type EndpointBuilder = ReturnType<typeof createEndpointBuilder>
 
 export function createEndpointBuilder(
-  initConfiguration: InitConfiguration,
+  initConfiguration: EndpointBuilderInitConfiguration,
   trackType: TrackType,
   extraParameters?: string[]
 ) {
@@ -40,7 +56,7 @@ export function createEndpointBuilder(
  * request, as only parameters are changing.
  */
 function createEndpointUrlWithParametersBuilder(
-  initConfiguration: InitConfiguration,
+  initConfiguration: EndpointBuilderInitConfiguration,
   trackType: TrackType
 ): (parameters: string) => string {
   const path = `/api/v2/${trackType}`
@@ -58,7 +74,7 @@ function createEndpointUrlWithParametersBuilder(
 
 export function buildEndpointHost(
   trackType: TrackType,
-  initConfiguration: InitConfiguration & { usePciIntake?: boolean }
+  initConfiguration: Omit<InitConfiguration, 'source'> & { usePciIntake?: boolean }
 ) {
   const { site = INTAKE_SITE_US1, internalAnalyticsSubdomain } = initConfiguration
 
@@ -84,7 +100,7 @@ export function buildEndpointHost(
  * request, as they change randomly.
  */
 function buildEndpointParameters(
-  { clientToken, internalAnalyticsSubdomain, source = 'browser' }: InitConfiguration,
+  { clientToken, internalAnalyticsSubdomain, source = 'browser' }: EndpointBuilderInitConfiguration,
   trackType: TrackType,
   api: ApiType,
   { retry, encoding }: Payload,

packages/core/src/domain/configuration/transportConfiguration.ts

@@ -1,7 +1,7 @@
 import type { Site } from '../intakeSites'
 import { INTAKE_SITE_US1, INTAKE_URL_PARAMETERS } from '../intakeSites'
-import type { InitConfiguration } from './configuration'
-import type { EndpointBuilder } from './endpointBuilder'
+import type { InitConfiguration, SdkSource } from './configuration'
+import type { EndpointBuilder, TransportSource } from './endpointBuilder'
 import { createEndpointBuilder } from './endpointBuilder'
 
 export interface TransportConfiguration {
@@ -15,20 +15,47 @@ export interface TransportConfiguration {
   datacenter?: string | undefined
   replica?: ReplicaConfiguration
   site: Site
-  source: 'browser' | 'flutter' | 'unity' | 'dd_debugger'
+  source: TransportSource
 }
 
 export interface ReplicaConfiguration {
   logsEndpointBuilder: EndpointBuilder
   rumEndpointBuilder: EndpointBuilder
 }
 
-export function computeTransportConfiguration(initConfiguration: InitConfiguration): TransportConfiguration {
+// Internal: init configuration once the transport source has been resolved
+// (validated user value or `sourceOverride` from `computeTransportConfiguration`).
+type ResolvedSourceInitConfiguration = Omit<InitConfiguration, 'source'> & {
+  source: TransportSource
+}
+
+/**
+ * Compute the transport configuration (endpoint builders, replica, etc.) for an
+ * SDK init configuration.
+ *
+ * When called without `sourceOverride`, the resulting `source` is whatever was
+ * provided in `initConfiguration.source` (validated to a `SdkSource`, defaulting
+ * to `browser`).
+ *
+ * When called with `sourceOverride`, that value is used instead.
+ */
+export function computeTransportConfiguration(
+  initConfiguration: InitConfiguration
+): TransportConfiguration & { source: SdkSource }
+export function computeTransportConfiguration(
+  initConfiguration: InitConfiguration,
+  sourceOverride: TransportSource
+): TransportConfiguration
+export function computeTransportConfiguration(
+  initConfiguration: InitConfiguration,
+  sourceOverride?: TransportSource
+): TransportConfiguration {
   const site = initConfiguration.site || INTAKE_SITE_US1
-  const source = validateSource(initConfiguration.source)
+  const source: TransportSource = sourceOverride ?? validateSource(initConfiguration.source)
 
-  const endpointBuilders = computeEndpointBuilders({ ...initConfiguration, site, source })
-  const replicaConfiguration = computeReplicaConfiguration({ ...initConfiguration, site, source })
+  const resolvedConfiguration: ResolvedSourceInitConfiguration = { ...initConfiguration, site, source }
+  const endpointBuilders = computeEndpointBuilders(resolvedConfiguration)
+  const replicaConfiguration = computeReplicaConfiguration(resolvedConfiguration)
 
   return {
     replica: replicaConfiguration,
@@ -38,14 +65,14 @@ export function computeTransportConfiguration(initConfiguration: InitConfigurati
   }
 }
 
-function validateSource(source: string | undefined) {
-  if (source === 'flutter' || source === 'unity' || source === 'dd_debugger') {
+function validateSource(source: string | undefined): SdkSource {
+  if (source === 'flutter' || source === 'unity') {
     return source
   }
   return 'browser'
 }
 
-function computeEndpointBuilders(initConfiguration: InitConfiguration) {
+function computeEndpointBuilders(initConfiguration: ResolvedSourceInitConfiguration) {
   return {
     logsEndpointBuilder: createEndpointBuilder(initConfiguration, 'logs'),
     rumEndpointBuilder: createEndpointBuilder(initConfiguration, 'rum'),
@@ -57,12 +84,14 @@ function computeEndpointBuilders(initConfiguration: InitConfiguration) {
   }
 }
 
-function computeReplicaConfiguration(initConfiguration: InitConfiguration): ReplicaConfiguration | undefined {
+function computeReplicaConfiguration(
+  initConfiguration: ResolvedSourceInitConfiguration
+): ReplicaConfiguration | undefined {
   if (!initConfiguration.replica) {
     return
   }
 
-  const replicaConfiguration: InitConfiguration = {
+  const replicaConfiguration: ResolvedSourceInitConfiguration = {
     ...initConfiguration,
     site: INTAKE_SITE_US1,
     clientToken: initConfiguration.replica.clientToken,

packages/debugger/src/transport/startDebuggerBatch.ts

@@ -12,7 +12,7 @@ import {
 } from '@datadog/browser-core'
 
 export function startDebuggerBatch(initConfiguration: InitConfiguration): Batch {
-  const { debuggerEndpointBuilder } = computeTransportConfiguration({ ...initConfiguration, source: 'dd_debugger' })
+  const { debuggerEndpointBuilder } = computeTransportConfiguration(initConfiguration, 'dd_debugger')
 
   const batch = createBatch({
     encoder: createIdentityEncoder(),