@spotify-confidence/csr-common 0.0.0 → 0.17.2

package/src/uploader/worker/core.ts

@@ -0,0 +1,386 @@
+import type { ClientContext } from '../client-context';
+import type { Client, Frame, Transport } from '../types';
+import { CsrClient } from './csr-client';
+
+/** Adapter so this module is unaware of whether it's running in a SharedWorker or a dedicated Worker. */
+export interface PortAdapter {
+  postMessage(message: unknown): void;
+  onmessage(cb: (data: unknown) => void): void;
+}
+
+interface HelloMessage {
+  type: 'hello';
+  apiUrl: string;
+  websocketUrl?: string;
+  clientSecret: string;
+  targetingKey?: string;
+  context?: ClientContext;
+  forceRecord?: boolean;
+  sessionIdHint?: string;
+  sessionTokenHint?: string;
+  tabId: string;
+  debugLogs?: boolean;
+}
+
+interface FrameMessage {
+  type: 'frame';
+  frame: Frame;
+}
+
+interface ByeMessage {
+  type: 'bye';
+  reason: string;
+}
+
+type IncomingMessage = HelloMessage | FrameMessage | ByeMessage;
+
+interface PortHandle {
+  port: PortAdapter;
+  hello: HelloMessage | null;
+  /** Whether this port opted into debug log forwarding. Per-port so a quiet tab doesn't pay the message cost when another tab opts in. */
+  debugLogs: boolean;
+  /** Set when the worker minted a fresh tabId for this port (tab duplication). Sent to the tab in welcome. */
+  newTabId?: string;
+}
+
+const IDLE_GRACE_MS = 5_000;
+
+type State =
+  | { phase: 'init' }
+  | { phase: 'initializing' }
+  | {
+      phase: 'active';
+      client: Client;
+      transport: Transport;
+      sessionId: string;
+      sessionToken: string;
+    }
+  | {
+      phase: 'idle';
+      client: Client;
+      sessionId: string;
+      sessionToken: string;
+    }
+  | { phase: 'skipping' }
+  | { phase: 'dead'; reason: string };
+
+let state: State = { phase: 'init' };
+const ports: PortHandle[] = [];
+let idleTimer: ReturnType<typeof setTimeout> | null = null;
+
+function cancelIdleTimer(): void {
+  if (idleTimer !== null) {
+    clearTimeout(idleTimer);
+    idleTimer = null;
+  }
+}
+
+function log(msg: string): void {
+  for (const handle of ports) {
+    if (handle.debugLogs) handle.port.postMessage({ type: 'log', msg });
+  }
+}
+/**
+ * The first hello "locks in" the session's apiUrl/clientSecret. Any later tab arriving
+ * with different values is misconfigured — we reject it rather than silently using the
+ * locked values. In SharedWorker mode the `name = hash(clientSecret)` scoping already
+ * prevents secret-mismatch from sharing a worker, but this defends against the dedicated
+ * path and against future bugs.
+ */
+let lockedConfig: {
+  apiUrl: string;
+  websocketUrl: string | undefined;
+  clientSecret: string;
+} | null = null;
+
+export function registerPort(adapter: PortAdapter): void {
+  cancelIdleTimer();
+  const handle: PortHandle = { port: adapter, hello: null, debugLogs: false };
+  ports.push(handle);
+  adapter.onmessage((data: unknown) => {
+    handleMessage(handle, data as IncomingMessage);
+  });
+}
+
+function handleMessage(handle: PortHandle, message: IncomingMessage): void {
+  switch (message.type) {
+    case 'hello':
+      handle.hello = message;
+      handle.debugLogs = message.debugLogs ?? false;
+      if (rejectIfIncompatible(handle)) return;
+      // Skip tabId-mint for hellos that won't end up recording anyway.
+      if (state.phase !== 'dead' && state.phase !== 'skipping') {
+        detectDuplicateTab(handle);
+      }
+      onHello(handle);
+      return;
+    case 'frame':
+      onFrame(message.frame);
+      return;
+    case 'bye':
+      onBye(handle);
+      return;
+    default:
+      break;
+  }
+}
+
+/**
+ * Reject hellos whose `apiUrl`/`clientSecret` don't match the values established by the
+ * first hello. Returns true if the port was rejected (caller should not continue
+ * processing this hello).
+ */
+function rejectIfIncompatible(handle: PortHandle): boolean {
+  if (lockedConfig === null) return false;
+  const incoming = handle.hello!;
+  if (
+    incoming.apiUrl === lockedConfig.apiUrl &&
+    incoming.websocketUrl === lockedConfig.websocketUrl &&
+    incoming.clientSecret === lockedConfig.clientSecret
+  ) {
+    return false;
+  }
+  handle.port.postMessage({
+    type: 'dead',
+    reason: 'incompatible-options: apiUrl/websocketUrl/clientSecret differ from the worker session',
+  });
+  const idx = ports.indexOf(handle);
+  if (idx >= 0) ports.splice(idx, 1);
+  return true;
+}
+
+/**
+ * If another already-connected port has the same `tabId`, this hello is from a duplicate
+ * tab (browser "Duplicate" command clones sessionStorage). Mint a fresh `tabId` so the two
+ * tabs don't collide on the same `(sessionId, tabId)` Recording. The new tabId is returned
+ * to the tab in `welcome` so it can update its own state and sessionStorage.
+ */
+function detectDuplicateTab(handle: PortHandle): void {
+  const tabId = handle.hello!.tabId;
+  const isDuplicate = ports.some(p => p !== handle && p.hello?.tabId === tabId);
+  if (!isDuplicate) return;
+  const fresh = crypto.randomUUID();
+  handle.newTabId = fresh;
+  handle.hello!.tabId = fresh; // future duplicate checks see this updated id
+}
+
+function onHello(handle: PortHandle): void {
+  switch (state.phase) {
+    case 'init': {
+      lockedConfig = {
+        apiUrl: handle.hello!.apiUrl,
+        websocketUrl: handle.hello!.websocketUrl,
+        clientSecret: handle.hello!.clientSecret,
+      };
+      log(
+        `hello received apiUrl=${handle.hello!.apiUrl} websocketUrl=${
+          handle.hello!.websocketUrl ?? '(derive)'
+        } sessionIdHint=${handle.hello!.sessionIdHint ?? '(none)'}`,
+      );
+      state = { phase: 'initializing' };
+      void initializeSession(handle.hello!).then(flushPendingWelcomes);
+      return;
+    }
+    case 'initializing':
+      // Welcome will be sent once initialization resolves.
+      return;
+    case 'active':
+      sendActiveWelcome(handle, state.sessionId, state.sessionToken);
+      return;
+    case 'idle': {
+      const { client, sessionId, sessionToken } = state;
+      state = { phase: 'initializing' };
+      void resumeTransport(client, sessionId, sessionToken).then(flushPendingWelcomes);
+      return;
+    }
+    case 'skipping':
+      if (handle.hello!.forceRecord) {
+        log('forceRecord set; re-initializing from skipping state');
+        state = { phase: 'initializing' };
+        void initializeSession(handle.hello!).then(flushPendingWelcomes);
+        return;
+      }
+      handle.port.postMessage({
+        type: 'welcome',
+        result: { skipRecording: true },
+      });
+      return;
+    case 'dead':
+      handle.port.postMessage({ type: 'dead', reason: state.reason });
+      return;
+    default:
+      break;
+  }
+}
+
+async function initializeSession(firstHello: HelloMessage): Promise<void> {
+  const client = new CsrClient(
+    firstHello.apiUrl,
+    firstHello.clientSecret,
+    firstHello.targetingKey,
+    firstHello.context,
+    firstHello.websocketUrl,
+    log,
+    firstHello.forceRecord,
+  );
+
+  // Try to adopt the hint first. Need both sessionId (for tab-side state) and
+  // sessionToken (to authenticate the WS upgrade).
+  if (firstHello.sessionIdHint && firstHello.sessionTokenHint) {
+    log(`adopting sessionIdHint=${firstHello.sessionIdHint}`);
+    try {
+      const transport = await client.openTransport(firstHello.sessionTokenHint);
+      wireTransport(transport);
+      state = {
+        phase: 'active',
+        client,
+        transport,
+        sessionId: firstHello.sessionIdHint,
+        sessionToken: firstHello.sessionTokenHint,
+      };
+      log('hint adopted; transport open');
+      if (ports.length === 0) {
+        idleTimer = setTimeout(enterIdle, IDLE_GRACE_MS);
+      }
+      return;
+    } catch (err) {
+      // Stale or rejected — fall through to fresh init.
+      log(`hint rejected (${String(err)}); falling back to fresh init`);
+    }
+  }
+
+  let result: { sessionId: string; sessionToken: string } | { skipRecording: true };
+  try {
+    result = await client.initSession();
+  } catch (err) {
+    log(`init-session threw: ${String(err)}`);
+    transitionToDead(`init-session-failed: ${String(err)}`);
+    return;
+  }
+
+  if ('skipRecording' in result) {
+    log('init-session: skipRecording');
+    state = { phase: 'skipping' };
+    return;
+  }
+
+  log(`init-session ok sessionId=${result.sessionId}`);
+  let transport: Transport;
+  try {
+    transport = await client.openTransport(result.sessionToken);
+  } catch (err) {
+    log(`openTransport threw: ${String(err)}`);
+    transitionToDead(`open-transport-failed: ${String(err)}`);
+    return;
+  }
+  wireTransport(transport);
+  log('transport open; session active');
+  state = {
+    phase: 'active',
+    client,
+    transport,
+    sessionId: result.sessionId,
+    sessionToken: result.sessionToken,
+  };
+  if (ports.length === 0) {
+    idleTimer = setTimeout(enterIdle, IDLE_GRACE_MS);
+  }
+}
+
+async function resumeTransport(client: Client, sessionId: string, sessionToken: string): Promise<void> {
+  log('resuming transport from idle');
+  let transport: Transport;
+  try {
+    transport = await client.openTransport(sessionToken);
+  } catch (err) {
+    log(`resume-transport threw: ${String(err)}`);
+    transitionToDead(`resume-transport-failed: ${String(err)}`);
+    return;
+  }
+  wireTransport(transport);
+  log('transport resumed');
+  state = { phase: 'active', client, transport, sessionId, sessionToken };
+  if (ports.length === 0) {
+    idleTimer = setTimeout(enterIdle, IDLE_GRACE_MS);
+  }
+}
+
+function wireTransport(transport: Transport): void {
+  transport.onClose(info => {
+    if (state.phase !== 'active') return;
+    transitionToDead(info.reason);
+  });
+  transport.onStateChange(info => {
+    if (state.phase !== 'active') return;
+    for (const handle of ports) {
+      handle.port.postMessage({ type: 'state', connected: info.connected });
+    }
+  });
+}
+
+function transitionToDead(reason: string): void {
+  state = { phase: 'dead', reason };
+  for (const handle of ports) {
+    handle.port.postMessage({ type: 'dead', reason });
+  }
+}
+
+function flushPendingWelcomes(): void {
+  for (const handle of ports) {
+    if (handle.hello === null) continue;
+    if (state.phase === 'active') {
+      sendActiveWelcome(handle, state.sessionId, state.sessionToken);
+    } else if (state.phase === 'skipping') {
+      handle.port.postMessage({
+        type: 'welcome',
+        result: { skipRecording: true },
+      });
+    } else if (state.phase === 'dead') {
+      handle.port.postMessage({ type: 'dead', reason: state.reason });
+    }
+  }
+}
+
+function sendActiveWelcome(handle: PortHandle, currentSessionId: string, currentSessionToken: string): void {
+  const hint = handle.hello?.sessionIdHint;
+  const adopted = hint !== undefined && hint !== currentSessionId;
+  const newTabId = handle.newTabId;
+  handle.port.postMessage({
+    type: 'welcome',
+    result: { sessionId: currentSessionId, sessionToken: currentSessionToken },
+    adoptedFromSessionId: adopted ? hint : undefined,
+    newTabId,
+    resetCounter: adopted || newTabId !== undefined,
+  });
+}
+
+function onFrame(frame: Frame): void {
+  // In normal flow the tab can't send frames before receiving `welcome` (only sent in
+  // 'active') and stops after `dead` (its uploader throws). The race we're guarding is a
+  // frame already in flight at the instant we transition out of 'active' — e.g.
+  // `transport.onClose` fires while the tab has just posted a frame to the port. Drop it.
+  if (state.phase !== 'active') return;
+  state.transport.send(frame);
+}
+
+function onBye(handle: PortHandle): void {
+  const idx = ports.indexOf(handle);
+  if (idx >= 0) ports.splice(idx, 1);
+  if (ports.length === 0 && state.phase === 'active') {
+    log(`last tab disconnected; closing transport in ${IDLE_GRACE_MS}ms`);
+    idleTimer = setTimeout(enterIdle, IDLE_GRACE_MS);
+  }
+}
+
+function enterIdle(): void {
+  idleTimer = null;
+  if (state.phase !== 'active' || ports.length > 0) return;
+  log('idle timeout; closing transport');
+  state.transport.close('idle');
+  state = {
+    phase: 'idle',
+    client: state.client,
+    sessionId: state.sessionId,
+    sessionToken: state.sessionToken,
+  };
+}

