livekit-client 2.20.2 → 2.22.0

package/src/room/RTCEngine.ts

@@ -18,6 +18,7 @@ import {
   LeaveRequest_Action,
   MediaSectionsRequirement,
   ParticipantInfo,
+  ConnectionQuality as ProtoConnectionQuality,
   PublishDataTrackResponse,
   ReconnectReason,
   type ReconnectResponse,
@@ -44,7 +45,6 @@ import {
   type UserPacket,
 } from '@livekit/protocol';
 import { EventEmitter } from 'events';
-import type { Throws } from '@livekit/throws-transformer/throws';
 import type { MediaAttributes } from 'sdp-transform';
 import type TypedEventEmitter from 'typed-emitter';
 import type { SignalOptions } from '../api/SignalClient';
@@ -64,11 +64,15 @@ import log, { LoggerNames, getLogger } from '../logger';
 import type { InternalRoomOptions } from '../options';
 import type { NonSharedUint8Array } from '../type-polyfills/non-shared-typed-arrays';
 import TypedPromise from '../utils/TypedPromise';
-import { DataPacketBuffer } from '../utils/dataPacketBuffer';
 import { TTLMap } from '../utils/ttlmap';
 import PCTransport, { PCEvents } from './PCTransport';
 import { PCTransportManager, PCTransportState } from './PCTransportManager';
 import type { ReconnectContext, ReconnectPolicy } from './ReconnectPolicy';
+import { DataChannelManager } from './data-channel/DataChannelManager';
+import type { FlowControlledDataChannel } from './data-channel/FlowControlledDataChannel';
+import type { LossyDataChannel } from './data-channel/LossyDataChannel';
+import type { ReliableDataChannel } from './data-channel/ReliableDataChannel';
+import { DataChannelKind } from './data-channel/types';
 import { DataTrackInfo } from './data-track/types';
 import { roomConnectOptionDefaults } from './defaults';
 import {
@@ -97,29 +101,22 @@ import {
   isVideoCodec,
   isVideoTrack,
   isWeb,
+  negotiateDependencyDescriptor,
   sleep,
   supportsAddTrack,
   supportsTransceiver,
   toHttpUrl,
 } from './utils';
 
-const lossyDataChannel = '_lossy';
-const reliableDataChannel = '_reliable';
-const dataTrackDataChannel = '_data_track';
 const minReconnectWait = 2 * 1000;
 const leaveReconnect = 'leave-reconnect';
-const reliabeReceiveStateTTL = 30_000;
 
-// Two-watermark flow control for the reliable and data-track channels. Senders fill the buffer
-// freely up to the high-water mark; once it's exceeded they block until the browser's
-// `bufferedamountlow` event (which we arm at the low-water mark) signals the buffer has drained.
-// The gap between the marks keeps the SCTP send buffer saturated while we refill, so throughput
-// isn't starved, while the high-water mark bounds the buffer well below the level that would abort
-// the channel (see livekit/client-sdk-js#1995).
-const reliableDataChannelWaterMarkLow = 64 * 1024;
-const reliableDataChannelWaterMarkHigh = 1024 * 1024;
-const lossyDataChannelWaterMarkLow = 8 * 1024;
-const lossyDataChannelWaterMarkHigh = 256 * 1024;
+/**
+ * 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;
 const initialMediaSectionsVideo = 3;
@@ -132,11 +129,7 @@ enum PCState {
   Closed,
 }
 
-export enum DataChannelKind {
-  RELIABLE = DataPacket_Kind.RELIABLE,
-  LOSSY = DataPacket_Kind.LOSSY,
-  DATA_TRACK_LOSSY = 2,
-}
+export { DataChannelKind };
 
 // Default data-channel max message size (bytes), used when the remote SDP
 // answer does not advertise an `a=max-message-size` attribute (RFC 8841).
@@ -180,22 +173,24 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
     return !!this.reconnectTimeout;
   }
 
-  private lossyDC?: RTCDataChannel;
-
-  // @ts-ignore noUnusedLocals
-  private lossyDCSub?: RTCDataChannel;
-
-  private reliableDC?: RTCDataChannel;
-
-  // @ts-ignore noUnusedLocals
-  private reliableDCSub?: RTCDataChannel;
+  /**
+   * Owns the data channels: the three flow-controlled publisher wrappers (engine-lifetime; the
+   * RTCDataChannel handles underneath are attached/detached as peer connections come and go, with
+   * waiter invalidation built into the turnover) plus the subscriber-side receive handles.
+   */
+  private dataChannels: DataChannelManager;
 
-  private dataTrackDC?: RTCDataChannel;
+  private get reliableChannel(): ReliableDataChannel {
+    return this.dataChannels.reliable;
+  }
 
-  // @ts-ignore noUnusedLocals
-  private dataTrackDCSub?: RTCDataChannel;
+  private get lossyChannel(): LossyDataChannel {
+    return this.dataChannels.lossy;
+  }
 
-  private dcBufferStatus: Map<DataChannelKind, boolean>;
+  private get dataTrackChannel(): LossyDataChannel {
+    return this.dataChannels.dataTrack;
+  }
 
   private subscriberPrimary: boolean = false;
 
@@ -252,25 +247,19 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
 
   private publisherConnectionPromise: Promise<void> | undefined;
 
-  private reliableDataSequence: number = 1;
-
-  private reliableMessageBuffer = new DataPacketBuffer();
-
   private reliableReceivedState: TTLMap<string, number> = new TTLMap(reliabeReceiveStateTTL);
 
-  private lossyDataStatCurrentBytes: number = 0;
-
-  private lossyDataStatByterate: number = 0;
-
-  private lossyDataStatInterval: ReturnType<typeof setInterval> | undefined;
-
-  private lossyDataDropCount: number = 0;
-
   private midToTrackId: { [key: string]: string } = {};
 
   /** 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);
@@ -283,16 +272,23 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
     this.reconnectPolicy = this.options.reconnectPolicy;
     this.closingLock = new Mutex();
     this.dataProcessLock = new Mutex();
-    this.dcBufferStatus = new Map([
-      [DataChannelKind.RELIABLE, true],
-      [DataChannelKind.LOSSY, true],
-      [DataChannelKind.DATA_TRACK_LOSSY, true],
-    ]);
+    this.dataChannels = new DataChannelManager({
+      isEngineClosed: () => this.isClosed,
+      isReconnecting: () => this.attemptingReconnect,
+      onDataMessage: (message) => this.handleDataMessage(message),
+      onDataTrackMessage: (message) => this.handleDataTrackMessage(message),
+      onDataError: (event) => this.handleDataError(event),
+      onChannelClose: (kind) => this.handleDataChannelClose(kind)(),
+      onBufferStatusChanged: (kind, isLow) =>
+        this.emit(EngineEvent.DCBufferStatusChanged, isLow, kind),
+    });
 
     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) =>
@@ -449,6 +445,7 @@ 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();
@@ -458,60 +455,18 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
   }
 
   async cleanupPeerConnections() {
-    // Reject parked headroom waiters up front: closing the peer connection is allowed (per spec)
-    // to transition data channels to 'closed' without firing events, which would otherwise strand
-    // a waiter holding the headroom lock.
-    this.invalidateDataChannelWaiters('peer connections cleaned up');
-
-    const dcCleanup = (dc: RTCDataChannel | undefined) => {
-      if (!dc) {
-        return;
-      }
-
-      // Detach the data channel handlers before closing anything. Closing a peer connection tears
-      // down the SCTP transport, which can dispatch `error`/`close` events on the still-open data
-      // channels; if our handlers are still attached at that point, handleDataError logs a spurious
-      // "Unknown DataChannel error" during an otherwise graceful disconnect. Removing the handlers
-      // before dc.close()/pcManager.close() makes this deterministic regardless of how/when the
-      // browser dispatches those teardown events. See livekit/client-sdk-js#1953.
-      dc.onbufferedamountlow = null;
-      dc.onclose = null;
-      dc.onclosing = null;
-      dc.onerror = null;
-      dc.onmessage = null;
-      dc.onopen = null;
-
-      dc.close();
-    };
-    dcCleanup(this.lossyDC);
-    dcCleanup(this.lossyDCSub);
-    dcCleanup(this.reliableDC);
-    dcCleanup(this.reliableDCSub);
-    dcCleanup(this.dataTrackDC);
-    dcCleanup(this.dataTrackDCSub);
+    this.dataChannels.teardown();
 
     await this.pcManager?.close();
     this.pcManager = undefined;
+    // the connecting timestamp belongs to the transports we just tore down
+    this.transportConnectingSince = undefined;
 
-    this.lossyDC = undefined;
-    this.lossyDCSub = undefined;
-    this.reliableDC = undefined;
-    this.reliableDCSub = undefined;
-    this.dataTrackDC = undefined;
-    this.dataTrackDCSub = undefined;
-    this.reliableMessageBuffer = new DataPacketBuffer();
-    this.reliableDataSequence = 1;
     this.reliableReceivedState.clear();
   }
 
   cleanupLossyDataStats() {
-    this.lossyDataStatByterate = 0;
-    this.lossyDataStatCurrentBytes = 0;
-    if (this.lossyDataStatInterval) {
-      clearInterval(this.lossyDataStatInterval);
-      this.lossyDataStatInterval = undefined;
-    }
-    this.lossyDataDropCount = 0;
+    this.lossyChannel.stopThresholdTuning();
   }
 
   async cleanupClient() {
@@ -532,7 +487,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'),
@@ -540,11 +495,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'));
         },
       };
@@ -580,7 +535,7 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
   }
 
   get dataSubscriberReadyState(): string | undefined {
-    return this.reliableDCSub?.readyState;
+    return this.dataChannelForKind(DataChannelKind.RELIABLE, true)?.readyState;
   }
 
   async getConnectedServerAddress(): Promise<string | undefined> {
@@ -629,6 +584,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;
@@ -880,8 +845,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 });
+      }
     }
   }
 
@@ -890,121 +862,39 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
       return;
     }
 
-    // Waiters parked on the old channel objects would never see another event from them once they
-    // are replaced below — reject them so the headroom lock is released and queued senders
-    // re-check against the new channels.
-    this.invalidateDataChannelWaiters('data channels recreated');
-
-    // clear old data channel callbacks if recreate
-    if (this.lossyDC) {
-      this.lossyDC.onmessage = null;
-      this.lossyDC.onerror = null;
-      this.lossyDC.onclose = null;
-    }
-    if (this.reliableDC) {
-      this.reliableDC.onmessage = null;
-      this.reliableDC.onerror = null;
-      this.reliableDC.onclose = null;
-    }
-    if (this.dataTrackDC) {
-      this.dataTrackDC.onmessage = null;
-      this.dataTrackDC.onerror = null;
-      this.dataTrackDC.onclose = null;
-    }
-
-    // create data channels
-    this.lossyDC = this.pcManager.createPublisherDataChannel(lossyDataChannel, {
-      ordered: false,
-      maxRetransmits: 0,
-    });
-    this.reliableDC = this.pcManager.createPublisherDataChannel(reliableDataChannel, {
-      ordered: true,
-    });
-    this.dataTrackDC = this.pcManager.createPublisherDataChannel(dataTrackDataChannel, {
-      ordered: false,
-      maxRetransmits: 0,
-    });
-
-    // also handle messages over the pub channel, for backwards compatibility
-    this.lossyDC.onmessage = this.handleDataMessage;
-    this.reliableDC.onmessage = this.handleDataMessage;
-    this.dataTrackDC.onmessage = this.handleDataTrackMessage;
-
-    // handle datachannel errors
-    this.lossyDC.onerror = this.handleDataError;
-    this.reliableDC.onerror = this.handleDataError;
-    this.dataTrackDC.onerror = this.handleDataError;
-
-    // detect unexpected publisher data channel closes
-    this.lossyDC.onclose = this.handleDataChannelClose(DataChannelKind.LOSSY);
-    this.reliableDC.onclose = this.handleDataChannelClose(DataChannelKind.RELIABLE);
-    this.dataTrackDC.onclose = this.handleDataChannelClose(DataChannelKind.DATA_TRACK_LOSSY);
-
-    // set up dc buffer threshold - if this is not set, it will default to 0
-    this.lossyDC.bufferedAmountLowThreshold = lossyDataChannelWaterMarkLow;
-    this.reliableDC.bufferedAmountLowThreshold = reliableDataChannelWaterMarkLow;
-    this.dataTrackDC.bufferedAmountLowThreshold = lossyDataChannelWaterMarkLow;
-
-    // handle buffer amount low events
-    this.lossyDC.onbufferedamountlow = () => this.handleBufferedAmountLow(DataChannelKind.LOSSY);
-    this.reliableDC.onbufferedamountlow = () =>
-      this.handleBufferedAmountLow(DataChannelKind.RELIABLE);
-    this.dataTrackDC.onbufferedamountlow = () =>
-      this.handleBufferedAmountLow(DataChannelKind.DATA_TRACK_LOSSY);
-
-    this.cleanupLossyDataStats();
-    this.lossyDataStatInterval = setInterval(() => {
-      this.lossyDataStatByterate = this.lossyDataStatCurrentBytes;
-      this.lossyDataStatCurrentBytes = 0;
-
-      const dc = this.dataChannelForKind(DataChannelKind.LOSSY);
-      if (dc) {
-        // control buffered latency to ~100ms
-        const threshold = this.lossyDataStatByterate / 10;
-        dc.bufferedAmountLowThreshold = Math.min(
-          Math.max(threshold, lossyDataChannelWaterMarkLow),
-          lossyDataChannelWaterMarkHigh,
-        );
-      }
-    }, 1000);
+    this.dataChannels.createPublisherChannels(this.pcManager);
   }
 
   private handleDataChannel = async ({ channel }: RTCDataChannelEvent) => {
     if (!channel) {
       return;
     }
-    let handler;
-    if (channel.label === reliableDataChannel) {
-      this.reliableDCSub = channel;
-      handler = this.handleDataMessage;
-    } else if (channel.label === lossyDataChannel) {
-      this.lossyDCSub = channel;
-      handler = this.handleDataMessage;
-    } else if (channel.label === dataTrackDataChannel) {
-      this.dataTrackDCSub = channel;
-      handler = this.handleDataTrackMessage;
-    } else {
-      return;
+    if (this.dataChannels.adoptSubscriberChannel(channel)) {
+      this.log.debug(`on data channel ${channel.id}, ${channel.label}`);
     }
-    this.log.debug(`on data channel ${channel.id}, ${channel.label}`);
-    channel.onmessage = handler;
   };
 
+  /** Normalizes an incoming data-channel message into bytes, or logs and returns undefined. */
+  private async decodeDataMessage(message: MessageEvent): Promise<Uint8Array | undefined> {
+    if (message.data instanceof ArrayBuffer) {
+      return new Uint8Array(message.data);
+    }
+    if (message.data instanceof Blob) {
+      return new Uint8Array(await message.data.arrayBuffer());
+    }
+    this.log.error('unsupported data type', { data: message.data });
+    return undefined;
+  }
+
   private handleDataMessage = async (message: MessageEvent) => {
     // make sure to respect incoming data message order by processing message events one after the other
     const unlock = await this.dataProcessLock.lock();
     try {
-      // decode
-      let buffer: ArrayBuffer | undefined;
-      if (message.data instanceof ArrayBuffer) {
-        buffer = message.data;
-      } else if (message.data instanceof Blob) {
-        buffer = await message.data.arrayBuffer();
-      } else {
-        this.log.error('unsupported data type', { data: message.data });
+      const bytes = await this.decodeDataMessage(message);
+      if (!bytes) {
         return;
       }
-      const dp = DataPacket.fromBinary(new Uint8Array(buffer));
+      const dp = DataPacket.fromBinary(bytes);
 
       if (dp.sequence > 0 && dp.participantSid !== '') {
         const lastSeq = this.reliableReceivedState.get(dp.participantSid);
@@ -1053,18 +943,11 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
   };
 
   private handleDataTrackMessage = async (message: MessageEvent) => {
-    // Decode / normalize into a common format
-    let buffer: ArrayBuffer | undefined;
-    if (message.data instanceof ArrayBuffer) {
-      buffer = message.data;
-    } else if (message.data instanceof Blob) {
-      buffer = await message.data.arrayBuffer();
-    } else {
-      this.log.error('unsupported data type', { data: message.data });
+    const bytes = await this.decodeDataMessage(message);
+    if (!bytes) {
       return;
     }
-
-    this.emit('dataTrackPacketReceived', new Uint8Array(buffer));
+    this.emit('dataTrackPacketReceived', bytes);
   };
 
   private handleDataError = (event: Event) => {
@@ -1103,10 +986,6 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
     }
   };
 
-  private handleBufferedAmountLow = (channelKind: DataChannelKind) => {
-    this.updateAndEmitDCBufferStatus(channelKind);
-  };
-
   async createSender(
     track: LocalTrack,
     opts: TrackPublishOptions,
@@ -1252,7 +1131,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;
   }
 
@@ -1314,6 +1193,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;
@@ -1323,6 +1269,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
@@ -1332,15 +1284,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;
@@ -1348,8 +1308,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;
       }
 
@@ -1366,6 +1327,14 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
       }
     } 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');
+      }
     }
   }
 
