@kubesense/kubesense-browser-rum-core 1.8.0 → 2.0.0-beta.1

package/src/domain/plugins.ts

@@ -1,59 +1,88 @@
-import type { RumPublicApi, Strategy } from '../boot/rumPublicApi'
+import { isThenable } from '@kubesense/kubesense-browser-core'
+import type { RumPublicApi } from '../boot/rumPublicApi'
 import type { StartRumResult } from '../boot/startRum'
 import type { RumInitConfiguration } from './configuration'
+import type { AssembleHook } from './hooks'
 
 /**
- * onRumStart plugin API options.
+ * onInit plugin API options.
  *
  * @experimental
  */
-export interface OnRumStartOptions {
+export interface RumPluginOnInitOptions {
+  initConfiguration: RumInitConfiguration
+  publicApi: RumPublicApi
   /**
-   * @deprecated Use `addEvent` instead.
+   * Register a callback invoked when a RUM event is assembled, so plugins can enrich or override
+   * event fields before they are sent. Callbacks registered in `onInit` run before any event is
+   * assembled, including events buffered during the pre-start phase.
    */
-  strategy?: Strategy
+  registerAssembleEventHook: AssembleHook['register']
+}
+
+/**
+ * onRumStart plugin API options.
+ *
+ * @experimental
+ */
+export interface OnRumStartOptions {
   /**
    * Add an event to the RUM browser SDK.
    */
   addEvent?: StartRumResult['addEvent']
+  /**
+   * Add a custom error to the RUM browser SDK.
+   */
+  addError?: StartRumResult['addError']
 }
 
 /**
  * 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
+ * notice. Please use only plugins provided by KubeSense matching the version of the SDK you are
  * using.
  *
+ * `onInit` may abort the SDK initialization by returning (or resolving to) `false`. All plugins'
+ * `onInit` are called concurrently and independently; a Promise defers the actual initialization
+ * until it resolves, but does not delay any other plugin's `onInit` call.
+ *
  * @experimental
  */
 export interface RumPlugin {
   name: string
   getConfigurationTelemetry?(): Record<string, unknown>
-  onInit?(options: { initConfiguration: RumInitConfiguration; publicApi: RumPublicApi }): void
+  onInit?(options: RumPluginOnInitOptions): false | void | Promise<false | 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>(
+/**
+ * Calls every plugin's `onInit` method concurrently, without waiting for one to resolve before
+ * calling the next. Stays synchronous as long as no plugin returns a thenable.
+ * Returns `false` if any plugin returned (or resolved to) `false`, `true` otherwise.
+ */
+export function callPluginsOnInit(
   plugins: RumPlugin[] | undefined,
-  methodName: MethodName,
-  parameter: any
-) {
+  parameter: RumPluginOnInitOptions
+): boolean | Promise<boolean> {
   if (!plugins) {
-    return
+    return true
+  }
+
+  const results = plugins.map((plugin) => plugin.onInit?.(parameter))
+
+  if (results.some(isThenable)) {
+    return Promise.all(results as Array<Promise<false | void>>).then((results) => !results.includes(false))
   }
-  for (const plugin of plugins) {
-    const method = plugin[methodName]
-    if (method) {
-      method(parameter)
-    }
+
+  return !results.includes(false)
+}
+
+/**
+ * Calls each plugin's `onRumStart` method in order.
+ */
+export function callPluginsOnRumStart(plugins: RumPlugin[] | undefined, options: OnRumStartOptions): void {
+  for (const plugin of plugins ?? []) {
+    plugin.onRumStart?.(options)
   }
 }

package/src/domain/privacy.ts

@@ -23,7 +23,7 @@ export function getNodePrivacyLevel(
   defaultPrivacyLevel: NodePrivacyLevel,
   cache?: NodePrivacyLevelCache
 ): NodePrivacyLevel {
-  if (cache && cache.has(node)) {
+  if (cache?.has(node)) {
     return cache.get(node)!
   }
   const parentNode = getParentNode(node)
@@ -216,48 +216,40 @@ function isFormElement(node: Node | null): boolean {
  * Text censoring non-destructively maintains whitespace characters in order to preserve text shape
  * during replay.
  */
-const censorText = (text: string) => text.replace(/\S/g, TEXT_MASKING_CHAR)
+export function censorText(text: string): string {
+  return text.replace(/\S/g, TEXT_MASKING_CHAR)
+}
 
-export function getTextContent(textNode: Node, parentNodePrivacyLevel: NodePrivacyLevel): string | undefined {
+export function getTextContent(textNode: Node, parentNodePrivacyLevel: NodePrivacyLevel): string {
   // The parent node may not be a html element which has a tagName attribute.
   // So just let it be undefined which is ok in this use case.
   const parentTagName = textNode.parentElement?.tagName
   let textContent = textNode.textContent || ''
-
-  const shouldIgnoreWhiteSpace = parentTagName === 'HEAD'
-  if (shouldIgnoreWhiteSpace && !textContent.trim()) {
-    return
-  }
-
   const nodePrivacyLevel = parentNodePrivacyLevel
 
-  const isScript = parentTagName === 'SCRIPT'
-
-  if (isScript) {
+  if (parentTagName === 'SCRIPT') {
     // For perf reasons, we don't record script (heuristic)
     textContent = CENSORED_STRING_MARK
   } else if (nodePrivacyLevel === NodePrivacyLevel.HIDDEN) {
     // Should never occur, but just in case, we set to CENSORED_MARK.
     textContent = CENSORED_STRING_MARK
   } else if (shouldMaskNode(textNode, nodePrivacyLevel)) {
-    if (
-      // Scrambling the child list breaks text nodes for DATALIST/SELECT/OPTGROUP
-      parentTagName === 'DATALIST' ||
-      parentTagName === 'SELECT' ||
-      parentTagName === 'OPTGROUP'
-    ) {
-      if (!textContent.trim()) {
-        return
-      }
+    if (parentTagName === 'DATALIST' || parentTagName === 'SELECT' || parentTagName === 'OPTGROUP') {
+      // Masking the child list breaks text nodes for DATALIST/SELECT/OPTGROUP.
+      // TODO: Reinvestigate this.
     } else if (parentTagName === 'OPTION') {
       // <Option> has low entropy in charset + text length, so use `CENSORED_STRING_MARK` when masked
       textContent = CENSORED_STRING_MARK
-    } else if (nodePrivacyLevel === NodePrivacyLevel.MASK_UNLESS_ALLOWLISTED) {
-      textContent = maskDisallowedTextContent(textContent)
     } else {
       textContent = censorText(textContent)
     }
   }
+
+  const shouldCollapseWhiteSpace = parentTagName === 'HEAD'
+  if (shouldCollapseWhiteSpace && !textContent.trim()) {
+    return ''
+  }
+
   return textContent
 }
 
@@ -339,7 +331,7 @@ export interface BrowserWindow extends Window {
 }
 
 export function isAllowlisted(text: string): boolean {
-  if (!text || !text.trim()) {
+  if (!text?.trim()) {
     return true
   }
   // We are using toLocaleLowerCase when adding to the allowlist to avoid case sensitivity

package/src/domain/requestCollection.ts

@@ -1,21 +1,23 @@
+import { elapsed, timeStampNow } from '@kubesense/kubesense-js-core/time'
+import type { Duration, ClocksState } from '@kubesense/kubesense-js-core/time'
 import type {
-  Duration,
   XhrCompleteContext,
   XhrStartContext,
-  ClocksState,
   FetchStartContext,
   FetchResolveContext,
   ContextManager,
+  SessionManager,
+  Observable,
+  BufferedData,
+  Subscription,
 } from '@kubesense/kubesense-browser-core'
 import {
   RequestType,
   ResponseBodyAction,
-  elapsed,
+  BufferedDataType,
   initFetchObservable,
   initXhrObservable,
-  timeStampNow,
 } from '@kubesense/kubesense-browser-core'
-import type { RumSessionManager } from '..'
 import type { RumConfiguration } from './configuration'
 import type { LifeCycle } from './lifeCycle'
 import { LifeCycleEventType } from './lifeCycle'
@@ -58,6 +60,7 @@ export interface RequestCompleteEvent {
   init?: RequestInit
   error?: Error
   isAborted: boolean
+  isAbortedOnStart: boolean
   handlingStack?: string
   requestBody?: unknown
   responseBody?: string
@@ -68,112 +71,120 @@ let nextRequestIndex = 1
 export function startRequestCollection(
   lifeCycle: LifeCycle,
   configuration: RumConfiguration,
-  sessionManager: RumSessionManager,
+  sessionManager: SessionManager,
   userContext: ContextManager,
-  accountContext: ContextManager
+  accountContext: ContextManager,
+  bufferedDataObservable: Observable<BufferedData>
 ) {
   const tracer = startTracer(configuration, sessionManager, userContext, accountContext)
-  trackXhr(lifeCycle, configuration, tracer)
-  trackFetch(lifeCycle, configuration, tracer)
+  trackXhr(lifeCycle, tracer, bufferedDataObservable)
+  trackFetch(lifeCycle, configuration, tracer, bufferedDataObservable)
 }
 
-export function trackXhr(lifeCycle: LifeCycle, configuration: RumConfiguration, tracer: Tracer) {
-  const subscription = initXhrObservable(configuration).subscribe((rawContext) => {
-    const context = rawContext as RumXhrStartContext | RumXhrCompleteContext
-    if (!isAllowedRequestUrl(context.url)) {
-      return
-    }
+export function trackXhr(lifeCycle: LifeCycle, tracer: Tracer, bufferedDataObservable: Observable<BufferedData>) {
+  const subscriptions: Subscription[] = []
 
-    switch (context.state) {
-      case 'start':
+  subscriptions.push(
+    initXhrObservable().subscribe((context) => {
+      if (context.state === 'start' && isAllowedRequestUrl(context.url)) {
         tracer.traceXhr(context, context.xhr)
-        context.requestIndex = getNextRequestIndex()
+        assignRequestIndex(context as RumXhrStartContext)
+      }
+    })
+  )
 
-        lifeCycle.notify(LifeCycleEventType.REQUEST_STARTED, {
-          requestIndex: context.requestIndex,
-          url: context.url,
-        })
-        break
-      case 'complete':
-        tracer.clearTracingIfNeeded(context)
-        lifeCycle.notify(LifeCycleEventType.REQUEST_COMPLETED, {
-          duration: context.duration,
-          method: context.method,
-          requestIndex: context.requestIndex,
-          spanId: context.spanId,
-          startClocks: context.startClocks,
-          status: context.status,
-          traceId: context.traceId,
-          traceSampled: context.traceSampled,
-          type: RequestType.XHR,
-          url: context.url,
-          xhr: context.xhr,
-          isAborted: context.isAborted,
-          handlingStack: context.handlingStack,
-          requestBody: context.requestBody,
-          responseBody: context.responseBody,
-        })
-        break
-    }
-  })
+  subscriptions.push(
+    bufferedDataObservable.subscribe(({ data, type }) => {
+      if (type !== BufferedDataType.XHR) {
+        return
+      }
+      const context = data as RumXhrStartContext | RumXhrCompleteContext
+      if (!isAllowedRequestUrl(context.url)) {
+        return
+      }
 
-  return { stop: () => subscription.unsubscribe() }
+      switch (context.state) {
+        case 'start':
+          assignRequestIndex(context)
+          lifeCycle.notify(LifeCycleEventType.REQUEST_STARTED, {
+            requestIndex: context.requestIndex,
+            url: context.url,
+          })
+          break
+        case 'complete':
+          tracer.clearTracingIfNeeded(context)
+          lifeCycle.notify(LifeCycleEventType.REQUEST_COMPLETED, {
+            ...context,
+            type: RequestType.XHR,
+            isAbortedOnStart: false,
+          })
+          break
+      }
+    })
+  )
+
+  return { stop: () => subscriptions.forEach((subscription) => subscription.unsubscribe()) }
 }
 
-export function trackFetch(lifeCycle: LifeCycle, configuration: RumConfiguration, tracer: Tracer) {
-  const subscription = initFetchObservable({
-    responseBodyAction: (context) => {
-      if (findGraphQlConfiguration(context.url, configuration)?.trackResponseErrors) {
-        return ResponseBodyAction.COLLECT
-      }
-      return ResponseBodyAction.WAIT
-    },
-  }).subscribe((rawContext) => {
-    const context = rawContext as RumFetchResolveContext | RumFetchStartContext
-    if (!isAllowedRequestUrl(context.url)) {
-      return
-    }
+export function trackFetch(
+  lifeCycle: LifeCycle,
+  configuration: RumConfiguration,
+  tracer: Tracer,
+  bufferedDataObservable: Observable<BufferedData>
+) {
+  const subscriptions: Subscription[] = []
 
-    switch (context.state) {
-      case 'start':
+  subscriptions.push(
+    initFetchObservable({
+      responseBodyAction: (context) => {
+        if (findGraphQlConfiguration(context.url, configuration)?.trackResponseErrors) {
+          return ResponseBodyAction.COLLECT
+        }
+        return ResponseBodyAction.IGNORE
+      },
+    }).subscribe((context) => {
+      if (context.state === 'start' && isAllowedRequestUrl(context.url)) {
         tracer.traceFetch(context)
-        context.requestIndex = getNextRequestIndex()
+        assignRequestIndex(context as RumFetchStartContext)
+      }
+    })
+  )
 
-        lifeCycle.notify(LifeCycleEventType.REQUEST_STARTED, {
-          requestIndex: context.requestIndex,
-          url: context.url,
-        })
-        break
-      case 'resolve':
-        tracer.clearTracingIfNeeded(context)
-        lifeCycle.notify(LifeCycleEventType.REQUEST_COMPLETED, {
-          duration: elapsed(context.startClocks.timeStamp, timeStampNow()),
-          method: context.method,
-          requestIndex: context.requestIndex,
-          responseType: context.responseType,
-          spanId: context.spanId,
-          startClocks: context.startClocks,
-          status: context.status,
-          traceId: context.traceId,
-          traceSampled: context.traceSampled,
-          type: RequestType.FETCH,
-          url: context.url,
-          response: context.response,
-          init: context.init,
-          input: context.input,
-          isAborted: context.isAborted,
-          handlingStack: context.handlingStack,
-          requestBody: context.init?.body,
-          responseBody: context.responseBody,
-        })
-        break
-    }
-  })
-  return { stop: () => subscription.unsubscribe() }
+  subscriptions.push(
+    bufferedDataObservable.subscribe(({ data, type }) => {
+      if (type !== BufferedDataType.FETCH) {
+        return
+      }
+      const context = data as RumFetchResolveContext | RumFetchStartContext
+      if (!isAllowedRequestUrl(context.url)) {
+        return
+      }
+
+      switch (context.state) {
+        case 'start':
+          assignRequestIndex(context)
+          lifeCycle.notify(LifeCycleEventType.REQUEST_STARTED, {
+            requestIndex: context.requestIndex,
+            url: context.url,
+          })
+          break
+        case 'resolve':
+          tracer.clearTracingIfNeeded(context)
+          lifeCycle.notify(LifeCycleEventType.REQUEST_COMPLETED, {
+            ...context,
+            duration: elapsed(context.startClocks.timeStamp, timeStampNow()),
+            type: RequestType.FETCH,
+            requestBody: context.init?.body,
+          })
+          break
+      }
+    })
+  )
+  return { stop: () => subscriptions.forEach((subscription) => subscription.unsubscribe()) }
 }
 
-function getNextRequestIndex() {
-  const result = nextRequestIndex
-  nextRequestIndex += 1
-  return result
+function assignRequestIndex(context: CustomContext) {
+  if (!context.requestIndex) {
+    context.requestIndex = nextRequestIndex++
+  }
 }

package/src/domain/resource/graphql.ts

@@ -1,4 +1,11 @@
-import { isNonEmptyArray, matchList, ONE_KIBI_BYTE, safeTruncate } from '@kubesense/kubesense-browser-core'
+import {
+  isNonEmptyArray,
+  matchList,
+  ONE_KIBI_BYTE,
+  safeTruncate,
+  tryJsonParse,
+} from '@kubesense/kubesense-browser-core'
+import { buildUrl } from '@kubesense/kubesense-js-core/util'
 import type { RumConfiguration, GraphQlUrlOption } from '../configuration'
 import type { RequestCompleteEvent } from '../requestCollection'
 
@@ -7,6 +14,13 @@ import type { RequestCompleteEvent } from '../requestCollection'
  */
 const GRAPHQL_PAYLOAD_LIMIT = 32 * ONE_KIBI_BYTE
 
+interface RawGraphQlMetadata {
+  query?: string
+  operationName?: string
+  variables?: string
+  operationType?: string
+}
+
 export interface GraphQlError {
   message: string
   code?: string
@@ -27,7 +41,7 @@ export function extractGraphQlMetadata(
   request: RequestCompleteEvent,
   graphQlConfig: GraphQlUrlOption
 ): GraphQlMetadata | undefined {
-  const metadata = extractGraphQlRequestMetadata(request.requestBody, graphQlConfig.trackPayload)
+  const metadata = extractGraphQlRequestMetadata(request, graphQlConfig.trackPayload)
   if (!metadata) {
     return
   }
@@ -44,13 +58,7 @@ export function extractGraphQlMetadata(
 }
 
 export function parseGraphQlResponse(responseText: string): GraphQlError[] | undefined {
-  let response: unknown
-  try {
-    response = JSON.parse(responseText)
-  } catch {
-    // Invalid JSON response
-    return
-  }
+  const response = tryJsonParse(responseText)
 
   if (!response || typeof response !== 'object') {
     return
@@ -81,50 +89,88 @@ export function findGraphQlConfiguration(url: string, configuration: RumConfigur
 }
 
 export function extractGraphQlRequestMetadata(
-  requestBody: unknown,
+  request: Pick<RequestCompleteEvent, 'method' | 'url' | 'requestBody'>,
   trackPayload: boolean = false
 ): GraphQlMetadata | undefined {
+  let rawMetadata: RawGraphQlMetadata | undefined
+
+  if (request.method === 'POST') {
+    rawMetadata = extractFromBody(request.requestBody)
+  } else if (request.method === 'GET') {
+    rawMetadata = extractFromUrlQueryParams(request.url)
+  }
+
+  if (!rawMetadata) {
+    return
+  }
+
+  return sanitizeGraphQlMetadata(rawMetadata, trackPayload)
+}
+
+function extractFromBody(requestBody: unknown): RawGraphQlMetadata | undefined {
   if (!requestBody || typeof requestBody !== 'string') {
     return
   }
 
-  let graphqlBody: {
+  const graphqlBody = tryJsonParse<{
     query?: string
     operationName?: string
     variables?: unknown
-  }
+    operationType?: string
+  }>(requestBody)
 
-  try {
-    graphqlBody = JSON.parse(requestBody)
-  } catch {
-    // Not valid JSON
+  if (!graphqlBody) {
     return
   }
 
-  if (!graphqlBody) {
-    return
+  return {
+    query: graphqlBody.query,
+    operationName: graphqlBody.operationName,
+    variables: graphqlBody.variables ? JSON.stringify(graphqlBody.variables) : undefined,
+    operationType: graphqlBody.operationType,
   }
+}
 
+function extractFromUrlQueryParams(url: string): RawGraphQlMetadata {
+  const searchParams = buildUrl(url).searchParams
+  const variablesParam = searchParams.get('variables')
+  const variables = variablesParam && tryJsonParse(variablesParam) !== undefined ? variablesParam : undefined
+
+  return {
+    query: searchParams.get('query') || undefined,
+    operationName: searchParams.get('operationName') || undefined,
+    variables,
+    operationType: searchParams.get('operationType') || undefined,
+  }
+}
+
+function sanitizeGraphQlMetadata(rawMetadata: RawGraphQlMetadata, trackPayload: boolean): GraphQlMetadata {
   let operationType: 'query' | 'mutation' | 'subscription' | undefined
   let payload: string | undefined
+  let variables: string | undefined
 
-  if (graphqlBody.query) {
-    const trimmedQuery = graphqlBody.query.trim()
+  if (rawMetadata.query) {
+    const trimmedQuery = rawMetadata.query.trim()
     operationType = getOperationType(trimmedQuery)
     if (trackPayload) {
       payload = safeTruncate(trimmedQuery, GRAPHQL_PAYLOAD_LIMIT, '...')
     }
   }
 
-  const operationName = graphqlBody.operationName
-  let variables: string | undefined
-  if (graphqlBody.variables) {
-    variables = JSON.stringify(graphqlBody.variables)
+  if (!operationType) {
+    const bodyType = rawMetadata.operationType
+    if (bodyType === 'query' || bodyType === 'mutation' || bodyType === 'subscription') {
+      operationType = bodyType
+    }
+  }
+
+  if (rawMetadata.variables) {
+    variables = rawMetadata.variables
   }
 
   return {
     operationType,
-    operationName,
+    operationName: rawMetadata.operationName,
     variables,
     payload,
   }

package/src/domain/resource/requestRegistry.ts

@@ -1,4 +1,3 @@
-import { addTelemetryDebug } from '@kubesense/kubesense-browser-core'
 import type { RumPerformanceResourceTiming } from '../../browser/performanceObservable'
 import type { LifeCycle } from '../lifeCycle'
 import { LifeCycleEventType } from '../lifeCycle'
@@ -18,9 +17,8 @@ export function createRequestRegistry(lifeCycle: LifeCycle): RequestRegistry {
 
   const subscription = lifeCycle.subscribe(LifeCycleEventType.REQUEST_COMPLETED, (request) => {
     requests.add(request)
+
     if (requests.size > MAX_REQUESTS) {
-      // monitor-until: 2026-01-01, after early request collection GA
-      addTelemetryDebug('Too many requests')
       requests.delete(requests.values().next().value!)
     }
   })