@depup/datadog__browser-rum 6.31.0-depup.0

package/src/domain/profiling/types/profilerApi.types.ts

@@ -0,0 +1,87 @@
+// Define types for the new Profiler API
+// https://wicg.github.io/js-self-profiling/
+
+export interface ProfilerFrame {
+  /** A function instance name. */
+  readonly name: string
+  /** Index in the trace.resources array. */
+  readonly resourceId?: number
+  /** 1-based index of the line. */
+  readonly line?: number
+  /** 1-based index of the column. */
+  readonly column?: number
+}
+
+export interface ProfilerStack {
+  /** Index in the trace.stacks array. */
+  readonly parentId?: number
+  /** Index in the trace.frames array. */
+  readonly frameId: number
+}
+
+export interface ProfilerSample {
+  /** High resolution time relative to the profiling session's time origin. */
+  readonly timestamp: number
+  /** Index in the trace.stacks array. */
+  readonly stackId?: number
+}
+
+export type ProfilerResource = string
+
+export interface ProfilerTrace {
+  /** An array of profiler resources. */
+  readonly resources: ProfilerResource[]
+  /** An array of profiler frames. */
+  readonly frames: ProfilerFrame[]
+  /** An array of profiler stacks. */
+  readonly stacks: ProfilerStack[]
+  /** An array of profiler samples. */
+  readonly samples: ProfilerSample[]
+}
+
+export interface ProfilerInitOptions {
+  /** Sample interval in ms. */
+  readonly sampleInterval: number
+  /** Max buffer size in number of samples. */
+  readonly maxBufferSize: number
+}
+
+export interface Profiler extends EventTarget {
+  /** Sample interval in ms. */
+  readonly sampleInterval: number
+  /** True if profiler is stopped. */
+  readonly stopped: boolean
+
+  // eslint-disable-next-line @typescript-eslint/no-misused-new
+  new (options: ProfilerInitOptions): Profiler
+  stop(): Promise<ProfilerTrace>
+
+  addEventListener<K extends keyof ProfilerEventMap>(
+    type: K,
+    listener: (this: typeof globalThis, ev: ProfilerEventMap[K]) => any,
+    options?: boolean | AddEventListenerOptions
+  ): void
+  addEventListener(
+    type: string,
+    listener: EventListenerOrEventListenerObject,
+    options?: boolean | AddEventListenerOptions
+  ): void
+  removeEventListener<K extends keyof ProfilerEventMap>(
+    type: K,
+    listener: (this: typeof globalThis, ev: ProfilerEventMap[K]) => any,
+    options?: boolean | EventListenerOptions
+  ): void
+  removeEventListener(
+    type: string,
+    listener: EventListenerOrEventListenerObject,
+    options?: boolean | EventListenerOptions
+  ): void
+}
+
+interface ProfilerEventMap {
+  samplebufferfull: SampleBufferFullEvent
+}
+
+export interface SampleBufferFullEvent extends Event {
+  readonly target: Profiler
+}

package/src/domain/profiling/types/rumProfiler.types.ts

