@kubesense/kubesense-browser-rum-core 1.0.0

package/src/domain/contexts/viewHistory.ts

@@ -0,0 +1,70 @@
+import type { RelativeTime, ClocksState, Context } from '@kubesense/kubesense-browser-core'
+import { SESSION_TIME_OUT_DELAY, createValueHistory } from '@kubesense/kubesense-browser-core'
+import type { LifeCycle } from '../lifeCycle'
+import { LifeCycleEventType } from '../lifeCycle'
+import type { BeforeViewUpdateEvent, ViewCreatedEvent } from '../view/trackViews'
+
+export const VIEW_CONTEXT_TIME_OUT_DELAY = SESSION_TIME_OUT_DELAY
+
+export interface ViewHistoryEntry {
+  service?: string
+  version?: string
+  context?: Context | undefined
+  id: string
+  name?: string
+  startClocks: ClocksState
+  sessionIsActive?: boolean
+}
+
+export interface ViewHistory {
+  findView: (startTime?: RelativeTime) => ViewHistoryEntry | undefined
+  stop: () => void
+}
+
+export function startViewHistory(lifeCycle: LifeCycle): ViewHistory {
+  const viewValueHistory = createValueHistory<ViewHistoryEntry>({ expireDelay: VIEW_CONTEXT_TIME_OUT_DELAY })
+
+  lifeCycle.subscribe(LifeCycleEventType.BEFORE_VIEW_CREATED, (view) => {
+    viewValueHistory.add(buildViewHistoryEntry(view), view.startClocks.relative)
+  })
+
+  lifeCycle.subscribe(LifeCycleEventType.AFTER_VIEW_ENDED, ({ endClocks }) => {
+    viewValueHistory.closeActive(endClocks.relative)
+  })
+
+  lifeCycle.subscribe(LifeCycleEventType.BEFORE_VIEW_UPDATED, (viewUpdate: BeforeViewUpdateEvent) => {
+    const currentView = viewValueHistory.find(viewUpdate.startClocks.relative)
+    if (!currentView) {
+      return
+    }
+    if (viewUpdate.name) {
+      currentView.name = viewUpdate.name
+    }
+    if (viewUpdate.context) {
+      currentView.context = viewUpdate.context
+    }
+    currentView.sessionIsActive = viewUpdate.sessionIsActive
+  })
+
+  lifeCycle.subscribe(LifeCycleEventType.SESSION_RENEWED, () => {
+    viewValueHistory.reset()
+  })
+
+  function buildViewHistoryEntry(view: ViewCreatedEvent) {
+    return {
+      service: view.service,
+      version: view.version,
+      context: view.context,
+      id: view.id,
+      name: view.name,
+      startClocks: view.startClocks,
+    }
+  }
+
+  return {
+    findView: (startTime) => viewValueHistory.find(startTime),
+    stop: () => {
+      viewValueHistory.stop()
+    },
+  }
+}

package/src/domain/discardNegativeDuration.ts

@@ -0,0 +1,6 @@
+import type { ServerDuration } from '@kubesense/kubesense-browser-core'
+import { isNumber } from '@kubesense/kubesense-browser-core'
+
+export function discardNegativeDuration(duration: ServerDuration | undefined): ServerDuration | undefined {
+  return isNumber(duration) && duration < 0 ? undefined : duration
+}

package/src/domain/error/errorCollection.ts

