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

package/src/domain/configuration/index.ts

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

package/src/domain/configuration/remoteConfiguration.ts

@@ -1,26 +1,39 @@
 import type { createContextManager, Context } from '@kubesense/kubesense-browser-core'
 import {
   display,
-  buildEndpointHost,
   mapValues,
   getCookie,
   addTelemetryMetrics,
   TelemetryMetrics,
+  fetch,
 } from '@kubesense/kubesense-browser-core'
+import { monitorError } from '@kubesense/kubesense-js-core/monitor'
+import { isIndexableObject } from '@kubesense/kubesense-js-core/util'
+import { buildEndpointUrl } from '@kubesense/kubesense-js-core/transport'
+import { extractRegexMatch } from '../extractRegexMatch'
 import type { RumInitConfiguration } from './configuration'
 import type { RumSdkConfig, DynamicOption, ContextItem } from './remoteConfiguration.types'
 import { parseJsonPath } from './jsonPathParser'
+import type { RemoteConfigurationMetadata } from './remoteConfigurationCache'
+import { CACHE_STATUS_TO_METRIC_MAP, createConfigurationCache } from './remoteConfigurationCache'
 
 export type RemoteConfiguration = RumSdkConfig
 export type RumRemoteConfiguration = Exclude<RemoteConfiguration['rum'], undefined>
 const REMOTE_CONFIGURATION_VERSION = 'v1'