package/src/uploader/worker/csr-client.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, it } from 'vitest';
+import { installMockFetch, installMockWsServer, jsonResponse } from '../../test-utils';
+import { CsrClient } from './csr-client';
+
+describe('CsrClient.initSession', () => {
+  it('POSTs to /v1/sessions:initSession with clientSecret', async () => {
+    const { calls } = installMockFetch(() => jsonResponse({ sessionId: 'sess-1', sessionToken: 'tok-1' }));
+
+    const client = new CsrClient('https://recording.confidence.dev', 'secret', undefined, undefined);
+    const result = await client.initSession();
+
+    expect(result).toEqual({ sessionId: 'sess-1', sessionToken: 'tok-1' });
+    expect(calls).toHaveLength(1);
+    expect(calls[0].url).toBe('https://recording.confidence.dev/v1/sessions:initSession');
+    expect(JSON.parse(calls[0].init!.body as string)).toEqual({
+      clientSecret: 'secret',
+    });
+  });
+
+  it('forwards targetingKey when set, omits it when undefined', async () => {
+    const { calls } = installMockFetch(() => jsonResponse({ sessionId: 's', sessionToken: 't' }));
+
+    const withKey = new CsrClient('https://api', 'secret', 'user-42', undefined);
+    await withKey.initSession();
+    expect(JSON.parse(calls[0].init!.body as string)).toEqual({
+      clientSecret: 'secret',
+      targetingKey: 'user-42',
+    });
+
+    const withoutKey = new CsrClient('https://api', 'secret', undefined, undefined);
+    await withoutKey.initSession();
+    expect(JSON.parse(calls[1].init!.body as string)).toEqual({
+      clientSecret: 'secret',
+    });
+  });
+
+  it('trims a trailing slash from apiUrl when building the init URL', async () => {
+    const { calls } = installMockFetch(() => jsonResponse({ sessionId: 's', sessionToken: 't' }));
+
+    const client = new CsrClient('https://api/', 'secret', undefined, undefined);
+    await client.initSession();
+
+    expect(calls[0].url).toBe('https://api/v1/sessions:initSession');
+  });
+
+  it('forwards context when set, omits it when empty/undefined', async () => {
+    const { calls } = installMockFetch(() => jsonResponse({ sessionId: 's', sessionToken: 't' }));
+
+    const ctx = {
+      userAgent: { os: 'macos', browser: 'chrome', viewportWidth: 1440 },
+    };
+    const withCtx = new CsrClient('https://api', 'secret', undefined, ctx);
+    await withCtx.initSession();
+    expect(JSON.parse(calls[0].init!.body as string)).toEqual({
+      clientSecret: 'secret',
+      context: ctx,
+    });
+
+    const withEmpty = new CsrClient('https://api', 'secret', undefined, {});
+    await withEmpty.initSession();
+    expect(JSON.parse(calls[1].init!.body as string)).toEqual({
+      clientSecret: 'secret',
+    });
+  });
+
+  it('returns skipRecording when the backend asks to skip', async () => {
+    installMockFetch(() => jsonResponse({ skipRecording: true }));
+
+    const client = new CsrClient('https://api', 'secret', undefined, undefined);
+    expect(await client.initSession()).toEqual({ skipRecording: true });
+  });
+
+  it('throws on non-2xx response', async () => {
+    installMockFetch(() => new Response(null, { status: 500 }));
+
+    const client = new CsrClient('https://api', 'secret', undefined, undefined);
+    await expect(client.initSession()).rejects.toThrow(/HTTP 500/);
+  });
+
+  it('throws when the response is missing sessionId/sessionToken', async () => {
+    installMockFetch(() => jsonResponse({ sessionId: 'x' }));
+
+    const client = new CsrClient('https://api', 'secret', undefined, undefined);
+    await expect(client.initSession()).rejects.toThrow(/missing sessionId or sessionToken/);
+  });
+});
+
+describe('CsrClient.openTransport', () => {
+  it('derives a ws:// URL from an http:// apiUrl when websocketUrl is unset', async () => {
+    installMockWsServer('ws://api.example/sessions/stream?session_token=tok');
+
+    const client = new CsrClient('http://api.example', 'secret', undefined, undefined);
+    await expect(client.openTransport('tok')).resolves.toBeDefined();
+  });
+
+  it('derives a wss:// URL from an https:// apiUrl', async () => {
+    installMockWsServer('wss://api.example/sessions/stream?session_token=tok');
+
+    const client = new CsrClient('https://api.example', 'secret', undefined, undefined);
+    await expect(client.openTransport('tok')).resolves.toBeDefined();
+  });
+
+  it('uses websocketUrl verbatim when provided (split-host prod layout)', async () => {
+    installMockWsServer('wss://recording-ws.confidence.dev/sessions/stream?session_token=tok');
+
+    const client = new CsrClient(
+      'https://recording.confidence.dev',
+      'secret',
+      undefined,
+      undefined,
+      'wss://recording-ws.confidence.dev/sessions/stream',
+    );
+    await expect(client.openTransport('tok')).resolves.toBeDefined();
+  });
+
+  it('URL-encodes the session token', async () => {
+    installMockWsServer('wss://api/sessions/stream?session_token=tok%2Fwith%3Dspecials');
+
+    const client = new CsrClient('https://api', 'secret', undefined, undefined);
+    await expect(client.openTransport('tok/with=specials')).resolves.toBeDefined();
+  });
+});

