@kubesense/kubesense-browser-rum-core 1.0.0

package/src/domain/lifeCycle.ts

@@ -0,0 +1,103 @@
+import type { Context, Duration, PageMayExitEvent, RawError, RelativeTime } from '@kubesense/kubesense-browser-core'
+import { AbstractLifeCycle } from '@kubesense/kubesense-browser-core'
+import type { RumEventDomainContext } from '../domainContext.types'
+import type { RawRumEvent, AssembledRumEvent } from '../rawRumEvent.types'
+import type { RequestCompleteEvent, RequestStartEvent } from './requestCollection'
+import type { AutoAction } from './action/actionCollection'
+import type { ViewEvent, ViewCreatedEvent, ViewEndedEvent, BeforeViewUpdateEvent } from './view/trackViews'
+
+export const enum LifeCycleEventType {
+  // Contexts (like viewHistory) should be opened using prefixed BEFORE_XXX events and closed using prefixed AFTER_XXX events
+  // It ensures the context is available during the non prefixed event callbacks
+  AUTO_ACTION_COMPLETED,
+  BEFORE_VIEW_CREATED,
+  VIEW_CREATED,
+  BEFORE_VIEW_UPDATED,
+  VIEW_UPDATED,
+  VIEW_ENDED,
+  AFTER_VIEW_ENDED,
+  REQUEST_STARTED,
+  REQUEST_COMPLETED,
+
+  // The SESSION_EXPIRED lifecycle event has been introduced to represent when a session has expired
+  // and trigger cleanup tasks related to this, prior to renewing the session. Its implementation is
+  // slightly naive: it is not triggered as soon as the session is expired, but rather just before
+  // notifying that the session is renewed. Thus, the session id is already set to the newly renewed
+  // session.
+  //
+  // This implementation is "good enough" for our use-cases. Improving this is not trivial,
+  // primarily because multiple instances of the SDK may be managing the same session cookie at
+  // the same time, for example when using Logs and RUM on the same page, or opening multiple tabs
+  // on the same domain.
+  SESSION_EXPIRED,
+  SESSION_RENEWED,
+  PAGE_MAY_EXIT,
+  RAW_RUM_EVENT_COLLECTED,
+  RUM_EVENT_COLLECTED,
+  RAW_ERROR_COLLECTED,
+}
+
+// This is a workaround for an issue occurring when the Browser SDK is included in a TypeScript
+// project configured with `isolatedModules: true`. Even if the const enum is declared in this
+// module, we cannot use it directly to define the EventMap interface keys (TS error: "Cannot access
+// ambient const enums when the '--isolatedModules' flag is provided.").
+//
+// Using a plain enum would fix the issue, but would also add 2KB to the minified bundle. By using
+// this workaround, we can keep using a const enum without impacting the bundle size (since it is a
+// "declare" statement, it will only be used during typecheck and completely ignored when building
+// JavaScript).
+//
+// See issues:
+// * https://github.com/DataDog/browser-sdk/issues/2208
+// * https://github.com/microsoft/TypeScript/issues/54152
+declare const LifeCycleEventTypeAsConst: {
+  AUTO_ACTION_COMPLETED: LifeCycleEventType.AUTO_ACTION_COMPLETED
+  BEFORE_VIEW_CREATED: LifeCycleEventType.BEFORE_VIEW_CREATED
+  VIEW_CREATED: LifeCycleEventType.VIEW_CREATED
+  BEFORE_VIEW_UPDATED: LifeCycleEventType.BEFORE_VIEW_UPDATED
+  VIEW_UPDATED: LifeCycleEventType.VIEW_UPDATED
+  VIEW_ENDED: LifeCycleEventType.VIEW_ENDED
+  AFTER_VIEW_ENDED: LifeCycleEventType.AFTER_VIEW_ENDED
+  REQUEST_STARTED: LifeCycleEventType.REQUEST_STARTED
+  REQUEST_COMPLETED: LifeCycleEventType.REQUEST_COMPLETED
+  SESSION_EXPIRED: LifeCycleEventType.SESSION_EXPIRED
+  SESSION_RENEWED: LifeCycleEventType.SESSION_RENEWED
+  PAGE_MAY_EXIT: LifeCycleEventType.PAGE_MAY_EXIT
+  RAW_RUM_EVENT_COLLECTED: LifeCycleEventType.RAW_RUM_EVENT_COLLECTED
+  RUM_EVENT_COLLECTED: LifeCycleEventType.RUM_EVENT_COLLECTED
+  RAW_ERROR_COLLECTED: LifeCycleEventType.RAW_ERROR_COLLECTED
+}
+
+// Note: this interface needs to be exported even if it is not used outside of this module, else TS
+// fails to build the rum-core package with error TS4058
+export interface LifeCycleEventMap {
+  [LifeCycleEventTypeAsConst.AUTO_ACTION_COMPLETED]: AutoAction
+  [LifeCycleEventTypeAsConst.BEFORE_VIEW_CREATED]: ViewCreatedEvent
+  [LifeCycleEventTypeAsConst.VIEW_CREATED]: ViewCreatedEvent
+  [LifeCycleEventTypeAsConst.BEFORE_VIEW_UPDATED]: BeforeViewUpdateEvent
+  [LifeCycleEventTypeAsConst.VIEW_UPDATED]: ViewEvent
+  [LifeCycleEventTypeAsConst.VIEW_ENDED]: ViewEndedEvent
+  [LifeCycleEventTypeAsConst.AFTER_VIEW_ENDED]: ViewEndedEvent
+  [LifeCycleEventTypeAsConst.REQUEST_STARTED]: RequestStartEvent
+  [LifeCycleEventTypeAsConst.REQUEST_COMPLETED]: RequestCompleteEvent
+  [LifeCycleEventTypeAsConst.SESSION_EXPIRED]: void
+  [LifeCycleEventTypeAsConst.SESSION_RENEWED]: void
+  [LifeCycleEventTypeAsConst.PAGE_MAY_EXIT]: PageMayExitEvent
+  [LifeCycleEventTypeAsConst.RAW_RUM_EVENT_COLLECTED]: RawRumEventCollectedData
+  [LifeCycleEventTypeAsConst.RUM_EVENT_COLLECTED]: AssembledRumEvent
+  [LifeCycleEventTypeAsConst.RAW_ERROR_COLLECTED]: {
+    error: RawError
+    customerContext?: Context
+  }
+}
+
+export interface RawRumEventCollectedData<E extends RawRumEvent = RawRumEvent> {
+  startTime: RelativeTime
+  duration?: Duration
+  customerContext?: Context
+  rawRumEvent: E
+  domainContext: RumEventDomainContext<E['type']>
+}
+
+export const LifeCycle = AbstractLifeCycle<LifeCycleEventMap>
+export type LifeCycle = AbstractLifeCycle<LifeCycleEventMap>