@@ -0,0 +1,107 @@
+import type { Context, RawError, ClocksState, BufferedData } from '@kubesense/kubesense-browser-core'
+import {
+  BufferedDataType,
+  Observable,
+  ErrorSource,
+  generateUUID,
+  computeRawError,
+  ErrorHandling,
+  NonErrorPrefix,
+  combine,
+} from '@kubesense/kubesense-browser-core'
+import type { RumConfiguration } from '../configuration'
+import type { RawRumErrorEvent } from '../../rawRumEvent.types'
+import { RumEventType } from '../../rawRumEvent.types'
+import type { LifeCycle, RawRumEventCollectedData } from '../lifeCycle'
+import { LifeCycleEventType } from '../lifeCycle'
+import type { RumErrorEventDomainContext } from '../../domainContext.types'
+import { trackConsoleError } from './trackConsoleError'
+import { trackReportError } from './trackReportError'
+
+export interface ProvidedError {
+  startClocks: ClocksState
+  error: unknown
+  context?: Context
+  handlingStack: string
+  componentStack?: string
+}
+
+export function startErrorCollection(
+  lifeCycle: LifeCycle,
+  configuration: RumConfiguration,
+  bufferedDataObservable: Observable<BufferedData>
+) {
+  const errorObservable = new Observable<RawError>()
+
+  bufferedDataObservable.subscribe((bufferedData) => {
+    if (bufferedData.type === BufferedDataType.RUNTIME_ERROR) {
+      errorObservable.notify(bufferedData.error)
+    }
+  })
+
+  trackConsoleError(errorObservable)
+  trackReportError(configuration, errorObservable)
+
+  errorObservable.subscribe((error) => lifeCycle.notify(LifeCycleEventType.RAW_ERROR_COLLECTED, { error }))
+
+  return doStartErrorCollection(lifeCycle)
+}
+
+export function doStartErrorCollection(lifeCycle: LifeCycle) {
+  lifeCycle.subscribe(LifeCycleEventType.RAW_ERROR_COLLECTED, ({ error }) => {
+    lifeCycle.notify(LifeCycleEventType.RAW_RUM_EVENT_COLLECTED, processError(error))
+  })
+
+  return {
+    addError: ({ error, handlingStack, componentStack, startClocks, context }: ProvidedError) => {
+      const rawError = computeRawError({
+        originalError: error,
+        handlingStack,
+        componentStack,
+        startClocks,
+        nonErrorPrefix: NonErrorPrefix.PROVIDED,
+        source: ErrorSource.CUSTOM,
+        handling: ErrorHandling.HANDLED,
+      })
+      rawError.context = combine(rawError.context, context)
+
+      lifeCycle.notify(LifeCycleEventType.RAW_ERROR_COLLECTED, { error: rawError })
+    },
+  }
+}
+
+function processError(error: RawError): RawRumEventCollectedData<RawRumErrorEvent> {
+  const rawRumEvent: RawRumErrorEvent = {
+    date: error.startClocks.timeStamp,
+    error: {
+      id: generateUUID(),
+      message: error.message,
+      source: error.source,
+      stack: error.stack,
+      handling_stack: error.handlingStack,
+      component_stack: error.componentStack,
+      type: error.type,
+      handling: error.handling,
+      causes: error.causes,
+      source_type: 'browser',
+      fingerprint: error.fingerprint,
+      csp: error.csp,
+    },
+    _kubesense: {
+      discarded: false,
+    },
+    type: RumEventType.ERROR,
+    context: error.context,
+  }
+
+  const domainContext: RumErrorEventDomainContext = {
+    error: error.originalError,
+    handlingStack: error.handlingStack,
+  }
+
+  return {
+    rawRumEvent,
+    startTime: error.startClocks.relative,
+    domainContext,
+  }
+}

package/src/domain/error/trackConsoleError.ts

@@ -0,0 +1,14 @@
+import type { Observable, RawError } from '@kubesense/kubesense-browser-core'
+import { initConsoleObservable, ConsoleApiName } from '@kubesense/kubesense-browser-core'
+
+export function trackConsoleError(errorObservable: Observable<RawError>) {
+  const subscription = initConsoleObservable([ConsoleApiName.error]).subscribe((consoleLog) =>
+    errorObservable.notify(consoleLog.error)
+  )
+
+  return {
+    stop: () => {
+      subscription.unsubscribe()
+    },
+  }
+}

package/src/domain/error/trackReportError.ts

