@kubesense/kubesense-browser-rum 1.0.0

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

@@ -0,0 +1,18 @@
+import type { StyleSheet } from '../../../types'
+
+export function serializeStyleSheets(cssStyleSheets: CSSStyleSheet[] | undefined): StyleSheet[] | undefined {
+  if (cssStyleSheets === undefined || cssStyleSheets.length === 0) {
+    return undefined
+  }
+  return cssStyleSheets.map((cssStyleSheet) => {
+    const rules = cssStyleSheet.cssRules || cssStyleSheet.rules
+    const cssRules = Array.from(rules, (cssRule) => cssRule.cssText)
+
+    const styleSheet: StyleSheet = {
+      cssRules,
+      disabled: cssStyleSheet.disabled || undefined,
+      media: cssStyleSheet.media.length > 0 ? Array.from(cssStyleSheet.media) : undefined,
+    }
+    return styleSheet
+  })
+}

package/src/domain/record/shadowRootsController.ts

@@ -0,0 +1,62 @@
+import type { RecordingScope } from './recordingScope.ts'
+import type { EmitRecordCallback, EmitStatsCallback } from './record.types'
+import { trackInput, trackMutation, trackScroll } from './trackers'
+
+interface ShadowRootController {
+  stop: () => void
+  flush: () => void
+}
+
+export type AddShadowRootCallBack = (shadowRoot: ShadowRoot, scope: RecordingScope) => void
+export type RemoveShadowRootCallBack = (shadowRoot: ShadowRoot) => void
+
+export interface ShadowRootsController {
+  addShadowRoot: AddShadowRootCallBack
+  removeShadowRoot: RemoveShadowRootCallBack
+  stop: () => void
+  flush: () => void
+}
+
+export const initShadowRootsController = (
+  emitRecord: EmitRecordCallback,
+  emitStats: EmitStatsCallback
+): ShadowRootsController => {
+  const controllerByShadowRoot = new Map<ShadowRoot, ShadowRootController>()
+
+  const shadowRootsController: ShadowRootsController = {
+    addShadowRoot: (shadowRoot: ShadowRoot, scope: RecordingScope) => {
+      if (controllerByShadowRoot.has(shadowRoot)) {
+        return
+      }
+      const mutationTracker = trackMutation(shadowRoot, emitRecord, emitStats, scope)
+      // The change event does not bubble up across the shadow root, we have to listen on the shadow root
+      const inputTracker = trackInput(shadowRoot, emitRecord, scope)
+      // The scroll event does not bubble up across the shadow root, we have to listen on the shadow root
+      const scrollTracker = trackScroll(shadowRoot, emitRecord, scope)
+      controllerByShadowRoot.set(shadowRoot, {
+        flush: () => mutationTracker.flush(),
+        stop: () => {
+          mutationTracker.stop()
+          inputTracker.stop()
+          scrollTracker.stop()
+        },
+      })
+    },
+    removeShadowRoot: (shadowRoot: ShadowRoot) => {
+      const entry = controllerByShadowRoot.get(shadowRoot)
+      if (!entry) {
+        // unidentified root cause: observed in some cases with shadow DOM added by browser extensions
+        return
+      }
+      entry.stop()
+      controllerByShadowRoot.delete(shadowRoot)
+    },
+    stop: () => {
+      controllerByShadowRoot.forEach(({ stop }) => stop())
+    },
+    flush: () => {
+      controllerByShadowRoot.forEach(({ flush }) => flush())
+    },
+  }
+  return shadowRootsController
+}

package/src/domain/record/startFullSnapshots.ts

