feat(highlight.run): stop session replay when uploads cannot succeed

[abelonogov-ld]

Brings the browser SDK in line with the iOS and Android work on unrecoverable Session Replay errors, and closes the memory paths that surfaced along the way.

Why

Every public graph failure was retried three times with backoff, permanent ones included, and the only thing that ever stopped recording was an upload timeout. So:

• A refused environment (bad SDK key, replay disabled, quota) cost four doomed requests and roughly 6.5s of backoff on every page load.
• The timeout stop left rrweb attached while _save no longer ran, so events accumulated for the rest of the page load, which is the opposite of what that stop was for.
• Five failed sends in a row closed the worker's send gate without stopping anything, and every later payload was queued for good.

What changed

Error classification (src/client/utils/error-recoverability.ts) mirrors the Swift ErrorRecoverability: 400, 408, 429 and anything outside the 4xx range are recoverable, the rest of the 4xx range is not, an explicit extensions.retryable overrides the status either way, and a 200 carrying GraphQL errors is treated like a generic 4xx. BillingQuotaExceeded stays permanent regardless, which is the one case the old message-matching handled. Anything that is not a ClientError (offline, DNS, aborted fetch) stays recoverable.

The retry wrapper asks the classifier instead of comparing error message strings, so a refusal throws on the first attempt. This covers initializeSession on the main thread and the worker's uploads, since both share the wrapper.

The worker turns an unrecoverable failure, and an exhausted retry budget, into the stop signal that previously only fired on timeouts. stopRecording() now owns stopping: it drops the pending queue and batched metrics, posts the stop with a StopReason, records the reason as a track property, and stops accepting work until the client initializes again.

The client detaches rrweb and clears its event buffer for any stop the worker asks for, in both RecordSDK and the legacy Highlight class. stop() keeps its existing behavior for manual stops; the teardown moved into a shared _stopRecorder().

Notes

• An unrecoverable failure on any worker operation (identify, session properties, feedback) stops recording, not just payload pushes. The realistic causes are environment-wide, so they get the same verdict.
• identify and friends called after a stop are now dropped instead of queued forever.
• Unlike mobile, there is no disk-cached refusal and no eager probe: a page load is the natural fresh launch, and initializeSession already runs before capture starts.

Test plan

• yarn turbo run test --filter highlight.run (lint, build, enforce-size, tests) green
• 461 tests across 26 files, tsc --noEmit clean
• New coverage: the classifier, the retry wrapper (no retry when unrecoverable, full budget when not), the worker end to end against a mocked graph SDK (403 stops once and drops later messages, 503 does not stop, exhausted budget stops, a new Initialize resumes), and RecordSDK releasing rrweb plus clearing its buffer for all three stop reasons

Made with Cursor

[Vadman97]

there is probably a lot that can be cleaned up in this implementation... but we don't have to do it now

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 485eea4. Configure here.}

[cursor]

Stale failures stop new sessions

Medium Severity

handleFailedMessage still stops recording for failures from requests that were already in flight when a prior stop happened. Initialize and Reset clear hasStoppedRecording without invalidating those older requests, so a late 403 or exhausted retry from the previous session can post a new Stop and tear down a session that just resumed.

Additional Locations (2)

• sdk/highlight-run/src/client/workers/highlight-client-worker.ts#L434-L454
• sdk/highlight-run/src/client/workers/highlight-client-worker.ts#L458-L470

 

^{Reviewed by Cursor Bugbot for commit 485eea4. Configure here.}