livekit-client 2.20.2 → 2.22.0

package/src/room/Room.test.ts

@@ -1,8 +1,22 @@
-import { ClientInfo_Capability, JoinResponse } from '@livekit/protocol';
+import {
+  ClientInfo_Capability,
+  JoinResponse,
+  StreamState as ProtoStreamState,
+  StreamStateUpdate,
+  SubscriptionError,
+  SubscriptionResponse,
+  TrackInfo,
+  TrackType,
+} from '@livekit/protocol';
 import { afterEach, describe, expect, it, vi } from 'vitest';
-import Room from './Room';
+import MockMediaStreamTrack from '../test/MockMediaStreamTrack';
+import Room, { ConnectionState } from './Room';
 import { roomConnectOptionDefaults, roomOptionDefaults } from './defaults';
-import { RoomEvent } from './events';
+import { EngineEvent, ParticipantEvent, RoomEvent } from './events';
+import RemoteParticipant from './participant/RemoteParticipant';
+import RemoteTrackPublication from './track/RemoteTrackPublication';
+import RemoteVideoTrack from './track/RemoteVideoTrack';
+import { Track } from './track/Track';
 
 describe('Active device switch', () => {
   it('updates devices correctly', async () => {
@@ -81,7 +95,10 @@ describe('Room signaling options', () => {
       'wss://test.livekit.io',
       'test-token',
       expect.objectContaining({
-        clientInfoCapabilities: [ClientInfo_Capability.CAP_PACKET_TRAILER],
+        clientInfoCapabilities: [
+          ClientInfo_Capability.CAP_PACKET_TRAILER,
+          ClientInfo_Capability.CAP_COMPRESSION_DEFLATE_RAW,
+        ],
         e2eeEnabled: true,
       }),
       expect.any(AbortSignal),
@@ -187,3 +204,120 @@ describe('Room lifecycle', () => {
     }
   });
 });
+
+describe('remote track subscription', () => {
+  it('does not replay a deferred ontrack after the subscription failed', () => {
+    const room = new Room();
+    room.state = ConnectionState.Connecting;
+
+    const trackSid = 'TR_h264';
+    const mediaTrack = { id: trackSid } as MediaStreamTrack;
+    const stream = {
+      id: `PA_remote|${trackSid}`,
+      getTracks: () => [mediaTrack],
+    } as unknown as MediaStream;
+    const receiver = {} as RTCRtpReceiver;
+
+    room.engine.emit(EngineEvent.MediaTrackAdded, mediaTrack, stream, receiver);
+
+    const replay = vi.spyOn(
+      room as unknown as {
+        onTrackAdded(
+          mediaTrack: MediaStreamTrack,
+          stream: MediaStream,
+          receiver: RTCRtpReceiver,
+        ): void;
+      },
+      'onTrackAdded',
+    );
+
+    room.engine.emit(
+      EngineEvent.SubscriptionError,
+      new SubscriptionResponse({
+        trackSid,
+        err: SubscriptionError.SE_CODEC_UNSUPPORTED,
+      }),
+    );
+
+    room.state = ConnectionState.Connected;
+    room.emit(RoomEvent.Connected);
+
+    expect(replay).not.toHaveBeenCalled();
+  });
+});
+
+describe('stream state updates', () => {
+  const participantSid = 'PA_remote';
+  const participantIdentity = 'remote-user';
+  const trackSid = 'TR_video';
+
+  function setupSubscribedTrack() {
+    const room = new Room();
+    room.state = ConnectionState.Connected;
+
+    const participant = new RemoteParticipant(
+      room.engine.client,
+      participantSid,
+      participantIdentity,
+    );
+    const publication = new RemoteTrackPublication(
+      Track.Kind.Video,
+      new TrackInfo({ sid: trackSid, type: TrackType.VIDEO, name: 'camera' }),
+      true,
+    );
+    publication.setTrack(
+      new RemoteVideoTrack(new MockMediaStreamTrack(), trackSid, undefined as never, {}),
+    );
+    participant.trackPublications.set(trackSid, publication);
+
+    (
+      room as unknown as { remoteParticipants: Map<string, RemoteParticipant> }
+    ).remoteParticipants.set(participantIdentity, participant);
+    (room as unknown as { sidToIdentity: Map<string, string> }).sidToIdentity.set(
+      participantSid,
+      participantIdentity,
+    );
+
+    return { room, participant, publication };
+  }
+
+  function pushStreamState(room: Room, state: ProtoStreamState) {
+    (
+      room as unknown as { handleStreamStateUpdate: (update: StreamStateUpdate) => void }
+    ).handleStreamStateUpdate(
+      new StreamStateUpdate({
+        streamStates: [{ participantSid, trackSid, state }],
+      }),
+    );
+  }
+
+  it('emits TrackStreamStateChanged when the SFU pauses a subscribed track', () => {
+    const { room, participant, publication } = setupSubscribedTrack();
+
+    const roomEvents = vi.fn();
+    const participantEvents = vi.fn();
+    room.on(RoomEvent.TrackStreamStateChanged, roomEvents);
+    participant.on(ParticipantEvent.TrackStreamStateChanged, participantEvents);
+
+    pushStreamState(room, ProtoStreamState.PAUSED);
+
+    expect(publication.track?.streamState).toBe(Track.StreamState.Paused);
+    expect(roomEvents).toHaveBeenCalledWith(publication, Track.StreamState.Paused, participant);
+    expect(participantEvents).toHaveBeenCalledWith(publication, Track.StreamState.Paused);
+  });
+
+  it('does not emit TrackStreamStateChanged when the state is unchanged', () => {
+    const { room, participant } = setupSubscribedTrack();
+
+    const roomEvents = vi.fn();
+    const participantEvents = vi.fn();
+    room.on(RoomEvent.TrackStreamStateChanged, roomEvents);
+    participant.on(ParticipantEvent.TrackStreamStateChanged, participantEvents);
+
+    // The track starts Active; a redundant ACTIVE update must stay silent.
+    pushStreamState(room, ProtoStreamState.ACTIVE);
+
+    expect(roomEvents).not.toHaveBeenCalled();
+    expect(participantEvents).not.toHaveBeenCalled();
+  });
+});

package/src/room/Room.ts

@@ -113,11 +113,13 @@ import {
   Future,
   createDummyVideoStreamTrack,
   extractChatMessage,
+  extractTrackSid,
   extractTranscriptionSegments,
   getDisconnectReasonFromConnectionError,
   getEmptyAudioStreamTrack,
   isBrowserSupported,
   isCloud,
+  isCompressionStreamSupported,
   isLocalAudioTrack,
   isLocalParticipant,
   isReactNative,
@@ -217,6 +219,8 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
 
   private isResuming: boolean = false;
 
+  private pendingTrackAddedCallbacks = new Map<Track.SID, Set<() => void>>();
+
   /**
    * map to store first point in time when a particular transcription segment was received
    */
@@ -268,7 +272,13 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
     this.maybeCreateEngine();
 
     this.incomingDataStreamManager = new IncomingDataStreamManager();
-    this.outgoingDataStreamManager = new OutgoingDataStreamManager(this.engine, this.log);
+    this.outgoingDataStreamManager = new OutgoingDataStreamManager(
+      this.engine,
+      this.log,
+      this.getRemoteParticipantClientProtocol,
+      this.getRemoteParticipantCapabilities,
+      this.getAllRemoteParticipantIdentities,
+    );
 
     this.incomingDataTrackManager = new IncomingDataTrackManager({ e2eeManager: this.e2eeManager });
     this.incomingDataTrackManager
@@ -308,7 +318,7 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
       })
       .on('packetAvailable', ({ handle, bytes }) => {
         this.engine
-          .sendLossyBytes(bytes, DataChannelKind.DATA_TRACK_LOSSY, 'wait')
+          .sendDataTrackFrame(bytes)
           .finally(() => this.outgoingDataTrackManager.handlePacketSendComplete(handle));
       });
 
@@ -623,16 +633,16 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
         this.isResuming = false;
         this.log.debug('Resumed signal connection');
         this.updateSubscriptions();
-        this.emitBufferedEvents();
         if (this.setAndEmitConnectionState(ConnectionState.Connected)) {
           this.emit(RoomEvent.Reconnected);
         }
+        this.emitBufferedEvents();
       })
       .on(EngineEvent.SignalResumed, () => {
-        this.bufferedEvents = [];
         if (this.state === ConnectionState.Reconnecting || this.isResuming) {
           this.sendSyncState();
         }
+        this.emitBufferedEvents();
       })
       .on(EngineEvent.Restarting, this.handleRestarting)
       .on(EngineEvent.Restarted, this.handleRestarted)
