@kubesense/kubesense-browser-rum 1.0.0

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

@@ -0,0 +1,81 @@
+import type { TimeoutId, ClocksState } from '@kubesense/kubesense-browser-core'
+import type { LongTaskContext } from '@kubesense/kubesense-browser-rum-core'
+import type { ProfilerTrace, Profiler } from './profilerApi.types'
+
+export interface RumViewEntry {
+  /** Detected start time of view */
+  readonly startClocks: ClocksState
+  /** RUM view id */
+  readonly viewId: string
+  /** RUM view name */
+  readonly viewName: string | undefined
+}
+
+/**
+ * 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[]
+}
+
+export interface RumProfilerTrace extends ProfilerTrace, RumProfilerEnrichmentData {
+  /** High resolution time when profiler trace started, relative to the profiling session's time origin */
+  readonly startClocks: ClocksState
+  /** High resolution time when profiler trace ended, relative to the profiling session's time origin */
+  readonly endClocks: ClocksState
+  /** Time origin of the profiling session */
+  readonly clocksOrigin: ClocksState
+  /** Sample interval in milliseconds */
+  readonly sampleInterval: number
+}
+
+/**
+ * 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: () => Promise<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,16 @@
+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/record/assembly.ts

@@ -0,0 +1,17 @@
+import { timeStampNow } from '@kubesense/kubesense-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'>
+): BrowserIncrementalSnapshotRecord {
+  return {
+    data: {
+      source,
+      ...data,
+    } as Data,
+    type: RecordType.IncrementalSnapshot,
+    timestamp: timeStampNow(),
+  }
+}

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/eventIds.ts

@@ -0,0 +1,17 @@
+export interface EventIds {
+  getIdForEvent(event: Event): number
+}
+
+export function createEventIds(): EventIds {
+  const eventIds = new WeakMap<Event, number>()
+  let nextId = 1
+
+  return {
+    getIdForEvent(event: Event): number {
+      if (!eventIds.has(event)) {
+        eventIds.set(event, nextId++)
+      }
+      return eventIds.get(event)!
+    },
+  }
+}

package/src/domain/record/eventsUtils.ts

@@ -0,0 +1,12 @@
+import { isNodeShadowHost } from '@kubesense/kubesense-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,7 @@
+export { takeFullSnapshot, takeNodeSnapshot } from './internalApi'
+export { record } from './record'
+export type { SerializationMetric, SerializationStats } from './serialization'
+export { createSerializationStats, aggregateSerializationStats } from './serialization'
+export { serializeNode, serializeDocument } from './serialization'
+export { createElementsScrollPositions } from './elementsScrollPositions'
+export type { ShadowRootsController } from './shadowRootsController'

package/src/domain/record/internalApi.ts

@@ -0,0 +1,88 @@
+import { noop, timeStampNow } from '@kubesense/kubesense-browser-core'
+import type { RumConfiguration } from '@kubesense/kubesense-browser-rum-core'
+import { getNodePrivacyLevel, NodePrivacyLevel } from '@kubesense/kubesense-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 { createEventIds } from './eventIds'
+import { createNodeIds } from './nodeIds'
+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 Kubesense browser SDK
+ * would generate.
+ *
+ * This is an internal API function. Be sure to update kubesense-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
+ * kubesense browser SDK would generate.
+ *
+ * This is an internal API function. Be sure to update Kubesense-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(),
+    createEventIds(),
+    createNodeIds(),
+    {
+      addShadowRoot: noop,
+      removeShadowRoot: noop,
+      flush: noop,
+      stop: noop,
+    } as ShadowRootsController
+  )
+}

package/src/domain/record/mutationBatch.ts

@@ -0,0 +1,47 @@
+import { noop, throttle, requestIdleCallback } from '@kubesense/kubesense-browser-core'
+import type { RumMutationRecord } from '@kubesense/kubesense-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/nodeIds.ts

@@ -0,0 +1,46 @@
+import { getParentNode, isNodeShadowRoot } from '@kubesense/kubesense-browser-rum-core'
+
+export type NodeWithSerializedNode = Node & { __brand: 'NodeWithSerializedNode' }
+export type NodeId = number & { __brand: 'NodeId' }
+
+export const enum NodeIdConstants {
+  FIRST_ID = 0,
+}
+
+export interface NodeIds {
+  assign(node: Node): NodeId
+  get(node: Node): NodeId | undefined
+  areAssignedForNodeAndAncestors(node: Node): node is NodeWithSerializedNode
+}
+
+export function createNodeIds(): NodeIds {
+  const nodeIds = new WeakMap<Node, NodeId>()
+  let nextNodeId = NodeIdConstants.FIRST_ID
+
+  const get = (node: Node): NodeId | undefined => nodeIds.get(node)
+
+  return {
+    assign: (node: Node): NodeId => {
+      // Try to reuse any existing id.
+      let nodeId = get(node)
+      if (nodeId === undefined) {
+        nodeId = nextNodeId++ as NodeId
+        nodeIds.set(node, nodeId)
+      }
+      return nodeId
+    },
+
+    get,
+
+    areAssignedForNodeAndAncestors: (node: Node): node is NodeWithSerializedNode => {
+      let current: Node | null = node
+      while (current) {
+        if (get(current) === undefined && !isNodeShadowRoot(current)) {
+          return false
+        }
+        current = getParentNode(current)
+      }
+      return true
+    },
+  }
+}

package/src/domain/record/record.ts

@@ -0,0 +1,98 @@
+import { sendToExtension } from '@kubesense/kubesense-browser-core'
+import type { LifeCycle, RumConfiguration, ViewHistory } from '@kubesense/kubesense-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 { createEventIds } from './eventIds'
+import { createNodeIds } from './nodeIds'
+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(),
+    createEventIds(),
+    createNodeIds(),
+    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,5 @@
+import type { BrowserRecord } from '../../types'
+import type { SerializationStats } from './serialization'
+
+export type EmitRecordCallback<Record extends BrowserRecord = BrowserRecord> = (record: Record) => void
+export type EmitStatsCallback = (stats: SerializationStats) => void

package/src/domain/record/recordingScope.ts

@@ -0,0 +1,36 @@
+import type { RumConfiguration } from '@kubesense/kubesense-browser-rum-core'
+
+import type { ElementsScrollPositions } from './elementsScrollPositions'
+import type { EventIds } from './eventIds'
+import type { NodeIds } from './nodeIds'
+import type { ShadowRootsController } from './shadowRootsController'
+
+/**
+ * State associated with a stream of session replay records. When a new stream of records
+ * starts (e.g. because recording has shut down and restarted), a new RecordingScope
+ * object must be created; this ensures that we don't generate records that reference ids
+ * or data which aren't present in the current stream.
+ */
+export interface RecordingScope {
+  configuration: RumConfiguration
+  elementsScrollPositions: ElementsScrollPositions
+  eventIds: EventIds
+  nodeIds: NodeIds
+  shadowRootsController: ShadowRootsController
+}
+
+export function createRecordingScope(
+  configuration: RumConfiguration,
+  elementsScrollPositions: ElementsScrollPositions,
+  eventIds: EventIds,
+  nodeIds: NodeIds,
+  shadowRootsController: ShadowRootsController
+): RecordingScope {
+  return {
+    configuration,
+    elementsScrollPositions,
+    eventIds,
+    nodeIds,
+    shadowRootsController,
+  }
+}

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