@@ -0,0 +1,16 @@
+import type { Observable, RawError } from '@kubesense/kubesense-browser-core'
+import { initReportObservable, RawReportType } from '@kubesense/kubesense-browser-core'
+import type { RumConfiguration } from '../configuration'
+
+export function trackReportError(configuration: RumConfiguration, errorObservable: Observable<RawError>) {
+  const subscription = initReportObservable(configuration, [
+    RawReportType.cspViolation,
+    RawReportType.intervention,
+  ]).subscribe((rawError) => errorObservable.notify(rawError))
+
+  return {
+    stop: () => {
+      subscription.unsubscribe()
+    },
+  }
+}

package/src/domain/event/eventCollection.ts

@@ -0,0 +1,53 @@
+import type { Context, Duration, RelativeTime } from '@kubesense/kubesense-browser-core'
+import type { RumEventDomainContext } from '../../domainContext.types'
+import type { LifeCycle } from '../lifeCycle'
+import { LifeCycleEventType } from '../lifeCycle'
+
+import type {
+  RawRumActionEvent,
+  RawRumErrorEvent,
+  RawRumLongAnimationFrameEvent,
+  RawRumLongTaskEvent,
+  RawRumResourceEvent,
+  RawRumVitalEvent,
+} from '../../rawRumEvent.types'
+import { RumEventType } from '../../rawRumEvent.types'
+
+const allowedEventTypes = [
+  RumEventType.ACTION,
+  RumEventType.ERROR,
+  RumEventType.LONG_TASK,
+  RumEventType.RESOURCE,
+  RumEventType.VITAL,
+] as const
+
+export type AllowedRawRumEvent = (
+  | RawRumErrorEvent
+  | RawRumResourceEvent
+  | RawRumLongTaskEvent
+  | RawRumLongAnimationFrameEvent
+  | RawRumActionEvent
+  | RawRumVitalEvent
+) & { context?: Context }
+
+export function startEventCollection(lifeCycle: LifeCycle) {
+  return {
+    addEvent: (
+      startTime: RelativeTime,
+      event: AllowedRawRumEvent,
+      domainContext: RumEventDomainContext,
+      duration?: Duration
+    ) => {
+      if (!allowedEventTypes.includes(event.type)) {
+        return
+      }
+
+      lifeCycle.notify(LifeCycleEventType.RAW_RUM_EVENT_COLLECTED, {
+        startTime,
+        rawRumEvent: event,
+        domainContext,
+        duration,
+      })
+    },
+  }
+}

package/src/domain/getSelectorFromElement.ts

