Add Live Debugger package

.github/CODEOWNERS

@@ -12,3 +12,10 @@ test/e2e/scenario/recorder/**                   @Datadog/rum-browser @Datadog/se
 
 # Docs
 /README.md    @Datadog/rum-browser @DataDog/documentation
+
+# Debugger
+packages/debugger                                               @Datadog/rum-browser @DataDog/debugger
+packages/debugger/README.md                                     @Datadog/rum-browser @DataDog/debugger @DataDog/documentation
+test/apps/instrumentation-overhead                              @Datadog/rum-browser @DataDog/debugger
+test/e2e/scenario/debugger.scenario.ts                          @Datadog/rum-browser @DataDog/debugger
+test/performance/scenarios/instrumentationOverhead.scenario.ts  @Datadog/rum-browser @DataDog/debugger

LICENSE-3rdparty.csv

@@ -38,6 +38,7 @@ dev,@vitejs/plugin-react,MIT,Copyright (c) 2019-present Evan You & Vite Contribu
 dev,@vitejs/plugin-vue,MIT,Copyright (c) 2019-present, Yuxi (Evan) You and Vite contributors
 dev,@module-federation/enhanced,MIT, Copyright (c) 2020 ScriptedAlchemy LLC (Zack Jackson) Zhou Shaw (zhouxiao)
 dev,@vue/test-utils,MIT,Copyright (c) 2021-present vuejs
+dev,acorn,MIT,Copyright (C) 2012-2022 by various contributors (see AUTHORS)
 dev,ajv,MIT,Copyright 2015-2017 Evgeny Poberezkin
 dev,babel-loader,MIT,Copyright (c) 2014-2019 Luís Couto <hello@luiscouto.pt>
 dev,browserstack-local,MIT,Copyright 2016 BrowserStack

eslint-local-rules/disallowSideEffects.js

@@ -29,6 +29,7 @@ const pathsWithSideEffect = new Set([
   `${packagesRoot}/logs/src/entries/main.ts`,
   `${packagesRoot}/rum/src/entries/main.ts`,
   `${packagesRoot}/rum-slim/src/entries/main.ts`,
+  `${packagesRoot}/debugger/src/entries/main.ts`,
 ])
 
 // Those packages are known to have no side effects when evaluated

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

@@ -311,6 +311,8 @@ export interface ReplicaUserConfiguration {
   clientToken: string
 }
 
+export type SdkSource = 'browser' | 'flutter' | 'unity'
+
 export interface Configuration extends TransportConfiguration {
   // Built from init configuration
   beforeSend: GenericBeforeSendCallback | undefined
@@ -331,7 +333,6 @@ export interface Configuration extends TransportConfiguration {
 
   // internal
   sdkVersion: string | undefined
-  source: 'browser' | 'flutter' | 'unity'
   variant: string | undefined
 }
 

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

@@ -8,18 +8,34 @@ import type { InitConfiguration } from './configuration'
 // replaced at build time
 declare const __BUILD_ENV__SDK_VERSION__: string
 
-export type TrackType = 'logs' | 'rum' | 'replay' | 'profile' | 'exposures' | 'flagevaluation'
+export type TrackType = 'logs' | 'rum' | 'replay' | 'profile' | 'exposures' | 'flagevaluation' | 'debugger'
 export type ApiType =
   | 'fetch'
   | 'beacon'
   // 'manual' reflects that the request have been sent manually, outside of the SDK (ex: via curl or
   // 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 {
@@ -11,23 +11,48 @@ export interface TransportConfiguration {
   profilingEndpointBuilder: EndpointBuilder
   exposuresEndpointBuilder: EndpointBuilder
   flagEvaluationEndpointBuilder: EndpointBuilder
+  debuggerEndpointBuilder: EndpointBuilder
   datacenter?: string | undefined
   replica?: ReplicaConfiguration
   site: Site
-  source: 'browser' | 'flutter' | 'unity'
+  source: SdkSource
 }
 
 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.
+ *
+ * `sourceOverride` (if provided) is only used to build the `ddsource` URL
+ * parameter on outgoing requests; it does not appear on the returned
+ * `TransportConfiguration.source`, which is always the validated `SdkSource`
+ * derived from `initConfiguration.source`.
+ */
+export function computeTransportConfiguration(
+  initConfiguration: InitConfiguration,
+  sourceOverride?: TransportSource
+): TransportConfiguration {
   const site = initConfiguration.site || INTAKE_SITE_US1
   const source = validateSource(initConfiguration.source)
+  const transportSource: TransportSource = sourceOverride ?? source
 
-  const endpointBuilders = computeEndpointBuilders({ ...initConfiguration, site, source })
-  const replicaConfiguration = computeReplicaConfiguration({ ...initConfiguration, site, source })
+  const resolvedConfiguration: ResolvedSourceInitConfiguration = {
+    ...initConfiguration,
+    site,
+    source: transportSource,
+  }
+  const endpointBuilders = computeEndpointBuilders(resolvedConfiguration)
+  const replicaConfiguration = computeReplicaConfiguration(resolvedConfiguration)
 
   return {
     replica: replicaConfiguration,
@@ -37,30 +62,33 @@ export function computeTransportConfiguration(initConfiguration: InitConfigurati
   }
 }
 
-function validateSource(source: string | undefined) {
+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'),
     profilingEndpointBuilder: createEndpointBuilder(initConfiguration, 'profile'),
     sessionReplayEndpointBuilder: createEndpointBuilder(initConfiguration, 'replay'),
     exposuresEndpointBuilder: createEndpointBuilder(initConfiguration, 'exposures'),
     flagEvaluationEndpointBuilder: createEndpointBuilder(initConfiguration, 'flagevaluation'),
+    debuggerEndpointBuilder: createEndpointBuilder(initConfiguration, 'debugger'),
   }
 }
 
-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/core/src/index.ts

@@ -7,6 +7,7 @@ export {
   isSampleRate,
   buildEndpointHost,
   isIntakeUrl,
+  computeTransportConfiguration,
 } from './domain/configuration'
 export * from './domain/intakeSites'
 export type { TrackingConsentState } from './domain/trackingConsent'
@@ -57,7 +58,15 @@ export {
   SESSION_NOT_TRACKED,
   SessionPersistence,
 } from './domain/session/sessionConstants'
-export type { BandwidthStats, HttpRequest, HttpRequestEvent, Payload, FlushEvent, FlushReason } from './transport'
+export type {
+  Batch,
+  BandwidthStats,
+  HttpRequest,
+  HttpRequestEvent,
+  Payload,
+  FlushEvent,
+  FlushReason,
+} from './transport'
 export {
   createHttpRequest,
   canUseEventBridge,

packages/core/src/transport/index.ts

@@ -2,6 +2,7 @@ export type { BandwidthStats, HttpRequest, HttpRequestEvent, Payload, RetryInfo
 export { createHttpRequest } from './httpRequest'
 export type { BrowserWindowWithEventBridge, DatadogEventBridge } from './eventBridge'
 export { canUseEventBridge, bridgeSupports, getEventBridge, BridgeCapability } from './eventBridge'
+export type { Batch } from './batch'
 export { createBatch } from './batch'
 export type { FlushController, FlushEvent, FlushReason } from './flushController'
 export { createFlushController, FLUSH_DURATION_LIMIT } from './flushController'