@@ -1510,7 +1479,8 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
 
     // recreate publish datachannel if it's id is null
     // (for safari https://bugs.webkit.org/show_bug.cgi?id=184688)
-    if (this.reliableDC?.readyState === 'open' && this.reliableDC.id === null) {
+    const reliableDC = this.dataChannelForKind(DataChannelKind.RELIABLE);
+    if (reliableDC?.readyState === 'open' && reliableDC.id === null) {
       this.createDataChannels();
     }
 
@@ -1586,7 +1556,11 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
   }
 
   /* @internal */
-  async sendDataPacket(packet: DataPacket, kind: DataChannelKind) {
+  async sendDataPacket(
+    packet: DataPacket,
+    /**  Data-track frames don't come through here — they're sent pre-serialized via {@link sendDataTrackFrame }. */
+    kind: Exclude<DataChannelKind, DataChannelKind.DATA_TRACK_LOSSY>,
+  ) {
     // make sure we do have a data connection
     await this.ensurePublisherConnected(kind);
 
@@ -1608,8 +1582,7 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
     }
 
     if (kind === DataChannelKind.RELIABLE) {
-      packet.sequence = this.reliableDataSequence;
-      this.reliableDataSequence += 1;
+      packet.sequence = this.reliableChannel.nextSequence();
     }
 
     const msg = packet.toBinary() as Uint8Array<ArrayBuffer>;
@@ -1631,314 +1604,46 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
       );
     }
 