package/src/uploader/worker/csr-client.ts

@@ -0,0 +1,67 @@
+import type { ClientContext } from '../client-context';
+import type { Client, Transport } from '../types';
+import { WebSocketTransport } from './web-socket-transport';
+
+/**
+ * Single Client implementation that talks to the recording backend's REST + WS protocol.
+ * Both dev-server and prod implement the same protocol, so we don't need polymorphism here yet.
+ */
+export class CsrClient implements Client {
+  constructor(
+    private readonly apiUrl: string,
+    private readonly clientSecret: string,
+    private readonly targetingKey: string | undefined,
+    private readonly context: ClientContext | undefined,
+    private readonly websocketUrl?: string,
+    private readonly log: (msg: string) => void = () => {},
+    private readonly forceRecord?: boolean,
+  ) {}
+
+  async initSession(): Promise<{ sessionId: string; sessionToken: string } | { skipRecording: true }> {
+    const url = `${this.trimSlash(this.apiUrl)}/v1/sessions:initSession`;
+    this.log(`fetch POST ${url}`);
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        clientSecret: this.clientSecret,
+        ...(this.targetingKey ? { targetingKey: this.targetingKey } : {}),
+        ...(this.context && Object.keys(this.context).length > 0 ? { context: this.context } : {}),
+        ...(this.forceRecord ? { forceRecord: true } : {}),
+      }),
+    });
+    if (!res.ok) {
+      throw new Error(`init-session failed: HTTP ${res.status}`);
+    }
+    const data = (await res.json()) as {
+      sessionId?: string;
+      sessionToken?: string;
+      skipRecording?: boolean;
+    };
+    if (data.skipRecording) return { skipRecording: true };
+    if (!data.sessionId || !data.sessionToken) {
+      throw new Error('init-session response missing sessionId or sessionToken');
+    }
+    return { sessionId: data.sessionId, sessionToken: data.sessionToken };
+  }
+
+  async openTransport(sessionToken: string): Promise<Transport> {
+    const wsBase = this.websocketUrl ?? `${this.toWsScheme(this.trimSlash(this.apiUrl))}/sessions/stream`;
+    const sep = wsBase.includes('?') ? '&' : '?';
+    const url = `${wsBase}${sep}session_token=${encodeURIComponent(sessionToken)}`;
+    this.log(`WebSocket connect ${url}`);
+    const transport = new WebSocketTransport(url);
+    await transport.ready();
+    return transport;
+  }
+
+  private trimSlash(s: string): string {
+    return s.endsWith('/') ? s.slice(0, -1) : s;
+  }
+
+  private toWsScheme(base: string): string {
+    if (base.startsWith('https://')) return `wss://${base.slice('https://'.length)}`;
+    if (base.startsWith('http://')) return `ws://${base.slice('http://'.length)}`;
+    return base;
+  }
+}