@@ -971,11 +981,7 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
         autoSubscribe: connectOptions.autoSubscribe,
         adaptiveStream:
           typeof roomOptions.adaptiveStream === 'object' ? true : roomOptions.adaptiveStream,
-        clientInfoCapabilities:
-          isFrameMetadataSupported(roomOptions.frameMetadata ?? roomOptions.packetTrailer) ||
-          !!this.e2eeManager
-            ? [ClientInfo_Capability.CAP_PACKET_TRAILER]
-            : undefined,
+        clientInfoCapabilities: this.getClientInfoCapabilities(roomOptions),
         maxRetries: connectOptions.maxRetries,
         e2eeEnabled: !!this.e2eeManager,
         websocketTimeout: connectOptions.websocketTimeout,
@@ -1585,24 +1591,38 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
     // at that time, ICE connectivity has not been established so the track is not
     // technically subscribed.
     // We'll defer these events until when the room is connected or eventually disconnected.
-    if (this.state === ConnectionState.Connecting || this.state === ConnectionState.Reconnecting) {
+    if ([ConnectionState.Connecting, ConnectionState.Reconnecting].includes(this.state)) {
+      const pendingTrackSid = extractTrackSid(mediaTrack, stream);
+      this.log.debug('deferring on track for later', {
+        mediaTrackId: mediaTrack.id,
+        mediaStreamId: stream.id,
+        tracksInStream: stream.getTracks().map((track) => track.id),
+      });
       const reconnectedHandler = () => {
-        this.log.debug('deferring on track for later', {
-          mediaTrackId: mediaTrack.id,
-          mediaStreamId: stream.id,
-          tracksInStream: stream.getTracks().map((track) => track.id),
-        });
-        this.onTrackAdded(mediaTrack, stream, receiver);
         cleanup();
+        this.onTrackAdded(mediaTrack, stream, receiver);
       };
       const cleanup = () => {
         this.off(RoomEvent.Reconnected, reconnectedHandler);
         this.off(RoomEvent.Connected, reconnectedHandler);
         this.off(RoomEvent.Disconnected, cleanup);
+        if (pendingTrackSid) {
+          const pendingCallbacks = this.pendingTrackAddedCallbacks.get(pendingTrackSid);
+          pendingCallbacks?.delete(cleanup);
+          if (pendingCallbacks?.size === 0) {
+            this.pendingTrackAddedCallbacks.delete(pendingTrackSid);
+          }
+        }
       };
       this.once(RoomEvent.Reconnected, reconnectedHandler);
       this.once(RoomEvent.Connected, reconnectedHandler);
       this.once(RoomEvent.Disconnected, cleanup);
+      if (pendingTrackSid) {
+        const pendingCallbacks =
+          this.pendingTrackAddedCallbacks.get(pendingTrackSid) ?? new Set<() => void>();
+        pendingCallbacks.add(cleanup);
+        this.pendingTrackAddedCallbacks.set(pendingTrackSid, pendingCallbacks);
+      }
       return;
     }
     if (this.state === ConnectionState.Disconnected) {
@@ -1615,11 +1635,10 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
     }
     const parts = unpackStreamId(stream.id);
     const participantSid = parts[0];
-    let streamId = parts[1];
-    let trackId = mediaTrack.id;
+    const streamId = parts[1];
     // firefox will get streamId (pID|trackId) instead of (pID|streamId) as it doesn't support sync tracks by stream
     // and generates its own track id instead of infer from sdp track id.
-    if (streamId && streamId.startsWith('TR')) trackId = streamId;
+    let trackId = extractTrackSid(mediaTrack, stream) ?? mediaTrack.id;
 
     if (participantSid === this.localParticipant.sid) {
       this.log.warn('tried to create RemoteParticipant for local participant');
@@ -1688,6 +1707,10 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
     }
   }
 