-    switch (kind) {
-      case DataChannelKind.LOSSY:
-      case DataChannelKind.DATA_TRACK_LOSSY:
-        return this.sendLossyBytes(msg, kind);
-
-      case DataChannelKind.RELIABLE: {
-        if (this.attemptingReconnect) {
-          // A reconnect is already underway — queue for the resume replay instead of parking on a
-          // channel that is being torn down. The send resolves; delivery is deferred to the replay.
-          this.reliableMessageBuffer.push({ data: msg, sequence: packet.sequence, sent: false });
-          return;
-        }
-
-        const dc = this.dataChannelForKind(kind);
-        if (dc) {
-          try {
-            await this.waitForBufferHeadroomWithLock(kind);
-          } catch (error) {
-            if (this.isClosed) {
-              // No replay is coming after an engine close — surface the failure.
-              throw error;
-            }
-            // Transient teardown (the channel closed or was replaced while we waited): the
-            // reliable channel promises delivery across resume, so queue the packet for the
-            // replay instead of rejecting a send the app can't meaningfully retry.
-            this.reliableMessageBuffer.push({ data: msg, sequence: packet.sequence, sent: false });
-            return;
-          }
-
-          if (this.attemptingReconnect) {
-            // A reconnect began while we waited for headroom — same deal as above.
-            this.reliableMessageBuffer.push({ data: msg, sequence: packet.sequence, sent: false });
-            return;
-          }
-
-          this.reliableMessageBuffer.push({ data: msg, sequence: packet.sequence, sent: true });
-          dc.send(msg);
-        }
-
-        this.updateAndEmitDCBufferStatus(kind);
-        break;
-      }
-    }
-  }
-
-  /* @internal */
-  async sendLossyBytes(
-    bytes: NonSharedUint8Array,
-    kind: Exclude<DataChannelKind, DataChannelKind.RELIABLE>,
-    bufferStatusFullBehavior: 'drop' | 'wait' = 'drop',
-  ) {
-    // Make sure we do have a data connection. This matters most for the direct data-track path
-    // (Room's packetAvailable handler), which doesn't go through sendDataPacket: it both waits for
-    // the channel to be open and — on lazily negotiated publisher connections — is what kicks the
-    // negotiation off in the first place. The call is memoized, so the steady-state cost is one
-    // await on an already-resolved promise.
-    await this.ensurePublisherConnected(kind);
-
-    const dc = this.dataChannelForKind(kind);
-    try {
-      if (dc) {
-        // Depending on the exact circumstance that data is being sent, either drop or wait for the
-        // buffer to drain below the high-water mark before continuing.
-        switch (bufferStatusFullBehavior) {
-          case 'wait':
-            if (!this.isBelowHighWaterMark(kind)) {
-              await this.waitForBufferHeadroomWithLock(kind);
-            }
-            break;
-          case 'drop':
-            // we check against the actual threshold on the DC here, as it is dynamic for the lossy DC
-            if (!this.isBelowLowWaterMark(kind)) {
-              // Drop messages to reduce latency
-              this.lossyDataDropCount += 1;
-              if (this.lossyDataDropCount % 100 === 0) {
-                this.log.warn(
-                  `dropping lossy data channel messages, total dropped: ${this.lossyDataDropCount}`,
-                );
-              }
-              return;
-            }
-        }
-        if (kind === DataChannelKind.LOSSY) {
-          // The byterate stat tunes the LOSSY channel's dynamic drop threshold; counting data-track
-          // bytes here would inflate it and let the lossy channel buffer far more latency than the
-          // ~100ms the tuning targets.
-          this.lossyDataStatCurrentBytes += bytes.byteLength;
-        }
-
-        if (this.attemptingReconnect) {
-          return;
-        }
-
-        dc.send(bytes);
-      }
-
-      this.updateAndEmitDCBufferStatus(kind);
-    } catch (error: unknown) {
-      // ensure same surface behaviour as before with missing data channel being silently ignored, just log an error message for clarity
-      if (error instanceof TypeError) {
-        this.log.error(error);
-      } else {
-        throw error;
-      }
-    }
-  }
-
-  private async resendReliableMessagesForResume(lastMessageSeq: number) {
-    await this.ensurePublisherConnected(DataChannelKind.RELIABLE);
-    const dc = this.dataChannelForKind(DataChannelKind.RELIABLE);
-    if (dc) {
-      this.reliableMessageBuffer.popToSequence(lastMessageSeq);
-      // Hold the headroom lock across the whole replay. Releasing it between messages would let a
-      // concurrent send — whose (newer) sequence was already assigned in sendDataPacket before it
-      // queued on the lock — hit the wire mid-replay, and receivers would then discard the
-      // remaining lower-sequence resent messages as duplicates.
-      const unlock = await this.getBufferHeadroomLock(DataChannelKind.RELIABLE).lock();
-      try {
-        // Everything left after the ack cutoff must be re-handed to the current channel.
-        this.reliableMessageBuffer.markAllUnsent();
-        // Drain in passes, re-scanning the live buffer each time: a send that arrives (deferred,
-        // sent:false) during our own awaits appends after this pass started, so we pick it up on
-        // the next one. We mark each packet only once we've actually handed it to the channel — a
-        // blanket "mark all sent" would flip such a late arrival to sent without transmitting it,
-        // and a later alignBufferedAmount would then drop it for good. If the loop throws
-        // mid-drain, unsent entries keep their flag and the next replay picks them up.
-        for (
-          let batch = this.reliableMessageBuffer.getUnsent();
-          batch.length > 0;
-          batch = this.reliableMessageBuffer.getUnsent()
-        ) {
-          for (const item of batch) {
-            // Respect flow control on resume too, so a large resend doesn't overflow the buffer.
-            // We already hold the lock across the whole replay, so use the lock-free wait.
-            await this.waitForBufferHeadroomWithoutLock(DataChannelKind.RELIABLE);
-            dc.send(item.data);
-            this.reliableMessageBuffer.markSent(item);
-          }
-        }
-      } finally {
-        unlock();
-      }
-    }
-    this.updateAndEmitDCBufferStatus(DataChannelKind.RELIABLE);
-  }
-
-  private updateAndEmitDCBufferStatus = (kind: DataChannelKind) => {
+    // The full-buffer policy (drop for lossy, wait/replay for reliable) is the channel's own, as
+    // is emitting the buffer-status change once the send settles.
     if (kind === DataChannelKind.RELIABLE) {
-      const dc = this.dataChannelForKind(kind);
-      if (dc) {
-        this.reliableMessageBuffer.alignBufferedAmount(dc.bufferedAmount);
-      }
-    }
-    try {
-      const status = this.isBelowLowWaterMark(kind);
-      if (typeof status !== 'undefined' && status !== this.dcBufferStatus.get(kind)) {
-        this.dcBufferStatus.set(kind, status);
-        this.emit(EngineEvent.DCBufferStatusChanged, status, kind);
-      }
-    } catch (e) {
-      this.log.warn('could not update buffer status', { error: e });
-    }
-  };
-
-  /**
-   * Whether the send buffer has room to accept more data (the send gate). Senders proceed while
-   * this is true and block once it goes false.
-   */
-  private isBelowHighWaterMark = (kind: DataChannelKind): Throws<boolean, TypeError> => {
-    const dc = this.dataChannelForKind(kind);
-    if (!dc) {
-      throw new TypeError(`Could not get data channel for kind ${kind}`);
-    }
-    // because RTCDatachannel has no high water mark built in we read the statically defined versions as constants
-    const highMark =
-      kind === DataChannelKind.RELIABLE
-        ? reliableDataChannelWaterMarkHigh
-        : lossyDataChannelWaterMarkHigh;
-    return dc.bufferedAmount <= highMark;
-  };
-
-  /**
-   * Whether the send buffer has drained to its low-water mark. Drives the public
-   * {@link EngineEvent.DCBufferStatusChanged} event.
-   */
-  private isBelowLowWaterMark = (kind: DataChannelKind): Throws<boolean, TypeError> => {
-    const dc = this.dataChannelForKind(kind);
-    if (!dc) {
-      throw new TypeError(`Could not get data channel for kind ${kind}`);
+      await this.reliableChannel.send(msg, packet.sequence);
+    } else {
+      await this.lossyChannel.send(msg);
     }
-    // because RTCDatachannel has the threshold built in we can read it dynamically to account for changing thresholds over time
-    return dc.bufferedAmount <= dc.bufferedAmountLowThreshold;
-  };
-
-  /** Per-kind lock serializing senders that have to wait for the buffer to drain. */
-  private waitForBufferHeadroomLocks = new Map<DataChannelKind, Mutex>();
+  }
 
   /**
-   * Per-kind AbortController that cancels parked headroom waiters whenever a kind's channel object
-   * stops being current (replaced by createDataChannels or torn down by cleanupPeerConnections). A
-   * waiter is parked on the channel object it captured at wait entry; if that object is abandoned
-   * its events may never fire again, so the abort is what rejects the waiter and releases the
-   * headroom lock instead of stranding every future sender behind it.
+   * Sends pre-serialized bytes on the data-track channel. This is the one send path that doesn't
+   * go through {@link sendDataPacket} — Room's `packetAvailable` handler calls it directly with
+   * bytes the data-track pipeline already serialized.
+   *
+   * @internal
    */
