@depup/datadog__browser-rum 6.31.0-depup.0

package/src/domain/record/serialization/conversions/vNode.ts

@@ -0,0 +1,417 @@
+import type { SerializedNodeWithId } from '../../../../types'
+import { PlaybackState, NodeType } from '../../../../types'
+import type { NodeId } from '../../itemIds'
+import type { V1RenderOptions } from './renderOptions'
+import type { VDocument } from './vDocument'
+import type { VStyleSheet } from './vStyleSheet'
+
+export interface VNode {
+  after(node: VNode): void
+  appendChild(node: VNode): void
+  before(node: VNode): void
+  remove(): void
+
+  setAttachedStyleSheets(sheets: VStyleSheet[]): void
+  setAttribute(name: string, value: string | null): void
+  setPlaybackState(state: PlaybackState): void
+  setScrollPosition(left: number, top: number): void
+  setSize(width: number, height: number): void
+  setTextContent(value: string): void
+
+  forEachAddedNodeRoot(nodeAdds: Set<NodeId>, action: (node: VNode) => void): void
+  forSelfAndEachDescendant(action: (node: VNode) => void): void
+  mapChildren<Result>(action: (node: VNode) => Result): Result[]
+
+  render(options: V1RenderOptions): SerializedNodeWithId
+
+  get data(): VNodeData
+  get id(): NodeId
+  get ownerDocument(): VDocument
+
+  state: VNodeState
+  firstChild: VNode | undefined
+  lastChild: VNode | undefined
+  previousSibling: VNode | undefined
+  nextSibling: VNode | undefined
+  parent: VNode | undefined
+}
+
+export type VNodeState = 'new' | 'connected' | 'disconnected'
+
+export type VNodeData =
+  | {
+      kind: '#cdata-section'
+    }
+  | {
+      kind: '#document'
+      attachedStyleSheets?: VStyleSheet[] | undefined
+      scrollLeft?: number
+      scrollTop?: number
+    }
+  | {
+      kind: '#doctype'
+      name: string
+      publicId: string
+      systemId: string
+    }
+  | {
+      kind: '#document-fragment'
+      attachedStyleSheets?: VStyleSheet[] | undefined
+    }
+  | {
+      kind: '#element'
+      tag: string
+      attachedStyleSheets?: VStyleSheet[] | undefined
+      attributes: Record<string, string>
+      isSVG?: boolean
+      playbackState?: PlaybackState
+      scrollLeft?: number
+      scrollTop?: number
+      width?: number
+      height?: number
+    }
+  | {
+      kind: '#shadow-root'
+      attachedStyleSheets?: VStyleSheet[] | undefined
+    }
+  | {
+      kind: '#text'
+      textContent: string
+    }
+
+export function createVNode(document: VDocument, id: NodeId, data: VNodeData): VNode {
+  let state: VNodeState = 'new'
+
+  const assertConnectedCorrectly = (): void => {
+    if (self.state !== 'connected') {
+      throw new Error(`Expected node ${self.id} to be connected, not ${self.state}`)
+    }
+
+    for (const connection of ['firstChild', 'lastChild', 'previousSibling', 'nextSibling', 'parent'] as const) {
+      const connectedNode = self[connection]
+      if (connectedNode && connectedNode.state !== 'connected') {
+        throw new Error(`Expected node ${self.id}'s ${connection} to be connected, not ${connectedNode.state}`)
+      }
+    }
+  }
+
+  const self: VNode = {
+    after(node: VNode): void {
+      node.parent = self.parent
+      node.previousSibling = self
+
+      if (self.nextSibling) {
+        self.nextSibling.previousSibling = node
+      }
+      node.nextSibling = self.nextSibling
+      self.nextSibling = node
+
+      if (self.parent?.lastChild === self) {
+        self.parent.lastChild = node
+      }
+
+      document.onNodeConnected(node, self.parent)
+      assertConnectedCorrectly()
+    },
+
+    appendChild(node: VNode): void {
+      if (self.lastChild) {
+        self.lastChild.after(node)
+        return
+      }
+
+      node.parent = self
+      self.firstChild = node
+      self.lastChild = node
+
+      document.onNodeConnected(node, self)
+      assertConnectedCorrectly()
+    },
+
+    before(node: VNode): void {
+      node.parent = self.parent
+      node.nextSibling = self
+
+      if (self.previousSibling) {
+        self.previousSibling.nextSibling = node
+      }
+      node.previousSibling = self.previousSibling
+      self.previousSibling = node
+
+      if (self.parent?.firstChild === self) {
+        self.parent.firstChild = node
+      }
+
+      document.onNodeConnected(node, self.parent)
+      assertConnectedCorrectly()
+    },
+
+    remove(): void {
+      if (self.state === 'disconnected') {
+        return // This is a redundant remove.
+      }
+
+      if (self.parent?.firstChild === self) {
+        self.parent.firstChild = self.nextSibling
+      }
+      if (self.parent?.lastChild === self) {
+        self.parent.lastChild = self.previousSibling
+      }
+      if (self.previousSibling) {
+        self.previousSibling.nextSibling = self.nextSibling
+      }
+      if (self.nextSibling) {
+        self.nextSibling.previousSibling = self.previousSibling
+      }
+
+      const parent = self.parent
+      self.parent = undefined
+      self.previousSibling = undefined
+      self.nextSibling = undefined
+
+      document.onNodeDisconnected(self, parent)
+    },
+
+    setAttachedStyleSheets(sheets: VStyleSheet[]): void {
+      assertConnectedCorrectly()
+
+      switch (data.kind) {
+        case '#document':
+        case '#document-fragment':
+        case '#element':
+        case '#shadow-root':
+          data.attachedStyleSheets = sheets
+          break
+
+        default:
+          throw new Error(`Cannot attach stylesheets to ${data.kind} node ${id}`)
+      }
+    },
+
+    setAttribute(name: string, value: string | null): void {
+      assertConnectedCorrectly()
+
+      if (data.kind !== '#element') {
+        throw new Error(`Cannot set attribute ${name} on ${data.kind} node ${id}`)
+      }
+
+      if (value === null) {
+        delete data.attributes[name]
+      } else {
+        data.attributes[name] = value
+      }
+
+      document.onAttributeChanged(self, name)
+    },
+
+    setPlaybackState(state: PlaybackState): void {
+      assertConnectedCorrectly()
+
+      if (data.kind !== '#element') {
+        throw new Error(`Cannot set media playback state of ${data.kind} node ${id}`)
+      }
+
+      data.playbackState = state
+    },
+
+    setScrollPosition(left: number, top: number): void {
+      assertConnectedCorrectly()
+
+      if (data.kind !== '#document' && data.kind !== '#element') {
+        throw new Error(`Cannot set scroll position on ${data.kind} node ${id}`)
+      }
+
+      // Treat zero coordinates as 'not scrolled' unless this element has scrolled in the past.
+      if (left !== 0 || data.scrollLeft !== undefined) {
+        data.scrollLeft = left
+      }
+      if (top !== 0 || data.scrollTop !== undefined) {
+        data.scrollTop = top
+      }
+    },
+
+    setSize(width: number, height: number): void {
+      assertConnectedCorrectly()
+
+      if (data.kind !== '#element') {
+        throw new Error(`Cannot set size of ${data.kind} node ${id}`)
+      }
+
+      data.width = width
+      data.height = height
+    },
+
+    setTextContent(value: string): void {
+      assertConnectedCorrectly()
+
+      if (data.kind !== '#text') {
+        throw new Error(`Cannot set text on ${data.kind} node ${id}`)
+      }
+
+      data.textContent = value
+
+      document.onTextChanged(self)
+    },
+
+    forEachAddedNodeRoot(nodeAdds: Set<NodeId>, action: (node: VNode) => void): void {
+      if (nodeAdds.has(id)) {
+        // This is the root of a newly-added subtree.
+        action(self)
+        return
+      }
+
+      // This is an existing node, but there may be new nodes among our descendants. Visit
+      // children in reverse order to match the ordering that the V1 serialization
+      // algorithm would use.
+      for (let child = self.lastChild; child; child = child.previousSibling) {
+        child.forEachAddedNodeRoot(nodeAdds, action)
+      }
+    },
+
+    forSelfAndEachDescendant(action: (node: VNode) => void): void {
+      action(self)
+      for (let child = self.firstChild; child; child = child.nextSibling) {
+        child.forSelfAndEachDescendant(action)
+      }
+    },
+
+    mapChildren<Result>(action: (node: VNode) => Result): Result[] {
+      const results: Result[] = []
+      for (let child = self.firstChild; child; child = child.nextSibling) {
+        results.push(action(child))
+      }
+      return results
+    },
+
+    render(options: V1RenderOptions): SerializedNodeWithId {
+      assertConnectedCorrectly()
+
+      const id = options.nodeIdRemapper?.remap(self.id) ?? self.id
+
+      switch (data.kind) {
+        case '#cdata-section':
+          return {
+            type: NodeType.CDATA,
+            id,
+            textContent: '',
+          }
+
+        case '#doctype':
+          return {
+            type: NodeType.DocumentType,
+            id,
+            name: data.name,
+            publicId: data.publicId,
+            systemId: data.systemId,
+          }
+
+        case '#document':
+          return {
+            type: NodeType.Document,
+            id,
+            childNodes: self.mapChildren((node) => node.render(options)),
+            adoptedStyleSheets: data.attachedStyleSheets?.map((sheet) => sheet.renderAsAdoptedStyleSheet()),
+          }
+
+        case '#document-fragment':
+          return {
+            type: NodeType.DocumentFragment,
+            id,
+            childNodes: self.mapChildren((node) => node.render(options)),
+            adoptedStyleSheets: data.attachedStyleSheets?.map((sheet) => sheet.renderAsAdoptedStyleSheet()),
+            isShadowRoot: false,
+          }
+
+        case '#element': {
+          const attributes: Record<string, string | number> = {}
+
+          // Add size-related virtual attributes before the real DOM attributes, to match
+          // the ordering used in the V1 format.
+          if (data.width !== undefined && data.height !== undefined) {
+            attributes.rr_width = `${data.width}px`
+            attributes.rr_height = `${data.height}px`
+          }
+
+          // Add DOM attributes.
+          Object.assign(attributes, data.attributes)
+
+          // Add other virtual attributes after the real DOM attributes, to match the
+          // ordering used in the V1 format.
+          if (data.attachedStyleSheets !== undefined) {
+            attributes._cssText = data.attachedStyleSheets.map((sheet) => sheet.renderAsCssText()).join('')
+          }
+          if (data.playbackState !== undefined) {
+            attributes.rr_mediaState = data.playbackState === PlaybackState.Paused ? 'paused' : 'played'
+          }
+          if (data.scrollLeft) {
+            attributes.rr_scrollLeft = data.scrollLeft
+          }
+          if (data.scrollTop) {
+            attributes.rr_scrollTop = data.scrollTop
+          }
+
+          return {
+            type: NodeType.Element,
+            id,
+            tagName: data.tag,
+            attributes,
+            childNodes: self.mapChildren((node) => node.render(options)),
+            isSVG: data.isSVG === true ? true : undefined,
+          }
+        }
+
+        case '#shadow-root':
+          return {
+            type: NodeType.DocumentFragment,
+            id,
+            childNodes: self.mapChildren((node) => node.render(options)),
+            adoptedStyleSheets: data.attachedStyleSheets?.map((sheet) => sheet.renderAsAdoptedStyleSheet()),
+            isShadowRoot: true,
+          }
+
+        case '#text':
+          return {
+            type: NodeType.Text,
+            id,
+            textContent: data.textContent,
+          }
+
+        default:
+          data satisfies never
+          throw new Error(`Rendering not implemented for ${self.data.kind} node ${id}`)
+      }
+    },
+
+    get data(): VNodeData {
+      return data
+    },
+    get ownerDocument(): VDocument {
+      return document
+    },
+    get id(): NodeId {
+      return id
+    },
+
+    get state(): VNodeState {
+      return state
+    },
+    set state(value: VNodeState) {
+      if (
+        (state === 'new' && value !== 'connected') ||
+        (state === 'connected' && value !== 'disconnected') ||
+        state === 'disconnected'
+      ) {
+        throw new Error(`Invalid state transition from ${state} to ${value}`)
+      }
+      state = value
+    },
+
+    firstChild: undefined,
+    lastChild: undefined,
+    previousSibling: undefined,
+    nextSibling: undefined,
+    parent: undefined,
+  }
+
+  return self
+}