@@ -0,0 +1,84 @@
+import { LifeCycleEventType, getScrollX, getScrollY, getViewportDimension } from '@kubesense/kubesense-browser-rum-core'
+import type { LifeCycle } from '@kubesense/kubesense-browser-rum-core'
+import { timeStampNow } from '@kubesense/kubesense-browser-core'
+import type { TimeStamp } from '@kubesense/kubesense-browser-core'
+import { RecordType } from '../../types'
+import type { SerializationTransaction } from './serialization'
+import { serializeDocument, serializeInTransaction, SerializationKind } from './serialization'
+import { getVisualViewport } from './viewports'
+import type { RecordingScope } from './recordingScope'
+import type { EmitRecordCallback, EmitStatsCallback } from './record.types'
+
+export function startFullSnapshots(
+  lifeCycle: LifeCycle,
+  emitRecord: EmitRecordCallback,
+  emitStats: EmitStatsCallback,
+  flushMutations: () => void,
+  scope: RecordingScope
+) {
+  takeFullSnapshot(timeStampNow(), SerializationKind.INITIAL_FULL_SNAPSHOT, emitRecord, emitStats, scope)
+
+  const { unsubscribe } = lifeCycle.subscribe(LifeCycleEventType.VIEW_CREATED, (view) => {
+    flushMutations()
+    takeFullSnapshot(
+      view.startClocks.timeStamp,
+      SerializationKind.SUBSEQUENT_FULL_SNAPSHOT,
+      emitRecord,
+      emitStats,
+      scope
+    )
+  })
+
+  return {
+    stop: unsubscribe,
+  }
+}
+
+export function takeFullSnapshot(
+  timestamp: TimeStamp,
+  kind: SerializationKind,
+  emitRecord: EmitRecordCallback,
+  emitStats: EmitStatsCallback,
+  scope: RecordingScope
+): void {
+  serializeInTransaction(kind, emitRecord, emitStats, scope, (transaction: SerializationTransaction): void => {
+    const { width, height } = getViewportDimension()
+    transaction.add({
+      data: {
+        height,
+        href: window.location.href,
+        width,
+      },
+      type: RecordType.Meta,
+      timestamp,
+    })
+
+    transaction.add({
+      data: {
+        has_focus: document.hasFocus(),
+      },
+      type: RecordType.Focus,
+      timestamp,
+    })
+
+    transaction.add({
+      data: {
+        node: serializeDocument(document, transaction),
+        initialOffset: {
+          left: getScrollX(),
+          top: getScrollY(),
+        },
+      },
+      type: RecordType.FullSnapshot,
+      timestamp,
+    })
+
+    if (window.visualViewport) {
+      transaction.add({
+        data: getVisualViewport(window.visualViewport),
+        type: RecordType.VisualViewport,
+        timestamp,
+      })
+    }
+  })
+}

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

@@ -0,0 +1,12 @@
+export { trackMove } from './trackMove'
+export { trackMouseInteraction } from './trackMouseInteraction'
+export { trackScroll } from './trackScroll'
+export { trackViewportResize, trackVisualViewportResize } from './trackViewportResize'
+export { trackMediaInteraction } from './trackMediaInteraction'
+export { trackStyleSheet } from './trackStyleSheet'
+export { trackFocus } from './trackFocus'
+export { trackFrustration } from './trackFrustration'
+export { trackViewEnd } from './trackViewEnd'
+export { trackInput } from './trackInput'
+export { trackMutation } from './trackMutation'
+export type { Tracker } from './tracker.types'

package/src/domain/record/trackers/trackFocus.ts

@@ -0,0 +1,16 @@
+import { DOM_EVENT, addEventListeners, timeStampNow } from '@kubesense/kubesense-browser-core'
+import type { FocusRecord } from '../../../types'
+import { RecordType } from '../../../types'
+import type { RecordingScope } from '../recordingScope'
+import type { EmitRecordCallback } from '../record.types'
+import type { Tracker } from './tracker.types'
+
+export function trackFocus(emitRecord: EmitRecordCallback<FocusRecord>, scope: RecordingScope): Tracker {
+  return addEventListeners(scope.configuration, window, [DOM_EVENT.FOCUS, DOM_EVENT.BLUR], () => {
+    emitRecord({
+      data: { has_focus: document.hasFocus() },
+      type: RecordType.Focus,
+      timestamp: timeStampNow(),
+    })
+  })
+}

