feat(rum): let the console set the sampling configuration

CHANGELOG.md

@@ -18,6 +18,42 @@
 
 ---
 
+## Unreleased
+
+- 💥 **Breaking**: `remoteConfigurationId` is gone from `RumInitConfiguration`. It fetched a
+  different endpoint under a different contract, and is replaced by `remoteConfigurationEnabled`.
+  A site still passing it in JavaScript keeps working and gets the settings it passed to `init`;
+  a TypeScript project passing it no longer compiles and should drop the option.
+- 📝 Behind a `proxy`, the settings request travels to `/api/v2/rum/config`. A proxy that checks the
+  forwarded path against a list of known intake paths must be told about this one, or the settings
+  never arrive — the SDK keeps collecting with the values passed to `init`, so the only symptom is
+  that the console appears to have no effect.
+- 💥 **Breaking for TypeScript code that implements our interfaces**: `RumPublicApi` gains
+  `setForcedSession` and `getRemoteConfig`, and `RumSessionManager` gains `setForcedSession`. Code
+  that only calls these interfaces is unaffected; code that implements or hand-mocks them needs the
+  new members. The two new methods are also absent from the legacy ES5 bundle, so feature-detect
+  them if the same code runs against both.
+- ✨ `remoteConfigurationEnabled` lets the sampling rates, the trace sample rate and the Session
+  Replay privacy level be set from the console instead of only at `init`. Off by default: without
+  it the SDK makes no extra request. A change applies to sessions created after it arrives, never
+  to one already under way. `remoteConfigurationFetchTimeout` (default 3000 ms) bounds how long
+  that request may take; an unusable value falls back to the default rather than refusing `init`.
+- 📝 Withdrawing tracking consent now also removes the record of the sampling draw, which holds the
+  session id. The session store was already rewritten without that id on withdrawal; this keeps the
+  copy in `localStorage` from outliving it.
+- 📝 This release reads `localStorage` on every site, not only those that opt into remote
+  configuration: at start-up and at each new session it looks for the record of the sampling draw
+  that session was created under, so that another tab on the same session, and the page load that
+  restores it, report and trace it the same way. It only WRITES that record when a draw lands
+  somewhere other than the values passed to `init` — which needs remote configuration,
+  `beforeSampling`, or `setForcedSession()`; a site using none of them never writes. Sessions
+  themselves are unaffected and stay in a cookie unless `sessionPersistence` says otherwise. Called
+  out for privacy reviews.
+- ✨ `beforeSampling` gives the application the last word on the rates at the moment a session is
+  drawn, with the console's custom values in hand.
+- ✨ `setForcedSession()` collects the current visitor regardless of the rates, and
+  `getRemoteConfig()` returns the console's custom values verbatim.
+
 ## v0.1.1
 
 Sessions on pages that stay open no longer run without end. A stored session whose state could not

packages/core/src/domain/configuration/endpointBuilder.ts