package/src/domain/record/serialization/conversions/vStyleSheet.ts

@@ -0,0 +1,47 @@
+import type { StyleSheet } from '../../../../types'
+import type { StyleSheetId } from '../../itemIds'
+import type { VDocument } from './vDocument'
+
+export interface VStyleSheet {
+  renderAsAdoptedStyleSheet(): StyleSheet
+  renderAsCssText(): string
+
+  get data(): VStyleSheetData
+  get id(): StyleSheetId
+  get ownerDocument(): VDocument
+}
+
+export interface VStyleSheetData {
+  disabled: boolean
+  mediaList: string[]
+  rules: string | string[]
+}
+
+export function createVStyleSheet(document: VDocument, id: StyleSheetId, data: VStyleSheetData): VStyleSheet {
+  const self: VStyleSheet = {
+    renderAsAdoptedStyleSheet(): StyleSheet {
+      const cssRules = typeof data.rules === 'string' ? [data.rules] : data.rules
+      return {
+        cssRules,
+        disabled: data.disabled ? true : undefined,
+        media: data.mediaList.length > 0 ? data.mediaList : undefined,
+      }
+    },
+
+    renderAsCssText(): string {
+      return typeof data.rules === 'string' ? data.rules : data.rules.join('')
+    },
+
+    get data(): VStyleSheetData {
+      return data
+    },
+    get id(): StyleSheetId {
+      return id
+    },
+    get ownerDocument(): VDocument {
+      return document
+    },
+  }
+
+  return self
+}