package/src/domain/record/trackers/trackFrustration.ts

@@ -0,0 +1,41 @@
+import type { LifeCycle } from '@kubesense/kubesense-browser-rum-core'
+import { ActionType, RumEventType, LifeCycleEventType } from '@kubesense/kubesense-browser-rum-core'
+import type { FrustrationRecord } from '../../../types'
+import { RecordType } from '../../../types'
+import type { EmitRecordCallback } from '../record.types'
+import type { RecordingScope } from '../recordingScope'
+import type { Tracker } from './tracker.types'
+
+export type FrustrationCallback = (record: FrustrationRecord) => void
+
+export function trackFrustration(
+  lifeCycle: LifeCycle,
+  emitRecord: EmitRecordCallback<FrustrationRecord>,
+  scope: RecordingScope
+): Tracker {
+  const frustrationSubscription = lifeCycle.subscribe(LifeCycleEventType.RAW_RUM_EVENT_COLLECTED, (data) => {
+    if (
+      data.rawRumEvent.type === RumEventType.ACTION &&
+      data.rawRumEvent.action.type === ActionType.CLICK &&
+      data.rawRumEvent.action.frustration?.type?.length &&
+      'events' in data.domainContext &&
+      data.domainContext.events &&
+      data.domainContext.events.length
+    ) {
+      emitRecord({
+        timestamp: data.rawRumEvent.date,
+        type: RecordType.FrustrationRecord,
+        data: {
+          frustrationTypes: data.rawRumEvent.action.frustration.type,
+          recordIds: data.domainContext.events.map((e) => scope.eventIds.getIdForEvent(e)),
+        },
+      })
+    }
+  })
+
+  return {
+    stop: () => {
+      frustrationSubscription.unsubscribe()
+    },
+  }
+}

package/src/domain/record/trackers/trackInput.ts

