livekit-client 2.20.0 → 2.20.2

package/src/room/track/Track.ts

@@ -9,6 +9,7 @@ import { EventEmitter } from 'events';
 import type TypedEventEmitter from 'typed-emitter';
 import type { SignalClient } from '../../api/SignalClient';
 import log, { LoggerNames, type StructuredLogger, getLogger } from '../../logger';
+import type { NonSharedUint8Array } from '../../type-polyfills/non-shared-typed-arrays';
 import { TrackEvent } from '../events';
 import type { LoggerOptions } from '../types';
 import { isFireFox, isSafari, isWeb } from '../utils';
@@ -59,6 +60,9 @@ export abstract class Track<
 
   /** @internal */
   setStreamState(value: Track.StreamState) {
+    if (this._streamState !== value) {
+      this.log.debug(`stream state changed: ${this._streamState} -> ${value}`);
+    }
     this._streamState = value;
   }
 
@@ -89,8 +93,8 @@ export abstract class Track<
     loggerOptions: LoggerOptions = {},
   ) {
     super();
-    this.log = getLogger(loggerOptions.loggerName ?? LoggerNames.Track);
     this.loggerContextCb = loggerOptions.loggerContextCb;
+    this.log = getLogger(loggerOptions.loggerName ?? LoggerNames.Track, () => this.logContext);
 
     this.setMaxListeners(100);
     this.kind = kind;
@@ -184,11 +188,11 @@ export abstract class Track<
           this.emit(hasAudio ? TrackEvent.AudioPlaybackFailed : TrackEvent.VideoPlaybackFailed, e);
         } else if (e.name === 'AbortError') {
           // commonly triggered by another `play` request, only log for debugging purposes
-          log.debug(
+          this.log.debug(
             `${hasAudio ? 'audio' : 'video'} playback aborted, likely due to new play request`,
           );
         } else {
-          log.warn(`could not playback ${hasAudio ? 'audio' : 'video'}`, e);
+          this.log.warn(`could not playback ${hasAudio ? 'audio' : 'video'}`, { error: e });
         }
         // If audio playback isn't allowed make sure we still play back the video
         if (
@@ -251,6 +255,7 @@ export abstract class Track<
   }
 
   stop() {
+    this.log.debug('stopping track');
     this.stopMonitor();
     this._mediaStreamTrack.stop();
   }
@@ -278,12 +283,12 @@ export abstract class Track<
 
   /** @internal */
   updateLoggerOptions(loggerOptions: LoggerOptions) {
-    if (loggerOptions.loggerName) {
-      this.log = getLogger(loggerOptions.loggerName);
-    }
     if (loggerOptions.loggerContextCb) {
       this.loggerContextCb = loggerOptions.loggerContextCb;
     }
+    if (loggerOptions.loggerName) {
+      this.log = getLogger(loggerOptions.loggerName, () => this.logContext);
+    }
   }
 
   private recycleElement(element: HTMLMediaElement) {

package/src/room/track/options.ts

@@ -84,7 +84,17 @@ export interface TrackPublishDefaults {
   scalabilityMode?: ScalabilityMode;
 
   /**
-   * degradation preference
+   * Controls how the encoder trades off between resolution and framerate
+   * when bandwidth is constrained.
+   *
+   * - 'maintain-framerate': Prioritizes framerate, reduces resolution if needed
+   * - 'maintain-resolution': Prioritizes resolution, drops frames if needed
+   * - 'balanced': Balances between both
+   *
+   * If not set, the SDK uses defaults based on track source:
+   * - Camera: 'maintain-framerate' (smoother video for real-time communication)
+   * - Screen share: 'maintain-resolution' (clarity is critical for text/UI)
+   * - Other/unknown: 'balanced'
    */
   degradationPreference?: RTCDegradationPreference;
 

package/src/room/track/record.ts

@@ -1,3 +1,4 @@
+import type { NonSharedUint8Array } from '../../type-polyfills/non-shared-typed-arrays';
 import type LocalTrack from './LocalTrack';
 
 // Check if MediaRecorder is available

package/src/room/utils.ts

@@ -7,6 +7,7 @@ import {
   Transcription as TranscriptionModel,
 } from '@livekit/protocol';
 import { type Throws } from '@livekit/throws-transformer/throws';
+import type { NonSharedUint8Array } from '../type-polyfills/non-shared-typed-arrays';
 import TypedPromise from '../utils/TypedPromise';
 import { getBrowser } from '../utils/browserParser';
 import type { BrowserDetails } from '../utils/browserParser';

package/src/test/signalServerSetup.ts

@@ -0,0 +1,151 @@
+import { type ChildProcess, execFileSync, spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { Socket, createServer } from 'node:net';
+import { join } from 'node:path';
+import { createToken } from './signalToken';
+
+/**
+ * vitest globalSetup for the browser signal e2e suite. It provides the tests a
+ * ws:// base URL for the LiveKit mock test-server, via one of two paths:
+ *
+ *   - LK_TEST_SERVER_URL — connect to an already-running server (CI runs the
+ *     published test-server Docker image as a service; see .github/workflows/e2e.yaml).
+ *   - LK_SERVER_DIR — a local livekit-server checkout: build cmd/test-server
+ *     and spawn it on an ephemeral port (dev convenience).
+ *
+ * If neither is set (or the toolchain is unavailable) the suite is skipped.
+ */
+
+const HOST = '127.0.0.1';
+
+let child: ChildProcess | undefined;
+
+function getFreePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const srv = createServer();
+    srv.unref();
+    srv.on('error', reject);
+    srv.listen(0, HOST, () => {
+      const addr = srv.address();
+      const port = typeof addr === 'object' && addr ? addr.port : 0;
+      srv.close(() => resolve(port));
+    });
+  });
+}
+
+// Poll the validate endpoint (from Node — no CORS here) until it answers 200.
+async function waitReady(serverUrl: string): Promise<boolean> {
+  const token = await createToken({ signal: 'happy' });
+  const httpBase = serverUrl.replace(/^ws/, 'http');
+  const validateUrl = `${httpBase}/rtc/validate?access_token=${encodeURIComponent(token)}`;
+  const deadline = Date.now() + 20_000;
+  while (Date.now() < deadline) {
+    try {
+      if ((await fetch(validateUrl)).status === 200) {
+        return true;
+      }
+    } catch {
+      // not up yet
+    }
+    await new Promise((r) => setTimeout(r, 200));
+  }
+  return false;
+}
+
+export default async function setup(project: { provide: (name: string, value: unknown) => void }) {
+  const provide = (serverUrl: string) => {
+    project.provide('serverUrl', serverUrl);
+    project.provide('e2eUnavailable', '');
+  };
+  const skip = (reason: string) => {
+    // eslint-disable-next-line no-console
+    console.warn(`\n[e2e] signal-connection e2e suite SKIPPED: ${reason}\n`);
+    project.provide('serverUrl', '');
+    project.provide('e2eUnavailable', reason);
+    return () => {};
+  };
+
+  // CI / Docker: connect to an externally-managed server.
+  const externalUrl = process.env.LK_TEST_SERVER_URL;
+  if (externalUrl) {
+    if (!(await waitReady(externalUrl))) {
+      return skip(`test-server at ${externalUrl} did not become ready`);
+    }
+    provide(externalUrl);
+    return () => {}; // container lifecycle is owned by CI
+  }
+
+  // Local dev: build + spawn cmd/test-server from a livekit-server checkout.
+  const serverDir = process.env.LK_SERVER_DIR;
+  if (!serverDir || !existsSync(serverDir)) {
+    return skip(
+      'set LK_TEST_SERVER_URL (a running server) or LK_SERVER_DIR (a livekit-server checkout)',
+    );
+  }
+
+  const binary = join(serverDir, 'bin', 'test-server');
+  if (!process.env.LK_E2E_SKIP_BUILD) {
+    try {
+      execFileSync('go', ['build', '-o', 'bin/test-server', './cmd/test-server'], {
+        cwd: serverDir,
+        stdio: 'pipe',
+      });
+    } catch (e) {
+      return skip(`failed to build test-server: ${(e as Error).message}`);
+    }
+  }
+  if (!existsSync(binary)) {
+    return skip(`test-server binary missing at ${binary}`);
+  }
+
+  // Fresh ephemeral port each run so a leftover server from a crashed run can
+  // never be mistaken for ours (vitest browser-mode teardown is unreliable, so
+  // a spawned server may outlive the run; the ephemeral port makes that
+  // harmless, at the cost of leaving at most one idle process per run).
+  const port = Number(process.env.LK_TEST_SERVER_PORT) || (await getFreePort());
+  const serverUrl = `ws://${HOST}:${port}`;
+
+  child = spawn(binary, ['--ports', String(port), '--bind', HOST], {
+    cwd: serverDir,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  let serverLog = '';
+  child.stdout?.on('data', (d: unknown) => {
+    serverLog += String(d);
+  });
+  child.stderr?.on('data', (d: unknown) => {
+    serverLog += String(d);
+  });
+  // With stdio: 'pipe' these are net.Sockets (typed as Readable, which lacks unref);
+  // unref the pipe handles so their 'data' listeners don't keep the parent alive.
+  if (child.stdout instanceof Socket) child.stdout.unref();
+  if (child.stderr instanceof Socket) child.stderr.unref();
+  child.unref();
+
+  const kill = () => {
+    try {
+      child?.kill('SIGKILL');
+    } catch {
+      // already gone
+    }
+  };
+  process.once('exit', kill);
+  process.once('SIGINT', () => {
+    kill();
+    process.exit(130);
+  });
+  process.once('SIGTERM', () => {
+    kill();
+    process.exit(143);
+  });
+
+  if (!(await waitReady(serverUrl))) {
+    kill();
+    return skip(
+      `test-server did not become ready on ${serverUrl}\n--- server output ---\n${serverLog}`,
+    );
+  }
+
+  provide(serverUrl);
+  return kill;
+}

package/src/test/signalToken.ts

@@ -0,0 +1,59 @@
+import { SignJWT } from 'jose';
+
+/**
+ * Mint a LiveKit access token for the mock test-server (HS256, dev secret).
+ *
+ * The mock's signal behavior mode is selected via a participant attribute
+ * under the reserved key `lk.mock` (dot notation, matching LiveKit's internal
+ * attribute convention), whose value is the JSON control object
+ * `{"signal":"<mode>"}` — mirroring the X-Lk-Mock header protocol. Attributes
+ * are a standard AccessToken field (a string map), so a dedicated `lk-mock`
+ * key coexists with any real metadata/attributes and needs no bespoke token
+ * construction. The room name is just a room; it no longer encodes behavior.
+ */
+export interface TokenOptions {
+  /** Mock behavior mode (e.g. 'no_pong'); omitted → the mock defaults to 'happy'. */
+  signal?: string;
+  /** LeaveRequest action the leave modes should send (0=DISCONNECT,1=RESUME,2=RECONNECT). */
+  leaveAction?: number;
+  room?: string;
+  identity?: string;
+  apiKey?: string;
+  secret?: string;
+  ttlSeconds?: number;
+}
+
+export async function createToken(opts: TokenOptions = {}): Promise<string> {
+  const {
+    signal,
+    leaveAction,
+    room = 'e2e-room',
+    identity = `test-${Math.random().toString(36).slice(2, 8)}`,
+    apiKey = 'devkey',
+    secret = 'secret',
+    ttlSeconds = 600,
+  } = opts;
+  const key = new TextEncoder().encode(secret);
+  const payload: Record<string, unknown> = {
+    video: { room, roomJoin: true, canPublish: true, canSubscribe: true, canPublishData: true },
+  };
+  if (signal) {
+    const control: Record<string, unknown> = { signal };
+    if (leaveAction !== undefined) {
+      control.leaveAction = leaveAction;
+    }
+    payload.attributes = { 'lk.mock': JSON.stringify(control) };
+  }
+  return new SignJWT(payload)
+    .setProtectedHeader({ alg: 'HS256' })
+    .setIssuer(apiKey)
+    .setSubject(identity)
+    .setIssuedAt()
+    .setExpirationTime(`${ttlSeconds}s`)
+    .sign(key);
+}
+
+/** A syntactically-valid token signed with the WRONG secret — for 401 tests. */
+export async function createInvalidToken(): Promise<string> {
+  return createToken({ secret: 'not-the-secret' });
+}

package/src/test/vitest-context.d.ts

@@ -0,0 +1,10 @@
+import 'vitest';
+
+declare module 'vitest' {
+  interface ProvidedContext {
+    /** ws:// base URL of the spawned mock test-server, or '' when unavailable. */
+    serverUrl: string;
+    /** Non-empty reason string when the e2e suite must be skipped. */
+    e2eUnavailable: string;
+  }
+}

package/src/type-polyfills/{non-shared-typed-arrays.d.ts → non-shared-typed-arrays.ts}

@@ -3,4 +3,9 @@
 // only accept the non-shared variant `Uint8Array<ArrayBuffer>`. Using `ReturnType<typeof Uint8Array.from>`
 // resolves to that non-shared variant on TS versions that support the generic, while remaining
 // equivalent to plain `Uint8Array` on older versions — so this alias works across the range we support.
-type NonSharedUint8Array = ReturnType<typeof Uint8Array.from>;
+//
+// Exported as a normal type (rather than an ambient global) so it is emitted into the published `dist`
+// types and imported explicitly wherever it is used. An earlier ambient `.d.ts` declaration was resolved
+// during our own build but never shipped, so consumers' type-checkers (and tools like API Extractor)
+// failed with "Cannot find name 'NonSharedUint8Array'" on our emitted `.d.ts` files.
+export type NonSharedUint8Array = ReturnType<typeof Uint8Array.from>;

package/src/utils/dataPacketBuffer.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, it } from 'vitest';
+import { DataPacketBuffer } from './dataPacketBuffer';
+
+const item = (sequence: number, size: number, sent: boolean) => ({
+  data: new Uint8Array(size),
+  sequence,
+  sent,
+});
+
+describe('DataPacketBuffer', () => {
+  it('trims sent packets down to the buffered amount', () => {
+    const buffer = new DataPacketBuffer();
+    buffer.push(item(1, 100, true));
+    buffer.push(item(2, 100, true));
+    buffer.push(item(3, 100, true));
+
+    // 150 buffered bytes cover the last two packets; the first is fully delivered.
+    buffer.alignBufferedAmount(150);
+
+    expect(buffer.getAll().map((i) => i.sequence)).toEqual([2, 3]);
+  });
+
+  it('never trims unsent packets, even when the buffered amount is zero', () => {
+    const buffer = new DataPacketBuffer();
+    buffer.push(item(1, 100, false));
+    buffer.push(item(2, 100, false));
+
+    buffer.alignBufferedAmount(0);
+
+    expect(buffer.length).toBe(2);
+  });
+
+  it('does not let unsent tail bytes cause over-trimming of the sent prefix', () => {
+    const buffer = new DataPacketBuffer();
+    buffer.push(item(1, 100, true));
+    buffer.push(item(2, 100, true));
+    // Queued during a reconnect window — not part of the channel's bufferedAmount.
+    buffer.push(item(3, 100, false));
+    buffer.push(item(4, 100, false));
+
+    // Both sent packets are still in flight; nothing may be trimmed. With size accounting based
+    // on the total (400) instead of sent bytes (200), both sent packets would be popped here.
+    buffer.alignBufferedAmount(200);
+
+    expect(buffer.getAll().map((i) => i.sequence)).toEqual([1, 2, 3, 4]);
+  });
+
+  it('markSent makes a single packet eligible for trimming and tracks sent size', () => {
+    const buffer = new DataPacketBuffer();
+    const first = item(1, 100, false);
+    const second = item(2, 100, false);
+    buffer.push(first);
+    buffer.push(second);
+
+    // Only the marked packet can be trimmed; the still-unsent one blocks the front.
+    buffer.markSent(first);
+    buffer.alignBufferedAmount(0);
+    expect(buffer.getAll().map((i) => i.sequence)).toEqual([1, 2]);
+
+    buffer.markSent(second);
+    buffer.alignBufferedAmount(50);
+    expect(buffer.getAll().map((i) => i.sequence)).toEqual([2]);
+  });
+
+  it('getUnsent returns only unsent packets, in order', () => {
+    const buffer = new DataPacketBuffer();
+    const a = item(1, 100, false);
+    const b = item(2, 100, false);
+    buffer.push(a);
+    buffer.push(b);
+    buffer.push(item(3, 100, false));
+    buffer.markSent(b);
+
+    expect(buffer.getUnsent().map((i) => i.sequence)).toEqual([1, 3]);
+  });
+
+  it('markAllUnsent flags every packet for re-send and resets sent size', () => {
+    const buffer = new DataPacketBuffer();
+    buffer.push(item(1, 100, true));
+    buffer.push(item(2, 100, true));
+
+    buffer.markAllUnsent();
+    expect(buffer.getUnsent().map((i) => i.sequence)).toEqual([1, 2]);
+
+    // With everything unsent, nothing can be trimmed even at a zero buffered amount.
+    buffer.alignBufferedAmount(0);
+    expect(buffer.getAll().map((i) => i.sequence)).toEqual([1, 2]);
+  });
+
+  it('popToSequence drops acked packets regardless of sent state', () => {
+    const buffer = new DataPacketBuffer();
+    buffer.push(item(1, 100, true));
+    buffer.push(item(2, 100, false));
+    buffer.push(item(3, 100, false));
+
+    buffer.popToSequence(2);
+
+    expect(buffer.getAll().map((i) => i.sequence)).toEqual([3]);
+  });
+});

package/src/utils/dataPacketBuffer.ts

@@ -1,6 +1,15 @@
+import type { NonSharedUint8Array } from '../type-polyfills/non-shared-typed-arrays';
+
 export interface DataPacketItem {
   data: NonSharedUint8Array;
   sequence: number;
+  /**
+   * Whether the packet has been handed to the data channel. Unsent packets are queued for the
+   * resume replay (e.g. sends that landed in a reconnect window) and must never be trimmed by
+   * {@link DataPacketBuffer.alignBufferedAmount}, which reasons about the channel's buffered
+   * bytes — those only ever contain sent packets.
+   */
+  sent: boolean;
 }
 
 export class DataPacketBuffer {
@@ -8,15 +17,23 @@ export class DataPacketBuffer {
 
   private _totalSize = 0;
 
+  private _sentSize = 0;
+
   push(item: DataPacketItem) {
     this.buffer.push(item);
     this._totalSize += item.data.byteLength;
+    if (item.sent) {
+      this._sentSize += item.data.byteLength;
+    }
   }
 
   pop(): DataPacketItem | undefined {
     const item = this.buffer.shift();
     if (item) {
       this._totalSize -= item.data.byteLength;
+      if (item.sent) {
+        this._sentSize -= item.data.byteLength;
+      }
     }
     return item;
   }
@@ -25,6 +42,31 @@ export class DataPacketBuffer {
     return this.buffer.slice();
   }
 
+  /** Every queued packet not yet handed to the channel, in sequence order. */
+  getUnsent(): DataPacketItem[] {
+    return this.buffer.filter((item) => !item.sent);
+  }
+
+  /** Marks a single queued packet as handed to the channel. */
+  markSent(item: DataPacketItem) {
+    if (!item.sent) {
+      item.sent = true;
+      this._sentSize += item.data.byteLength;
+    }
+  }
+
+  /**
+   * Marks every queued packet as not-yet-sent. Used at the start of a resume replay: whatever is
+   * still buffered was sent on the previous channel (or deferred) and must be re-handed to the
+   * current one, so none of it counts as sent until the replay actually transmits it.
+   */
+  markAllUnsent() {
+    for (const item of this.buffer) {
+      item.sent = false;
+    }
+    this._sentSize = 0;
+  }
+
   popToSequence(sequence: number) {
     while (this.buffer.length > 0) {
       const first = this.buffer[0];
@@ -39,7 +81,12 @@ export class DataPacketBuffer {
   alignBufferedAmount(bufferedAmount: number) {
     while (this.buffer.length > 0) {
       const first = this.buffer[0];
-      if (this._totalSize - first.data.byteLength <= bufferedAmount) {
+      // Unsent packets aren't part of the channel's bufferedAmount and are still awaiting the
+      // resume replay — trimming them would silently lose them.
+      if (!first.sent) {
+        break;
+      }
+      if (this._sentSize - first.data.byteLength <= bufferedAmount) {
         break;
       }
       this.pop();