+  private cancelPendingTrackAdded(trackSid: Track.SID) {
+    this.pendingTrackAddedCallbacks.get(trackSid)?.forEach((cleanup) => cleanup());
+  }
+
   private handleLocalTrackSubscribed(subscribedSid: string) {
     const findPublication = () =>
       this.localParticipant
@@ -2005,8 +2028,9 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
         return;
       }
       const newStreamState = Track.streamStateFromProto(streamState.state);
+      const prevStreamState = pub.track.streamState;
       pub.track.setStreamState(newStreamState);
-      if (newStreamState !== pub.track.streamState) {
+      if (newStreamState !== prevStreamState) {
         participant.emit(ParticipantEvent.TrackStreamStateChanged, pub, pub.track.streamState);
         this.emitWhenConnected(
           RoomEvent.TrackStreamStateChanged,
@@ -2032,6 +2056,8 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
   };
 
   private handleSubscriptionError = (update: SubscriptionResponse) => {
+    this.cancelPendingTrackAdded(update.trackSid);
+
     const participant = Array.from(this.remoteParticipants.values()).find((p) =>
       p.trackPublications.has(update.trackSid),
     );
@@ -2406,6 +2432,7 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
         },
       )
       .on(ParticipantEvent.TrackUnpublished, (publication: RemoteTrackPublication) => {
+        this.cancelPendingTrackAdded(publication.trackSid);
         this.emit(RoomEvent.TrackUnpublished, publication, participant);
       })
       .on(
@@ -2505,10 +2532,39 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
     }
   }
 
