livekit-client 2.22.0 → 2.22.1

package/src/room/track/Track.ts

@@ -11,6 +11,7 @@ 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 { summarizeStatsReport } from '../statsSummary';
 import type { LoggerOptions } from '../types';
 import { isFireFox, isSafari, isWeb } from '../utils';
 import type { TrackProcessor } from './processor/types';
@@ -85,6 +86,8 @@ export abstract class Track<
 
   protected monitorInterval?: ReturnType<typeof setInterval>;
 
+  private finalStatsLogged = false;
+
   protected log: StructuredLogger = log;
 
   protected constructor(
@@ -271,6 +274,11 @@ export abstract class Track<
   /* @internal */
   abstract startMonitor(signalClient?: SignalClient): void;
 
+  /**
+   * Raw stats of the sender or receiver this track is attached to.
+   */
+  abstract getRTCStatsReport(): Promise<RTCStatsReport | undefined>;
+
   /* @internal */
   stopMonitor() {
     if (this.monitorInterval) {
@@ -280,6 +288,25 @@ export abstract class Track<
       cancelAnimationFrame(this.timeSyncHandle);
       this.timeSyncHandle = undefined;
     }
+    this.logFinalStats();
+  }
+
+  /**
+   * Dumps the raw stats of the track as it ends, once: a track that stops
+   * between two of the room's stats dumps is gone by the time the next one runs.
+   */
+  private logFinalStats() {
+    if (this.finalStatsLogged) {
+      return;
+    }
+    this.finalStatsLogged = true;
+    this.getRTCStatsReport()
+      .then((report) => {
+        if (report) {
+          this.log.info('final track stats', summarizeStatsReport(report));
+        }
+      })
+      .catch((error) => this.log.debug('could not collect final track stats', { error }));
   }
 
   /** @internal */

package/src/room/utils.test.ts

@@ -1,11 +1,12 @@
 import { ClientInfo_Capability } from '@livekit/protocol';
-import { describe, expect, it, vi } from 'vitest';
+import { afterEach, describe, expect, it, vi } from 'vitest';
 import {
   ddExtensionURI,
   extractMaxAgeFromRequestHeaders,
   getClientInfo,
   negotiateDependencyDescriptor,
   splitUtf8,
+  supportsAdaptiveStream,
   toWebsocketUrl,
 } from './utils';
 
@@ -257,3 +258,25 @@ describe('negotiateDependencyDescriptor', () => {
     expect(negotiateDependencyDescriptor(transceiver)).toBe(false);
   });
 });
+
+describe('supportsAdaptiveStream', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it('reports support where both observers exist', () => {
+    expect(supportsAdaptiveStream()).toBe(true);
+  });
+
+  it('reports no support where ResizeObserver is missing', () => {
+    vi.stubGlobal('ResizeObserver', undefined);
+
+    expect(supportsAdaptiveStream()).toBe(false);
+  });
+
+  it('reports no support where IntersectionObserver is missing', () => {
+    vi.stubGlobal('IntersectionObserver', undefined);
+
+    expect(supportsAdaptiveStream()).toBe(false);
+  });
+});

package/src/room/utils.ts

@@ -58,7 +58,7 @@ export function supportsAddTrack() {
 }
 
 export function supportsAdaptiveStream() {
-  return typeof ResizeObserver !== undefined && typeof IntersectionObserver !== undefined;
+  return typeof ResizeObserver !== 'undefined' && typeof IntersectionObserver !== 'undefined';
 }
 
 export function supportsDynacast() {

package/src/utils/machineInspector.ts

@@ -0,0 +1,90 @@
+/**
+ * Opt-in registry that lets a development tool observe the state machines driving the connection
+ * layer.
+ *
+ * The machines are private to the objects that own them and, more importantly, do not outlive them:
+ * a full reconnect replaces the whole engine along with its `SignalClient`, so anything watching a
+ * single machine reference goes blind exactly when the interesting part starts. Machines therefore
+ * announce themselves here as they are constructed, and a subscriber sees the whole succession.
+ *
+ * Nothing is recorded until {@link enableMachineInspector} is called, which no shipping code does —
+ * with the registry off, announcing is a comparison and a return.
+ */
+
+/**
+ * The slice of machina's `Fsm` surface an inspector needs. Structural rather than machina's own
+ * type so that any machine satisfies it regardless of its state and input unions.
+ */
+export interface InspectableMachine {
+  readonly id: string;
+  readonly initialState: string;
+  readonly states: Record<string, Record<string, unknown>>;
+  readonly context?: unknown;
+  currentState(): string;
+  canHandle(input: string): boolean;
+  on(eventName: string, callback: (data: any) => void): { off(): void };
+}
+
+export interface MachineAnnouncement {
+  /** What the machine drives, e.g. `signal`. Not unique: each new `SignalClient` announces one. */
+  label: string;
+  /** How many machines have been announced before this one, so successive instances are tellable apart. */
+  seq: number;
+  /**
+   * When the machine was constructed. Carried on the announcement because subscribers receive the
+   * recorded ones on subscribe, and stamping those at replay time would date them all to whenever
+   * the tool happened to open.
+   */
+  at: number;
+  machine: InspectableMachine;
+}
+
+/** Kept small: enough for a panel opened mid-session to see how the connection got where it is. */
+const HISTORY_LIMIT = 16;
+
+let enabled = false;
+let announced: MachineAnnouncement[] = [];
+let subscribers: Array<(announcement: MachineAnnouncement) => void> = [];
+
+/**
+ * Starts recording machine announcements. Call before the machines of interest are constructed —
+ * for the signal machine that means before the `Room` is created.
+ */
+export function enableMachineInspector() {
+  enabled = true;
+}
+
+export function isMachineInspectorEnabled() {
+  return enabled;
+}
+
+/** Announces a machine to whatever is watching. A no-op unless the inspector was enabled. */
+export function announceMachine(label: string, machine: InspectableMachine) {
+  if (!enabled) {
+    return;
+  }
+  const announcement: MachineAnnouncement = {
+    label,
+    seq: announced.length,
+    at: Date.now(),
+    machine,
+  };
+  announced = [...announced.slice(-(HISTORY_LIMIT - 1)), announcement];
+  for (const subscriber of subscribers) {
+    subscriber(announcement);
+  }
+}
+
+/**
+ * Subscribes to machine announcements, replaying the ones already recorded so that a panel opened
+ * after connecting still sees the machine currently in charge. Returns an unsubscribe function.
+ */
+export function onMachineAnnounced(callback: (announcement: MachineAnnouncement) => void) {
+  subscribers = [...subscribers, callback];
+  for (const announcement of announced) {
+    callback(announcement);
+  }
+  return () => {
+    subscribers = subscribers.filter((subscriber) => subscriber !== callback);
+  };
+}