package/src/domain/limitModification.ts

@@ -0,0 +1,66 @@
+import { sanitize, deepClone, getType, objectEntries } from '@kubesense/kubesense-browser-core'
+import type { Context } from '@kubesense/kubesense-browser-core'
+
+export type ModifiableFieldPaths = Record<string, 'string' | 'object'>
+
+/**
+ * Allows declaring and enforcing modifications to specific fields of an object.
+ * Only supports modifying properties of an object (even if nested in an array).
+ * Does not support array manipulation (adding/removing items).
+ */
+export function limitModification<T extends Context, Result>(
+  object: T,
+  modifiableFieldPaths: ModifiableFieldPaths,
+  modifier: (object: T) => Result
+): Result | undefined {
+  const clone = deepClone(object)
+  const result = modifier(clone)
+
+  objectEntries(modifiableFieldPaths).forEach(([fieldPath, fieldType]) =>
+    // Traverse both object and clone simultaneously up to the path and apply the modification from the clone to the original object when the type is valid
+    setValueAtPath(object, clone, fieldPath.split(/\.|(?=\[\])/), fieldType)
+  )
+
+  return result
+}
+
+function setValueAtPath(object: unknown, clone: unknown, pathSegments: string[], fieldType: 'string' | 'object') {
+  const [field, ...restPathSegments] = pathSegments
+
+  if (field === '[]') {
+    if (Array.isArray(object) && Array.isArray(clone)) {
+      object.forEach((item, i) => setValueAtPath(item, clone[i], restPathSegments, fieldType))
+    }
+
+    return
+  }
+
+  if (!isValidObject(object) || !isValidObject(clone)) {
+    return
+  }
+
+  if (restPathSegments.length > 0) {
+    return setValueAtPath(object[field], clone[field], restPathSegments, fieldType)
+  }
+
+  setNestedValue(object, field, clone[field], fieldType)
+}
+
+function setNestedValue(
+  object: Record<string, unknown>,
+  field: string,
+  value: unknown,
+  fieldType: 'string' | 'object'
+) {
+  const newType = getType(value)
+
+  if (newType === fieldType) {
+    object[field] = sanitize(value)
+  } else if (fieldType === 'object' && (newType === 'undefined' || newType === 'null')) {
+    object[field] = {}
+  }
+}
+
+function isValidObject(object: unknown): object is Record<string, unknown> {
+  return getType(object) === 'object'
+}