@@ -0,0 +1,8 @@
+export { getElementInputValue } from './serializationUtils'
+export { serializeDocument } from './serializeDocument'
+export { serializeNode } from './serializeNode'
+export { serializeAttribute } from './serializeAttribute'
+export { createSerializationStats, updateSerializationStats, aggregateSerializationStats } from './serializationStats'
+export type { SerializationMetric, SerializationStats } from './serializationStats'
+export { serializeInTransaction, SerializationKind } from './serializationTransaction'
+export type { SerializationTransaction, SerializationTransactionCallback } from './serializationTransaction'

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

@@ -0,0 +1,43 @@
+import type { NodePrivacyLevel } from '@kubesense/kubesense-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
+}
+
+export interface SerializeOptions {
+  /** For HIDDEN elements, the height of the element's bounding client rect. */
+  rr_height?: string
+}

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

@@ -0,0 +1,43 @@
+export interface SerializationMetric {
+  count: number
+  max: number
+  sum: number
+}
+
+export interface SerializationStats {
+  cssText: SerializationMetric
+  serializationDuration: SerializationMetric
+}
+
+export function createSerializationStats(): SerializationStats {
+  return {
+    cssText: {
+      count: 0,
+      max: 0,
+      sum: 0,
+    },
+    serializationDuration: {
+      count: 0,
+      max: 0,
+      sum: 0,
+    },
+  }
+}
+
+export function updateSerializationStats(
+  stats: SerializationStats,
+  metric: keyof SerializationStats,
+  value: number
+): void {
+  stats[metric].count += 1
+  stats[metric].max = Math.max(stats[metric].max, value)
+  stats[metric].sum += value
+}
+
+export function aggregateSerializationStats(aggregateStats: SerializationStats, stats: SerializationStats) {
+  for (const metric of ['cssText', 'serializationDuration'] as const) {
+    aggregateStats[metric].count += stats[metric].count
+    aggregateStats[metric].max = Math.max(aggregateStats[metric].max, stats[metric].max)
+    aggregateStats[metric].sum += stats[metric].sum
+  }
+}