livekit-client 2.18.6 → 2.18.8

package/src/room/data-track/outgoing/OutgoingDataTrackManager.test.ts

@@ -586,7 +586,7 @@ describe('DataTrackOutgoingManager', () => {
     ]);
 
     // Shut down the manager
-    const shutdownPromise = manager.shutdown();
+    const shutdownPromise = manager.reset();
 
     // The pending data track should be cancelled
     await expect(pendingDescriptor.completionFuture.promise).rejects.toThrowError(
@@ -602,4 +602,238 @@ describe('DataTrackOutgoingManager', () => {
 
     await shutdownPromise;
   });
+
+  it('should resolve flush() after a single tryPush once the packet is acknowledged', async () => {
+    const pubHandle = 5;
+    const manager = OutgoingDataTrackManager.withDescriptors(
+      new Map([
+        [
+          DataTrackHandle.fromNumber(pubHandle),
+          Descriptor.active(
+            {
+              sid: 'bogus-sid',
+              pubHandle,
+              name: 'test',
+              usesE2ee: false,
+            },
+            null,
+          ),
+        ],
+      ]),
+    );
+    const managerEvents = subscribeToEvents<DataTrackOutgoingManagerCallbacks>(manager, [
+      'packetAvailable',
+      'packetsFlushed',
+    ]);
+    const localDataTrack = LocalDataTrack.withExplicitHandle(
+      { name: 'track name' },
+      manager,
+      pubHandle,
+    );
+
+    // 1. Push a single-packet payload
+    await localDataTrack.tryPush({ payload: new Uint8Array([0x01, 0x02, 0x03, 0x04, 0x05]) });
+
+    // 2. The packet should have been emitted to be sent over the data channel
+    const packetEvent = await managerEvents.waitFor('packetAvailable');
+    expect(packetEvent.handle).toStrictEqual(pubHandle);
+
+    // 3. Calling flush() right after tryPush() should not resolve until the packet
+    // is acknowledged via handlePacketSendComplete
+    let flushed = false;
+    const flushPromise = localDataTrack.flush().then(() => {
+      flushed = true;
+    });
+
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    expect(flushed).toStrictEqual(false);
+    expect(managerEvents.areThereBufferedEvents('packetsFlushed')).toBe(false);
+
+    // 4. Acknowledge that the packet has been sent over the data channel
+    manager.handlePacketSendComplete(DataTrackHandle.fromNumber(pubHandle));
+
+    // 5. The packetsFlushed event fires once the in-flight packet counter reaches 0
+    const flushedEvent = await managerEvents.waitFor('packetsFlushed');
+    expect(flushedEvent.handle).toStrictEqual(pubHandle);
+
+    // 6. The flush() promise resolves
+    await flushPromise;
+    expect(flushed).toStrictEqual(true);
+  });
+
+  it('should resolve flush() only after all packets in a multi-packet payload are acknowledged', async () => {
+    const pubHandle = 5;
+    const manager = OutgoingDataTrackManager.withDescriptors(
+      new Map([
+        [
+          DataTrackHandle.fromNumber(pubHandle),
+          Descriptor.active(
+            {
+              sid: 'bogus-sid',
+              pubHandle,
+              name: 'test',
+              usesE2ee: false,
+            },
+            null,
+          ),
+        ],
+      ]),
+    );
+    const managerEvents = subscribeToEvents<DataTrackOutgoingManagerCallbacks>(manager, [
+      'packetAvailable',
+      'packetsFlushed',
+    ]);
+    const localDataTrack = LocalDataTrack.withExplicitHandle(
+      { name: 'track name' },
+      manager,
+      pubHandle,
+    );
+
+    // 1. Push a payload large enough to span multiple packets (24k > single packet mtu)
+    await localDataTrack.tryPush({ payload: new Uint8Array(24_000).fill(0xbe) });
+
+    // 2. Two packetAvailable events should be emitted for this payload
+    await managerEvents.waitFor('packetAvailable');
+    await managerEvents.waitFor('packetAvailable');
+
+    // 3. Call flush() before any of the packets have been acknowledged
+    let flushed = false;
+    const flushPromise = localDataTrack.flush().then(() => {
+      flushed = true;
+    });
+
+    // 4. Acknowledge the first packet -- flush should not resolve yet, in-flight counter still > 0
+    manager.handlePacketSendComplete(DataTrackHandle.fromNumber(pubHandle));
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    expect(flushed).toStrictEqual(false);
+    expect(managerEvents.areThereBufferedEvents('packetsFlushed')).toBe(false);
+
+    // 5. Acknowledge the second packet -- flush resolves once the counter reaches 0
+    manager.handlePacketSendComplete(DataTrackHandle.fromNumber(pubHandle));
+
+    const flushedEvent = await managerEvents.waitFor('packetsFlushed');
+    expect(flushedEvent.handle).toStrictEqual(pubHandle);
+
+    await flushPromise;
+    expect(flushed).toStrictEqual(true);
+  });
+
+  it('should resolve any pending flush() calls when the manager is reset', async () => {
+    const pubHandle = 5;
+    const manager = OutgoingDataTrackManager.withDescriptors(
+      new Map([
+        [
+          DataTrackHandle.fromNumber(pubHandle),
+          Descriptor.active(
+            {
+              sid: 'bogus-sid',
+              pubHandle,
+              name: 'test',
+              usesE2ee: false,
+            },
+            null,
+          ),
+        ],
+      ]),
+    );
+    const managerEvents = subscribeToEvents<DataTrackOutgoingManagerCallbacks>(manager, [
+      'packetAvailable',
+      'packetsFlushed',
+      'reset',
+    ]);
+    const localDataTrack = LocalDataTrack.withExplicitHandle(
+      { name: 'track name' },
+      manager,
+      pubHandle,
+    );
+
+    // 1. Push a single-packet payload
+    await localDataTrack.tryPush({ payload: new Uint8Array([0x01, 0x02, 0x03, 0x04, 0x05]) });
+    await managerEvents.waitFor('packetAvailable');
+
+    // 2. Call flush() before the in-flight packet is acknowledged -- it should remain
+    // pending because the in-flight counter is still > 0
+    let flushed = false;
+    const flushPromise = localDataTrack.flush().then(() => {
+      flushed = true;
+    });
+
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    expect(flushed).toStrictEqual(false);
+    expect(managerEvents.areThereBufferedEvents('packetsFlushed')).toBe(false);
+
+    // 3. Reset the manager. This simulates a RTCEngine disconnect and should resolve
+    // the pending flush() even though the packet was never acknowledged.
+    await manager.reset();
+    await managerEvents.waitFor('reset');
+
+    // 4. The flush() promise resolves
+    await flushPromise;
+    expect(flushed).toStrictEqual(true);
+
+    // 5. No packetsFlushed event was emitted -- reset short-circuits the flush directly
+    // on the LocalDataTrack rather than going through the in-flight counter.
+    expect(managerEvents.areThereBufferedEvents('packetsFlushed')).toBe(false);
+  });
+
+  it('should resolve flush() at the end of a batch of tryPush calls once all packets are acknowledged', async () => {
+    const pubHandle = 5;
+    const manager = OutgoingDataTrackManager.withDescriptors(
+      new Map([
+        [
+          DataTrackHandle.fromNumber(pubHandle),
+          Descriptor.active(
+            {
+              sid: 'bogus-sid',
+              pubHandle,
+              name: 'test',
+              usesE2ee: false,
+            },
+            null,
+          ),
+        ],
+      ]),
+    );
+    const managerEvents = subscribeToEvents<DataTrackOutgoingManagerCallbacks>(manager, [
+      'packetAvailable',
+      'packetsFlushed',
+    ]);
+    const localDataTrack = LocalDataTrack.withExplicitHandle(
+      { name: 'track name' },
+      manager,
+      pubHandle,
+    );
+
+    // 1. Run a batch of tryPush calls
+    await localDataTrack.tryPush({ payload: new Uint8Array([0x01]) });
+    await localDataTrack.tryPush({ payload: new Uint8Array([0x02]) });
+    await localDataTrack.tryPush({ payload: new Uint8Array([0x03]) });
+
+    // 2. Three packetAvailable events should be emitted, one per pushed frame
+    await managerEvents.waitFor('packetAvailable');
+    await managerEvents.waitFor('packetAvailable');
+    await managerEvents.waitFor('packetAvailable');
+
+    // 3. After the batch is enqueued, call flush() to wait for the SFU to drain them
+    let flushed = false;
+    const flushPromise = localDataTrack.flush().then(() => {
+      flushed = true;
+    });
+
+    // 4. Acknowledge two of the three packets -- flush should not resolve yet
+    manager.handlePacketSendComplete(DataTrackHandle.fromNumber(pubHandle));
+    manager.handlePacketSendComplete(DataTrackHandle.fromNumber(pubHandle));
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    expect(flushed).toStrictEqual(false);
+    expect(managerEvents.areThereBufferedEvents('packetsFlushed')).toBe(false);
+
+    // 5. Acknowledge the last packet -- flush resolves once the counter reaches 0
+    manager.handlePacketSendComplete(DataTrackHandle.fromNumber(pubHandle));
+
+    const flushedEvent = await managerEvents.waitFor('packetsFlushed');
+    expect(flushedEvent.handle).toStrictEqual(pubHandle);
+
+    await flushPromise;
+    expect(flushed).toStrictEqual(true);
+  });
 });

