feat(rum): keep collecting Session Replay in the page when a host bridge is present

[Fiona2016]

What

Adds a sessionReplayDirectUpload init option to @flashcatcloud/browser-rum, so that a page embedded in a host application keeps collecting Session Replay and uploads it itself, instead of handing it over to the host.

Draft: do not merge, do not publish.

Baseline: this branch is cut from publish (97bcf9b7, v0.0.6), which is this fork's mainline — not main. main is stuck 75 commits behind at the fork point; npm @flashcatcloud/browser-core@0.0.6 matches publish. An earlier revision of this work was mistakenly based on main (PR #17, now closed).

Why

When the SDK runs inside a host application that injects a DatadogEventBridge (an Electron renderer process, a mobile WebView), upstream assumes the host takes over Session Replay. If the host does not declare the records capability, the whole recorder API is replaced by a no-op shell and no replay is collected at all.

Our Electron SDK (@flashcatcloud/electron-sdk) injects the bridge from its preload script but returns an empty capability list, so customers who had working Session Replay lose it as soon as they adopt the Electron SDK.

The upstream design — the host receives raw records over bridge.send('record', ...) and does the segmentation, compression and multipart upload itself — is a large amount of work and has no Electron implementation upstream to this day. This change takes the other route: let the page stay on the path it already uses on the web.

The intake side needs no change. The payload, the endpoint builder (including proxy, which applies to the replay track exactly like to rum) and the authentication (dd-api-key = the same client token) are the ones a plain web page already uses. This was verified end to end on dev: segments uploaded from an application of type electron, both direct and through a ddforward proxy, return 202, land in S3 and in t_replay_segments, and the read endpoint hands back a presigned URL.

The four change points

They are the only behavioral changes, each marked FLASHCAT FORK (n/4) in the code so the fork delta stays easy to spot if an upstream patch ever has to be picked. Points 1-3 turn the recorder back on; point 4 is what makes the resulting uploads actually accepted, and was added after the first end-to-end round on Electron.

1. packages/rum/src/boot/recorderApi.ts — the recorder is no longer disabled up front when a bridge is present without the records capability. That check moved from makeRecorderApi() into onRumStart(), because it now depends on a configuration option, and the configuration does not exist yet when makeRecorderApi() runs at module evaluation. makeRecorderApi() keeps only the browser support check; the resulting behavior for a host that does not opt in is unchanged (the strategy stays the pre-start one, so isRecording() is false, getReplayStats() and getSessionReplayLink() are undefined, and no worker is ever started).
2. packages/rum/src/boot/startRecording.ts — records go to startSegmentCollection (segment + upload) instead of startRecordBridge (hand over to the host).
3. packages/rum-core/src/domain/rumSessionManager.ts — the stub session is marked SAMPLED, so view events carry session.has_replay. That flag is what the read side keys on to expose the replay; without it the segments would be uploaded but never reachable.
4. packages/rum-core/src/boot/preStartRum.ts — overrideInitConfigurationForBridge() no longer replaces clientToken with the literal 'empty' and applicationId with a placeholder when the option is set. See below; without this every segment is rejected with 401.

Plus one correctness fix that falls out of point 3, in packages/rum-core/src/domain/contexts/userContext.ts — also below.

Why point 4 is required, not cosmetic

overrideInitConfigurationForBridge() swaps the real credentials for placeholders:

applicationId: '00000000-aaaa-0000-aaaa-000000000000',
clientToken: 'empty',

That is sound upstream, because the premise is that a page hosting a bridge never sends a request of its own. This PR breaks exactly that premise: the page starts sending replay requests again, and it was sending them with the string 'empty' as its credential.

The first end-to-end round pinned it down by comparison — same URL, same payload, only the key changed:

credential	result
dd-api-key=empty	401
real client token	400 (authenticated; the probe payload was just synthetic)
real token + real application id + a well formed segment	202, stored, with acct_id/session_id matching its session row

So the join logic was fine all along and only the credential was blocking. The application id matters too, not just the token: computeSegmentContext() builds segment metadata from configuration.applicationId, and t_replay_segments.application_id is a NOT NULL column.