package/src/uploader/worker/entry.ts

@@ -0,0 +1,40 @@
+import { registerPort, type PortAdapter } from './core';
+
+// Branch on which worker context we're running in. SharedWorkerGlobalScope only exists
+// at runtime inside a SharedWorker; we feature-detect it via `globalThis`.
+const SharedWorkerScopeCtor = (
+  globalThis as unknown as {
+    SharedWorkerGlobalScope?: new () => unknown;
+  }
+).SharedWorkerGlobalScope;
+
+const isShared = typeof SharedWorkerScopeCtor === 'function' && self instanceof SharedWorkerScopeCtor;
+
+if (isShared) {
+  (self as unknown as SharedWorkerGlobalScope).onconnect = (event: MessageEvent) => {
+    const port = event.ports[0];
+    port.start();
+    registerPort(adaptMessagePort(port));
+  };
+} else {
+  registerPort(adaptDedicatedSelf());
+}
+
+function adaptMessagePort(port: MessagePort): PortAdapter {
+  return {
+    postMessage: message => port.postMessage(message),
+    onmessage: cb => {
+      port.onmessage = (e: MessageEvent) => cb(e.data);
+    },
+  };
+}
+
+function adaptDedicatedSelf(): PortAdapter {
+  const ws = self as unknown as DedicatedWorkerGlobalScope;
+  return {
+    postMessage: message => ws.postMessage(message),
+    onmessage: cb => {
+      ws.onmessage = (e: MessageEvent) => cb(e.data);
+    },
+  };
+}