package/src/domain/longTask/longTaskCollection.ts

@@ -0,0 +1,133 @@
+import type { RelativeTime, ClocksState, Duration } from '@kubesense/kubesense-browser-core'
+import {
+  toServerDuration,
+  relativeToClocks,
+  generateUUID,
+  createValueHistory,
+  SESSION_TIME_OUT_DELAY,
+  addDuration,
+} from '@kubesense/kubesense-browser-core'
+import type { RawRumLongTaskEvent, RawRumLongAnimationFrameEvent } from '../../rawRumEvent.types'
+import { RumEventType, RumLongTaskEntryType } from '../../rawRumEvent.types'
+import type { LifeCycle } from '../lifeCycle'
+import { LifeCycleEventType } from '../lifeCycle'
+import {
+  createPerformanceObservable,
+  RumPerformanceEntryType,
+  supportPerformanceTimingEvent,
+} from '../../browser/performanceObservable'
+import type {
+  RumPerformanceLongAnimationFrameTiming,
+  RumPerformanceLongTaskTiming,
+  RumPerformanceScriptTiming,
+} from '../../browser/performanceObservable'
+import type { RumConfiguration } from '../configuration'
+
+export const LONG_TASK_ID_HISTORY_TIME_OUT_DELAY = SESSION_TIME_OUT_DELAY
+
+export interface LongTaskContext {
+  id: string
+  startClocks: ClocksState
+  duration: Duration
+  entryType: RumPerformanceEntryType.LONG_ANIMATION_FRAME | RumPerformanceEntryType.LONG_TASK
+}
+
+export interface LongTaskContexts {
+  findLongTasks: (startTime: RelativeTime) => LongTaskContext[]
+}
+
+export function startLongTaskCollection(lifeCycle: LifeCycle, configuration: RumConfiguration) {
+  const history = createValueHistory<LongTaskContext>({
+    expireDelay: LONG_TASK_ID_HISTORY_TIME_OUT_DELAY,
+  })
+  const entryType = supportPerformanceTimingEvent(RumPerformanceEntryType.LONG_ANIMATION_FRAME)
+    ? RumPerformanceEntryType.LONG_ANIMATION_FRAME
+    : RumPerformanceEntryType.LONG_TASK
+
+  const subscription = createPerformanceObservable(configuration, {
+    type: entryType,
+    buffered: true,
+  }).subscribe((entries) => {
+    for (const entry of entries) {
+      if (!configuration.trackLongTasks) {
+        break
+      }
+
+      const startClocks = relativeToClocks(entry.startTime)
+      const taskId = generateUUID()
+      const rawRumEvent = processEntry(entry, startClocks, taskId)
+
+      lifeCycle.notify(LifeCycleEventType.RAW_RUM_EVENT_COLLECTED, {
+        rawRumEvent,
+        startTime: startClocks.relative,
+        duration: entry.duration,
+        domainContext: { performanceEntry: entry },
+      })
+
+      history.add({ id: taskId, startClocks, duration: entry.duration, entryType }, startClocks.relative)
+      history.closeActive(addDuration(startClocks.relative, entry.duration))
+    }
+  })
+
+  const longTaskContexts: LongTaskContexts = {
+    findLongTasks: (startTime: RelativeTime) => history.findAll(startTime),
+  }
+
+  return {
+    stop: () => {
+      subscription.unsubscribe()
+      history.stop()
+    },
+    longTaskContexts,
+  }
+}
+
+function processEntry(
+  entry: RumPerformanceLongTaskTiming | RumPerformanceLongAnimationFrameTiming,
+  startClocks: ClocksState,
+  taskId: string
+): RawRumLongTaskEvent | RawRumLongAnimationFrameEvent {
+  const baseEvent = {
+    date: startClocks.timeStamp,
+    type: RumEventType.LONG_TASK,
+    _kubesense: { discarded: false },
+  }
+
+  if (entry.entryType === RumPerformanceEntryType.LONG_TASK) {
+    return {
+      ...baseEvent,
+      long_task: {
+        id: taskId,
+        entry_type: RumLongTaskEntryType.LONG_TASK,
+        duration: toServerDuration(entry.duration),
+      },
+    }
+  }
+
+  return {
+    ...baseEvent,
+    long_task: {
+      id: taskId,
+      entry_type: RumLongTaskEntryType.LONG_ANIMATION_FRAME,
+      duration: toServerDuration(entry.duration),
+      blocking_duration: toServerDuration(entry.blockingDuration),
+      first_ui_event_timestamp: toServerDuration(entry.firstUIEventTimestamp),
+      render_start: toServerDuration(entry.renderStart),
+      style_and_layout_start: toServerDuration(entry.styleAndLayoutStart),
+      start_time: toServerDuration(entry.startTime),
+      scripts: entry.scripts.map((script: RumPerformanceScriptTiming) => ({
+        duration: toServerDuration(script.duration),
+        pause_duration: toServerDuration(script.pauseDuration),
+        forced_style_and_layout_duration: toServerDuration(script.forcedStyleAndLayoutDuration),
+        start_time: toServerDuration(script.startTime),
+        execution_start: toServerDuration(script.executionStart),
+        source_url: script.sourceURL,
+        source_function_name: script.sourceFunctionName,
+        source_char_position: script.sourceCharPosition,
+        invoker: script.invoker,
+        invoker_type: script.invokerType,
+        window_attribution: script.windowAttribution,
+      })),
+    },
+  }
+}