@@ -0,0 +1,128 @@
+import { instrumentSetter, DOM_EVENT, addEventListeners, noop } from '@kubesense/kubesense-browser-core'
+import { NodePrivacyLevel, getNodePrivacyLevel, shouldMaskNode } from '@kubesense/kubesense-browser-rum-core'
+import { IncrementalSource } from '../../../types'
+import type { InputData, InputState } from '../../../types'
+import { getEventTarget } from '../eventsUtils'
+import type { RecordingScope } from '../recordingScope'
+import { getElementInputValue } from '../serialization'
+import { assembleIncrementalSnapshot } from '../assembly'
+import type { EmitRecordCallback } from '../record.types'
+import type { Tracker } from './tracker.types'
+
+export function trackInput(
+  target: Document | ShadowRoot,
+  emitRecord: EmitRecordCallback,
+  scope: RecordingScope
+): Tracker {
+  const defaultPrivacyLevel = scope.configuration.defaultPrivacyLevel
+  const lastInputStateMap: WeakMap<Node, InputState> = new WeakMap()
+
+  const isShadowRoot = target !== document
+
+  const { stop: stopEventListeners } = addEventListeners(
+    scope.configuration,
+    target,
+    // The 'input' event bubbles across shadow roots, so we don't have to listen for it on shadow
+    // roots since it will be handled by the event listener that we did add to the document. Only
+    // the 'change' event is blocked and needs to be handled on shadow roots.
+    isShadowRoot ? [DOM_EVENT.CHANGE] : [DOM_EVENT.INPUT, DOM_EVENT.CHANGE],
+    (event) => {
+      const target = getEventTarget(event)
+      if (
+        target instanceof HTMLInputElement ||
+        target instanceof HTMLTextAreaElement ||
+        target instanceof HTMLSelectElement
+      ) {
+        onElementChange(target)
+      }
+    },
+    {
+      capture: true,
+      passive: true,
+    }
+  )
+
+  let stopPropertySetterInstrumentation: () => void
+  if (!isShadowRoot) {
+    const instrumentationStoppers = [
+      instrumentSetter(HTMLInputElement.prototype, 'value', onElementChange),
+      instrumentSetter(HTMLInputElement.prototype, 'checked', onElementChange),
+      instrumentSetter(HTMLSelectElement.prototype, 'value', onElementChange),
+      instrumentSetter(HTMLTextAreaElement.prototype, 'value', onElementChange),
+      instrumentSetter(HTMLSelectElement.prototype, 'selectedIndex', onElementChange),
+    ]
+    stopPropertySetterInstrumentation = () => {
+      instrumentationStoppers.forEach((stopper) => stopper.stop())
+    }
+  } else {
+    stopPropertySetterInstrumentation = noop
+  }
+
+  return {
+    stop: () => {
+      stopPropertySetterInstrumentation()
+      stopEventListeners()
+    },
+  }
+
+  function onElementChange(target: HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement) {
+    const nodePrivacyLevel = getNodePrivacyLevel(target, defaultPrivacyLevel)
+    if (nodePrivacyLevel === NodePrivacyLevel.HIDDEN) {
+      return
+    }
+
+    const type = target.type
+
+    let inputState: InputState
+    if (type === 'radio' || type === 'checkbox') {
+      if (shouldMaskNode(target, nodePrivacyLevel)) {
+        return
+      }
+      inputState = { isChecked: (target as HTMLInputElement).checked }
+    } else {
+      const value = getElementInputValue(target, nodePrivacyLevel)
+      if (value === undefined) {
+        return
+      }
+      inputState = { text: value }
+    }
+
+    // Can be multiple changes on the same node within the same batched mutation observation.
+    createRecordIfStateChanged(target, inputState)
+
+    // If a radio was checked, other radios with the same name attribute will be unchecked.
+    const name = target.name
+    if (type === 'radio' && name && (target as HTMLInputElement).checked) {
+      document.querySelectorAll(`input[type="radio"][name="${CSS.escape(name)}"]`).forEach((el: Element) => {
+        if (el !== target) {
+          // TODO: Consider the privacy implications for various differing input privacy levels
+          createRecordIfStateChanged(el, { isChecked: false })
+        }
+      })
+    }
+  }
+
+  /**
+   * There can be multiple changes on the same node within the same batched mutation observation.
+   */
+  function createRecordIfStateChanged(target: Node, inputState: InputState) {
+    const id = scope.nodeIds.get(target)
+    if (id === undefined) {
+      return
+    }
+    const lastInputState = lastInputStateMap.get(target)
+    if (
+      !lastInputState ||
+      (lastInputState as { text?: string }).text !== (inputState as { text?: string }).text ||
+      (lastInputState as { isChecked?: boolean }).isChecked !== (inputState as { isChecked?: boolean }).isChecked
+    ) {
+      lastInputStateMap.set(target, inputState)
+      emitRecord(
+        assembleIncrementalSnapshot<InputData>(IncrementalSource.Input, {
+          id,
+          ...inputState,
+        })
+      )
+    }
+  }
+}

package/src/domain/record/trackers/trackMediaInteraction.ts