@@ -0,0 +1,268 @@
+import { DEFAULT_PROGRAMMATIC_ACTION_NAME_ATTRIBUTE } from './action/actionNameConstants'
+
+/**
+ * Stable attributes are attributes that are commonly used to identify parts of a UI (ex:
+ * component). Those attribute values should not be generated randomly (hardcoded most of the time)
+ * and stay the same across deploys. They are not necessarily unique across the document.
+ */
+export const STABLE_ATTRIBUTES = [
+  DEFAULT_PROGRAMMATIC_ACTION_NAME_ATTRIBUTE,
+  // Common test attributes (list provided by google recorder)
+  'data-testid',
+  'data-test',
+  'data-qa',
+  'data-cy',
+  'data-test-id',
+  'data-qa-id',
+  'data-testing',
+  // FullStory decorator attributes:
+  'data-component',
+  'data-element',
+  'data-source-file',
+]
+
+type SelectorGetter = (element: Element, actionNameAttribute: string | undefined) => string | undefined
+
+// Selectors to use if they target a single element on the whole document. Those selectors are
+// considered as "stable" and uniquely identify an element regardless of the page state. If we find
+// one, we should consider the selector "complete" and stop iterating over ancestors.
+const GLOBALLY_UNIQUE_SELECTOR_GETTERS: SelectorGetter[] = [getStableAttributeSelector, getIDSelector]
+
+// Selectors to use if they target a single element among an element descendants. Those selectors
+// are more brittle than "globally unique" selectors and should be combined with ancestor selectors
+// to improve specificity.
+const UNIQUE_AMONG_CHILDREN_SELECTOR_GETTERS: SelectorGetter[] = [
+  getStableAttributeSelector,
+  getClassSelector,
+  getTagNameSelector,
+]
+
+export function getSelectorFromElement(
+  targetElement: Element,
+  actionNameAttribute: string | undefined
+): string | undefined {
+  if (!targetElement.isConnected) {
+    // We cannot compute a selector for a detached element, as we don't have access to all of its
+    // parents, and we cannot determine if it's unique in the document.
+    return
+  }
+  let targetElementSelector: string | undefined
+  let currentElement: Element | null = targetElement
+
+  while (currentElement && currentElement.nodeName !== 'HTML') {
+    const globallyUniqueSelector = findSelector(
+      currentElement,
+      GLOBALLY_UNIQUE_SELECTOR_GETTERS,
+      isSelectorUniqueGlobally,
+      actionNameAttribute,
+      targetElementSelector
+    )
+    if (globallyUniqueSelector) {
+      return globallyUniqueSelector
+    }
+
+    const uniqueSelectorAmongChildren = findSelector(
+      currentElement,
+      UNIQUE_AMONG_CHILDREN_SELECTOR_GETTERS,
+      isSelectorUniqueAmongSiblings,
+      actionNameAttribute,
+      targetElementSelector
+    )
+    targetElementSelector =
+      uniqueSelectorAmongChildren || combineSelector(getPositionSelector(currentElement), targetElementSelector)
+
+    currentElement = currentElement.parentElement
+  }
+
+  return targetElementSelector
+}
+
+function isGeneratedValue(value: string) {
+  // To compute the "URL path group", the backend replaces every URL path parts as a question mark
+  // if it thinks the part is an identifier. The condition it uses is to checks whether a digit is
+  // present.
+  //
+  // Here, we use the same strategy: if the value contains a digit, we consider it generated. This
+  // strategy might be a bit naive and fail in some cases, but there are many fallbacks to generate
+  // CSS selectors so it should be fine most of the time.
+  return /[0-9]/.test(value)
+}
+
+function getIDSelector(element: Element): string | undefined {
+  if (element.id && !isGeneratedValue(element.id)) {
+    return `#${CSS.escape(element.id)}`
+  }
+}
+
+function getClassSelector(element: Element): string | undefined {
+  if (element.tagName === 'BODY') {
+    return
+  }
+  const classList = element.classList
+  for (let i = 0; i < classList.length; i += 1) {
+    const className = classList[i]
+    if (isGeneratedValue(className)) {
+      continue
+    }
+
+    return `${CSS.escape(element.tagName)}.${CSS.escape(className)}`
+  }
+}
+
+function getTagNameSelector(element: Element): string {
+  return CSS.escape(element.tagName)
+}
+
+function getStableAttributeSelector(element: Element, actionNameAttribute: string | undefined): string | undefined {
+  if (actionNameAttribute) {
+    const selector = getAttributeSelector(actionNameAttribute)
+    if (selector) {
+      return selector
+    }
+  }
+
+  for (const attributeName of STABLE_ATTRIBUTES) {
+    const selector = getAttributeSelector(attributeName)
+    if (selector) {
+      return selector
+    }
+  }
+
+  function getAttributeSelector(attributeName: string) {
+    if (element.hasAttribute(attributeName)) {
+      return `${CSS.escape(element.tagName)}[${attributeName}="${CSS.escape(element.getAttribute(attributeName)!)}"]`
+    }
+  }
+}
+
+function getPositionSelector(element: Element): string {
+  let sibling = element.parentElement!.firstElementChild
+  let elementIndex = 1
+
+  while (sibling && sibling !== element) {
+    if (sibling.tagName === element.tagName) {
+      elementIndex += 1
+    }
+    sibling = sibling.nextElementSibling
+  }
+
+  return `${CSS.escape(element.tagName)}:nth-of-type(${elementIndex})`
+}
+
+function findSelector(
+  element: Element,
+  selectorGetters: SelectorGetter[],
+  predicate: (element: Element, elementSelector: string, childSelector: string | undefined) => boolean,
+  actionNameAttribute: string | undefined,
+  childSelector: string | undefined
+) {
+  for (const selectorGetter of selectorGetters) {
+    const elementSelector = selectorGetter(element, actionNameAttribute)
+    if (!elementSelector) {
+      continue
+    }
+    if (predicate(element, elementSelector, childSelector)) {
+      return combineSelector(elementSelector, childSelector)
+    }
+  }
+}
+
+/**
+ * Check whether the selector is unique among the whole document.
+ */
+function isSelectorUniqueGlobally(
+  element: Element,
+  elementSelector: string,
+  childSelector: string | undefined
+): boolean {
+  return element.ownerDocument.querySelectorAll(combineSelector(elementSelector, childSelector)).length === 1
+}
+
+/**
+ * Check whether the selector is unique among the element siblings. In other words, it returns true
+ * if "ELEMENT_PARENT > CHILD_SELECTOR" returns a single element.
+ *
+ * @param {Element} currentElement - the element being considered while iterating over the target
+ * element ancestors.
+ *
+ * @param {string} currentElementSelector - a selector that matches the current element. That
+ * selector is not a composed selector (i.e. it might be a single tag name, class name...).
+ *
+ * @param {string|undefined} childSelector - child selector is a selector that targets a descendant
+ * of the current element. When undefined, the current element is the target element.
+ *
+ * # Scope selector usage
+ *
+ * When composed together, the final selector will be joined with `>` operators to make sure we
+ * target direct descendants at each level. In this function, we'll use `querySelector` to check if
+ * a selector matches descendants of the current element. But by default, the query selector match
+ * elements at any level. Example:
+ *
+ * ```html
+ * <main>
+ *   <div>
+ *     <span></span>
+ *   </div>
+ *   <marquee>
+ *     <div>
+ *       <span></span>
+ *     </div>
+ *   </marquee>
+ * </main>
+ * ```
+ *
+ * `sibling.querySelector('DIV > SPAN')` will match both span elements, so we would consider the
+ * selector to be not unique, even if it is unique when we'll compose it with the parent with a `>`
+ * operator (`MAIN > DIV > SPAN`).
+ *
+ * To avoid this, we can use the `:scope` selector to make sure the selector starts from the current
+ * sibling (i.e. `sibling.querySelector('DIV:scope > SPAN')` will only match the first span).
+ *
+ * [1]: https://developer.mozilla.org/fr/docs/Web/CSS/:scope
+ *
+ * # Performance considerations
+ *
+ * We compute selectors in performance-critical operations (ex: during a click), so we need to make
+ * sure the function is as fast as possible. We observed that naively using `querySelectorAll` to
+ * check if the selector matches more than 1 element is quite expensive, so we want to avoid it.
+ *
+ * Because we are iterating the DOM upward and we use that function at every level, we know the
+ * child selector is already unique among the current element children, so we don't need to check
+ * for the current element subtree.
+ *
+ * Instead, we can focus on the current element siblings. If we find a single element matching the
+ * selector within a sibling, we know that it's not unique. This allows us to use `querySelector`
+ * (or `matches`, when the current element is the target element) instead of `querySelectorAll`.
+ */
+export function isSelectorUniqueAmongSiblings(
+  currentElement: Element,
+  currentElementSelector: string,
+  childSelector: string | undefined
+): boolean {
+  let isSiblingMatching: (sibling: Element) => boolean
+
+  if (childSelector === undefined) {
+    // If the child selector is undefined (meaning `currentElement` is the target element, not one
+    // of its ancestor), we need to use `matches` to check if the sibling is matching the selector,
+    // as `querySelector` only returns a descendant of the element.
+    isSiblingMatching = (sibling) => sibling.matches(currentElementSelector)
+  } else {
+    const scopedSelector = combineSelector(`${currentElementSelector}:scope`, childSelector)
+    isSiblingMatching = (sibling) => sibling.querySelector(scopedSelector) !== null
+  }
+
+  const parent = currentElement.parentElement!
+  let sibling = parent.firstElementChild
+  while (sibling) {
+    if (sibling !== currentElement && isSiblingMatching(sibling)) {
+      return false
+    }
+    sibling = sibling.nextElementSibling
+  }
+
+  return true
+}
+
+function combineSelector(parent: string, child: string | undefined): string {
+  return child ? `${parent}>${child}` : parent
+}