package/src/domain/record/serialization/experimentalFeatures.ts

@@ -0,0 +1,15 @@
+import { ExperimentalFeature, isExperimentalFeatureEnabled } from '@datadog/browser-core'
+
+export function isFullSnapshotChangeRecordsEnabled(): boolean {
+  // We don't want to have to support the case where full snapshots use the old format and
+  // incremental snapshots use the new one, so we should generate full snapshot Change
+  // records if either feature flag is enabled.
+  return (
+    isExperimentalFeatureEnabled(ExperimentalFeature.USE_CHANGE_RECORDS) ||
+    isExperimentalFeatureEnabled(ExperimentalFeature.USE_INCREMENTAL_CHANGE_RECORDS)
+  )
+}
+
+export function isIncrementalSnapshotChangeRecordsEnabled(): boolean {
+  return isExperimentalFeatureEnabled(ExperimentalFeature.USE_INCREMENTAL_CHANGE_RECORDS)
+}

package/src/domain/record/serialization/index.ts

@@ -0,0 +1,21 @@
+export type { ChangeConverter, MutationLog, NodeIdRemapper } from './conversions'
+export { createChangeConverter, createCopyingNodeIdRemapper, createIdentityNodeIdRemapper } from './conversions'
+export { isFullSnapshotChangeRecordsEnabled, isIncrementalSnapshotChangeRecordsEnabled } from './experimentalFeatures'
+export { createChildInsertionCursor, createRootInsertionCursor } from './insertionCursor'
+export { getElementInputValue } from './serializationUtils'
+export { serializeFullSnapshot } from './serializeFullSnapshot'
+export { serializeFullSnapshotAsChange } from './serializeFullSnapshotAsChange'
+export { serializeMutations } from './serializeMutations'
+export { serializeMutationsAsChange } from './serializeMutationsAsChange'
+export { serializeNode } from './serializeNode'
+export { serializeNodeAsChange } from './serializeNodeAsChange'
+export { serializeAttribute } from './serializeAttribute'
+export { createSerializationStats, updateSerializationStats, aggregateSerializationStats } from './serializationStats'
+export type { SerializationMetric, SerializationStats } from './serializationStats'
+export { serializeChangesInTransaction, serializeInTransaction, SerializationKind } from './serializationTransaction'
+export type {
+  ChangeSerializationTransaction,
+  SerializationTransaction,
+  SerializationTransactionCallback,
+} from './serializationTransaction'
+export type { ParentNodePrivacyLevel } from './serialization.types'