@@ -0,0 +1,43 @@
+import { DOM_EVENT, addEventListeners } from '@kubesense/kubesense-browser-core'
+import { NodePrivacyLevel, getNodePrivacyLevel } from '@kubesense/kubesense-browser-rum-core'
+import type { MediaInteractionData, BrowserIncrementalSnapshotRecord } from '../../../types'
+import { IncrementalSource, MediaInteractionType } from '../../../types'
+import { getEventTarget } from '../eventsUtils'
+import { assembleIncrementalSnapshot } from '../assembly'
+import type { EmitRecordCallback } from '../record.types'
+import type { RecordingScope } from '../recordingScope'
+import type { Tracker } from './tracker.types'
+
+export function trackMediaInteraction(
+  emitRecord: EmitRecordCallback<BrowserIncrementalSnapshotRecord>,
+  scope: RecordingScope
+): Tracker {
+  return addEventListeners(
+    scope.configuration,
+    document,
+    [DOM_EVENT.PLAY, DOM_EVENT.PAUSE],
+    (event) => {
+      const target = getEventTarget(event)
+      if (!target) {
+        return
+      }
+      const id = scope.nodeIds.get(target)
+      if (
+        id === undefined ||
+        getNodePrivacyLevel(target, scope.configuration.defaultPrivacyLevel) === NodePrivacyLevel.HIDDEN
+      ) {
+        return
+      }
+      emitRecord(
+        assembleIncrementalSnapshot<MediaInteractionData>(IncrementalSource.MediaInteraction, {
+          id,
+          type: event.type === DOM_EVENT.PLAY ? MediaInteractionType.Play : MediaInteractionType.Pause,
+        })
+      )
+    },
+    {
+      capture: true,
+      passive: true,
+    }
+  )
+}

package/src/domain/record/trackers/trackMouseInteraction.ts

@@ -0,0 +1,74 @@
+import { addEventListeners, DOM_EVENT } from '@kubesense/kubesense-browser-core'
+import { getNodePrivacyLevel, NodePrivacyLevel } from '@kubesense/kubesense-browser-rum-core'
+import type { MouseInteraction, MouseInteractionData, BrowserIncrementalSnapshotRecord } from '../../../types'
+import { IncrementalSource, MouseInteractionType } from '../../../types'
+import { assembleIncrementalSnapshot } from '../assembly'
+import { getEventTarget } from '../eventsUtils'
+import type { RecordingScope } from '../recordingScope'
+import type { EmitRecordCallback } from '../record.types'
+import { tryToComputeCoordinates } from './trackMove'
+import type { Tracker } from './tracker.types'
+
+const eventTypeToMouseInteraction = {
+  // Listen for pointerup DOM events instead of mouseup for MouseInteraction/MouseUp records. This
+  // allows to reference such records from Frustration records.
+  //
+  // In the context of supporting Mobile Session Replay, we introduced `PointerInteraction` records
+  // used by the Mobile SDKs in place of `MouseInteraction`. In the future, we should replace
+  // `MouseInteraction` by `PointerInteraction` in the Browser SDK so we have an uniform way to
+  // convey such interaction. This would cleanly solve the issue since we would have
+  // `PointerInteraction/Up` records that we could reference from `Frustration` records.
+  [DOM_EVENT.POINTER_UP]: MouseInteractionType.MouseUp,
+
+  [DOM_EVENT.MOUSE_DOWN]: MouseInteractionType.MouseDown,
+  [DOM_EVENT.CLICK]: MouseInteractionType.Click,
+  [DOM_EVENT.CONTEXT_MENU]: MouseInteractionType.ContextMenu,
+  [DOM_EVENT.DBL_CLICK]: MouseInteractionType.DblClick,
+  [DOM_EVENT.FOCUS]: MouseInteractionType.Focus,
+  [DOM_EVENT.BLUR]: MouseInteractionType.Blur,
+  [DOM_EVENT.TOUCH_START]: MouseInteractionType.TouchStart,
+  [DOM_EVENT.TOUCH_END]: MouseInteractionType.TouchEnd,
+}
+
+export function trackMouseInteraction(
+  emitRecord: EmitRecordCallback<BrowserIncrementalSnapshotRecord>,
+  scope: RecordingScope
+): Tracker {
+  const handler = (event: MouseEvent | TouchEvent | FocusEvent) => {
+    const target = getEventTarget(event)
+    const id = scope.nodeIds.get(target)
+    if (
+      id === undefined ||
+      getNodePrivacyLevel(target, scope.configuration.defaultPrivacyLevel) === NodePrivacyLevel.HIDDEN
+    ) {
+      return
+    }
+    const type = eventTypeToMouseInteraction[event.type as keyof typeof eventTypeToMouseInteraction]
+
+    let interaction: MouseInteraction
+    if (type !== MouseInteractionType.Blur && type !== MouseInteractionType.Focus) {
+      const coordinates = tryToComputeCoordinates(event as MouseEvent | TouchEvent)
+      if (!coordinates) {
+        return
+      }
+      interaction = { id, type, x: coordinates.x, y: coordinates.y }
+    } else {
+      interaction = { id, type }
+    }
+
+    emitRecord({
+      id: scope.eventIds.getIdForEvent(event),
+      ...assembleIncrementalSnapshot<MouseInteractionData>(IncrementalSource.MouseInteraction, interaction),
+    })
+  }
+  return addEventListeners(
+    scope.configuration,
+    document,
+    Object.keys(eventTypeToMouseInteraction) as Array<keyof typeof eventTypeToMouseInteraction>,
+    handler,
+    {
+      capture: true,
+      passive: true,
+    }
+  )
+}