package/src/room/data-track/outgoing/OutgoingDataTrackManager.ts

@@ -18,6 +18,7 @@ import DataTrackOutgoingPipeline from './pipeline';
 import {
   type DataTrackOptions,
   type EventPacketAvailable,
+  type EventPacketsFlushed,
   type EventSfuPublishRequest,
   type EventSfuUnpublishRequest,
   type EventTrackPublished,
@@ -74,6 +75,11 @@ export type DataTrackOutgoingManagerCallbacks = {
   trackPublished: (event: EventTrackPublished) => void;
   /** A {@link LocalDataTrack} has been unpublished */
   trackUnpublished: (event: EventTrackUnpublished) => void;
+  /** A {@link LocalDataTrack} has had all of its in flight packets sent via the rtc data channel. */
+  packetsFlushed: (event: EventPacketsFlushed) => void;
+  /** The manager has been reset and all state has been cleared in preparation for the next room
+   * connection. */
+  reset: () => void;
 };
 
 type OutgoingDataTrackManagerOptions = {
@@ -95,6 +101,11 @@ export default class OutgoingDataTrackManager extends (EventEmitter as new () =>
 
   private descriptors = new Map<DataTrackHandle, Descriptor>();
 
+  /** Number of packets for each data track which have been emitted via the `packetAvailable` event
+   * and which have not yet been sent via the rtc data channel yet. Once this goes to 0, then
+   * all in flight packets have been delivered, and the data tracks is "flushed". */
+  private inFlightPacketCounter = new Map<DataTrackHandle, number>();
+
   constructor(options?: OutgoingDataTrackManagerOptions) {
     super();
     this.e2eeManager = options?.e2eeManager ?? null;
@@ -154,7 +165,9 @@ export default class OutgoingDataTrackManager extends (EventEmitter as new () =>
 
     try {
       for await (const packet of descriptor.pipeline.processFrame(frame)) {
-        this.emit('packetAvailable', { bytes: packet.toBinary() });
+        const prev = this.inFlightPacketCounter.get(handle) ?? 0;
+        this.inFlightPacketCounter.set(handle, prev + 1);
+        this.emit('packetAvailable', { handle, bytes: packet.toBinary() });
       }
     } catch (err) {
       // NOTE: In the rust implementation this "dropped" error means something different (not enough room
@@ -163,6 +176,27 @@ export default class OutgoingDataTrackManager extends (EventEmitter as new () =>
     }
   }
 
+  /** The client has sent a packet over the rtc data channel. This signal is used for determining
+   * once all packets are sent and a data track has been "flushed".
+   *
+   * @internal */
+  handlePacketSendComplete(handle: DataTrackHandle) {
+    const prev = this.inFlightPacketCounter.get(handle) ?? 0;
+    let counter = prev - 1;
+
+    if (counter < 0) {
+      log.warn(
+        `OutgoingDataTrackManager.handlePacketSendComplete: inFlightPacketCounter was decremented below 0 (got ${this.inFlightPacketCounter} - resetting to 0. Were more packets send than were emitted?`,
+      );
+      counter = 0;
+    }
+    this.inFlightPacketCounter.set(handle, counter);
+
+    if (counter === 0) {
+      this.emit('packetsFlushed', { handle });
+    }
+  }
+
   /**
    * Client requested to publish a track.
    *
@@ -266,6 +300,7 @@ export default class OutgoingDataTrackManager extends (EventEmitter as new () =>
 
     await descriptor.unpublishingFuture.promise;
 
+    this.inFlightPacketCounter.delete(handle);
     this.emit('trackUnpublished', { sid: descriptor.info.sid });
   }
 
@@ -360,10 +395,13 @@ export default class OutgoingDataTrackManager extends (EventEmitter as new () =>
   }
 
   /**
-   * Shuts down the manager and all associated tracks.
+   * Reset's the state of the manager and all associated tracks. Run on room disconnect to get
+   * the manager ready for the next room connection.
    * @internal
    **/
-  async shutdown() {
+  async reset() {
+    this.handleAllocator.reset();
+
     for (const descriptor of this.descriptors.values()) {
       switch (descriptor.type) {
         case 'pending':
@@ -379,5 +417,9 @@ export default class OutgoingDataTrackManager extends (EventEmitter as new () =>
       }
     }
     this.descriptors.clear();
+
+    this.inFlightPacketCounter.clear();
+
+    this.emit('reset');
   }
 }

package/src/room/data-track/outgoing/types.ts

@@ -34,6 +34,8 @@ export type EventSfuUnpublishRequest = {
 
 /** A serialized packet is ready to be sent over the transport. */
 export type EventPacketAvailable = {
+  /** The handle associated with the data track which this packet bytes belong to. */
+  handle: DataTrackHandle;
   bytes: Uint8Array;
 };
 
@@ -43,3 +45,6 @@ export type EventTrackPublished = { track: LocalDataTrack };
 
 /** A track has been unpublished by a remote participant and can no longer be subscribed to. */
 export type EventTrackUnpublished = { sid: DataTrackSid };
+
+/** A track has had all of its in flight packets sent via the rtc data channel. */
+export type EventPacketsFlushed = { handle: DataTrackHandle };