@kubesense/kubesense-browser-rum-core 1.3.0 → 1.5.0

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/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
      */