package/src/domain/plugins.ts

@@ -0,0 +1,59 @@
+import type { RumPublicApi, Strategy } from '../boot/rumPublicApi'
+import type { StartRumResult } from '../boot/startRum'
+import type { RumInitConfiguration } from './configuration'
+
+/**
+ * onRumStart plugin API options.
+ *
+ * @experimental
+ */
+export interface OnRumStartOptions {
+  /**
+   * @deprecated Use `addEvent` instead.
+   */
+  strategy?: Strategy
+  /**
+   * Add an event to the RUM browser SDK.
+   */
+  addEvent?: StartRumResult['addEvent']
+}
+
+/**
+ * Plugin interface of the RUM browser SDK.
+ *
+ * The plugins API is unstable and experimental, and may change without
+ * notice. Please use only plugins provided by Kubesense matching the version of the SDK you are
+ * using.
+ *
+ * @experimental
+ */
+export interface RumPlugin {
+  name: string
+  getConfigurationTelemetry?(): Record<string, unknown>
+  onInit?(options: { initConfiguration: RumInitConfiguration; publicApi: RumPublicApi }): void
+  onRumStart?(options: OnRumStartOptions): void
+}
+
+type MethodNames = 'onInit' | 'onRumStart'
+type MethodParameter<MethodName extends MethodNames> = Parameters<NonNullable<RumPlugin[MethodName]>>[0]
+
+export function callPluginsMethod<MethodName extends MethodNames>(
+  plugins: RumPlugin[] | undefined,
+  methodName: MethodName,
+  parameter: MethodParameter<MethodName>
+): void
+export function callPluginsMethod<MethodName extends MethodNames>(
+  plugins: RumPlugin[] | undefined,
+  methodName: MethodName,
+  parameter: any
+) {
+  if (!plugins) {
+    return
+  }
+  for (const plugin of plugins) {
+    const method = plugin[methodName]
+    if (method) {
+      method(parameter)
+    }
+  }
+}