-const SUPPORTED_FIELDS: Array<keyof RumInitConfiguration> = [
+const SUPPORTED_RUM_FIELDS: Array<keyof RumInitConfiguration> = [
   'applicationId',
   'service',
   'env',
   'version',
   'sessionSampleRate',
   'sessionReplaySampleRate',
+  'telemetrySampleRate',
+  'trackAnonymousUser',
+  'trackUserInteractions',
+  'trackResources',
+  'trackLongTasks',
+  'traceContextInjection',
+  'actionNameAttribute',
   'defaultPrivacyLevel',
   'enablePrivacyForActionName',
   'traceSampleRate',
@@ -41,9 +54,11 @@ interface SupportedContextManagers {
 
 export interface RemoteConfigurationMetrics extends Context {
   fetch: RemoteConfigurationMetricCounters
+  cache?: RemoteConfigurationMetricCounters
   cookie?: RemoteConfigurationMetricCounters
   dom?: RemoteConfigurationMetricCounters
   js?: RemoteConfigurationMetricCounters
+  localStorage?: RemoteConfigurationMetricCounters
 }
 
 interface RemoteConfigurationMetricCounters {
@@ -79,7 +94,7 @@ export async function fetchAndApplyRemoteConfiguration(
 
 export function applyRemoteConfiguration(
   initConfiguration: RumInitConfiguration,
-  rumRemoteConfiguration: RumRemoteConfiguration & { [key: string]: unknown },
+  remoteConfiguration: RemoteConfiguration,
   supportedContextManagers: SupportedContextManagers,
   metrics: ReturnType<typeof initMetrics>
 ): RumInitConfiguration {
@@ -87,16 +102,22 @@ export function applyRemoteConfiguration(
   // - explicitly set each supported field to limit risk in case an attacker can create configurations
   // - check the existence in the remote config to avoid clearing a provided init field
   const appliedConfiguration = { ...initConfiguration } as RumInitConfiguration & { [key: string]: unknown }
-  SUPPORTED_FIELDS.forEach((option: string) => {
-    if (option in rumRemoteConfiguration) {
-      appliedConfiguration[option] = resolveConfigurationProperty(rumRemoteConfiguration[option])
-    }
-  })
-  ;(Object.keys(supportedContextManagers) as Array<keyof SupportedContextManagers>).forEach((context) => {
-    if (rumRemoteConfiguration[context] !== undefined) {
-      resolveContextProperty(supportedContextManagers[context], rumRemoteConfiguration[context])
-    }
-  })
+  if (remoteConfiguration.rum) {
+    const rumRemoteConfiguration = remoteConfiguration.rum as RumRemoteConfiguration & { [key: string]: unknown }
+    SUPPORTED_RUM_FIELDS.forEach((option: string) => {
+      if (option in rumRemoteConfiguration) {
+        appliedConfiguration[option] = resolveConfigurationProperty(rumRemoteConfiguration[option])
+      }
+    })
+    ;(Object.keys(supportedContextManagers) as Array<keyof SupportedContextManagers>).forEach((context) => {
+      if (rumRemoteConfiguration[context] !== undefined) {
+        resolveContextProperty(supportedContextManagers[context], rumRemoteConfiguration[context])
+      }
+    })
+  }
+  if (remoteConfiguration.profiling?.sampleRate !== undefined) {
+    appliedConfiguration.profilingSampleRate = remoteConfiguration.profiling.sampleRate
+  }
   return appliedConfiguration
 
   // share context to access metrics
@@ -105,7 +126,7 @@ export function applyRemoteConfiguration(
     if (Array.isArray(property)) {
       return property.map(resolveConfigurationProperty)
     }
-    if (isObject(property)) {
+    if (isIndexableObject(property)) {
       if (isSerializedOption(property)) {
         const type = property.rcSerializedType
         switch (type) {
@@ -147,6 +168,9 @@ export function applyRemoteConfiguration(
       case 'js':
         resolvedValue = resolveJsValue(property)
         break
+      case 'localStorage':
+        resolvedValue = resolveLocalStorageValue(property)
+        break
       default:
         display.error(`Unsupported remote configuration: "strategy": "${strategy as string}"`)
         return
@@ -164,6 +188,18 @@ export function applyRemoteConfiguration(
     return value
   }
 
+  function resolveLocalStorageValue({ key }: { key: string }) {
+    let value: string | null
+    try {
+      value = localStorage.getItem(key)
+    } catch {
+      metrics.increment('localStorage', 'failure')
+      return
+    }
+    metrics.increment('localStorage', value !== null ? 'success' : 'missing')
+    return value ?? undefined
+  }
+
   function resolveDomValue({ selector, attribute }: { selector: string; attribute?: string }) {
     let element: Element | null
     try {
@@ -225,7 +261,10 @@ export function initMetrics() {
   const metrics: RemoteConfigurationMetrics = { fetch: {} }
   return {
     get: () => metrics,
-    increment: (metricName: 'fetch' | DynamicOption['strategy'], type: keyof RemoteConfigurationMetricCounters) => {
+    increment: (
+      metricName: 'fetch' | 'cache' | DynamicOption['strategy'],
+      type: keyof RemoteConfigurationMetricCounters
+    ) => {
       if (!metrics[metricName]) {
         metrics[metricName] = {}
       }
@@ -237,10 +276,6 @@ export function initMetrics() {
   }
 }
 
-function isObject(property: unknown): property is { [key: string]: unknown } {
-  return typeof property === 'object' && property !== null
-}
-
 function isSerializedOption(value: object): value is SerializedOption {
   return 'rcSerializedType' in value
 }
@@ -258,15 +293,26 @@ function extractValue(extractor: SerializedRegex, candidate: string) {
   if (resolvedExtractor === undefined) {
     return
   }
-  const regexResult = resolvedExtractor.exec(candidate)
-  if (regexResult === null) {
+  return extractRegexMatch(candidate, resolvedExtractor)
+}
+
+type FetchRemoteConfigurationResult =
+  { ok: true; value: RemoteConfiguration; lastModified?: number } | { ok: false; error: Error }
+
+/**
+ * Reads the CDN publish time. `Last-Modified` is a CORS-safelisted response header, so it is
+ * readable cross-origin without the CDN having to expose it explicitly. It carries an HTTP-date,
+ * so the value is only accurate to the second.
+ */
+function parseLastModified(response: Response): number | undefined {
+  const header = response.headers?.get('last-modified')
+  if (!header) {
     return
   }
-  const [match, capture] = regexResult
-  return capture ? capture : match
-}
+  const timestamp = new Date(header).getTime()
 
-type FetchRemoteConfigurationResult = { ok: true; value: RumRemoteConfiguration } | { ok: false; error: Error }
+  return isNaN(timestamp) ? undefined : timestamp
+}
 
 export async function fetchRemoteConfiguration(
   configuration: RumInitConfiguration
@@ -277,17 +323,18 @@ export async function fetchRemoteConfiguration(
   } catch {
     response = undefined
   }
-  if (!response || !response.ok) {
+  if (!response?.ok) {
     return {
       ok: false,
       error: new Error('Error fetching the remote configuration.'),
     }
   }
   const remoteConfiguration: RemoteConfiguration = await response.json()
-  if (remoteConfiguration.rum) {
+  if (remoteConfiguration.rum || remoteConfiguration.profiling) {
     return {
       ok: true,
-      value: remoteConfiguration.rum,
+      value: remoteConfiguration,
+      lastModified: parseLastModified(response),
     }
   }
   return {
@@ -296,9 +343,85 @@ export async function fetchRemoteConfiguration(
   }
 }
 
+export function getRemoteConfigurationId(configuration: RumInitConfiguration): string | undefined {
+  return configuration.remoteConfiguration?.id ?? configuration.remoteConfigurationId
+}
+
 export function buildEndpoint(configuration: RumInitConfiguration) {
   if (configuration.remoteConfigurationProxy) {
     return configuration.remoteConfigurationProxy
   }
-  return `https://sdk-configuration.${buildEndpointHost('rum', configuration)}/${REMOTE_CONFIGURATION_VERSION}/${encodeURIComponent(configuration.remoteConfigurationId!)}.json`
+  const id = getRemoteConfigurationId(configuration)!
+  return buildEndpointUrl({
+    kubesenseRumEndpoint: configuration.kubesenseRumEndpoint,
+    path: `/${REMOTE_CONFIGURATION_VERSION}/${encodeURIComponent(id)}.json`,
+    subdomain: 'sdk-configuration',
+  })
+}
+
+function doBackgroundCacheSync(
+  initConfiguration: RumInitConfiguration,
+  cache: ReturnType<typeof createConfigurationCache>,
+  metrics: ReturnType<typeof initMetrics>
+) {
+  fetchRemoteConfiguration(initConfiguration)
+    .then((fetchResult) => {
+      if (!fetchResult.ok) {
+        metrics.increment('fetch', 'failure')
+        display.error(fetchResult.error)
+      } else {
+        metrics.increment('fetch', 'success')
+        cache.write(fetchResult.value, fetchResult.lastModified)
+      }
+    })
+    .catch(monitorError)
+    .finally(() => {
+      // monitor-until: forever
+      addTelemetryMetrics(TelemetryMetrics.REMOTE_CONFIGURATION_METRIC_NAME, { metrics: metrics.get() })
+    })
+}
+
+export interface ResolvedRemoteConfiguration {
+  initConfiguration: RumInitConfiguration
+  /** Only set when a cached configuration was applied, and reported on configuration telemetry. */
+  metadata?: RemoteConfigurationMetadata
+}
+
+/**
+ * Returns `undefined` when RUM must not start, which only happens with `required: true` and no
+ * usable cache entry.
+ */
+export function getRemoteConfiguration(
+  initConfiguration: RumInitConfiguration,
+  supportedContextManagers: SupportedContextManagers
+): ResolvedRemoteConfiguration | undefined {
+  const configurationCache = createConfigurationCache({
+    remoteConfigurationId: getRemoteConfigurationId(initConfiguration)!,
+  })
+  const metrics = initMetrics()
+
+  const cacheResult = configurationCache.read()
+
+  metrics.increment('cache', CACHE_STATUS_TO_METRIC_MAP[cacheResult.status])
+
+  doBackgroundCacheSync(initConfiguration, configurationCache, metrics)
+
+  if (cacheResult.status === 'hit') {
+    return {
+      // Stamping is synchronous, so it always lands before the background sync above can write.
+      metadata: configurationCache.stampFirstApplied(cacheResult),
+      initConfiguration: applyRemoteConfiguration(
+        initConfiguration,
+        cacheResult.config,
+        supportedContextManagers,
+        metrics
+      ),
+    }
+  }
+
+  if (initConfiguration.remoteConfiguration?.required) {
+    return
+  }
+
+  return { initConfiguration }
 }

package/src/domain/configuration/remoteConfiguration.types.ts

@@ -1,4 +1,3 @@
-/* eslint-disable */
 /**
  * DO NOT MODIFY IT BY HAND. Run `yarn json-schemas:sync` instead.
  */
@@ -26,11 +25,27 @@ export type DynamicOption =
       extractor?: SerializedRegex
       [k: string]: unknown
     }
+  | {
+      rcSerializedType: 'dynamic'
+      strategy: 'localStorage'
+      key: string
+      extractor?: SerializedRegex
+      [k: string]: unknown
+    }
 
 /**
  * RUM Browser & Mobile SDKs Remote Configuration properties
  */
 export interface RumSdkConfig {
+  /**
+   * Profiling feature Remote Configuration properties
+   */
+  profiling?: {
+    /**
+     * The percentage of users profiled
+     */
+    sampleRate?: number
+  }
   /**
    * RUM feature Remote Configuration properties
    */
@@ -73,6 +88,13 @@ export interface RumSdkConfig {
           extractor?: SerializedRegex
           [k: string]: unknown
         }
+      | {
+          rcSerializedType: 'dynamic'
+          strategy: 'localStorage'
+          key: string
+          extractor?: SerializedRegex
+          [k: string]: unknown
+        }
     /**
      * The percentage of sessions tracked
      */
@@ -81,6 +103,34 @@ export interface RumSdkConfig {
      * The percentage of sessions with RUM & Session Replay pricing tracked
      */
     sessionReplaySampleRate?: number
+    /**
+     * The percentage of telemetry events sampled
+     */
+    telemetrySampleRate?: number
+    /**
+     * Whether to track anonymous users
+     */
+    trackAnonymousUser?: boolean
+    /**
+     * Whether to automatically collect user actions
+     */
+    trackUserInteractions?: boolean
+    /**
+     * Whether to collect resource events
+     */
+    trackResources?: boolean
+    /**
+     * Whether to collect long task events
+     */
+    trackLongTasks?: boolean
+    /**
+     * Controls when tracing headers are injected
+     */
+    traceContextInjection?: 'all' | 'sampled'
+    /**
+     * HTML attribute used as the RUM action name
+     */
+    actionNameAttribute?: string
     /**
      * Session replay default privacy level
      */

package/src/domain/configuration/remoteConfigurationCache.ts

@@ -0,0 +1,153 @@
+import { timeStampNow } from '@kubesense/kubesense-js-core/time'
+import { generateUUID, tryJsonParse } from '@kubesense/kubesense-browser-core'
+import { isIndexableObject } from '@kubesense/kubesense-js-core/util'
+import type { TimeStamp } from '@kubesense/kubesense-js-core/time'
+import type { RemoteConfiguration } from './remoteConfiguration'
+
+export const CACHE_VERSION = 3
+export const CACHE_KEY_PREFIX = 'dd_rc_'
+
+/**
+ * Sync metadata for the cached configuration version, reported on configuration telemetry to
+ * measure how long a published configuration takes to take effect.
+ */
+export interface RemoteConfigurationMetadata {
+  /** CDN publish time, from the `last-modified` response header. */
+  lastModified?: number
+  /** When the SDK fetched the version currently cached. */
+  lastSynced: TimeStamp
+  /** When this version was first applied. Stamped once, then reused on every later page load. */
+  firstApplied?: TimeStamp
+  /** Identifies one sync, so repeat page loads from a device collapse into a single unit. */
+  syncId: string
+}
+
+interface CachedRemoteConfiguration {
+  version: number
+  config: RemoteConfiguration
+  metadata: RemoteConfigurationMetadata
+}
+
+export type CacheReadStatus = 'hit' | 'miss' | 'error'
+
+export interface CacheHitResult {
+  status: Extract<CacheReadStatus, 'hit'>
+  config: RemoteConfiguration
+  metadata: RemoteConfigurationMetadata
+}
+
+export type CacheReadResult =
+  | {
+      status: Exclude<CacheReadStatus, 'hit'>
+    }
+  | CacheHitResult
+
+export const CACHE_STATUS_TO_METRIC_MAP: Record<CacheReadStatus, 'success' | 'missing' | 'failure'> = {
+  hit: 'success',
+  miss: 'missing',
+  error: 'failure',
+}
+
+export function buildCacheKey(remoteConfigurationId: string): string {
+  return `${CACHE_KEY_PREFIX}${remoteConfigurationId}`
+}
+
+function isValidCacheEntry(value: unknown): value is CachedRemoteConfiguration {
+  if (typeof value !== 'object' || value === null) {
+    return false
+  }
+
+  const hasVersion = 'version' in value && value.version === CACHE_VERSION
+  const hasConfig = 'config' in value && typeof value.config === 'object' && value.config !== null
+  const hasMetadata =
+    'metadata' in value &&
+    isIndexableObject(value.metadata) &&
+    typeof value.metadata.syncId === 'string' &&
+    typeof value.metadata.lastSynced === 'number'
+
+  return hasVersion && hasConfig && hasMetadata
+}
+
+function persist(key: string, entry: CachedRemoteConfiguration) {
+  try {
+    localStorage.setItem(key, JSON.stringify(entry))
+  } catch {
+    // Ignore
+  }
+}
+
+export function createConfigurationCache({ remoteConfigurationId }: { remoteConfigurationId: string }) {
+  const key = buildCacheKey(remoteConfigurationId)
+
+  return {
+    read(): CacheReadResult {
+      let raw: string | null
+
+      try {
+        raw = localStorage.getItem(key)
+      } catch {
+        return { status: 'error' }
+      }
+
+      if (raw === null) {
+        return { status: 'miss' }
+      }
+
+      const parsed = tryJsonParse(raw)
+      if (parsed === undefined) {
+        this.remove()
+
+        return { status: 'error' }
+      }
+
+      if (!isValidCacheEntry(parsed)) {
+        this.remove()
+
+        return { status: 'error' }
+      }
+
+      return { status: 'hit', config: parsed.config, metadata: parsed.metadata }
+    },
+    remove() {
+      try {
+        localStorage.removeItem(key)
+      } catch {
+        // Ignore
+      }
+    },
+    write(config: RemoteConfiguration, lastModified?: number) {
+      const cached = this.read()
+
+      // Only a payload change counts as a sync. The SDK sends no `If-None-Match`, so it never
+      // observes a 304 and cannot otherwise tell a genuine sync from a repeated fetch of the same
+      // version. Skipping the write here is also what keeps `firstApplied` alive across refetches.
+      // TODO: compare on `ETag` instead once the CDN exposes it through
+      // `Access-Control-Expose-Headers`. The stringify compare is key-order sensitive, which holds
+      // only because both sides come from `JSON.parse` of the same CDN payload.
+      if (cached.status === 'hit' && JSON.stringify(cached.config) === JSON.stringify(config)) {
+        return
+      }
+
+      persist(key, {
+        version: CACHE_VERSION,
+        config,
+        metadata: { lastModified, lastSynced: timeStampNow(), syncId: generateUUID() },
+      })
+    },
+    /**
+     * Records when this configuration version was first put into effect. Stamped on the first page
+     * load that applies it, then reused by every later one, so the reported value marks a fixed
+     * point in time instead of drifting with each page load.
+     */
+    stampFirstApplied(cached: CacheHitResult): RemoteConfigurationMetadata {
+      if (cached.metadata.firstApplied !== undefined) {
+        return cached.metadata
+      }
+
+      const metadata: RemoteConfigurationMetadata = { ...cached.metadata, firstApplied: timeStampNow() }
+      persist(key, { version: CACHE_VERSION, config: cached.config, metadata })
+
+      return metadata
+    },
+  }
+}