@@ -0,0 +1,62 @@
+import type { TimeoutId, ClocksState } from '@datadog/browser-core'
+import type { RumViewEntry } from '../../../types'
+import type { LongTaskContext } from '../longTaskHistory'
+import type { Profiler } from './profilerApi.types'
+
+/**
+ * Additional data recorded during profiling session
+ */
+export interface RumProfilerEnrichmentData {
+  /** List of detected long tasks */
+  readonly longTasks: LongTaskContext[]
+  /** List of detected navigation entries */
+  readonly views: RumViewEntry[]
+}
+
+/**
+ * Describes profiler session state when it's stopped
+ */
+export interface RumProfilerStoppedInstance {
+  readonly state: 'stopped'
+  readonly stateReason: 'session-expired' | 'stopped-by-user' | 'initializing'
+}
+
+/**
+ * Describes profiler session state when it's paused
+ * (this happens when user focuses on a different tab)
+ */
+export interface RumProfilerPausedInstance {
+  readonly state: 'paused'
+}
+
+/**
+ * Describes profiler session state when it's running
+ */
+export interface RumProfilerRunningInstance extends RumProfilerEnrichmentData {
+  readonly state: 'running'
+  /** Current profiler instance */
+  readonly profiler: Profiler
+  /** High resolution time when profiler session started */
+  readonly startClocks: ClocksState
+  /** Timeout id to stop current session */
+  readonly timeoutId: TimeoutId
+  /** Clean-up tasks to execute after running the Profiler */
+  readonly cleanupTasks: Array<() => void>
+}
+
+export type RumProfilerInstance = RumProfilerStoppedInstance | RumProfilerPausedInstance | RumProfilerRunningInstance
+
+export interface RUMProfiler {
+  start: () => void
+  stop: () => void
+  isStopped: () => boolean
+  isRunning: () => boolean
+  isPaused: () => boolean
+}
+
+export interface RUMProfilerConfiguration {
+  sampleIntervalMs: number // Sample stack trace every x milliseconds (defaults to 10ms for Unix, 16ms on Windows)
+  collectIntervalMs: number // Interval for collecting RUM Profiles (defaults to 1min)
+  minProfileDurationMs: number // Minimum duration of a profile for it be sent (defaults to 5s). Profiles shorter than this duration are discarded.
+  minNumberOfSamples: number // Minimum number of samples to be collected before it can be sent (defaults to 50). Profiles with fewer samples are discarded.
+}

package/src/domain/profiling/utils/getCustomOrDefaultViewName.ts

@@ -0,0 +1,4 @@
+import { getDefaultViewName } from './getDefaultViewName'
+
+export const getCustomOrDefaultViewName = (customViewName: string | undefined, viewPathUrl: string): string =>
+  customViewName || getDefaultViewName(viewPathUrl)

package/src/domain/profiling/utils/getDefaultViewName.ts

@@ -0,0 +1,12 @@
+// This is the regex used to extract the path from the url (from SimpleUrlGroupingProcessor.java)
+// It's a bit different from the one in the java code because we removed the lookbehind unsupported by Safari.
+const PATH_MIXED_ALPHANUMERICS = /\/(?![vV]\d{1,2}\/)([^/\d?]*\d+[^/?]*)/g
+
+export function getDefaultViewName(viewPathUrl: string): string {
+  if (!viewPathUrl) {
+    return '/'
+  }
+
+  // Replace all the mixed alphanumerics with a ?
+  return viewPathUrl.replace(PATH_MIXED_ALPHANUMERICS, '/?')
+}

package/src/domain/profiling/utils/getNumberOfSamples.ts

@@ -0,0 +1,17 @@
+import type { ProfilerSample } from '../types'
+
+/**
+ * Counts number of samples when the thread was not idle (stackId is defined)
+ *
+ * @param samples - Array of collected samples
+ * @returns Number of samples
+ */
+export function getNumberOfSamples(samples: ProfilerSample[]): number {
+  let numberOfSamples = 0
+  for (const sample of samples) {
+    if (sample.stackId !== undefined) {
+      numberOfSamples++
+    }
+  }
+  return numberOfSamples
+}

package/src/domain/profiling/vitalHistory.ts

@@ -0,0 +1,58 @@
+import type { ClocksState, Duration } from '@datadog/browser-core'
+import { addDuration, createValueHistory, SESSION_TIME_OUT_DELAY } from '@datadog/browser-core'
+import type { LifeCycle } from '@datadog/browser-rum-core'
+import { LifeCycleEventType } from '@datadog/browser-rum-core'
+
+export const VITAL_ID_HISTORY_TIME_OUT_DELAY = SESSION_TIME_OUT_DELAY
+
+export interface VitalContext {
+  id: string
+  label: string
+  duration?: Duration
+  startClocks: ClocksState
+}
+
+export function createVitalHistory(lifeCycle: LifeCycle) {
+  const history = createValueHistory<VitalContext>({
+    expireDelay: VITAL_ID_HISTORY_TIME_OUT_DELAY,
+  })
+
+  lifeCycle.subscribe(LifeCycleEventType.VITAL_STARTED, (vitalStart) => {
+    history.add(
+      {
+        id: vitalStart.id,
+        startClocks: vitalStart.startClocks,
+        duration: undefined,
+        label: vitalStart.name,
+      },
+      vitalStart.startClocks.relative
+    )
+  })
+
+  lifeCycle.subscribe(LifeCycleEventType.RAW_RUM_EVENT_COLLECTED, ({ rawRumEvent, startClocks, duration }) => {
+    if (rawRumEvent.type === 'vital') {
+      const historyEntry = history
+        .getEntries(startClocks.relative)
+        .find((entry) => entry.value.id === rawRumEvent.vital.id)
+
+      if (historyEntry) {
+        historyEntry.value.duration = duration!
+        historyEntry.close(addDuration(startClocks.relative, duration!))
+      } else {
+        history
+          .add(
+            {
+              id: rawRumEvent.vital.id,
+              startClocks,
+              duration,
+              label: rawRumEvent.vital.name,
+            },
+            startClocks.relative
+          )
+          .close(addDuration(startClocks.relative, duration!))
+      }
+    }
+  })
+
+  return history
+}