+  /** The client capabilities this SDK advertises to other participants in its `ClientInfo`. */
+  private getClientInfoCapabilities(
+    roomOptions: InternalRoomOptions,
+  ): Array<ClientInfo_Capability> {
+    const capabilities: Array<ClientInfo_Capability> = [];
+    if (
+      isFrameMetadataSupported(roomOptions.frameMetadata ?? roomOptions.packetTrailer) ||
+      !!this.e2eeManager
+    ) {
+      capabilities.push(ClientInfo_Capability.CAP_PACKET_TRAILER);
+    }
+    // Advertise deflate-raw decompression support so peers know they can send us compressed data
+    // streams (gated separately from clientProtocol — see the data streams v2 spec).
+    if (isCompressionStreamSupported()) {
+      capabilities.push(ClientInfo_Capability.CAP_COMPRESSION_DEFLATE_RAW);
+    }
+    return capabilities;
+  }
+
   private getRemoteParticipantClientProtocol = (identity: Participant['identity']) => {
     return this.remoteParticipants.get(identity)?.clientProtocol ?? CLIENT_PROTOCOL_DEFAULT;
   };
 
+  private getRemoteParticipantCapabilities = (
+    identity: Participant['identity'],
+  ): Array<ClientInfo_Capability> => {
+    return this.remoteParticipants.get(identity)?.capabilities ?? [];
+  };
+
+  private getAllRemoteParticipantIdentities = () => {
+    return Array.from(this.remoteParticipants.keys());
+  };
+
   private registerRpcDataStreamHandler() {
     this.incomingDataStreamManager.registerTextStreamHandler(
       RPC_REQUEST_DATA_STREAM_TOPIC,
@@ -2549,11 +2605,20 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
             : undefined,
         });
         if (consecutiveFailures >= 3) {
-          this.recreateEngine();
-          this.handleDisconnect(
-            this.options.stopLocalTrackOnUnpublish,
-            DisconnectReason.STATE_MISMATCH,
-          );
+          this.clearConnectionReconcile();
+          if (this.engine && !this.engine.isClosed) {
+            // The transport silently died while we still looked connected. Try a full reconnect
+            // (keeps the room alive; the engine falls back to Disconnected if it ultimately fails).
+            this.log.warn('detected connection state mismatch, attempting full reconnect');
+            this.engine.reconnect();
+          } else {
+            // No usable engine to reconnect with; tear down.
+            this.recreateEngine();
+            this.handleDisconnect(
+              this.options.stopLocalTrackOnUnpublish,
+              DisconnectReason.STATE_MISMATCH,
+            );
+          }
         }
       } else {
         consecutiveFailures = 0;
@@ -2575,7 +2640,9 @@ class Room extends (EventEmitter as new () => TypedEmitter<RoomEventCallbacks>)
     this.log.info(`connection state changed: ${this.state} -> ${state}`);
     this.state = state;
     this.incomingDataStreamManager.setConnected(state === ConnectionState.Connected);
+
     this.emit(RoomEvent.ConnectionStateChanged, this.state);
+
     return true;
   }
 