package/src/domain/getSessionReplayUrl.ts

@@ -0,0 +1,47 @@
+import { INTAKE_SITE_STAGING, INTAKE_SITE_PROD } from '@kubesense/kubesense-browser-core'
+import type { RumConfiguration } from './configuration'
+import type { ViewHistoryEntry } from './contexts/viewHistory'
+import type { RumSession } from './rumSessionManager'
+
+export function getSessionReplayUrl(
+  configuration: RumConfiguration,
+  {
+    session,
+    viewContext,
+    errorType,
+  }: {
+    session?: RumSession
+    viewContext?: ViewHistoryEntry
+    errorType?: string
+  }
+): string {
+  const sessionId = session ? session.id : 'no-session-id'
+  const parameters: string[] = []
+  if (errorType !== undefined) {
+    parameters.push(`error-type=${errorType}`)
+  }
+  if (viewContext) {
+    parameters.push(`seed=${viewContext.id}`)
+    parameters.push(`from=${viewContext.startClocks.timeStamp}`)
+  }
+
+  const origin = getKubsesenseSiteUrl(configuration)
+  const path = `/rum/replay/sessions/${sessionId}`
+  return `${origin}${path}?${parameters.join('&')}`
+}
+
+export function getKubsesenseSiteUrl(rumConfiguration: RumConfiguration) {
+  const site = rumConfiguration.kubesenseRumEndpoint
+  const subdomain = rumConfiguration.subdomain 
+  return `https://${subdomain ? `${subdomain}.` : ''}${site}`
+}
+
+function getSiteDefaultSubdomain(configuration: RumConfiguration): string | undefined {
+  switch (configuration.kubesenseRumEndpoint) {
+    case INTAKE_SITE_PROD:
+    case INTAKE_SITE_STAGING:
+      return 'staging'
+    default:
+      return undefined
+  }
+}