package/src/domain/record/assembly.ts

@@ -0,0 +1,19 @@
+import type { TimeStamp } from '@datadog/browser-core'
+import { timeStampNow } from '@datadog/browser-core'
+import type { BrowserIncrementalData, BrowserIncrementalSnapshotRecord } from '../../types'
+import { RecordType } from '../../types'
+
+export function assembleIncrementalSnapshot<Data extends BrowserIncrementalData>(
+  source: Data['source'],
+  data: Omit<Data, 'source'>,
+  timestamp: TimeStamp = timeStampNow()
+): BrowserIncrementalSnapshotRecord {
+  return {
+    data: {
+      source,
+      ...data,
+    } as Data,
+    type: RecordType.IncrementalSnapshot,
+    timestamp,
+  }
+}

package/src/domain/record/elementsScrollPositions.ts

@@ -0,0 +1,28 @@
+export type ElementsScrollPositions = ReturnType<typeof createElementsScrollPositions>
+export interface ScrollPositions {
+  scrollLeft: number
+  scrollTop: number
+}
+
+export function createElementsScrollPositions() {
+  const scrollPositionsByElement = new WeakMap<Element, ScrollPositions>()
+  return {
+    set(element: Element | Document, scrollPositions: ScrollPositions) {
+      if (element === document && !document.scrollingElement) {
+        // cf https://drafts.csswg.org/cssom-view/#dom-document-scrollingelement,
+        // in some cases scrolling elements can not be defined, we don't support those for now
+        return
+      }
+      scrollPositionsByElement.set(
+        element === document ? document.scrollingElement! : (element as Element),
+        scrollPositions
+      )
+    },
+    get(element: Element) {
+      return scrollPositionsByElement.get(element)
+    },
+    has(element: Element) {
+      return scrollPositionsByElement.has(element)
+    },
+  }
+}

package/src/domain/record/eventsUtils.ts

@@ -0,0 +1,12 @@
+import { isNodeShadowHost } from '@datadog/browser-rum-core'
+
+export function isTouchEvent(event: MouseEvent | TouchEvent): event is TouchEvent {
+  return Boolean((event as TouchEvent).changedTouches)
+}
+
+export function getEventTarget(event: Event): Node {
+  if (event.composed === true && isNodeShadowHost(event.target as Node)) {
+    return event.composedPath()[0] as Node
+  }
+  return event.target as Node
+}

package/src/domain/record/index.ts

@@ -0,0 +1,12 @@
+export { takeFullSnapshot, takeNodeSnapshot } from './internalApi'
+export { record } from './record'
+export type { SerializationMetric, SerializationStats } from './serialization'
+export {
+  aggregateSerializationStats,
+  createSerializationStats,
+  isFullSnapshotChangeRecordsEnabled,
+  isIncrementalSnapshotChangeRecordsEnabled,
+  serializeNode,
+} from './serialization'
+export { createElementsScrollPositions } from './elementsScrollPositions'
+export type { ShadowRootsController } from './shadowRootsController'

package/src/domain/record/internalApi.ts