package/src/domain/record/trackers/trackMove.ts

@@ -0,0 +1,78 @@
+import { addEventListeners, DOM_EVENT, throttle } from '@kubesense/kubesense-browser-core'
+import type { BrowserIncrementalSnapshotRecord, MousemoveData, MousePosition } from '../../../types'
+import { IncrementalSource } from '../../../types'
+import { getEventTarget, isTouchEvent } from '../eventsUtils'
+import { convertMouseEventToLayoutCoordinates } from '../viewports'
+import { assembleIncrementalSnapshot } from '../assembly'
+import type { RecordingScope } from '../recordingScope'
+import type { EmitRecordCallback } from '../record.types'
+import type { Tracker } from './tracker.types'
+
+const MOUSE_MOVE_OBSERVER_THRESHOLD = 50
+
+export function trackMove(
+  emitRecord: EmitRecordCallback<BrowserIncrementalSnapshotRecord>,
+  scope: RecordingScope
+): Tracker {
+  const { throttled: updatePosition, cancel: cancelThrottle } = throttle(
+    (event: MouseEvent | TouchEvent) => {
+      const target = getEventTarget(event)
+      const id = scope.nodeIds.get(target)
+      if (id === undefined) {
+        return
+      }
+      const coordinates = tryToComputeCoordinates(event)
+      if (!coordinates) {
+        return
+      }
+      const position: MousePosition = {
+        id,
+        timeOffset: 0,
+        x: coordinates.x,
+        y: coordinates.y,
+      }
+
+      emitRecord(
+        assembleIncrementalSnapshot<MousemoveData>(
+          isTouchEvent(event) ? IncrementalSource.TouchMove : IncrementalSource.MouseMove,
+          { positions: [position] }
+        )
+      )
+    },
+    MOUSE_MOVE_OBSERVER_THRESHOLD,
+    {
+      trailing: false,
+    }
+  )
+
+  const { stop: removeListener } = addEventListeners(
+    scope.configuration,
+    document,
+    [DOM_EVENT.MOUSE_MOVE, DOM_EVENT.TOUCH_MOVE],
+    updatePosition,
+    {
+      capture: true,
+      passive: true,
+    }
+  )
+
+  return {
+    stop: () => {
+      removeListener()
+      cancelThrottle()
+    },
+  }
+}
+
+export function tryToComputeCoordinates(event: MouseEvent | TouchEvent) {
+  let { clientX: x, clientY: y } = isTouchEvent(event) ? event.changedTouches[0] : event
+  if (window.visualViewport) {
+    const { visualViewportX, visualViewportY } = convertMouseEventToLayoutCoordinates(x, y)
+    x = visualViewportX
+    y = visualViewportY
+  }
+  if (!Number.isFinite(x) || !Number.isFinite(y)) {
+    return undefined
+  }
+  return { x, y }
+}