livekit-client 2.21.0 → 2.22.1

package/src/room/RTCEngine.ts

@@ -18,6 +18,7 @@ import {
   LeaveRequest_Action,
   MediaSectionsRequirement,
   ParticipantInfo,
+  ConnectionQuality as ProtoConnectionQuality,
   PublishDataTrackResponse,
   ReconnectReason,
   type ReconnectResponse,
@@ -100,6 +101,7 @@ import {
   isVideoCodec,
   isVideoTrack,
   isWeb,
+  negotiateDependencyDescriptor,
   sleep,
   supportsAddTrack,
   supportsTransceiver,
@@ -108,6 +110,12 @@ import {
 
 const minReconnectWait = 2 * 1000;
 const leaveReconnect = 'leave-reconnect';
+
+/**
+ * How long local connection quality must stay `LOST` while connected and publishing before we
+ * force a full reconnect — `LOST` is the server's verdict that it isn't receiving our media.
+ */
+const connectionQualityLostTimeout = 10 * 1000;
 const reliabeReceiveStateTTL = 30_000;
 
 const initialMediaSectionsAudio = 3;
@@ -246,6 +254,12 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
   /** used to indicate whether the browser is currently waiting to reconnect */
   private isWaitingForNetworkReconnect: boolean = false;
 
+  /** set while the local participant's connection quality is `LOST`; forces a full reconnect on timeout */
+  private lostQualityTimeout?: ReturnType<typeof setTimeout>;
+
+  /** timestamp (ms) the primary transport entered `CONNECTING`, used to bound how long we tolerate it */
+  private transportConnectingSince?: number;
+
   constructor(private options: InternalRoomOptions) {
     super();
     this.log = getLogger(options.loggerName ?? LoggerNames.Engine, () => this.logContext);
@@ -271,8 +285,10 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
 
     this.client.onParticipantUpdate = (updates) =>
       this.emit(EngineEvent.ParticipantUpdate, updates);
-    this.client.onConnectionQuality = (update) =>
+    this.client.onConnectionQuality = (update) => {
+      this.handleLocalConnectionQuality(update);
       this.emit(EngineEvent.ConnectionQualityUpdate, update);
+    };
     this.client.onRoomUpdate = (update) => this.emit(EngineEvent.RoomUpdate, update);
     this.client.onSubscriptionError = (resp) => this.emit(EngineEvent.SubscriptionError, resp);
     this.client.onSubscriptionPermissionUpdate = (update) =>
@@ -416,7 +432,12 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
     }
   }
 
-  async close() {
+  /**
+   * @param reason why the session is ending, recorded by the signal lifecycle. Worth passing
+   * wherever the caller knows more than "someone called close" — the server's leave reason, or
+   * having given up on reconnecting.
+   */
+  async close(reason?: string) {
     const unlock = await this.closingLock.lock();
     if (this.isClosed) {
       unlock();
@@ -429,9 +450,10 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
       this.removeAllListeners();
       this.deregisterOnLineListener();
       this.clearPendingReconnect();
+      this.clearLostQualityTimeout();
       this.cleanupLossyDataStats();
       await this.cleanupPeerConnections();
-      await this.cleanupClient();
+      await this.cleanupClient(reason);
     } finally {
       unlock();
     }
@@ -442,6 +464,8 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
 
     await this.pcManager?.close();
     this.pcManager = undefined;
+    // the connecting timestamp belongs to the transports we just tore down
+    this.transportConnectingSince = undefined;
 
     this.reliableReceivedState.clear();
   }
@@ -450,8 +474,8 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
     this.lossyChannel.stopThresholdTuning();
   }
 
-  async cleanupClient() {
-    await this.client.close();
+  async cleanupClient(reason?: string) {
+    await this.client.close(true, reason);
     this.client.resetCallbacks();
     // Any in-flight addTrack requests are orphaned by the signal reconnect — the new session
     // won't deliver `trackPublishedResponse` for them, so reject the pending resolvers and
@@ -468,7 +492,7 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
       throw new TrackInvalidError('a track with the same ID has already been published');
     }
     return new Promise<TrackInfo>((resolve, reject) => {
-      const publicationTimeout = setTimeout(() => {
+      const publicationTimeout = CriticalTimers.setTimeout(() => {
         delete this.pendingTrackResolvers[req.cid];
         reject(
           ConnectionError.timeout('publication of local track timed out, no response from server'),
@@ -476,11 +500,11 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
       }, 10_000);
       this.pendingTrackResolvers[req.cid] = {
         resolve: (info: TrackInfo) => {
-          clearTimeout(publicationTimeout);
+          CriticalTimers.clearTimeout(publicationTimeout);
           resolve(info);
         },
         reject: () => {
-          clearTimeout(publicationTimeout);
+          CriticalTimers.clearTimeout(publicationTimeout);
           reject(new Error('Cancelled publication by calling unpublish'));
         },
       };
@@ -565,6 +589,16 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
     this.pcManager.onStateChange = async (connectionState, publisherState, subscriberState) => {
       this.log.debug(`primary PC state changed ${connectionState}`);
 
+      // Record when the primary transport actually entered CONNECTING so
+      // verifyTransport() can bound how long we tolerate it. Deriving it from the
+      // real transition (this handler only fires on state changes) rather than from
+      // observation time keeps it from going stale across peer-connection rebuilds.
+      if (connectionState === PCTransportState.CONNECTING) {
+        this.transportConnectingSince = Date.now();
+      } else {
+        this.transportConnectingSince = undefined;
+      }
+
       if (['closed', 'disconnected', 'failed'].includes(publisherState)) {
         // reset publisher connection promise
         this.publisherConnectionPromise = undefined;
@@ -722,7 +756,7 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
       switch (leave.action) {
         case LeaveRequest_Action.DISCONNECT:
           this.emit(EngineEvent.Disconnected, leave?.reason);
-          this.close();
+          this.close(`server leave: ${DisconnectReason[leave.reason] ?? leave.reason}`);
           break;
         case LeaveRequest_Action.RECONNECT:
           this.fullReconnectOnNext = true;
@@ -816,8 +850,15 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
     for (let i: number = 0; i < numAudios; i++) {
       this.pcManager?.addPublisherTransceiverOfKind('audio', transceiverInit);
     }
+    // media only arrives on these sections when there is no subscriber connection to arrive on
+    const receivesMedia = this.pcManager?.mode === 'publisher-only';
     for (let i: number = 0; i < numVideos; i++) {
-      this.pcManager?.addPublisherTransceiverOfKind('video', transceiverInit);
+      const transceiver = this.pcManager?.addPublisherTransceiverOfKind('video', transceiverInit);
+      if (receivesMedia && transceiver) {
+        const negotiated = negotiateDependencyDescriptor(transceiver);
+
+        this.log.debug('dependency descriptor negotiated for received video', { negotiated });
+      }
     }
   }
 
@@ -1095,7 +1136,7 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
     if (!opts.videoCodec) {
       return;
     }
-    track.setSimulcastTrackSender(opts.videoCodec, transceiver.sender);
+    await track.setSimulcastTrackSender(opts.videoCodec, transceiver.sender);
     return transceiver.sender;
   }
 
@@ -1125,7 +1166,7 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
         `could not recover connection after ${this.reconnectAttempts} attempts, ${duration}ms. giving up`,
       );
       this.emit(EngineEvent.Disconnected);
-      this.close();
+      this.close(`gave up reconnecting after ${this.reconnectAttempts} attempts, ${duration}ms`);
     };
 
     const duration = Date.now() - this.reconnectStart;
@@ -1157,6 +1198,73 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
     );
   };
 
+  /**
+   * A sustained local `LOST` while connected and publishing means the server isn't receiving
+   * our media, so force a full reconnect; any non-`LOST` value cancels a pending trigger.
+   */
+  private handleLocalConnectionQuality(update: ConnectionQualityUpdate) {
+    if (!this.participantSid) {
+      return;
+    }
+    const localUpdate = update.updates.find((u) => u.participantSid === this.participantSid);
+    if (!localUpdate) {
+      return;
+    }
+    if (localUpdate.quality === ProtoConnectionQuality.LOST) {
+      this.scheduleLostQualityReconnect();
+    } else {
+      this.clearLostQualityTimeout();
+    }
+  }
+
+  private scheduleLostQualityReconnect() {
+    if (this.lostQualityTimeout) {
+      // already counting down towards a reconnect
+      return;
+    }
+    this.lostQualityTimeout = CriticalTimers.setTimeout(() => {
+      this.lostQualityTimeout = undefined;
+      if (this._isClosed || this.pcState !== PCState.Connected || this.attemptingReconnect) {
+        return;
+      }
+      if (!this.hasActivePublisherSenders()) {
+        return;
+      }
+      this.log.warn(
+        'local connection quality lost while publishing, triggering full reconnect',
+        this.logContext,
+      );
+      this.fullReconnectOnNext = true;
+      this.handleDisconnect('connection quality lost', ReconnectReason.RR_PUBLISHER_FAILED);
+    }, connectionQualityLostTimeout);
+  }
+
+  private clearLostQualityTimeout() {
+    if (this.lostQualityTimeout) {
+      CriticalTimers.clearTimeout(this.lostQualityTimeout);
+      this.lostQualityTimeout = undefined;
+    }
+  }
+
+  /** Whether the publisher currently has any sender with a live track. */
+  private hasActivePublisherSenders(): boolean {
+    return (
+      this.pcManager?.publisher
+        .getSenders()
+        .some((sender) => !!sender.track && sender.track.readyState === 'live') ?? false
+    );
+  }
+
+  /**
+   * Forces a full reconnect while keeping the engine (and its saved credentials) alive. Used by
+   * Room's connection-reconcile safety net when the transport silently died but we looked connected.
+   * @internal
+   */
+  reconnect(reason: ReconnectReason = ReconnectReason.RR_UNKNOWN) {
+    this.fullReconnectOnNext = true;
+    this.handleDisconnect('reconcile', reason);
+  }
+
   private async attemptReconnect(reason?: ReconnectReason) {
     if (this._isClosed) {
       return;
@@ -1166,6 +1274,12 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
       this.log.warn('already attempting reconnect, returning early');
       return;
     }
+
+    // A pending Lost-quality countdown belongs to the session we're now leaving; cancel it so
+    // it can't fire against the reconnected session before the server has evaluated it. (A resume
+    // keeps the peer connections, so cleanupPeerConnections wouldn't cover this path.)
+    this.clearLostQualityTimeout();
+
     if (
       this.clientConfiguration?.resumeConnection === ClientConfigSetting.DISABLED ||
       // signaling state could change to closed due to hardware sleep
@@ -1175,15 +1289,23 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
       this.fullReconnectOnNext = true;
     }
 
+    // Consume the flag up front: capture whether this attempt is a full reconnect, then reset
+    // it. From here on a `true` value unambiguously represents a *new* full-reconnect request
+    // that arrived while this attempt was running (e.g. a server RECONNECT leave), which the
+    // finally block dispatches — for both the resume and full-reconnect paths.
+    const fullReconnect = this.fullReconnectOnNext;
+    this.fullReconnectOnNext = false;
+
+    let succeeded = false;
     try {
       this.attemptingReconnect = true;
-      if (this.fullReconnectOnNext) {
+      if (fullReconnect) {
         await this.restartConnection();
       } else {
         await this.resumeConnection(reason);
       }
       this.clearPendingReconnect();
-      this.fullReconnectOnNext = false;
+      succeeded = true;
     } catch (e) {
       this.reconnectAttempts += 1;
       let recoverable = true;
@@ -1191,8 +1313,9 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
         this.log.debug('received unrecoverable error', { error: e });
         // unrecoverable
         recoverable = false;
-      } else if (!(e instanceof SignalReconnectError)) {
-        // cannot resume
+      } else if (fullReconnect || !(e instanceof SignalReconnectError)) {
+        // a failed full reconnect stays a full reconnect; a failed resume can only be
+        // resumed again for a signal-level error, otherwise it escalates
         this.fullReconnectOnNext = true;
       }
 
@@ -1205,10 +1328,22 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
           }ms. giving up`,
         );
         this.emit(EngineEvent.Disconnected);
-        await this.close();
+        await this.close(
+          `gave up reconnecting after ${this.reconnectAttempts} attempts, ${
+            Date.now() - this.reconnectStart
+          }ms`,
+        );
       }
     } finally {
       this.attemptingReconnect = false;
+
+      // A full reconnect requested while this attempt was running (e.g. a `RECONNECT` leave
+      // during a resume or a restart) that a successful attempt didn't act on; dispatch it now
+      // (the failure path already retries).
+      if (succeeded && this.fullReconnectOnNext && !this._isClosed) {
+        this.log.debug('full reconnect requested during in-progress attempt, dispatching');
+        this.handleDisconnect('reconnect');
+      }
     }
   }
 
@@ -1591,11 +1726,12 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
     if (!this.pcManager) {
       return false;
     }
+    const state = this.pcManager.currentState;
     const allowedConnectionStates: PCTransportState[] = [
       PCTransportState.CONNECTING,
       PCTransportState.CONNECTED,
     ];
-    if (!allowedConnectionStates.includes(this.pcManager.currentState)) {
+    if (!allowedConnectionStates.includes(state)) {
       return false;
     }
 
@@ -1603,6 +1739,20 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
     if (!this.client.ws || this.client.ws.readyState === WebSocket.CLOSED) {
       return false;
     }
+
+    // A transport stuck in CONNECTING never reaches CONNECTED nor reports FAILED, so it would
+    // otherwise look healthy forever; bound how long we tolerate it. The entry time is recorded
+    // in the pcManager state-change handler (see configure()), so this is a pure read — an
+    // unrecorded CONNECTING fails open rather than measuring against a stale timestamp.
+    if (
+      state === PCTransportState.CONNECTING &&
+      this.transportConnectingSince !== undefined &&
+      Date.now() - this.transportConnectingSince > this.peerConnectionTimeout
+    ) {
+      this.log.warn('transport stuck in connecting state', this.logContext);
+      return false;
+    }
+
     return true;
   }
 

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 () => {
@@ -190,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();
+  });
+});