@@ -0,0 +1,84 @@
+import { noop, timeStampNow } from '@datadog/browser-core'
+import type { RumConfiguration } from '@datadog/browser-rum-core'
+import { getNodePrivacyLevel, NodePrivacyLevel } from '@datadog/browser-rum-core'
+import type { BrowserRecord, SerializedNodeWithId } from '../../types'
+import { takeFullSnapshot as doTakeFullSnapshot } from './startFullSnapshots'
+import type { ShadowRootsController } from './shadowRootsController'
+import type { RecordingScope } from './recordingScope'
+import { createRecordingScope } from './recordingScope'
+import { createElementsScrollPositions } from './elementsScrollPositions'
+import type { EmitRecordCallback } from './record.types'
+import type { SerializationTransaction } from './serialization'
+import { SerializationKind, serializeInTransaction, serializeNode } from './serialization'
+
+/**
+ * Take a full snapshot of the document, generating the same records that the browser SDK
+ * would generate.
+ *
+ * This is an internal API function. Be sure to update Datadog-internal callers if you
+ * change its signature or behavior.
+ */
+export function takeFullSnapshot({
+  configuration,
+}: { configuration?: Partial<RumConfiguration> } = {}): BrowserRecord[] {
+  const records: BrowserRecord[] = []
+  const emitRecord: EmitRecordCallback = (record: BrowserRecord) => {
+    records.push(record)
+  }
+
+  doTakeFullSnapshot(
+    timeStampNow(),
+    SerializationKind.INITIAL_FULL_SNAPSHOT,
+    emitRecord,
+    noop,
+    createTemporaryRecordingScope(configuration)
+  )
+
+  return records
+}
+
+/**
+ * Take a snapshot of a DOM node, generating the serialized representation that the
+ * browser SDK would generate.
+ *
+ * This is an internal API function. Be sure to update Datadog-internal callers if you
+ * change its signature or behavior.
+ */
+export function takeNodeSnapshot(
+  node: Node,
+  { configuration }: { configuration?: Partial<RumConfiguration> } = {}
+): SerializedNodeWithId | null {
+  let serializedNode: SerializedNodeWithId | null = null
+
+  serializeInTransaction(
+    SerializationKind.INITIAL_FULL_SNAPSHOT,
+    noop,
+    noop,
+    createTemporaryRecordingScope(configuration),
+    (transaction: SerializationTransaction): void => {
+      const privacyLevel = getNodePrivacyLevel(node, transaction.scope.configuration.defaultPrivacyLevel)
+      if (privacyLevel === NodePrivacyLevel.HIDDEN || privacyLevel === NodePrivacyLevel.IGNORE) {
+        return
+      }
+      serializedNode = serializeNode(node, privacyLevel, transaction)
+    }
+  )
+
+  return serializedNode
+}
+
+function createTemporaryRecordingScope(configuration?: Partial<RumConfiguration>): RecordingScope {
+  return createRecordingScope(
+    {
+      defaultPrivacyLevel: NodePrivacyLevel.ALLOW,
+      ...configuration,
+    } as RumConfiguration,
+    createElementsScrollPositions(),
+    {
+      addShadowRoot: noop,
+      removeShadowRoot: noop,
+      flush: noop,
+      stop: noop,
+    } as ShadowRootsController
+  )
+}

package/src/domain/record/itemIds.ts

