@kubesense/kubesense-browser-rum-core 1.4.0 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubesense/kubesense-browser-rum-core",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "Shared RUM event-collection logic for the Kubesense Browser SDK (consumed by the rum and rum-slim packages).",
   "license": "Apache-2.0",
   "keywords": [
@@ -19,7 +19,7 @@
     "build": "node ../../scripts/build/build-package.ts --modules"
   },
   "dependencies": {
-    "@kubesense/kubesense-browser-core": "1.4.0"
+    "@kubesense/kubesense-browser-core": "1.6.0"
   },
   "devDependencies": {
     "ajv": "8.17.1"
@@ -35,5 +35,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "af1a0950e2441f45b4303b2dc17b09f9cd0d999d"
+  "gitHead": "5b90a5a0ea4ee972c079b9a55c45d05c44f14688"
 }

package/src/boot/preStartRum.ts

@@ -24,6 +24,8 @@ import {
   validateAndBuildRumConfiguration,
   fetchAndApplyRemoteConfiguration,
   serializeRumConfiguration,
+  applyCachedSdkConfiguration,
+  scheduleSdkConfigurationRefresh,
 } from '../domain/configuration'
 import type { ViewOptions } from '../domain/view/trackViews'
 import type {
@@ -105,6 +107,22 @@ export function createPreStartStrategy(
       initConfiguration = overrideInitConfigurationForBridge(initConfiguration)
     }
 
+    const remoteSdkConfigurationEnabled = !!initConfiguration.enableRemoteSdkConfiguration
+    if (remoteSdkConfigurationEnabled) {
+      // Reading the cached document is synchronous and network-free, so it does not delay
+      // initialization. The document fetched below only applies from the next page load.
+      const cachedSdkConfiguration = applyCachedSdkConfiguration(initConfiguration)
+      initConfiguration = cachedSdkConfiguration.initConfiguration
+
+      if (!cachedSdkConfiguration.rumEnabled) {
+        // RUM is switched off from the dashboard. Still refresh the document, otherwise the
+        // switch would be one-way: the SDK could never learn that it has been turned back on.
+        cachedInitConfiguration = initConfiguration
+        scheduleSdkConfigurationRefresh(initConfiguration).catch(monitorError)
+        return
+      }
+    }
+
     // Update the exposed initConfiguration to reflect the bridge and remote configuration overrides
     cachedInitConfiguration = initConfiguration
     addTelemetryConfiguration(serializeRumConfiguration(initConfiguration))
@@ -127,10 +145,10 @@ export function createPreStartStrategy(
     if (configuration.compressIntakeRequests && !eventBridgeAvailable && startDeflateWorker) {
       deflateWorker = startDeflateWorker(
         configuration,
-        'Kubsesense RUM',
+        'KubeSense RUM',
         // Worker initialization can fail asynchronously, especially in Firefox where even CSP
         // issues are reported asynchronously. For now, the SDK will continue its execution even if
-        // data won't be sent to Kubsesense. We could improve this behavior in the future.
+        // data won't be sent to KubeSense. We could improve this behavior in the future.
         noop
       )
       if (!deflateWorker) {
@@ -148,6 +166,11 @@ export function createPreStartStrategy(
 
     trackingConsentState.tryToInit(configuration.trackingConsent)
     tryStartRum()
+
+    if (remoteSdkConfigurationEnabled) {
+      // Fire-and-forget, after the SDK is running: refreshes the cache for the next page load.
+      scheduleSdkConfigurationRefresh(initConfiguration).catch(monitorError)
+    }
   }
 
   const addDurationVital = (vital: DurationVital) => {

package/src/domain/configuration/configuration.ts

@@ -17,6 +17,8 @@ import type { RumEvent } from '../../rumEvent.types'
 import type { RumPlugin } from '../plugins'
 import { isTracingOption } from '../tracing/tracer'
 import type { PropagatorType, TracingOption } from '../tracing/tracer.types'
+import type { SessionReplayRoutes } from './sessionReplayRoutes'
+import { validateSessionReplayRoutes } from './sessionReplayRoutes'
 
 export const DEFAULT_PROPAGATOR_TYPES: PropagatorType[] = ['tracecontext', 'kubesense']
 
@@ -61,7 +63,7 @@ export interface RumInitConfiguration extends InitConfiguration {
   propagateTraceBaggage?: boolean | undefined
 
   /**
-   * Access to every event collected by the RUM SDK before they are sent to Kubsesense.
+   * Access to every event collected by the RUM SDK before they are sent to KubeSense.
    * It allows:
    * - Enrich your RUM events with additional context attributes
    * - Modify your RUM events to modify their content, or redact sensitive sequences (see the list of editable properties)
@@ -112,6 +114,18 @@ export interface RumInitConfiguration extends InitConfiguration {
    */
   remoteConfigurationProxy?: string | undefined
 
+  /**
+   * Enable dashboard-managed SDK settings served by the Kubesense collector.
+   *
+   * The configuration document is fetched asynchronously after the SDK starts and cached in
+   * local storage, so it never delays initialization. Cached settings are applied on the next
+   * page load. Local `init()` values are used until a document has been fetched, and any
+   * setting absent from the document keeps its local value.
+   *
+   * @defaultValue false
+   */
+  enableRemoteSdkConfiguration?: boolean | undefined
+
   // tracing options
   /**
    * A list of request URLs used to inject tracing headers.
@@ -175,6 +189,25 @@ export interface RumInitConfiguration extends InitConfiguration {
    */
   startSessionReplayRecordingManually?: boolean | undefined
 
+  /**
+   * Restrict Session Replay recording to specific routes.
+   *
+   * Recording starts and stops as the user navigates: it runs only while the current route
+   * matches `include` (when provided) and does not match `exclude`. Rules are matched against
+   * the path (`pathname` + `search` + `hash`), and string entries match by prefix, so
+   * `/checkout` also covers `/checkout/payment`.
+   *
+   * These rules only narrow recording — a session that was not sampled in by
+   * `sessionReplaySampleRate` is never recorded, whatever the routes say.
+   *
+   * @category Session Replay
+   * @example
+   * ```ts
+   * sessionReplayRoutes: { include: ['/checkout', '/signup'], exclude: ['/checkout/card'] }
+   * ```
+   */
+  sessionReplayRoutes?: SessionReplayRoutes | undefined
+
   /**
    * Enables privacy control for action names.
    *
@@ -305,6 +338,7 @@ export interface RumConfiguration extends Configuration {
   enablePrivacyForActionName: boolean
   sessionReplaySampleRate: number
   startSessionReplayRecordingManually: boolean
+  sessionReplayRoutes: SessionReplayRoutes | undefined
   trackUserInteractions: boolean
   trackViewsManually: boolean
   trackResources: boolean
@@ -372,6 +406,7 @@ export function validateAndBuildRumConfiguration(
       initConfiguration.startSessionReplayRecordingManually !== undefined
         ? !!initConfiguration.startSessionReplayRecordingManually
         : sessionReplaySampleRate === 0,
+    sessionReplayRoutes: validateSessionReplayRoutes(initConfiguration.sessionReplayRoutes),
     traceSampleRate: initConfiguration.traceSampleRate ?? 100,
     rulePsr: isNumber(initConfiguration.traceSampleRate) ? initConfiguration.traceSampleRate / 100 : undefined,
     allowedTracingUrls,

package/src/domain/configuration/index.ts

@@ -1,2 +1,4 @@
 export * from './configuration'
 export * from './remoteConfiguration'
+export * from './remoteSdkConfiguration'
+export * from './sessionReplayRoutes'

package/src/domain/configuration/remoteSdkConfiguration.ts

@@ -0,0 +1,190 @@
+import type { RemoteSdkConfig } from '@kubesense/kubesense-browser-core'
+import {
+  DefaultPrivacyLevel,
+  TraceContextInjection,
+  getCachedSdkConfig,
+  readBoolean,
+  readEnum,
+  readSampleRate,
+  readString,
+  refreshSdkConfig,
+} from '@kubesense/kubesense-browser-core'
+import type { RumInitConfiguration } from './configuration'
+import type { SessionReplayRoutes } from './sessionReplayRoutes'
+
+/**
+ * Applies the dashboard-managed configuration document to the user's init configuration.
+ *
+ * Only scalar settings travel: anything that is a function or a matcher (`beforeSend`,
+ * `allowedTracingUrls`, `excludedActivityUrls`, plugins) stays in application code. Identity and
+ * endpoint settings (`clientToken`, `applicationId`, `kubesenseRumEndpoint`, `proxy`) are also
+ * excluded — they determine where the configuration request itself goes, and letting them be
+ * remotely rewritten would be a redirection risk.
+ *
+ * Every field is applied only when present and valid, so the user's own init configuration —
+ * and failing that, the SDK default — always wins over a missing or malformed remote value.
+ */
+
+const PRIVACY_LEVELS = [
+  DefaultPrivacyLevel.ALLOW,
+  DefaultPrivacyLevel.MASK,
+  DefaultPrivacyLevel.MASK_USER_INPUT,
+] as const
+
+const TRACE_CONTEXT_INJECTIONS = [TraceContextInjection.ALL, TraceContextInjection.SAMPLED] as const
+
+export interface RemoteSdkConfigurationResult {
+  initConfiguration: RumInitConfiguration
+  /** `false` when the dashboard has switched RUM off entirely. */
+  rumEnabled: boolean
+}
+
+/**
+ * Read the cached document and merge it into the init configuration. Synchronous and
+ * network-free: this runs on the initialization path.
+ */
+export function applyCachedSdkConfiguration(initConfiguration: RumInitConfiguration): RemoteSdkConfigurationResult {
+  const remoteConfig = getCachedSdkConfig()
+  if (!remoteConfig) {
+    return { initConfiguration, rumEnabled: true }
+  }
+  return applySdkConfiguration(initConfiguration, remoteConfig)
+}
+
+export function applySdkConfiguration(
+  initConfiguration: RumInitConfiguration,
+  remoteConfig: RemoteSdkConfig
+): RemoteSdkConfigurationResult {
+  const features = remoteConfig.features
+  if (readBoolean(features as { [key: string]: unknown } | undefined, 'rum') === false) {
+    return { initConfiguration, rumEnabled: false }
+  }
+
+  const applied: RumInitConfiguration = { ...initConfiguration }
+
+  applyRumSection(applied, remoteConfig.rum)
+  applySessionReplaySection(applied, remoteConfig.sessionReplay)
+  applyProfilingSection(applied, remoteConfig.profiling)
+  applyFeatureSwitches(applied, features)
+
+  return { initConfiguration: applied, rumEnabled: true }
+}
+
+function applyRumSection(applied: RumInitConfiguration, rum: { [key: string]: unknown } | undefined) {
+  if (!rum) {
+    return
+  }
+
+  assign(applied, 'sessionSampleRate', readSampleRate(rum, 'sessionSampleRate'))
+  assign(applied, 'telemetrySampleRate', readSampleRate(rum, 'telemetrySampleRate'))
+  assign(applied, 'traceSampleRate', readSampleRate(rum, 'traceSampleRate'))
+
+  assign(applied, 'trackUserInteractions', readBoolean(rum, 'trackUserInteractions'))
+  assign(applied, 'trackResources', readBoolean(rum, 'trackResources'))
+  assign(applied, 'trackLongTasks', readBoolean(rum, 'trackLongTasks'))
+  assign(applied, 'trackViewsManually', readBoolean(rum, 'trackViewsManually'))
+  assign(applied, 'trackBfcacheViews', readBoolean(rum, 'trackBfcacheViews'))
+  assign(applied, 'trackAnonymousUser', readBoolean(rum, 'trackAnonymousUser'))
+  assign(applied, 'trackSessionAcrossSubdomains', readBoolean(rum, 'trackSessionAcrossSubdomains'))
+  assign(applied, 'enablePrivacyForActionName', readBoolean(rum, 'enablePrivacyForActionName'))
+  assign(applied, 'propagateTraceBaggage', readBoolean(rum, 'propagateTraceBaggage'))
+
+  assign(applied, 'defaultPrivacyLevel', readEnum(rum, 'defaultPrivacyLevel', PRIVACY_LEVELS))
+  assign(applied, 'traceContextInjection', readEnum(rum, 'traceContextInjection', TRACE_CONTEXT_INJECTIONS))
+  assign(applied, 'actionNameAttribute', readString(rum, 'actionNameAttribute'))
+
+  assign(applied, 'service', readString(rum, 'service'))
+  assign(applied, 'env', readString(rum, 'env'))
+  assign(applied, 'version', readString(rum, 'version'))
+}
+
+function applySessionReplaySection(
+  applied: RumInitConfiguration,
+  sessionReplay: { [key: string]: unknown } | undefined
+) {
+  if (!sessionReplay) {
+    return
+  }
+
+  assign(applied, 'sessionReplaySampleRate', readSampleRate(sessionReplay, 'sampleRate'))
+  assign(applied, 'startSessionReplayRecordingManually', readBoolean(sessionReplay, 'startRecordingManually'))
+  assign(applied, 'defaultPrivacyLevel', readEnum(sessionReplay, 'defaultPrivacyLevel', PRIVACY_LEVELS))
+  assign(applied, 'sessionReplayRoutes', readRoutes(sessionReplay.routes))
+}
+
+/**
+ * Route rules arriving as JSON can only be plain strings (prefix matches). Regexes and functions
+ * are deliberately not accepted from the dashboard: they cannot be expressed safely in JSON and a
+ * pathological pattern would run on every view change.
+ */
+function readRoutes(routes: unknown): SessionReplayRoutes | undefined {
+  if (!routes || typeof routes !== 'object' || Array.isArray(routes)) {
+    return undefined
+  }
+
+  const include = readStringList((routes as { include?: unknown }).include)
+  const exclude = readStringList((routes as { exclude?: unknown }).exclude)
+
+  if (!include && !exclude) {
+    return undefined
+  }
+
+  return { include, exclude }
+}
+
+function readStringList(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) {
+    return undefined
+  }
+  const strings = value.filter((item): item is string => typeof item === 'string' && item.length > 0)
+  return strings.length > 0 ? strings : undefined
+}
+
+function applyProfilingSection(applied: RumInitConfiguration, profiling: { [key: string]: unknown } | undefined) {
+  if (!profiling) {
+    return
+  }
+  assign(applied, 'profilingSampleRate', readSampleRate(profiling, 'sampleRate'))
+}
+
+/**
+ * Feature switches are applied last so they always win over the per-section sample rates above.
+ * Turning a feature off is expressed through the setting that stops all of its collection.
+ */
+function applyFeatureSwitches(applied: RumInitConfiguration, features: RemoteSdkConfig['features']) {
+  const source = features as { [key: string]: unknown } | undefined
+
+  if (readBoolean(source, 'sessionReplay') === false) {
+    applied.sessionReplaySampleRate = 0
+    applied.startSessionReplayRecordingManually = true
+    // Drop any route rules too: with replay off they are dead weight, and leaving them behind
+    // would suggest recording still happens somewhere.
+    applied.sessionReplayRoutes = undefined
+  }
+
+  if (readBoolean(source, 'profiling') === false) {
+    applied.profilingSampleRate = 0
+  }
+}
+
+/**
+ * Assigning only defined values keeps the "absent means keep the local value" guarantee in one
+ * place instead of at every call site.
+ */
+function assign<K extends keyof RumInitConfiguration>(
+  target: RumInitConfiguration,
+  key: K,
+  value: RumInitConfiguration[K] | undefined
+) {
+  if (value !== undefined) {
+    target[key] = value
+  }
+}
+
+/**
+ * Refresh the cache for the next page load. Must be called *after* the SDK has started so it
+ * never delays initialization.
+ */
+export function scheduleSdkConfigurationRefresh(initConfiguration: RumInitConfiguration) {
+  return refreshSdkConfig(initConfiguration, initConfiguration.applicationId)
+}

package/src/domain/configuration/sessionReplayRoutes.ts

@@ -0,0 +1,96 @@
+import type { MatchOption } from '@kubesense/kubesense-browser-core'
+import { display, isMatchOption, matchList } from '@kubesense/kubesense-browser-core'
+
+/**
+ * Route-scoped Session Replay.
+ *
+ * Recording is normally decided once per session by `sessionReplaySampleRate`. These rules add a
+ * second, per-view gate so a session that *is* eligible only gets recorded while the user is on
+ * a matching route.
+ *
+ * Rules can only ever narrow recording, never widen it: a session that lost the replay sampling
+ * draw is never recorded, whatever the routes say.
+ */
+export interface SessionReplayRoutes {
+  /** Record only on these routes. When omitted, every route is eligible. */
+  include?: MatchOption[] | undefined
+  /** Never record on these routes. Takes precedence over `include`. */
+  exclude?: MatchOption[] | undefined
+}
+
+/**
+ * Rules are matched against the **path** — `pathname` + `search` + `hash` — not the full URL, so
+ * a dashboard entry reads the way a route is written (`/checkout`). String options match by
+ * prefix, so `/checkout` also covers `/checkout/payment`.
+ */
+export function getRoutePath(location: Location | URL = window.location): string {
+  return `${location.pathname}${location.search}${location.hash}`
+}
+
+/**
+ * Returns whether recording is allowed on the given path.
+ *
+ * No rules at all means "record everywhere", which keeps the behaviour of an SDK that has never
+ * been configured with routes.
+ */
+export function isRouteRecordable(routes: SessionReplayRoutes | undefined, path: string): boolean {
+  if (!routes) {
+    return true
+  }
+
+  // Exclusions win, so a route can always be carved out of a broad `include`.
+  if (routes.exclude && routes.exclude.length > 0 && matchList(routes.exclude, path, true)) {
+    return false
+  }
+
+  if (routes.include && routes.include.length > 0) {
+    return matchList(routes.include, path, true)
+  }
+
+  return true
+}
+
+/**
+ * Validates the user-provided option. An invalid entry is dropped rather than silently treated
+ * as "match nothing", which would turn a typo into a total loss of replay.
+ */
+export function validateSessionReplayRoutes(routes: unknown): SessionReplayRoutes | undefined {
+  if (routes === undefined || routes === null) {
+    return undefined
+  }
+
+  if (typeof routes !== 'object' || Array.isArray(routes)) {
+    display.error('Session Replay routes should be an object with optional include and exclude arrays')
+    return undefined
+  }
+
+  const include = validateMatchOptionList((routes as SessionReplayRoutes).include, 'include')
+  const exclude = validateMatchOptionList((routes as SessionReplayRoutes).exclude, 'exclude')
+
+  if (!include && !exclude) {
+    return undefined
+  }
+
+  return { include, exclude }
+}
+
+function validateMatchOptionList(list: unknown, name: string): MatchOption[] | undefined {
+  if (list === undefined) {
+    return undefined
+  }
+
+  if (!Array.isArray(list)) {
+    display.error(`Session Replay routes "${name}" should be an array`)
+    return undefined
+  }
+
+  const validOptions = list.filter((item) => {
+    if (isMatchOption(item)) {
+      return true
+    }
+    display.error(`Session Replay routes "${name}" entries should be a string, RegExp or function`)
+    return false
+  }) as MatchOption[]
+
+  return validOptions.length > 0 ? validOptions : undefined
+}

package/src/domain/getSessionReplayUrl.ts

@@ -25,14 +25,14 @@ export function getSessionReplayUrl(
     parameters.push(`from=${viewContext.startClocks.timeStamp}`)
   }
 
-  const origin = getKubsesenseSiteUrl(configuration)
+  const origin = getKubeSenseSiteUrl(configuration)
   const path = `/rum/replay/sessions/${sessionId}`
   return `${origin}${path}?${parameters.join('&')}`
 }
 
-export function getKubsesenseSiteUrl(rumConfiguration: RumConfiguration) {
+export function getKubeSenseSiteUrl(rumConfiguration: RumConfiguration) {
   const site = rumConfiguration.kubesenseRumEndpoint
-  const subdomain = rumConfiguration.subdomain 
+  const subdomain = rumConfiguration.subdomain
   return `https://${subdomain ? `${subdomain}.` : ''}${site}`
 }
 

package/src/domain/tracing/tracer.types.ts

@@ -1,7 +1,7 @@
 import type { MatchOption } from '@kubesense/kubesense-browser-core'
 
 /**
- * kubesense: Kubsesense (x-kubesense-*)
+ * kubesense: KubeSense (x-kubesense-*)
  * tracecontext: W3C Trace Context (traceparent, tracestate)
  * b3: B3 Single Header (b3)
  * b3multi: B3 Multiple Headers (X-B3-*)

package/src/index.ts

@@ -48,7 +48,9 @@ export type {
   RumConfiguration,
   FeatureFlagsForEvents,
   RemoteConfiguration,
+  SessionReplayRoutes,
 } from './domain/configuration'
+export { isRouteRecordable, getRoutePath } from './domain/configuration'
 export { DEFAULT_PROGRAMMATIC_ACTION_NAME_ATTRIBUTE } from './domain/action/actionNameConstants'
 export { STABLE_ATTRIBUTES } from './domain/getSelectorFromElement'
 export * from './browser/htmlDomUtils'

package/src/rumEvent.types.ts

@@ -1519,6 +1519,10 @@ export interface CommonProperties {
      * Email of the user
      */
     readonly email?: string
+    /**
+     * Mobile phone number of the user
+     */
+    readonly mobile?: string
     /**
      * Identifier of the user across sessions
      */