package/src/domain/record/serialization/insertionCursor.ts

@@ -0,0 +1,131 @@
+import type { InsertionPoint } from '../../../types'
+import type { NodeId, NodeIds } from '../itemIds'
+
+/**
+ * InsertionCursor tracks the point at which the next node will be inserted during
+ * Change-style DOM serialization.
+ *
+ * When a new node is added to the document, we use an InsertionPoint to encode its
+ * position. There are often multiple equally-valid ways to express the same insertion
+ * point; we generally want to favor encodings that use as few characters as possible (to
+ * reduce uncompressed size) and that are as repetitive as possible (to reduce compressed
+ * size). InsertionCursor's purpose is to heuristically pick an efficient encoding based
+ * on the nodes we've recently serialized, while doing as little work as possible. The
+ * results are not optimal, but should be close to it in most situations.
+ *
+ * At the beginning of the serialization process, use a factory function like
+ * createRootInsertionCursor() to create a new cursor with an appropriate initial
+ * position.
+ *
+ * When visiting a node, the expected usage pattern is as follows:
+ * 1. Call advance() to get a node id and insertion point for the node.
+ * 2. Serialize the node.
+ * 3. If the node has no children, we're done; continue to the node's next
+ * sibling and apply this algorithm again.
+ * 4. Otherwise, call descend() to move the cursor into the node's child list.
+ * 5. Recursively apply this algorithm.
+ * 6. Call ascend() to move the cursor out of the node's child list. We're done;
+ * continue to the node's next sibling and apply this algorithm again.
+ */
+export interface InsertionCursor {
+  /**
+   * Given the node id for a new node, returns the InsertionPoint for that node.
+   * Updates the cursor to point to the new node's next sibling.
+   */
+  advance(node: Node): { nodeId: NodeId; insertionPoint: InsertionPoint }
+
+  /**
+   * Ascends out of the current child list and updates the cursor to point to the parent
+   * node's next sibling.
+   */
+  ascend(): void
+
+  /**
+   * Descends into the child list of the last node we inserted and updates the cursor to
+   * point to the node's first child.
+   */
+  descend(): void
+}
+
+/** Returns an InsertionCursor which starts positioned at the root of the document. */
+export function createRootInsertionCursor(nodeIds: NodeIds): InsertionCursor {
+  return createInsertionCursor(undefined, undefined, nodeIds)
+}
+
+/**
+ * Returns an InsertionCursor which starts positioned in the child list of the given
+ * parent node. If a next sibling is provided, the cursor points to the position
+ * immediately before the next sibling; otherwise, the cursor points to the end of the
+ * child list.
+ */
+export function createChildInsertionCursor(
+  parentId: NodeId,
+  nextSiblingId: NodeId | undefined,
+  nodeIds: NodeIds
+): InsertionCursor {
+  return createInsertionCursor(parentId, nextSiblingId, nodeIds)
+}
+
+function createInsertionCursor(
+  parentId: NodeId | undefined,
+  nextSiblingId: NodeId | undefined,
+  nodeIds: NodeIds
+): InsertionCursor {
+  interface ChildListCursor {
+    container: ChildListCursor | undefined
+    parentId: NodeId | undefined
+    previousSiblingId: NodeId | undefined
+    nextSiblingId: NodeId | undefined
+  }
+
+  let cursor: ChildListCursor = {
+    container: undefined,
+    parentId,
+    previousSiblingId: undefined,
+    nextSiblingId,
+  }
+
+  const computeInsertionPoint = (nodeId: NodeId): InsertionPoint => {
+    if (cursor.previousSiblingId === nodeId - 1) {
+      // Use an AppendAfterPreviousInsertionPoint. (i.e., 0)
+      return 0
+    }
+    if (cursor.nextSiblingId !== undefined) {
+      // Use an InsertBeforeInsertionPoint. We identify the next sibling using a
+      // negative integer indicating the difference between the new node's id and its next
+      // sibling's id.
+      return cursor.nextSiblingId - nodeId
+    }
+    if (cursor.parentId !== undefined) {
+      // Use an AppendChildInsertionPoint. We identify the parent node using a positive
+      // integer indicating the difference between the new node's id and its parent's id.
+      return nodeId - cursor.parentId
+    }
+    // There's no parent. Use a RootInsertionPoint. (i.e., null)
+    return null
+  }
+
+  return {
+    advance(node: Node): { nodeId: NodeId; insertionPoint: InsertionPoint } {
+      const nodeId = nodeIds.getOrInsert(node)
+      const insertionPoint = computeInsertionPoint(nodeId)
+      cursor.previousSiblingId = nodeId
+      return { nodeId, insertionPoint }
+    },
+    ascend(): void {
+      if (cursor.container) {
+        cursor = cursor.container
+      }
+    },
+    descend(): void {
+      if (cursor.previousSiblingId !== undefined) {
+        cursor = {
+          container: cursor,
+          parentId: cursor.previousSiblingId,
+          previousSiblingId: undefined,
+          nextSiblingId: undefined,
+        }
+      }
+    },
+  }
+}

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