@@ -0,0 +1,97 @@
+export type EventId = number & { __brand: 'EventId' }
+export type EventIds = ItemIds<Event, EventId>
+export const enum EventIdConstants {
+  FIRST_ID = 1,
+}
+export function createEventIds(): EventIds {
+  return createWeakIdMap(EventIdConstants.FIRST_ID as EventId)
+}
+
+export type NodeId = number & { __brand: 'NodeId' }
+export type NodeIds = ItemIds<Node, NodeId>
+export const enum NodeIdConstants {
+  FIRST_ID = 0,
+}
+export function createNodeIds(): NodeIds {
+  return createWeakIdMap(NodeIdConstants.FIRST_ID as NodeId)
+}
+
+export type StringId = number & { __brand: 'StringId' }
+export type StringIds = ItemIds<string, StringId>
+export const enum StringIdConstants {
+  FIRST_ID = 0,
+}
+export function createStringIds(): StringIds {
+  return createIdMap(StringIdConstants.FIRST_ID as StringId)
+}
+
+export type StyleSheetId = number & { __brand: 'StyleSheetId' }
+export type StyleSheetIds = ItemIds<CSSStyleSheet, StyleSheetId>
+export const enum StyleSheetIdConstants {
+  FIRST_ID = 0,
+}
+export function createStyleSheetIds(): StyleSheetIds {
+  return createWeakIdMap(StyleSheetIdConstants.FIRST_ID as StyleSheetId)
+}
+
+export interface ItemIds<ItemType, ItemId extends number> {
+  clear(this: void): void
+  delete(this: void, item: ItemType): void
+  get(this: void, item: ItemType): ItemId | undefined
+  getOrInsert(this: void, item: ItemType): ItemId
+  get nextId(): ItemId
+  get size(): number
+}
+
+function createIdMap<ItemType, ItemId extends number>(firstId: ItemId): ItemIds<ItemType, ItemId> {
+  return createItemIds(() => new Map<ItemType, ItemId>(), firstId)
+}
+
+function createWeakIdMap<ItemType extends object, ItemId extends number>(firstId: ItemId): ItemIds<ItemType, ItemId> {
+  return createItemIds(() => new WeakMap<ItemType, ItemId>(), firstId)
+}
+
+interface MapLike<Key, Value> {
+  delete(key: Key): void
+  get(key: Key): Value | undefined
+  set(key: Key, value: Value): void
+}
+
+function createItemIds<ItemType, ItemId extends number>(
+  createMap: () => MapLike<ItemType, ItemId>,
+  firstId: ItemId
+): ItemIds<ItemType, ItemId> {
+  let map = createMap()
+  let nextId = firstId
+
+  const get = (object: ItemType): ItemId | undefined => map.get(object)
+
+  return {
+    clear(): void {
+      if (nextId === firstId) {
+        return
+      }
+      map = createMap()
+      nextId = firstId
+    },
+    delete(object: ItemType): void {
+      map.delete(object)
+    },
+    get,
+    getOrInsert(object: ItemType): ItemId {
+      // Try to reuse any existing id.
+      let id = get(object)
+      if (id === undefined) {
+        id = nextId++ as ItemId
+        map.set(object, id)
+      }
+      return id
+    },
+    get nextId(): ItemId {
+      return nextId
+    },
+    get size(): number {
+      return nextId - firstId
+    },
+  }
+}

package/src/domain/record/mutationBatch.ts

@@ -0,0 +1,47 @@
+import { noop, throttle, requestIdleCallback } from '@datadog/browser-core'
+import type { RumMutationRecord } from '@datadog/browser-rum-core'
+
+/**
+ * Maximum duration to wait before processing mutations. If the browser is idle, mutations will be
+ * processed more quickly. If the browser is busy executing small tasks (ex: rendering frames), the
+ * mutations will wait MUTATION_PROCESS_MAX_DELAY milliseconds before being processed. If the
+ * browser is busy executing a longer task, mutations will be processed after this task.
+ */
+const MUTATION_PROCESS_MAX_DELAY = 100
+/**
+ * Minimum duration to wait before processing mutations. This is used to batch mutations together
+ * and be able to deduplicate them to save processing time and bandwidth.
+ * 16ms is the duration of a frame at 60fps that ensure fluid UI.
+ */
+export const MUTATION_PROCESS_MIN_DELAY = 16
+
+export function createMutationBatch(processMutationBatch: (mutations: RumMutationRecord[]) => void) {
+  let cancelScheduledFlush = noop
+  let pendingMutations: RumMutationRecord[] = []
+
+  function flush() {
+    cancelScheduledFlush()
+    processMutationBatch(pendingMutations)
+    pendingMutations = []
+  }
+
+  const { throttled: throttledFlush, cancel: cancelThrottle } = throttle(flush, MUTATION_PROCESS_MIN_DELAY, {
+    leading: false,
+  })
+
+  return {
+    addMutations: (mutations: RumMutationRecord[]) => {
+      if (pendingMutations.length === 0) {
+        cancelScheduledFlush = requestIdleCallback(throttledFlush, { timeout: MUTATION_PROCESS_MAX_DELAY })
+      }
+      pendingMutations.push(...mutations)
+    },
+
+    flush,
+
+    stop: () => {
+      cancelScheduledFlush()
+      cancelThrottle()
+    },
+  }
+}

package/src/domain/record/record.ts