package/src/domain/hooks.ts

@@ -0,0 +1,31 @@
+import type {
+  DISCARDED,
+  Duration,
+  HookNamesAsConst,
+  RecursivePartial,
+  RelativeTime,
+  SKIPPED,
+  TelemetryEvent,
+} from '@kubesense/kubesense-browser-core'
+import { abstractHooks } from '@kubesense/kubesense-browser-core'
+import type { RumEvent } from '../rumEvent.types'
+
+// Define a partial RUM event type.
+// Ensuring the `type` field is always present improves type checking, especially in conditional logic in hooks (e.g., `if (eventType === 'view')`).
+export type DefaultRumEventAttributes = RecursivePartial<RumEvent> & { type: RumEvent['type'] }
+export type DefaultTelemetryEventAttributes = RecursivePartial<TelemetryEvent>
+
+export interface HookCallbackMap {
+  [HookNamesAsConst.ASSEMBLE]: (param: {
+    eventType: RumEvent['type']
+    startTime: RelativeTime
+    duration?: Duration | undefined
+  }) => DefaultRumEventAttributes | SKIPPED | DISCARDED
+  [HookNamesAsConst.ASSEMBLE_TELEMETRY]: (param: {
+    startTime: RelativeTime
+  }) => DefaultTelemetryEventAttributes | SKIPPED | DISCARDED
+}
+
+export type Hooks = ReturnType<typeof createHooks>
+
+export const createHooks = abstractHooks<HookCallbackMap>