livekit-client 2.22.3 → 2.23.0

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

@@ -24,13 +24,24 @@ export interface DataChannelManagerOptions {
   onBufferStatusChanged: (kind: DataChannelKind, isLow: boolean) => void;
 }
 
+/** Unhooks every handler the manager may have wired onto `dc`, ahead of closing it. */
+function clearHandlers(dc: RTCDataChannel) {
+  dc.onbufferedamountlow = null;
+  dc.onclose = null;
+  dc.onclosing = null;
+  dc.onerror = null;
+  dc.onmessage = null;
+  dc.onopen = null;
+}
+
 /**
  * Owns the engine's data channels: the three flow-controlled publisher channel wrappers (which
  * live for the engine's lifetime and have RTCDataChannel handles attached/detached as peer
  * connections come and go) plus the subscriber-side receive handles adopted by label.
  *
- * Handle turnover goes through {@link FlowControlledDataChannel.attach}/`detach`, which reject
- * parked headroom waiters as a built-in — there is no separate invalidation step to forget.
+ * Handle turnover goes through {@link FlowControlledDataChannel.attach}/`detach`, which close the
+ * released handle and reject parked headroom waiters as a built-in — there is no separate
+ * invalidation step to forget.
  */
 export class DataChannelManager {
   readonly reliable: ReliableDataChannel;
@@ -110,17 +121,16 @@ export class DataChannelManager {
 
   /**
    * Creates the three publisher data channels on the given transport, wires their handlers, and
-   * attaches them to the wrappers — attaching rejects any waiters still parked on replaced
-   * channel objects.
+   * attaches them to the wrappers — attaching closes any replaced channel objects and rejects the
+   * waiters still parked on them.
    */
   createPublisherChannels(pcManager: PCTransportManager) {
-    // clear old data channel callbacks if recreate
+    // Recreating (the Safari null-id path): attaching the new handles below closes the old ones,
+    // so unhook them first — the old channel's close must not report an unexpected close.
     for (const channel of [this.lossy, this.reliable, this.dataTrack]) {
       const old = channel.channelHandle;
       if (old) {
-        old.onmessage = null;
-        old.onerror = null;
-        old.onclose = null;
+        clearHandlers(old);
       }
     }
 
@@ -192,41 +202,36 @@ export class DataChannelManager {
   }
 
   /**
-   * Tears down all channels for a peer-connection cleanup: rejects parked waiters (detach — the
-   * spec allows `pc.close()` to transition channels to 'closed' without firing events, so waiting
-   * for browser close events is not an option), strips handlers, closes the handles, and resets
-   * the reliable session state.
+   * Tears down all channels for a peer-connection cleanup: strips handlers, closes the handles,
+   * and resets the reliable session state. Detaching the publisher handles closes them and
+   * rejects parked waiters (the spec allows `pc.close()` to transition channels to 'closed'
+   * without firing events, so waiting for browser close events is not an option).
    */
   teardown() {
-    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();
-    };
-
-    for (const channel of [this.lossy, this.reliable, this.dataTrack]) {
+    // 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.
+    const publisherDataChannels = [this.lossy, this.reliable, this.dataTrack];
+    const subscriberDataChannels = [this.lossySub, this.reliableSub, this.dataTrackSub];
+
+    // Publisher handles are closed by detach, which also rejects parked waiters.
+    for (const channel of publisherDataChannels) {
       const dc = channel.channelHandle;
+      if (dc) {
+        clearHandlers(dc);
+      }
       channel.detach('peer connections cleaned up');
-      dcCleanup(dc);
     }
-    dcCleanup(this.lossySub);
-    dcCleanup(this.reliableSub);
-    dcCleanup(this.dataTrackSub);
+    // Subscriber handles have no wrapper, so close them directly.
+    for (const dc of subscriberDataChannels) {
+      if (dc) {
+        clearHandlers(dc);
+        dc.close();
+      }
+    }
     this.lossySub = undefined;
     this.reliableSub = undefined;
     this.dataTrackSub = undefined;

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

@@ -7,8 +7,17 @@ class FakeDataChannel extends EventTarget {
   bufferedAmount = 0;
 
   bufferedAmountLowThreshold = 64;
+
+  readyState: RTCDataChannelState = 'open';
+
+  // Like the real thing, close() moves to 'closing' synchronously.
+  close = vi.fn(() => {
+    this.readyState = 'closing';
+  });
 }
 
+const handle = (dc: FakeDataChannel) => dc as unknown as RTCDataChannel;
+
 const tick = () => new Promise<void>((resolve) => setTimeout(resolve, 0));
 
 // Pass `dc: null` for a handle-less channel; omit it to get a fresh one. `null` (not `undefined`)
@@ -62,37 +71,54 @@ describe('FlowControlledDataChannel', () => {
 
   it('reports watermark status against the given channel', () => {
     const { channel, dc } = makeChannel();
-    const handle = dc as unknown as RTCDataChannel;
     dc.bufferedAmount = 0;
-    expect(channel.isBelowHighWaterMark(handle)).toBe(true);
-    expect(channel.isBelowLowWaterMark(handle)).toBe(true);
+    expect(channel.isBelowHighWaterMark(handle(dc))).toBe(true);
+    expect(channel.isBelowLowWaterMark(handle(dc))).toBe(true);
 
     dc.bufferedAmount = 512; // between low (64) and high (1024)
-    expect(channel.isBelowHighWaterMark(handle)).toBe(true);
-    expect(channel.isBelowLowWaterMark(handle)).toBe(false);
+    expect(channel.isBelowHighWaterMark(handle(dc))).toBe(true);
+    expect(channel.isBelowLowWaterMark(handle(dc))).toBe(false);
 
     dc.bufferedAmount = 2048;
-    expect(channel.isBelowHighWaterMark(handle)).toBe(false);
+    expect(channel.isBelowHighWaterMark(handle(dc))).toBe(false);
   });
 
-  it('waiting for headroom without a handle rejects with a connection error', async () => {
-    const { channel } = makeChannel({ dc: null });
-    await expect(channel.waitForHeadroomWithLock()).rejects.toBeInstanceOf(
+  it('rejects a wait on a handle that is not open', async () => {
+    const { channel, dc } = makeChannel();
+    dc.readyState = 'connecting';
+    await expect(channel.waitForHeadroomWithLock(handle(dc))).rejects.toBeInstanceOf(
       UnexpectedConnectionState,
     );
   });
 
+  it('rejects a wait queued on the lock once its handle is replaced', async () => {
+    const { channel, dc: oldDc } = makeChannel();
+    oldDc.bufferedAmount = 2048;
+    const parked = channel.waitForHeadroomWithLock(handle(oldDc));
+    parked.catch(() => {});
+    // Queued behind the parked waiter, so the abort on replacement doesn't reach it — the closed
+    // handle does, once it gets the lock.
+    const queued = channel.waitForHeadroomWithLock(handle(oldDc));
+    queued.catch(() => {});
+    await tick();
+
+    channel.attach(handle(new FakeDataChannel()));
+
+    await expect(parked).rejects.toBeInstanceOf(UnexpectedConnectionState);
+    await expect(queued).rejects.toBeInstanceOf(UnexpectedConnectionState);
+  });
+
   it('resolves immediately while below the high-water mark', async () => {
     const { channel, dc } = makeChannel();
     dc.bufferedAmount = 1024;
-    await expect(channel.waitForHeadroomWithLock()).resolves.toBeUndefined();
+    await expect(channel.waitForHeadroomWithLock(handle(dc))).resolves.toBeUndefined();
   });
 
   it('parks above the high-water mark and resumes on bufferedamountlow', async () => {
     const { channel, dc } = makeChannel();
     dc.bufferedAmount = 2048;
     const resolved = vi.fn();
-    const wait = channel.waitForHeadroomWithLock().then(resolved);
+    const wait = channel.waitForHeadroomWithLock(handle(dc)).then(resolved);
     await tick();
     expect(resolved).not.toHaveBeenCalled();
 
@@ -105,7 +131,7 @@ describe('FlowControlledDataChannel', () => {
   it('rejects a parked waiter when the channel closes', async () => {
     const { channel, dc } = makeChannel();
     dc.bufferedAmount = 2048;
-    const wait = channel.waitForHeadroomWithLock();
+    const wait = channel.waitForHeadroomWithLock(handle(dc));
     wait.catch(() => {});
     await tick();
 
@@ -116,7 +142,7 @@ describe('FlowControlledDataChannel', () => {
   it('rejects a parked waiter on invalidateWaiters and recovers with a fresh controller', async () => {
     const { channel, dc } = makeChannel();
     dc.bufferedAmount = 2048;
-    const wait = channel.waitForHeadroomWithLock();
+    const wait = channel.waitForHeadroomWithLock(handle(dc));
     wait.catch(() => {});
     await tick();
 
@@ -125,13 +151,29 @@ describe('FlowControlledDataChannel', () => {
 
     // Fresh controller: the gate is usable again and the lock was released.
     dc.bufferedAmount = 0;
-    await expect(channel.waitForHeadroomWithLock()).resolves.toBeUndefined();
+    await expect(channel.waitForHeadroomWithLock(handle(dc))).resolves.toBeUndefined();
+  });
+
+  it('closes the handle it lets go of, on replacement and on detach', () => {
+    const { channel, dc: first } = makeChannel();
+    const second = new FakeDataChannel();
+
+    channel.attach(first as unknown as RTCDataChannel); // re-attaching the same handle is a no-op
+    expect(first.close).not.toHaveBeenCalled();
+
+    channel.attach(second as unknown as RTCDataChannel);
+    expect(first.close).toHaveBeenCalledTimes(1);
+    expect(second.close).not.toHaveBeenCalled();
+
+    channel.detach();
+    expect(second.close).toHaveBeenCalledTimes(1);
+    expect(channel.channelHandle).toBeUndefined();
   });
 
   it('rejects immediately when the engine is closed', async () => {
-    const { channel, state } = makeChannel();
+    const { channel, dc, state } = makeChannel();
     state.engineClosed = true;
-    await expect(channel.waitForHeadroomWithLock()).rejects.toBeInstanceOf(
+    await expect(channel.waitForHeadroomWithLock(handle(dc))).rejects.toBeInstanceOf(
       UnexpectedConnectionState,
     );
   });
@@ -140,8 +182,8 @@ describe('FlowControlledDataChannel', () => {
     const { channel, dc } = makeChannel();
     dc.bufferedAmount = 2048;
     const order: number[] = [];
-    const first = channel.waitForHeadroomWithLock().then(() => order.push(1));
-    const second = channel.waitForHeadroomWithLock().then(() => order.push(2));
+    const first = channel.waitForHeadroomWithLock(handle(dc)).then(() => order.push(1));
+    const second = channel.waitForHeadroomWithLock(handle(dc)).then(() => order.push(2));
     await tick();
 
     // One drain event wakes the head waiter; the second re-checks under the lock and, with the

package/src/room/data-channel/FlowControlledDataChannel.ts

@@ -30,7 +30,8 @@ export interface FlowControlledDataChannelOptions {
  * Waiters are parked on the channel object captured at wait entry. If that object stops being
  * current — replaced or torn down — its events may never fire again, so the owner must call
  * {@link invalidateWaiters}, which aborts parked waiters (releasing the gate); the next waiter
- * gets a fresh controller.
+ * gets a fresh controller. {@link attach} and {@link detach} do this, and close the released
+ * handle, as part of handle turnover.
  */
 export class FlowControlledDataChannel {
   readonly kind: DataChannelKind;
@@ -67,25 +68,39 @@ export class FlowControlledDataChannel {
   }
 
   /**
-   * Attaches the channel handle this wrapper controls. Replacing an existing handle rejects
-   * parked waiters — their events would never fire again on the abandoned object — and installs a
-   * fresh controller, so queued senders re-check against the new channel. Wrappers outlive their
-   * handles: this is the one place handle turnover happens, which is what makes stranding a
-   * waiter structurally impossible.
+   * Attaches the channel handle this wrapper controls. Replacing an existing handle closes it and
+   * rejects parked waiters — their events would never fire again on the abandoned object — and
+   * installs a fresh controller. Wrappers outlive their handles: this is the one place handle
+   * turnover happens, so a handle the wrapper lets go of is never left open, and stranding a
+   * waiter is structurally impossible.
    */
   attach(dc: RTCDataChannel) {
-    if (this.handle && this.handle !== dc) {
-      this.invalidateWaiters('data channel replaced');
-    }
+    const old = this.handle;
     this.handle = dc;
+    if (old && old !== dc) {
+      this.release(old, 'data channel replaced');
+    }
   }
 
-  /** Detaches the handle on teardown, rejecting parked waiters. */
+  /** Detaches and closes the handle on teardown, rejecting parked waiters. */
   detach(reason: string = 'data channel torn down') {
-    if (this.handle) {
-      this.invalidateWaiters(reason);
-    }
+    const old = this.handle;
     this.handle = undefined;
+    if (old) {
+      this.release(old, reason);
+    }
+  }
+
+  /**
+   * Closes a handle the wrapper no longer controls. `close()` moves it to `closing` synchronously,
+   * so senders still holding it (queued on the headroom lock) fail the open check once they get
+   * the lock. Parked waiters are aborted directly instead of relying on the `close` event, which
+   * fires asynchronously, if at all (the spec lets `pc.close()` skip it). Strip any handlers that
+   * must not observe the close before calling this.
+   */
+  private release(dc: RTCDataChannel, reason: string) {
+    this.invalidateWaiters(reason);
+    dc.close();
   }
 
   protected getChannel(): RTCDataChannel | undefined {
@@ -121,30 +136,33 @@ export class FlowControlledDataChannel {
   }
 
   /**
-   * Resolves once the caller may send on this channel: immediately while the send buffer is at or
-   * below its high-water mark, otherwise once the buffer has drained to the low-water mark (the
+   * Resolves once the caller may send on `dc`: immediately while its send buffer is at or below
+   * the high-water mark, otherwise once the buffer has drained to the low-water mark (the
    * `bufferedamountlow` event). Callers are serialized through the headroom lock so that, when
    * the buffer drains, they refill it one at a time (up to the high-water mark) rather than all
    * sending at once and overflowing the SCTP send buffer (see livekit/client-sdk-js#1995). The
-   * closed/buffer checks run inside the lock so queued callers proceed in FIFO order.
+   * checks run inside the lock so queued callers proceed in FIFO order.
+   *
+   * The caller passes the handle it resolved before queueing, and the wait is against that one
+   * handle throughout: if it was replaced meanwhile, it has been closed, so the wait rejects
+   * rather than letting the caller send on the replacement out of turn.
    */
-  async waitForHeadroomWithLock() {
+  async waitForHeadroomWithLock(dc: RTCDataChannel) {
     const unlock = await this.lockHeadroom();
     try {
-      await this.waitForHeadroomWithoutLock();
+      await this.waitForHeadroomWithoutLock(dc);
     } finally {
       unlock();
     }
   }
 
   /** Core wait of {@link waitForHeadroomWithLock}. The caller must hold the headroom lock. */
-  async waitForHeadroomWithoutLock() {
+  async waitForHeadroomWithoutLock(dc: RTCDataChannel) {
     if (this.isEngineClosed()) {
       throw new UnexpectedConnectionState('engine closed');
     }
-    const dc = this.getChannel();
-    if (!dc) {
-      throw new UnexpectedConnectionState(`DataChannel not found, kind: ${this.kind}`);
+    if (dc.readyState !== 'open') {
+      throw new UnexpectedConnectionState(`DataChannel ${this.kind} is ${dc.readyState}`);
     }
     if (this.isBelowHighWaterMark(dc)) {
       return;

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

@@ -8,6 +8,13 @@ class FakeDataChannel extends EventTarget {
   bufferedAmountLowThreshold = 64;
 
   send = vi.fn();
+
+  readyState: RTCDataChannelState = 'open';
+
+  // Like the real thing, close() moves to 'closing' synchronously.
+  close = vi.fn(() => {
+    this.readyState = 'closing';
+  });
 }
 
 // Pass `dc: null` for a handle-less channel; omit it to get a fresh one. `null` (not `undefined`)
@@ -76,6 +83,37 @@ describe('LossyDataChannel', () => {
     expect(dc.send).toHaveBeenCalledTimes(1);
   });
 
+  it('wait policy: drops waiting sends when the channel is replaced', async () => {
+    const { channel, dc: oldDc } = makeChannel('wait');
+    oldDc.bufferedAmount = 2048;
+    const parked = channel.send(new Uint8Array([1]));
+    const queued = channel.send(new Uint8Array([2]));
+    await vi.advanceTimersByTimeAsync(0);
+
+    const newDc = new FakeDataChannel();
+    channel.attach(newDc as unknown as RTCDataChannel);
+
+    // Both resolve: a dropped frame mustn't reject (the room doesn't handle frame send failures).
+    await expect(parked).resolves.toBeUndefined();
+    await expect(queued).resolves.toBeUndefined();
+    // Not on the abandoned channel, and not on the replacement, which may still be connecting.
+    expect(oldDc.send).not.toHaveBeenCalled();
+    expect(newDc.send).not.toHaveBeenCalled();
+  });
+
+  it('wait policy: rejects a waiting send when the engine closes', async () => {
+    const { channel, dc, state } = makeChannel('wait');
+    dc.bufferedAmount = 2048;
+    const send = channel.send(new Uint8Array([1]));
+    send.catch(() => {});
+    await vi.advanceTimersByTimeAsync(0);
+
+    state.engineClosed = true;
+    channel.detach();
+
+    await expect(send).rejects.toThrow();
+  });
+
   it('skips sends while a reconnect is underway', async () => {
     const { channel, dc, state } = makeChannel('drop');
     state.skipSends = true;

package/src/room/data-channel/LossyDataChannel.ts

@@ -55,7 +55,16 @@ export class LossyDataChannel extends FlowControlledDataChannel {
     switch (this.bufferFullBehavior) {
       case 'wait':
         if (!this.isBelowHighWaterMark(dc)) {
-          await this.waitForHeadroomWithLock();
+          try {
+            await this.waitForHeadroomWithLock(dc);
+          } catch (error) {
+            if (this.isEngineClosed()) {
+              throw error;
+            }
+            // The channel closed or was replaced while this send waited. The replacement may
+            // still be connecting, so drop the packet, as sends during a reconnect are.
+            return;
+          }
         }
         break;
       case 'drop':

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

@@ -9,6 +9,13 @@ class FakeDataChannel extends EventTarget {
   bufferedAmountLowThreshold = 64;
 
   send = vi.fn();
+
+  readyState: RTCDataChannelState = 'open';
+
+  // Like the real thing, close() moves to 'closing' synchronously.
+  close = vi.fn(() => {
+    this.readyState = 'closing';
+  });
 }
 
 const tick = () => new Promise<void>((resolve) => setTimeout(resolve, 0));
@@ -77,6 +84,33 @@ describe('ReliableDataChannel', () => {
     expect(buffer.getAll()[0].sent).toBe(false);
   });
 
+  it('defers a send queued on the lock to the replay when the channel is replaced, preserving order', async () => {
+    const { channel, dc: oldDc, buffer } = makeChannel();
+    oldDc.bufferedAmount = 2048; // above high mark → the first send parks
+    const parked = channel.send(new Uint8Array([1]), channel.nextSequence());
+    // Queues behind the parked send on the headroom lock; replacing the handle rejects only the
+    // parked waiter, so this one gets the lock afterwards.
+    const queued = channel.send(new Uint8Array([2]), channel.nextSequence());
+    await tick();
+
+    const newDc = new FakeDataChannel();
+    channel.attach(newDc as unknown as RTCDataChannel);
+
+    await expect(parked).resolves.toBeUndefined();
+    await expect(queued).resolves.toBeUndefined();
+    // Neither goes out ahead of the replay: sending seq 2 now would make receivers discard seq 1
+    // once the replay delivers it.
+    expect(oldDc.send).not.toHaveBeenCalled();
+    expect(newDc.send).not.toHaveBeenCalled();
+    expect(buffer.getAll().map(({ sequence, sent }) => ({ sequence, sent }))).toEqual([
+      { sequence: 1, sent: false },
+      { sequence: 2, sent: false },
+    ]);
+
+    await channel.replay(0);
+    expect(newDc.send.mock.calls.map(([data]) => data[0])).toEqual([1, 2]);
+  });
+
   it('rejects when the engine is closed while waiting', async () => {
     const { channel, dc, state } = makeChannel();
     dc.bufferedAmount = 2048;
@@ -135,6 +169,44 @@ describe('ReliableDataChannel', () => {
     expect(buffer.getAll().filter((i) => !i.sent)).toHaveLength(0);
   });
 
+  it('replays on the replacement handle when the channel is replaced while replay waits for the lock', async () => {
+    const { channel, dc: oldDc } = makeChannel();
+    await channel.send(new Uint8Array([1]), channel.nextSequence());
+    oldDc.send.mockClear();
+
+    const unlock = await channel.lockHeadroom();
+    const replay = channel.replay(0);
+    await tick();
+
+    const newDc = new FakeDataChannel();
+    channel.attach(newDc as unknown as RTCDataChannel);
+    unlock();
+    await replay;
+
+    expect(oldDc.send).not.toHaveBeenCalled();
+    expect(newDc.send).toHaveBeenCalledTimes(1);
+  });
+
+  it('stops the replay, keeping the rest unsent, when the channel is replaced mid-replay', async () => {
+    const { channel, dc: oldDc, state, buffer } = makeChannel();
+    state.deferring = true;
+    await channel.send(new Uint8Array([1]), channel.nextSequence());
+    await channel.send(new Uint8Array([2]), channel.nextSequence());
+    state.deferring = false;
+
+    oldDc.bufferedAmount = 2048; // the replay parks before its first send
+    const replay = channel.replay(0);
+    replay.catch(() => {});
+    await tick();
+
+    // A second replacement belongs to another resume, whose replay delivers the backlog.
+    channel.attach(new FakeDataChannel() as unknown as RTCDataChannel);
+
+    await expect(replay).rejects.toBeInstanceOf(UnexpectedConnectionState);
+    expect(oldDc.send).not.toHaveBeenCalled();
+    expect(buffer.getAll().every((item) => !item.sent)).toBe(true);
+  });
+
   it('holds the headroom lock across the whole replay so new sends cannot interleave', async () => {
     const { channel, dc } = makeChannel();
     (channel as unknown as { isDeferringSends: () => boolean }).isDeferringSends = () => true;

package/src/room/data-channel/ReliableDataChannel.ts

@@ -1,5 +1,6 @@
 import type { NonSharedUint8Array } from '../../type-polyfills/non-shared-typed-arrays';
 import { DataPacketBuffer } from '../../utils/dataPacketBuffer';
+import { UnexpectedConnectionState } from '../errors';
 import {
   FlowControlledDataChannel,
   type FlowControlledDataChannelOptions,
@@ -64,7 +65,7 @@ export class ReliableDataChannel extends FlowControlledDataChannel {
     }
 
     try {
-      await this.waitForHeadroomWithLock();
+      await this.waitForHeadroomWithLock(dc);
     } catch (error) {
       if (this.isEngineClosed()) {
         // No replay is coming after an engine close — surface the failure.
@@ -72,7 +73,9 @@ export class ReliableDataChannel extends FlowControlledDataChannel {
       }
       // 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.
+      // rejecting a send the app can't meaningfully retry. This also keeps the order: a send
+      // queued behind one aborted by a replacement fails the same way (the old handle is closed),
+      // so it can't reach the replacement ahead of the lower sequence the replay will deliver.
       this.messageBuffer.push({ data: msg, sequence, sent: false });
       return;
     }
@@ -96,13 +99,18 @@ export class ReliableDataChannel extends FlowControlledDataChannel {
    * receivers would then discard the remaining lower-sequence resent messages as duplicates.
    */
   async replay(lastMessageSeq: number) {
-    const dc = this.getChannel();
-    if (!dc) {
+    if (!this.getChannel()) {
       return;
     }
     this.messageBuffer.popToSequence(lastMessageSeq);
     const unlock = await this.lockHeadroom();
     try {
+      // Resolved only once the lock is held: the handle can be replaced while the replay waits
+      // for it.
+      const dc = this.getChannel();
+      if (!dc) {
+        throw new UnexpectedConnectionState(`DataChannel not found, kind: ${this.kind}`);
+      }
       // Everything left after the ack cutoff must be re-handed to the current channel.
       this.messageBuffer.markAllUnsent();
       // Drain in passes, re-scanning the live buffer each time: a send that arrives (deferred,
@@ -118,7 +126,10 @@ export class ReliableDataChannel extends FlowControlledDataChannel {
       ) {
         for (const item of batch) {
           // Respect flow control on resume too, so a large resend doesn't overflow the buffer.
-          await this.waitForHeadroomWithoutLock();
+          // Against the handle resolved under the lock: if it is replaced mid-replay (another
+          // resume), it has been closed, so this throws and that resume's replay picks up the
+          // entries still flagged unsent.
+          await this.waitForHeadroomWithoutLock(dc);
           dc.send(item.data);
           this.messageBuffer.markSent(item);
         }