@@ -0,0 +1,90 @@
+import { sendToExtension } from '@datadog/browser-core'
+import type { LifeCycle, RumConfiguration, ViewHistory } from '@datadog/browser-rum-core'
+import * as replayStats from '../replayStats'
+import type { BrowserRecord } from '../../types'
+import type { Tracker } from './trackers'
+import {
+  trackFocus,
+  trackFrustration,
+  trackInput,
+  trackMediaInteraction,
+  trackMouseInteraction,
+  trackMove,
+  trackMutation,
+  trackScroll,
+  trackStyleSheet,
+  trackViewEnd,
+  trackViewportResize,
+  trackVisualViewportResize,
+} from './trackers'
+import { createElementsScrollPositions } from './elementsScrollPositions'
+import type { ShadowRootsController } from './shadowRootsController'
+import { initShadowRootsController } from './shadowRootsController'
+import { startFullSnapshots } from './startFullSnapshots'
+import type { EmitRecordCallback, EmitStatsCallback } from './record.types'
+import { createRecordingScope } from './recordingScope'
+
+export interface RecordOptions {
+  emitRecord: EmitRecordCallback
+  emitStats: EmitStatsCallback
+  configuration: RumConfiguration
+  lifeCycle: LifeCycle
+  viewHistory: ViewHistory
+}
+
+export interface RecordAPI {
+  stop: () => void
+  flushMutations: () => void
+  shadowRootsController: ShadowRootsController
+}
+
+export function record(options: RecordOptions): RecordAPI {
+  const { emitRecord, emitStats, configuration, lifeCycle } = options
+  // runtime checks for user options
+  if (!emitRecord || !emitStats) {
+    throw new Error('emit functions are required')
+  }
+
+  const processRecord: EmitRecordCallback = (record: BrowserRecord) => {
+    emitRecord(record)
+    sendToExtension('record', { record })
+    const view = options.viewHistory.findView()!
+    replayStats.addRecord(view.id)
+  }
+
+  const shadowRootsController = initShadowRootsController(processRecord, emitStats)
+  const scope = createRecordingScope(configuration, createElementsScrollPositions(), shadowRootsController)
+
+  const { stop: stopFullSnapshots } = startFullSnapshots(lifeCycle, processRecord, emitStats, flushMutations, scope)
+
+  function flushMutations() {
+    shadowRootsController.flush()
+    mutationTracker.flush()
+  }
+
+  const mutationTracker = trackMutation(document, processRecord, emitStats, scope)
+  const trackers: Tracker[] = [
+    mutationTracker,
+    trackMove(processRecord, scope),
+    trackMouseInteraction(processRecord, scope),
+    trackScroll(document, processRecord, scope),
+    trackViewportResize(processRecord, scope),
+    trackInput(document, processRecord, scope),
+    trackMediaInteraction(processRecord, scope),
+    trackStyleSheet(processRecord, scope),
+    trackFocus(processRecord, scope),
+    trackVisualViewportResize(processRecord, scope),
+    trackFrustration(lifeCycle, processRecord, scope),
+    trackViewEnd(lifeCycle, processRecord, flushMutations),
+  ]
+
+  return {
+    stop: () => {
+      shadowRootsController.stop()
+      trackers.forEach((tracker) => tracker.stop())
+      stopFullSnapshots()
+    },
+    flushMutations,
+    shadowRootsController,
+  }
+}

package/src/domain/record/record.types.ts

@@ -0,0 +1,22 @@
+import type { RumMutationRecord } from '@datadog/browser-rum-core'
+import type { TimeStamp } from '@datadog/browser-core'
+import type { BrowserFullSnapshotRecord, BrowserIncrementalSnapshotRecord, BrowserRecord } from '../../types'
+import type { SerializationKind, SerializationStats } from './serialization'
+
+export type EmitRecordCallback<Record extends BrowserRecord = BrowserRecord> = (record: Record) => void
+export type EmitStatsCallback = (stats: SerializationStats) => void
+
+export type SerializeEvent =
+  | {
+      type: 'full'
+      kind: SerializationKind
+      target: Document
+      timestamp: TimeStamp
+      v1: BrowserFullSnapshotRecord
+    }
+  | {
+      type: 'incremental'
+      target: RumMutationRecord[]
+      timestamp: TimeStamp
+      v1: BrowserIncrementalSnapshotRecord
+    }