-  private waiterAbortControllers = new Map<DataChannelKind, AbortController>();
-
-  private waiterAbortSignal(kind: DataChannelKind): AbortSignal {
-    let controller = this.waiterAbortControllers.get(kind);
-    if (!controller) {
-      controller = new AbortController();
-      this.waiterAbortControllers.set(kind, controller);
-    }
-    return controller.signal;
+  async sendDataTrackFrame(bytes: NonSharedUint8Array) {
+    // Make sure we do have a data connection: on lazily negotiated publisher connections this is
+    // what kicks negotiation off, and it waits for the channel to open. Memoized, so the
+    // steady-state cost is one await on an already-resolved promise.
+    await this.ensurePublisherConnected(DataChannelKind.DATA_TRACK_LOSSY);
+    await this.dataTrackChannel.send(bytes);
   }
 
-  /** Rejects all parked headroom waiters (all kinds); the next waiter gets a fresh controller. */
-  private invalidateDataChannelWaiters(reason: string) {
-    for (const controller of this.waiterAbortControllers.values()) {
-      controller.abort(reason);
-    }
-    this.waiterAbortControllers.clear();
+  private async resendReliableMessagesForResume(lastMessageSeq: number) {
+    await this.ensurePublisherConnected(DataChannelKind.RELIABLE);
+    await this.reliableChannel.replay(lastMessageSeq);
   }
 
-  /** Acquires the per-kind headroom lock, resolving with the unlock function. */
-  private getBufferHeadroomLock(kind: DataChannelKind): Mutex {
-    let lock = this.waitForBufferHeadroomLocks.get(kind);
-    if (!lock) {
-      lock = new Mutex();
-      this.waitForBufferHeadroomLocks.set(kind, lock);
-    }
-    return lock;
+  /** The flow-control gate for `kind` — see {@link FlowControlledDataChannel}. */
+  private flowControlFor(kind: DataChannelKind): FlowControlledDataChannel {
+    return this.dataChannels.channelFor(kind);
   }
 
   /**
-   * Acquires the `kind` headroom lock, waits until the send buffer has room, then releases. The
-   * common single-send entry point. Callers that need to hold the lock across several sends (the
-   * resume replay) acquire it via {@link getBufferHeadroomLock} and call
-   * {@link waitForBufferHeadroomWithoutLock} per message instead.
+   * Resolves once the caller may send on the `kind` channel — see
+   * {@link FlowControlledDataChannel.waitForHeadroomWithLock}.
    */
-  async waitForBufferHeadroomWithLock(kind: DataChannelKind) {
-    const unlock = await this.getBufferHeadroomLock(kind).lock();
-    try {
-      await this.waitForBufferHeadroomWithoutLock(kind);
-    } finally {
-      unlock();
-    }
-  }
-
-  /**
-   * Waits until the send buffer for `kind` is at or below the high-water mark (draining, if
-   * needed, via the `bufferedamountlow` event). Does no locking of its own — the caller must
-   * already hold the kind's headroom lock (via {@link getBufferHeadroomLock}). The resume replay
-   * holds the lock across its whole batch and calls this per message so no other sender can
-   * interleave; the single-send path goes through {@link waitForBufferHeadroomWithLock}.
-   *
-   * Serializing through the per-kind lock means that, once the buffer drains, queued callers
-   * refill it one at a time (up to the high-water mark) rather than all at once and overflowing
-   * the SCTP send buffer (see livekit/client-sdk-js#1995).
-   */
-  private async waitForBufferHeadroomWithoutLock(
-    kind: DataChannelKind,
-  ): Promise<Throws<void, UnexpectedConnectionState | TypeError>> {
-    if (this.isClosed) {
-      throw new UnexpectedConnectionState('engine closed');
-    }
-    if (this.isBelowHighWaterMark(kind)) {
-      return;
-    }
-    const dc = this.dataChannelForKind(kind);
-    if (!dc) {
-      throw new UnexpectedConnectionState(`DataChannel not found, kind: ${kind}`);
-    }
-    const abortSignal = this.waiterAbortSignal(kind);
-    await new TypedPromise<void, UnexpectedConnectionState>((resolve, reject) => {
-      const onBufferedAmountLow = () => {
-        cleanup();
-        resolve();
-      };
-      const onDCClose = () => {
-        cleanup();
-        reject(
-          new UnexpectedConnectionState(`DataChannel ${kind} closed while draining the buffer`),
-        );
-      };
-      const onAbort = () => {
-        cleanup();
-        reject(
-          new UnexpectedConnectionState(
-            `DataChannel ${kind} was replaced or torn down while waiting for headroom`,
-          ),
-        );
-      };
-      const cleanup = () => {
-        dc.removeEventListener('bufferedamountlow', onBufferedAmountLow);
-        dc.removeEventListener('close', onDCClose);
-        abortSignal.removeEventListener('abort', onAbort);
-      };
-      if (abortSignal.aborted) {
-        onAbort();
-        return;
-      }
-      dc.addEventListener('bufferedamountlow', onBufferedAmountLow);
-      // Proxy along any error caused by the data channel closing while we wait.
-      dc.addEventListener('close', onDCClose);
-      // The channel object we're parked on can be abandoned without ever firing another event
-      // (e.g. createDataChannels replacing it); the abort is our way out.
-      abortSignal.addEventListener('abort', onAbort);
-    });
+  async waitForBufferHeadroom(kind: DataChannelKind) {
+    return this.flowControlFor(kind).waitForHeadroomWithLock();
   }
 
   /**
@@ -2012,11 +1717,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;
     }
 
@@ -2024,6 +1730,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;
   }
 
@@ -2040,9 +1760,7 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
       // don't negotiate without any transceivers or data channel, it will generate sdp without ice frag then negotiate failed
       if (
         this.pcManager.publisher.getTransceivers().length == 0 &&
-        !this.lossyDC &&
-        !this.reliableDC &&
-        !this.dataTrackDC
+        !this.dataChannels.hasPublisherChannels
       ) {
         this.createDataChannels();
       }
@@ -2091,26 +1809,7 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
   }
 
   dataChannelForKind(kind: DataChannelKind, sub?: boolean): RTCDataChannel | undefined {
-    switch (kind) {
-      case DataChannelKind.RELIABLE:
-        if (!sub) {
-          return this.reliableDC;
-        } else {
-          return this.reliableDCSub;
-        }
-      case DataChannelKind.LOSSY:
-        if (!sub) {
-          return this.lossyDC;
-        } else {
-          return this.lossyDCSub;
-        }
-      case DataChannelKind.DATA_TRACK_LOSSY:
-        if (!sub) {
-          return this.dataTrackDC;
-        } else {
-          return this.dataTrackDCSub;
-        }
-    }
+    return this.dataChannels.getHandle(kind, sub);
   }
 
   /** @internal */