package/src/room/data-channel/DataChannelManager.test.ts

@@ -0,0 +1,152 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { PCTransportManager } from '../PCTransportManager';
+import { UnexpectedConnectionState } from '../errors';
+import { DataChannelManager, type DataChannelManagerOptions } from './DataChannelManager';
+import { DataChannelKind } from './types';
+
+class FakeDataChannel extends EventTarget {
+  bufferedAmount = 0;
+
+  bufferedAmountLowThreshold = 0;
+
+  onmessage: ((message: MessageEvent) => void) | null = null;
+
+  onerror: ((event: Event) => void) | null = null;
+
+  onclose: (() => void) | null = null;
+
+  onbufferedamountlow: (() => void) | null = null;
+
+  send = vi.fn();
+
+  close = vi.fn();
+
+  constructor(public label: string) {
+    super();
+  }
+}
+
+const tick = () => new Promise<void>((resolve) => setTimeout(resolve, 0));
+
+function makeManager(overrides?: Partial<DataChannelManagerOptions>) {
+  const opts = {
+    isEngineClosed: () => false,
+    isReconnecting: () => false,
+    onDataMessage: vi.fn(),
+    onDataTrackMessage: vi.fn(),
+    onDataError: vi.fn(),
+    onChannelClose: vi.fn(),
+    onBufferStatusChanged: vi.fn(),
+    ...overrides,
+  };
+  const manager = new DataChannelManager(opts);
+  const created: Record<string, FakeDataChannel> = {};
+  const pcManager = {
+    createPublisherDataChannel: vi.fn((label: string) => {
+      const dc = new FakeDataChannel(label);
+      created[label] = dc;
+      return dc as unknown as RTCDataChannel;
+    }),
+  } as unknown as PCTransportManager;
+  return { manager, opts, pcManager, created };
+}
+
+describe('DataChannelManager', () => {
+  it('creates and wires the three publisher channels', () => {
+    const { manager, opts, pcManager, created } = makeManager();
+
+    manager.createPublisherChannels(pcManager);
+
+    expect(Object.keys(created).sort()).toEqual(['_data_track', '_lossy', '_reliable']);
+    expect(manager.getHandle(DataChannelKind.RELIABLE)).toBe(created._reliable);
+    expect(manager.hasPublisherChannels).toBe(true);
+    for (const dc of Object.values(created)) {
+      expect(dc.onmessage).toBeTruthy();
+      expect(dc.onerror).toBeTruthy();
+      expect(dc.onclose).toBeTruthy();
+      expect(dc.onbufferedamountlow).toBeTruthy();
+      expect(dc.bufferedAmountLowThreshold).toBeGreaterThan(0);
+    }
+
+    // Close handler reports the right kind.
+    created._reliable.onclose!();
+    expect(opts.onChannelClose).toHaveBeenCalledWith(DataChannelKind.RELIABLE);
+
+    // A drain event on the data-track channel refreshes its status; since the buffer starts empty
+    // (below the low mark) and the wrapper's initial status is already "low", no change fires —
+    // fill it first so the drain is an observable not-low → low transition.
+    const dataTrackDc = created._data_track;
+    dataTrackDc.bufferedAmount = 10 * 1024 * 1024;
+    dataTrackDc.onbufferedamountlow!(); // refresh: now "not low"
+    dataTrackDc.bufferedAmount = 0;
+    dataTrackDc.onbufferedamountlow!(); // refresh: back to "low"
+    expect(opts.onBufferStatusChanged).toHaveBeenCalledWith(
+      DataChannelKind.DATA_TRACK_LOSSY,
+      false,
+    );
+    expect(opts.onBufferStatusChanged).toHaveBeenCalledWith(DataChannelKind.DATA_TRACK_LOSSY, true);
+
+    manager.lossy.stopThresholdTuning();
+  });
+
+  it('recreating channels rejects waiters parked on the replaced handles', async () => {
+    const { manager, pcManager, created } = makeManager();
+    manager.createPublisherChannels(pcManager);
+
+    // Park a reliable sender on the first-generation channel.
+    created._reliable.bufferedAmount = 2 * 1024 * 1024;
+    const parked = manager.reliable.waitForHeadroomWithLock();
+    parked.catch(() => {});
+    await tick();
+
+    // Safari null-id path: channels recreated without closing the old ones.
+    manager.createPublisherChannels(pcManager);
+
+    await expect(parked).rejects.toBeInstanceOf(UnexpectedConnectionState);
+    // The gate recovers against the fresh (empty) channel.
+    await expect(manager.reliable.waitForHeadroomWithLock()).resolves.toBeUndefined();
+
+    manager.lossy.stopThresholdTuning();
+  });
+
+  it('adopts subscriber channels by label and rejects unknown labels', () => {
+    const { manager, opts } = makeManager();
+
+    const sub = new FakeDataChannel('_reliable');
+    expect(manager.adoptSubscriberChannel(sub as unknown as RTCDataChannel)).toBe(true);
+    expect(manager.getHandle(DataChannelKind.RELIABLE, true)).toBe(sub);
+    expect(sub.onmessage).toBe(opts.onDataMessage);
+
+    const dataTrackSub = new FakeDataChannel('_data_track');
+    expect(manager.adoptSubscriberChannel(dataTrackSub as unknown as RTCDataChannel)).toBe(true);
+    expect(dataTrackSub.onmessage).toBe(opts.onDataTrackMessage);
+
+    expect(
+      manager.adoptSubscriberChannel(new FakeDataChannel('_other') as unknown as RTCDataChannel),
+    ).toBe(false);
+  });
+
+  it('teardown rejects parked waiters, closes all handles, and detaches', async () => {
+    const { manager, pcManager, created } = makeManager();
+    manager.createPublisherChannels(pcManager);
+    const sub = new FakeDataChannel('_lossy');
+    manager.adoptSubscriberChannel(sub as unknown as RTCDataChannel);
+
+    created._reliable.bufferedAmount = 2 * 1024 * 1024;
+    const parked = manager.reliable.waitForHeadroomWithLock();
+    parked.catch(() => {});
+    await tick();
+
+    manager.teardown();
+
+    await expect(parked).rejects.toBeInstanceOf(UnexpectedConnectionState);
+    for (const dc of [...Object.values(created), sub]) {
+      expect(dc.close).toHaveBeenCalled();
+      expect(dc.onmessage).toBeNull();
+    }
+    expect(manager.hasPublisherChannels).toBe(false);
+    expect(manager.getHandle(DataChannelKind.LOSSY, true)).toBeUndefined();
+
+    manager.lossy.stopThresholdTuning();
+  });
+});