@@ -24,7 +24,7 @@ export function createEndpointBuilder(
   trackType: TrackType,
   configurationTags: string[]
 ) {
-  const buildUrlWithParameters = createEndpointUrlWithParametersBuilder(initConfiguration, trackType)
+  const buildUrlWithParameters = createEndpointUrlBuilder(initConfiguration, trackType, `/api/v2/${trackType}`)
 
   return {
     build(api: ApiType, payload: Payload) {
@@ -41,12 +41,17 @@ export function createEndpointBuilder(
  * Create a function used to build a full endpoint url from provided parameters. The goal of this
  * function is to pre-compute some parts of the URL to avoid re-computing everything on every
  * request, as only parameters are changing.
+ *
+ * FLASHCAT FORK - `path` is a parameter rather than derived from `trackType`, so endpoints that do
+ * not sit at `/api/v2/<trackType>` can be built here too. That keeps every request the SDK makes on
+ * one implementation of the proxy and site rules: an endpoint that built its own URL would quietly
+ * bypass a customer's `proxy` and go straight to the intake host.
  */
-function createEndpointUrlWithParametersBuilder(
+export function createEndpointUrlBuilder(
   initConfiguration: InitConfiguration,
-  trackType: TrackType
+  trackType: TrackType,
+  path: string
 ): (parameters: string) => string {
-  const path = `/api/v2/${trackType}`
   const proxy = initConfiguration.proxy
   if (typeof proxy === 'string') {
     const normalizedProxyUrl = normalizeUrl(proxy)

packages/core/src/domain/configuration/index.ts

@@ -7,6 +7,6 @@ export {
   serializeConfiguration,
 } from './configuration'
 export type { EndpointBuilder, TrackType } from './endpointBuilder'
-export { createEndpointBuilder, buildEndpointHost } from './endpointBuilder'
+export { createEndpointBuilder, createEndpointUrlBuilder, buildEndpointHost } from './endpointBuilder'
 export * from './intakeSites'
 export { computeTransportConfiguration, isIntakeUrl } from './transportConfiguration'

packages/core/src/index.ts

@@ -6,6 +6,7 @@ export {
   serializeConfiguration,
   isSampleRate,
   buildEndpointHost,
+  createEndpointUrlBuilder,
   INTAKE_SITE_STAGING,
   INTAKE_SITE_US1,
   INTAKE_SITE_US1_FED,

packages/core/test/emulate/mockXhr.ts

@@ -38,11 +38,14 @@ export class MockXhr extends MockEventTarget {
   public status: number | undefined = undefined
   public readyState: number = XMLHttpRequest.UNSENT
   public onreadystatechange: () => void = noop
+  // Recorded so tests can assert on where a request was addressed, not only on what came back.
+  public url: string | undefined = undefined
 
   private hasEnded = false
 
   /* eslint-disable @typescript-eslint/no-unused-vars */
   open(method: string | undefined | null, url: string | URL | undefined | null) {
+    this.url = url?.toString()
     this.hasEnded = false
   }
 

packages/rum-core/src/boot/preStartRum.spec.ts

@@ -14,7 +14,6 @@ import {
 import type { Clock } from '@flashcatcloud/browser-core/test'
 import {
   callbackAddsInstrumentation,
-  interceptRequests,
   mockClock,
   mockEventBridge,
   mockSyntheticsWorkerValues,
@@ -449,33 +448,31 @@ describe('preStartRum', () => {
     })
 
     describe('remote configuration', () => {
-      let interceptor: ReturnType<typeof interceptRequests>
+      it('starts collecting straight away, whatever the sampling settings do', () => {
+        // Fetching them belongs to startRum, next to the session manager. What matters here is
+        // that opting in never delays or blocks initialisation.
+        const strategy = createPreStartStrategy(
+          {},
+          createTrackingConsentState(),
+          createCustomVitalsState(),
+          doStartRumSpy
+        )
+        strategy.init({ ...DEFAULT_INIT_CONFIGURATION, remoteConfigurationEnabled: true }, PUBLIC_API)
 
-      beforeEach(() => {
-        interceptor = interceptRequests()
+        expect(doStartRumSpy).toHaveBeenCalled()
+        expect(doStartRumSpy.calls.mostRecent().args[0].remoteConfig).toBeDefined()
       })
 
-      it('should start with the remote configuration when a remoteConfigurationId is provided', (done) => {
-        interceptor.withMockXhr((xhr) => {
-          xhr.complete(200, '{"rum":{"sessionSampleRate":50}}')
-
-          expect(doStartRumSpy.calls.mostRecent().args[0].sessionSampleRate).toEqual(50)
-          done()
-        })
-
+      it('resolves no remote sampling setup at all when the site did not opt in', () => {
         const strategy = createPreStartStrategy(
           {},
           createTrackingConsentState(),
           createCustomVitalsState(),
           doStartRumSpy
         )
-        strategy.init(
-          {
-            ...DEFAULT_INIT_CONFIGURATION,
-            remoteConfigurationId: '123',
-          },
-          PUBLIC_API
-        )
+        strategy.init(DEFAULT_INIT_CONFIGURATION, PUBLIC_API)
+
+        expect(doStartRumSpy.calls.mostRecent().args[0].remoteConfig).toBeUndefined()
       })
     })
 
@@ -568,10 +565,8 @@ describe('preStartRum', () => {
   describe('initConfiguration', () => {
     let strategy: Strategy
     let initConfiguration: RumInitConfiguration
-    let interceptor: ReturnType<typeof interceptRequests>
 
     beforeEach(() => {
-      interceptor = interceptRequests()
       strategy = createPreStartStrategy({}, createTrackingConsentState(), createCustomVitalsState(), doStartRumSpy)
       initConfiguration = { ...DEFAULT_INIT_CONFIGURATION, service: 'my-service', version: '1.4.2', env: 'dev' }
     })
@@ -606,27 +601,20 @@ describe('preStartRum', () => {
       expect(strategy.initConfiguration).toEqual(initConfiguration)
     })
 
-    it('returns the initConfiguration with the remote configuration when a remoteConfigurationId is provided', (done) => {
-      interceptor.withMockXhr((xhr) => {
-        xhr.complete(200, '{"rum":{"sessionSampleRate":50}}')
-
-        expect(strategy.initConfiguration?.sessionSampleRate).toEqual(50)
-        done()
-      })
-
+    it('reports exactly what the site passed, with nothing merged in from the console', () => {
+      // Remote settings only ever move the sampling rates, and only inside the session manager.
+      // If they were merged into the init configuration instead, anything in it — the client
+      // token, the site — could be rewritten from the far end of a request.
+      const initConfiguration = { ...DEFAULT_INIT_CONFIGURATION, remoteConfigurationEnabled: true }
       const strategy = createPreStartStrategy(
         {},
         createTrackingConsentState(),
         createCustomVitalsState(),
         doStartRumSpy
       )
-      strategy.init(
-        {
-          ...DEFAULT_INIT_CONFIGURATION,
-          remoteConfigurationId: '123',
-        },
-        PUBLIC_API
-      )
+      strategy.init(initConfiguration, PUBLIC_API)
+
+      expect(strategy.initConfiguration).toEqual(initConfiguration)
     })
   })
 

packages/rum-core/src/boot/preStartRum.ts

@@ -24,11 +24,13 @@ import {
   validateAndBuildRumConfiguration,
   type RumConfiguration,
   type RumInitConfiguration,
+  readRemoteConfig,
+  buildRemoteConfigSetup,
 } from '../domain/configuration'
 import type { ViewOptions } from '../domain/view/trackViews'
 import type { DurationVital, CustomVitalsState } from '../domain/vital/vitalCollection'
 import { startDurationVital, stopDurationVital } from '../domain/vital/vitalCollection'
-import { fetchAndApplyRemoteConfiguration, serializeRumConfiguration } from '../domain/configuration'
+import { serializeRumConfiguration } from '../domain/configuration'
 import { callPluginsMethod } from '../domain/plugins'
 import { buildGlobalContextManager } from '../domain/contexts/globalContext'
 import { buildUserContextManager } from '../domain/contexts/userContext'
@@ -175,11 +177,7 @@ export function createPreStartStrategy(
 
       callPluginsMethod(initConfiguration.plugins, 'onInit', { initConfiguration, publicApi })
 
-      if (initConfiguration.remoteConfigurationId) {
-        fetchAndApplyRemoteConfiguration(initConfiguration, doInit)
-      } else {
-        doInit(initConfiguration)
-      }
+      doInit(initConfiguration)
     },
 
     get initConfiguration() {
@@ -190,6 +188,18 @@ export function createPreStartStrategy(
 
     stopSession: noop,
 
+    setForcedSession() {
+      bufferApiCalls.add((startRumResult) => startRumResult.setForcedSession())
+    },
+
+    getRemoteConfig() {
+      // Before the SDK starts, the last stored bag still answers — that is what lets application
+      // code read it right after init() without waiting for the first fetch.
+      return cachedInitConfiguration
+        ? readRemoteConfig(buildRemoteConfigSetup(cachedInitConfiguration)).custom
+        : undefined
+    },
+
     addTiming(name, time = timeStampNow()) {
       bufferApiCalls.add((startRumResult) => startRumResult.addTiming(name, time))
     },

packages/rum-core/src/boot/rumPublicApi.spec.ts

@@ -24,6 +24,8 @@ const noopStartRum = (): ReturnType<StartRum> => ({
   viewHistory: {} as any,
   session: {} as any,
   stopSession: () => undefined,
+  setForcedSession: () => undefined,
+  getRemoteConfig: () => undefined,
   startDurationVital: () => ({}) as DurationVitalReference,
   stopDurationVital: () => undefined,
   addDurationVital: () => undefined,

packages/rum-core/src/boot/rumPublicApi.ts

@@ -279,6 +279,38 @@ export interface RumPublicApi extends PublicApi {
    */
   stopSession: () => void
 
+  /**
+   * Force the session to be collected, with Session Replay where this build records it at all,
+   * regardless of the configured sample rates. Call it when your own code decides a visitor needs
+   * debugging (an allow-list, a support flow). On the slim build there is no recorder, so the
+   * visitor is collected without a replay. If the current session was not being collected, it ends and a collected one starts at
+   * the next user interaction; a session already collected keeps running and gets replay recording.
+   * The forced state lasts for the page lifetime — decide on each page load whether to call again.
+   *
+   * The forced state belongs to the page that called, but the session belongs to every tab. So if
+   * the visitor has this site open in another tab and acts there first, that tab draws the
+   * replacement session under the ordinary rates and the visitor is not collected after all —
+   * silently, since nothing failed. The call is not lost: this page stays forced, so a later
+   * session it draws itself is collected. But nothing forces one to arrive soon. Call it from the
+   * page the visitor is actually using, or have them close the others.
+   *
+   * Inside a WebView the host application owns the session, so only the recording half applies:
+   * replay starts, but the session's own sampling decision belongs to the mobile SDK and is left
+   * to it. Force the session there through the host application instead.
+   */
+  setForcedSession: () => void
+
+  /**
+   * Read the custom values published for this application in the console. The SDK delivers them
+   * verbatim and never interprets them — what a value means is entirely up to your own code (a
+   * debug allow-list to pair with `setForcedSession()`, a feature toggle). Values are cached
+   * locally, so the bag published while a previous page was open answers immediately on the next.
+   * Returns undefined when nothing has been published, when remote configuration is off, and
+   * inside a WebView, where the host application owns these settings and nothing is fetched. The
+   * content is readable by anyone holding the public client token — it is public information.
+   */
+  getRemoteConfig: () => Record<string, unknown> | undefined
+
   /**
    * Add a feature flag evaluation,
    * stored in `@feature_flags.<feature_flag_key>`
@@ -397,6 +429,8 @@ export interface Strategy {
   initConfiguration: RumInitConfiguration | undefined
   getInternalContext: StartRumResult['getInternalContext']
   stopSession: StartRumResult['stopSession']
+  setForcedSession: StartRumResult['setForcedSession']
+  getRemoteConfig: StartRumResult['getRemoteConfig']
   addTiming: StartRumResult['addTiming']
   startView: StartRumResult['startView']
   setViewName: StartRumResult['setViewName']
@@ -625,6 +659,12 @@ export function makeRumPublicApi(
       addTelemetryUsage({ feature: 'stop-session' })
     }),
 
+    setForcedSession: monitor(() => {
+      strategy.setForcedSession()
+    }),
+
+    getRemoteConfig: monitor(() => strategy.getRemoteConfig()),
+
     addFeatureFlagEvaluation: monitor((key, value) => {
       strategy.addFeatureFlagEvaluation(sanitize(key)!, sanitize(value))
       addTelemetryUsage({ feature: 'add-feature-flag-evaluation' })