@@ -0,0 +1,38 @@
+import type { NodePrivacyLevel } from '@datadog/browser-rum-core'
+
+// Those values are the only one that can be used when inheriting privacy levels from parent to
+// children during serialization, since HIDDEN and IGNORE shouldn't serialize their children. This
+// ensures that no children are serialized when they shouldn't.
+export type ParentNodePrivacyLevel =
+  | typeof NodePrivacyLevel.ALLOW
+  | typeof NodePrivacyLevel.MASK
+  | typeof NodePrivacyLevel.MASK_USER_INPUT
+  | typeof NodePrivacyLevel.MASK_UNLESS_ALLOWLISTED
+
+/**
+ * Virtual attributes. These attributes appear in the serialized attribute map of
+ * elements, but they're not actually derived from the DOM; they're used to represent
+ * metadata about the element they're attached to.
+ */
+export interface VirtualAttributes {
+  /**
+   * For <style> and <link> elements, the rules in the element's stylesheet, extracted
+   * from the CSSOM.
+   */
+  _cssText?: string
+
+  /** For <audio> and <video> elements, the playback state of the element's media. */
+  rr_mediaState?: 'paused' | 'played'
+
+  /** For elements which are scroll containers, the element's X scroll position, if non-zero. */
+  rr_scrollLeft?: number
+
+  /** For elements which are scroll containers, the element's Y scroll position, if non-zero. */
+  rr_scrollTop?: number
+
+  /** For HIDDEN elements, the width of the element's bounding client rect. */
+  rr_width?: string
+
+  /** For HIDDEN elements, the height of the element's bounding client rect. */
+  rr_height?: string
+}