Keeping both is safe for everything else. RUM events under a bridge go through bridge.send() and never touch HTTP, so the credentials are irrelevant to them. And the renderer's application.id is overwritten by the Electron main process in assembleRendererRumEvent anyway, so restoring the real one introduces no inconsistency. sessionSampleRate: 100 is left exactly as upstream has it.

The usr.id fix

userContext.ts contains a Flashcat-only line (not upstream):

user.id = isEmptyObject(user) ? session.anonymousId : user.id

Giving the stub session an anonymousId in point 3 activated it — the first round measured every renderer process event carrying usr.id = anonymous_id, 6 of 6.

That is unwanted here. A host application's unique-user baseline already prefers the anonymous id (COALESCE(usr_anonymous_id, usr_id)), and that id is stable across logins, so the copy buys nothing — while importing the web's double-counting bug, where one device counts as two users before and after a login. fc-sdk-electron deliberately does not backfill on the main process side, and the renderer now matches.

Web behavior is deliberately untouched, since this file is shared by every web customer and that line is why web unique users are countable at all: the web baseline counts only usr.id, so without the backfill every logged-out visitor is missed. The skip is therefore conditional.

The condition is canUseEventBridge(), not the new option. The anonymous id becomes host-owned as soon as a bridge supplies it, whether or not direct upload is enabled, so gating on the option would leave the same double-counting in place for a host that provides getAnonymousId() without opting into replay. Bridge presence is what actually delimits "this id is ours" from "this id is the host's". It is evaluated once, since a bridge is injected before any page script runs.

Both sides are pinned by tests: the web backfill (which had no test before) and the bridge case where usr.id stays absent while usr.anonymous_id is set.

Session id and anonymous id

This is the part the approach stands or falls on.

With a bridge present, the page uses startRumSessionManagerStub(), whose session id is the hardcoded placeholder 00000000-aaaa-0000-aaaa-000000000000. That is fine upstream because the host overwrites session.id on every RUM event it forwards — which our Electron main process does. But nobody overwrites the session id of a replay segment, since the segment is uploaded by the page directly. Segments are joined to a session by (account, session id), so a placeholder id means the replay is stored and never associated with a real session.

The stub therefore reads the identifiers the host actually owns, through two new optional methods on the bridge:

getSessionId?(): string
getAnonymousId?(): string

Both are feature-detected: a host built against an older SDK does not implement them, and the page falls back to the placeholder session id and to no anonymous id, rather than crashing. The session id is read on every findTrackedSession() call, because the host renews it over time.

getAnonymousId() also fixes a second problem: the stub session had no anonymousId field at all, so usr.anonymous_id was always empty in a host application and unique user counts were always zero.

The host side of the contract is implemented and verified in flashcatcloud/fc-sdk-electron#11.

Configuration

flashcatRum.init({
  applicationId: '...',
  clientToken: '...',
  sessionReplayDirectUpload: true,
  sessionReplaySampleRate: 100, // required, see below
})

sessionReplaySampleRate defaults to 0, and this option does not change that. Enabling sessionReplayDirectUpload alone records nothing. The sample rate is applied to the stub session as well, so it has to be set explicitly. This is called out in the option's TSDoc.

The option has no effect outside a host application: without a bridge the page already records and uploads Session Replay.

Tests

New specs cover each branch:

• recorderApi.spec.ts — the recorder starts when the bridge does not support records but the option is set (the existing "should not start recording" case is untouched and still passes).
• startRecording.spec.ts — with a bridge present and the option set, segments are sent over the SDK's own request and nothing goes through bridge.send.
• rumSessionManager.spec.ts — the session is SAMPLED with the option set, OFF when sessionReplaySampleRate is 0; the bridge-provided session id and anonymous id are used, the placeholder is used when the bridge does not implement the methods or returns an empty string, and the session id is re-read on each call.
• preStartRum.spec.ts — credentials are still replaced by placeholders by default, and kept when the option is set.
• userContext.spec.ts — the web backfill is pinned (it had no coverage before), and under a bridge usr.id is not backfilled while usr.anonymous_id is still set, with a customer-provided usr.id left untouched.

mockEventBridge gained optional sessionId / anonymousId; omitting them leaves the methods off the mock entirely, which is what emulates an older host.

No existing assertion was relaxed or removed. configuration.spec.ts was updated only to include the new key in the exhaustive Required<RumInitConfiguration> object (the option is not reported to telemetry).

Checks

Green on this baseline, with no assertion relaxed or removed:

• yarn test:unit — 2669/2683 passing, 0 failures (baseline publish is 2656/2670, 0 failures; the delta is exactly the 13 new specs).
• yarn typecheck — 0 errors.
• yarn lint — 0 problems.
• prettier --check — clean on every touched file.

One local-setup note for reviewers: packages/core has to be built once (tsc -p packages/core/tsconfig.cjs.json && tsc -p packages/core/tsconfig.esm.json) before yarn lint / yarn typecheck resolve @flashcatcloud/browser-core. Without it you get ~246 spurious import/no-unresolved errors and 4 type errors in developer-extension/. This is a build-state artifact, not a code issue.

---

Follow-up: no collection while the host has no session

Review caught a hole in the identifier handling above. A host that owns the session id answers '' through the bridge while it has none — a session that timed out and has not been renewed. getEventBridge().getSessionId() folded that empty answer into undefined, the same value it returns for a host that does not implement the getter at all, and the stub then fell back to STUB_SESSION_ID.

RUM events survive that: the host overrides their session id, or drops them. Session Replay segments do not — this PR has the page upload them directly, so they reached the intake carrying a placeholder that is a single constant shared by every application built on the host. Records collected during the gap were both lost to the real session and mixed into a fake one shared across applications. The window is real: only a click counts as end-user activity in the Electron host, so scrolling or typing for 15 minutes expires the session while the recorder keeps running.

What changed

• eventBridge.ts — getSessionId() now returns undefined only when the host does not implement the getter, and '' when the host implements it and has no session. Any other falsy answer from an implementing host is normalised to ''. The interface doc says so.
• rumSessionManager.ts — findTrackedSession() returns undefined for ''. Nothing is cached: reusing the id the host held a moment ago would attribute records to a session that has ended, which is the same bug with a different id.
• rumSessionManager.ts — the stub now watches the host session and turns transitions into SESSION_EXPIRED / SESSION_RENEWED. It owns a stop(), which startRum registers as a cleanup task.

Why this semantic

findTrackedSession() returning undefined is already this SDK's "no session" state, and the replay pipeline already knows what to do with it — segmentCollection.ts documents it verbatim: "If the RUM session ends and no session id is available when creating a new segment, records will be ignored, until the session is renewed and a new session id is available." So segment creation pauses and resumes on its own. No new concept, no new code path.

The watch exists because that alone is not enough. Without a SESSION_EXPIRED, the recorder keeps a segment open across the end of the host session (up to SEGMENT_DURATION_LIMIT), and after a renewal the next segment starts from an incremental record with no full snapshot — unplayable. Both are what postStartStrategy already handles for a regular session, so the stub feeds it the same two events.

Polling is not a new mechanism either: the bridge is pull-only, and the regular session manager learns of its own expiry the same way, polling its store every STORAGE_POLL_DELAY and turning the transitions into expire/renew notifications. The stub mirrors that, at the same interval, and only when the host actually answers for the session id — an older host never starts a timer.

Tests

13 further specs, each verified by mutation (revert the behaviour, the spec fails):

Mutation	Specs that fail
getSessionId() folds '' back into undefined	7
findTrackedSession() falls back to the placeholder for ''	2
the host-session watch is removed	4

• eventBridge.spec.ts — the three answers are distinct, and a falsy answer from an implementing host normalises to ''.
• rumSessionManager.spec.ts — no tracked session while the host reports none, never the placeholder, and a tracked session again on renewal; SESSION_EXPIRED on expiry, SESSION_RENEWED on renewal, both when the host swaps one session for another without reporting a gap, the manager already answering with the new session when it notifies, nothing notified while the host session is unchanged, no watch for a host that does not implement the getter, and no notifications after stop().

The rest of the chain was already covered and is untouched: computeSegmentContext returns undefined when the session is not tracked, and addRecord ignores records with no context.

yarn test:unit — 2682/2696 passing, 0 failures (was 2669/2683; the delta is exactly the 13 new specs). yarn typecheck, yarn lint, prettier --check all clean.

🤖 Generated with Claude Code