livekit-client 2.18.0 → 2.18.2

package/src/room/data-track/depacketizer.ts

@@ -1,7 +1,7 @@
 import { type Throws } from '@livekit/throws-transformer/throws';
 import { LoggerNames, getLogger } from '../../logger';
 import { LivekitReasonedError } from '../errors';
-import { type DataTrackFrame } from './frame';
+import { type DataTrackFrameInternal } from './frame';
 import { DataTrackPacket, FrameMarker } from './packet';
 import { DataTrackExtensions } from './packet/extensions';
 import { U16_MAX_SIZE, WrapAroundUnsignedInt } from './utils';
@@ -38,9 +38,9 @@ export class DataTrackDepacketizerDropError<
     this.frameNumber = frameNumber;
   }
 
-  static interrupted(frameNumber: number) {
+  static interrupted(frameNumber: number, newFrameNumber: number) {
     return new DataTrackDepacketizerDropError(
-      'Interrupted by the start of a new frame',
+      `Interrupted by the start of a new frame ${newFrameNumber}`,
       DataTrackDepacketizerDropReason.Interrupted,
       frameNumber,
     );
@@ -94,12 +94,12 @@ export default class DataTrackDepacketizer {
   /** Should be repeatedly called with received {@link DataTrackPacket}s - intermediate calls
    * aggregate the packet's state internally, and return null.
    *
-   * Once this method is called with the final packet to form a frame, a new {@link DataTrackFrame}
+   * Once this method is called with the final packet to form a frame, a new {@link DataTrackFrameInternal}
    * is returned.*/
   push(
     packet: DataTrackPacket,
     options?: PushOptions,
-  ): Throws<DataTrackFrame | null, DataTrackDepacketizerDropError> {
+  ): Throws<DataTrackFrameInternal | null, DataTrackDepacketizerDropError> {
     switch (packet.header.marker) {
       case FrameMarker.Single:
         return this.frameFromSingle(packet, options);
@@ -119,7 +119,7 @@ export default class DataTrackDepacketizer {
     packet: DataTrackPacket,
     options?: PushOptions,
   ): Throws<
-    DataTrackFrame | null,
+    DataTrackFrameInternal | null,
     DataTrackDepacketizerDropError<DataTrackDepacketizerDropReason.Interrupted>
   > {
     if (packet.header.marker !== FrameMarker.Single) {
@@ -133,7 +133,10 @@ export default class DataTrackDepacketizer {
       if (options?.errorOnPartialFrames) {
         const frameNumber = this.partial.frameNumber;
         this.reset();
-        throw DataTrackDepacketizerDropError.interrupted(frameNumber);
+        throw DataTrackDepacketizerDropError.interrupted(
+          frameNumber,
+          packet.header.frameNumber.value,
+        );
       } else {
         log.warn(
           `Data track frame ${this.partial.frameNumber} was interrupted by the start of a new frame, dropping.`,
@@ -161,10 +164,13 @@ export default class DataTrackDepacketizer {
       if (options?.errorOnPartialFrames) {
         const frameNumber = this.partial.frameNumber;
         this.reset();
-        throw DataTrackDepacketizerDropError.interrupted(frameNumber);
+        throw DataTrackDepacketizerDropError.interrupted(
+          frameNumber,
+          packet.header.frameNumber.value,
+        );
       } else {
         log.warn(
-          `Data track frame ${this.partial.frameNumber} was interrupted by the start of a new frame, dropping.`,
+          `Data track frame ${this.partial.frameNumber} was interrupted by the start of a new frame ${packet.header.frameNumber.value}, dropping.`,
         );
       }
     }
@@ -185,7 +191,7 @@ export default class DataTrackDepacketizer {
   /** Push to the existing partial frame. */
   private pushToPartial(
     packet: DataTrackPacket,
-  ): Throws<DataTrackFrame | null, DataTrackDepacketizerDropError> {
+  ): Throws<DataTrackFrameInternal | null, DataTrackDepacketizerDropError> {
     if (packet.header.marker !== FrameMarker.Inter && packet.header.marker !== FrameMarker.Final) {
       // @throws-transformer ignore - this should be treated as a "panic" and not be caught
       throw new Error(
@@ -201,7 +207,10 @@ export default class DataTrackDepacketizer {
     if (packet.header.frameNumber.value !== this.partial.frameNumber) {
       const frameNumber = this.partial.frameNumber;
       this.reset();
-      throw DataTrackDepacketizerDropError.interrupted(frameNumber);
+      throw DataTrackDepacketizerDropError.interrupted(
+        frameNumber,
+        packet.header.frameNumber.value,
+      );
     }
 
     // NOTE: this check will block reprocessing packets with duplicate sequence values if the
@@ -234,7 +243,7 @@ export default class DataTrackDepacketizer {
     partial: PartialFrame,
     endSequence: number,
   ): Throws<
-    DataTrackFrame,
+    DataTrackFrameInternal,
     DataTrackDepacketizerDropError<DataTrackDepacketizerDropReason.Incomplete>
   > {
     const received = partial.payloads.size;

package/src/room/data-track/frame.ts

@@ -1,8 +1,34 @@
-import { DataTrackExtensions } from './packet/extensions';
-import DataTrackPacketizer from './packetizer';
+import { DataTrackExtensions, DataTrackUserTimestampExtension } from './packet/extensions';
 
 /** A pair of payload bytes and packet extensions which can be fed into a {@link DataTrackPacketizer}. */
 export type DataTrackFrame = {
+  payload: Uint8Array;
+  userTimestamp?: bigint;
+};
+
+/** An internal representation o data track frame which contains all SFU metadata. */
+export type DataTrackFrameInternal = {
   payload: Uint8Array;
   extensions: DataTrackExtensions;
 };
+
+export const DataTrackFrameInternal = {
+  from(frame: DataTrackFrame) {
+    return {
+      payload: frame.payload,
+      extensions: new DataTrackExtensions({
+        userTimestamp: frame.userTimestamp
+          ? new DataTrackUserTimestampExtension(frame.userTimestamp)
+          : undefined,
+      }),
+    };
+  },
+  /** Converts from a DataTrackFrameInternal -> DataTrackFrame. Some internal information is
+   * discarded like e2ee encrption extension data. */
+  lossyIntoFrame(frame: DataTrackFrameInternal): DataTrackFrame {
+    return {
+      payload: frame.payload,
+      userTimestamp: frame.extensions.userTimestamp?.timestamp,
+    };
+  },
+};

package/src/room/data-track/incoming/IncomingDataTrackManager.test.ts

@@ -1,43 +1,25 @@
 /* eslint-disable @typescript-eslint/no-unused-vars */
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { subscribeToEvents } from '../../../utils/subscribeToEvents';
-import { DecryptionProvider, EncryptedPayload } from '../e2ee';
-import { DataTrackFrame } from '../frame';
+import { type DataTrackFrame } from '../frame';
 import { DataTrackHandle, DataTrackHandleAllocator } from '../handle';
+import { PrefixingEncryptionProvider } from '../outgoing/OutgoingDataTrackManager.test';
 import { DataTrackPacket, DataTrackPacketHeader, FrameMarker } from '../packet';
 import { DataTrackE2eeExtension, DataTrackExtensions } from '../packet/extensions';
 import { DataTrackTimestamp, WrapAroundUnsignedInt } from '../utils';
 import IncomingDataTrackManager, {
-  DataTrackIncomingManagerCallbacks,
+  type DataTrackIncomingManagerCallbacks,
 } from './IncomingDataTrackManager';
 import { DataTrackSubscribeError } from './errors';
 
-/** A fake "decryption" provider used for test purposes. Assumes the payload is prefixed with
- * 0xdeafbeef, which is stripped off. */
-const PrefixingDecryptionProvider: DecryptionProvider = {
-  decrypt(p: EncryptedPayload, _senderIdentity: string) {
-    if (
-      p.payload[0] !== 0xde ||
-      p.payload[1] !== 0xad ||
-      p.payload[2] !== 0xbe ||
-      p.payload[3] !== 0xef
-    ) {
-      throw new Error(
-        `PrefixingDecryptionProvider: first four bytes of payload were not 0xdeadbeef, found ${p.payload.slice(0, 4)}`,
-      );
-    }
-    return p.payload.slice(4);
-  },
-};
-
 describe('DataTrackIncomingManager', () => {
   describe('Track publication', () => {
     it('should test track publication additions / removals', async () => {
       const manager = new IncomingDataTrackManager();
       const managerEvents = subscribeToEvents<DataTrackIncomingManagerCallbacks>(manager, [
         'sfuUpdateSubscription',
-        'trackAvailable',
-        'trackUnavailable',
+        'trackPublished',
+        'trackUnpublished',
       ]);
 
       // 1. Add a track, make sure the track available event was sent
@@ -57,11 +39,11 @@ describe('DataTrackIncomingManager', () => {
         ]),
       );
 
-      const trackAvailableEvent = await managerEvents.waitFor('trackAvailable');
-      expect(trackAvailableEvent.track.info.sid).toStrictEqual('sid1');
-      expect(trackAvailableEvent.track.info.pubHandle).toStrictEqual(DataTrackHandle.fromNumber(5));
-      expect(trackAvailableEvent.track.info.name).toStrictEqual('test');
-      expect(trackAvailableEvent.track.info.usesE2ee).toStrictEqual(false);
+      const trackPublishedEvent = await managerEvents.waitFor('trackPublished');
+      expect(trackPublishedEvent.track.info.sid).toStrictEqual('sid1');
+      expect(trackPublishedEvent.track.info.pubHandle).toStrictEqual(DataTrackHandle.fromNumber(5));
+      expect(trackPublishedEvent.track.info.name).toStrictEqual('test');
+      expect(trackPublishedEvent.track.info.usesE2ee).toStrictEqual(false);
 
       // 2. Check to make sure the publication has been noted in internal state
       expect((await manager.queryPublications()).map((p) => p.pubHandle)).to.deep.equal([
@@ -72,9 +54,9 @@ describe('DataTrackIncomingManager', () => {
       await manager.receiveSfuPublicationUpdates(new Map([['identity1', []]]));
       expect(await manager.queryPublications()).to.deep.equal([]);
 
-      const trackUnavailableEvent = await managerEvents.waitFor('trackUnavailable');
-      expect(trackUnavailableEvent.sid).toStrictEqual('sid1');
-      expect(trackUnavailableEvent.publisherIdentity).toStrictEqual('identity1');
+      const trackUnpublishedEvent = await managerEvents.waitFor('trackUnpublished');
+      expect(trackUnpublishedEvent.sid).toStrictEqual('sid1');
+      expect(trackUnpublishedEvent.publisherIdentity).toStrictEqual('identity1');
     });
 
     it('should process sfu publication updates idempotently', async () => {
@@ -111,7 +93,7 @@ describe('DataTrackIncomingManager', () => {
       const manager = new IncomingDataTrackManager();
       const managerEvents = subscribeToEvents<DataTrackIncomingManagerCallbacks>(manager, [
         'sfuUpdateSubscription',
-        'trackAvailable',
+        'trackPublished',
       ]);
 
       const senderIdentity = 'identity';
@@ -122,10 +104,11 @@ describe('DataTrackIncomingManager', () => {
       await manager.receiveSfuPublicationUpdates(
         new Map([[senderIdentity, [{ sid, pubHandle: handle, name: 'test', usesE2ee: false }]]]),
       );
-      await managerEvents.waitFor('trackAvailable');
+      await managerEvents.waitFor('trackPublished');
 
-      // 2. Subscribe to a data track
-      const subscribeRequestPromise = manager.subscribeRequest(sid);
+      // 2. Create a subscription readable stream (SFU subscription starts lazily in the background)
+      const [stream, sfuSubscriptionComplete] = manager.openSubscriptionStream(sid);
+      const reader = stream.getReader();
 
       // 3. This subscribe request should be sent along to the SFU
       const sfuUpdateSubscriptionEvent = await managerEvents.waitFor('sfuUpdateSubscription');
@@ -136,9 +119,8 @@ describe('DataTrackIncomingManager', () => {
       // the subscription
       manager.receivedSfuSubscriberHandles(new Map([[handle, sid]]));
 
-      // 5. Make sure that the subscription promise resolves.
-      const readableStream = await subscribeRequestPromise;
-      const reader = readableStream.getReader();
+      // 5. Wait for the subscription to be fully established
+      await sfuSubscriptionComplete;
 
       // 6. Simulate receiving a packet
       manager.packetReceived(
@@ -163,11 +145,11 @@ describe('DataTrackIncomingManager', () => {
 
     it('should test data track subscribing with end to end encryption (ok case)', async () => {
       const manager = new IncomingDataTrackManager({
-        decryptionProvider: PrefixingDecryptionProvider,
+        e2eeManager: new PrefixingEncryptionProvider(),
       });
       const managerEvents = subscribeToEvents<DataTrackIncomingManagerCallbacks>(manager, [
         'sfuUpdateSubscription',
-        'trackAvailable',
+        'trackPublished',
       ]);
 
       const senderIdentity = 'identity';
@@ -178,10 +160,11 @@ describe('DataTrackIncomingManager', () => {
       await manager.receiveSfuPublicationUpdates(
         new Map([[senderIdentity, [{ sid, pubHandle: handle, name: 'test', usesE2ee: true }]]]),
       );
-      await managerEvents.waitFor('trackAvailable');
+      await managerEvents.waitFor('trackPublished');
 
-      // 2. Subscribe to a data track
-      const subscribeRequestPromise = manager.subscribeRequest(sid);
+      // 2. Create a subscription readable stream
+      const [stream, sfuSubscriptionComplete] = manager.openSubscriptionStream(sid);
+      const reader = stream.getReader();
 
       // 3. This subscribe request should be sent along to the SFU
       const sfuUpdateSubscriptionEvent = await managerEvents.waitFor('sfuUpdateSubscription');
@@ -192,9 +175,8 @@ describe('DataTrackIncomingManager', () => {
       // the subscription
       manager.receivedSfuSubscriberHandles(new Map([[handle, sid]]));
 
-      // 5. Make sure that the subscription promise resolves.
-      const readableStream = await subscribeRequestPromise;
-      const reader = readableStream.getReader();
+      // 5. Wait for the subscription to be fully established
+      await sfuSubscriptionComplete;
 
       // 6. Simulate receiving a (fake) encrypted packet
       manager.packetReceived(
@@ -228,7 +210,7 @@ describe('DataTrackIncomingManager', () => {
       const manager = new IncomingDataTrackManager();
       const managerEvents = subscribeToEvents<DataTrackIncomingManagerCallbacks>(manager, [
         'sfuUpdateSubscription',
-        'trackAvailable',
+        'trackPublished',
       ]);
 
       const senderIdentity = 'identity';
@@ -241,13 +223,14 @@ describe('DataTrackIncomingManager', () => {
       await manager.receiveSfuPublicationUpdates(
         new Map([[senderIdentity, [{ sid, pubHandle, name: 'test', usesE2ee: false }]]]),
       );
-      await managerEvents.waitFor('trackAvailable');
+      await managerEvents.waitFor('trackPublished');
 
       // 2. Set up lots of subscribers
       const readers: Array<ReadableStreamDefaultReader<DataTrackFrame>> = [];
       for (let index = 0; index < 8; index += 1) {
-        // Subscribe to a data track
-        const subscribeRequestPromise = manager.subscribeRequest(sid);
+        // Create a subscription readable stream
+        const [stream, sfuSubscriptionComplete] = manager.openSubscriptionStream(sid);
+        readers.push(stream.getReader());
 
         // Make sure that the sfu interactions ONLY happen for the first subscription opened.
         if (index === 0) {
@@ -262,10 +245,8 @@ describe('DataTrackIncomingManager', () => {
           );
         }
 
-        // 5. Make sure that the subscription promise resolves.
-        const readableStream = await subscribeRequestPromise;
-        const reader = readableStream.getReader();
-        readers.push(reader);
+        // 5. Wait for the subscription to be fully established
+        await sfuSubscriptionComplete;
       }
 
       // 6. Simulate receiving a packet
@@ -302,7 +283,7 @@ describe('DataTrackIncomingManager', () => {
       const manager = new IncomingDataTrackManager();
       const managerEvents = subscribeToEvents<DataTrackIncomingManagerCallbacks>(manager, [
         'sfuUpdateSubscription',
-        'trackAvailable',
+        'trackPublished',
       ]);
 
       const sid = 'data track sid';
@@ -316,7 +297,7 @@ describe('DataTrackIncomingManager', () => {
           ],
         ]),
       );
-      await managerEvents.waitFor('trackAvailable');
+      await managerEvents.waitFor('trackPublished');
 
       // 2. Subscribe to a data track
       const controller = new AbortController();
@@ -340,7 +321,7 @@ describe('DataTrackIncomingManager', () => {
       const manager = new IncomingDataTrackManager();
       const managerEvents = subscribeToEvents<DataTrackIncomingManagerCallbacks>(manager, [
         'sfuUpdateSubscription',
-        'trackAvailable',
+        'trackPublished',
       ]);
 
       const sid = 'data track sid';
@@ -354,7 +335,7 @@ describe('DataTrackIncomingManager', () => {
           ],
         ]),
       );
-      await managerEvents.waitFor('trackAvailable');
+      await managerEvents.waitFor('trackPublished');
 
       // 2. Subscribe to a data track twice
       const controllerOne = new AbortController();
@@ -415,7 +396,7 @@ describe('DataTrackIncomingManager', () => {
       const manager = new IncomingDataTrackManager();
       const managerEvents = subscribeToEvents<DataTrackIncomingManagerCallbacks>(manager, [
         'sfuUpdateSubscription',
-        'trackAvailable',
+        'trackPublished',
       ]);
 
       const sid = 'data track sid';
@@ -429,7 +410,7 @@ describe('DataTrackIncomingManager', () => {
           ],
         ]),
       );
-      await managerEvents.waitFor('trackAvailable');
+      await managerEvents.waitFor('trackPublished');
 
       // 2. Create subscription A
       const controllerA = new AbortController();
@@ -461,7 +442,7 @@ describe('DataTrackIncomingManager', () => {
       const manager = new IncomingDataTrackManager();
       const managerEvents = subscribeToEvents<DataTrackIncomingManagerCallbacks>(manager, [
         'sfuUpdateSubscription',
-        'trackAvailable',
+        'trackPublished',
       ]);
 
       const senderIdentity = 'identity';
@@ -472,7 +453,7 @@ describe('DataTrackIncomingManager', () => {
       await manager.receiveSfuPublicationUpdates(
         new Map([[senderIdentity, [{ sid, pubHandle: handle, name: 'test', usesE2ee: false }]]]),
       );
-      await managerEvents.waitFor('trackAvailable');
+      await managerEvents.waitFor('trackPublished');
 
       // 2. Begin subscribing to a data track
       const promise = manager.subscribeRequest(sid);
@@ -490,7 +471,7 @@ describe('DataTrackIncomingManager', () => {
       const manager = new IncomingDataTrackManager();
       const managerEvents = subscribeToEvents<DataTrackIncomingManagerCallbacks>(manager, [
         'sfuUpdateSubscription',
-        'trackAvailable',
+        'trackPublished',
       ]);
 
       const senderIdentity = 'identity';
@@ -501,17 +482,18 @@ describe('DataTrackIncomingManager', () => {
       await manager.receiveSfuPublicationUpdates(
         new Map([[senderIdentity, [{ sid, pubHandle: handle, name: 'test', usesE2ee: false }]]]),
       );
-      await managerEvents.waitFor('trackAvailable');
+      await managerEvents.waitFor('trackPublished');
 
       // 2. Subscribe to a data track, and send the handle back as if the SFU acknowledged it
-      const subscribeRequestPromise = manager.subscribeRequest(sid);
+      const [stream, sfuSubscriptionComplete] = manager.openSubscriptionStream(sid);
+      const reader = stream.getReader();
       const sfuUpdateSubscriptionEvent = await managerEvents.waitFor('sfuUpdateSubscription');
       expect(sfuUpdateSubscriptionEvent.sid).toStrictEqual(sid);
       expect(sfuUpdateSubscriptionEvent.subscribe).toStrictEqual(true);
       manager.receivedSfuSubscriberHandles(new Map([[handle, sid]]));
 
       // 3. Start an active stream read for later
-      const reader = (await subscribeRequestPromise).getReader();
+      await sfuSubscriptionComplete;
 
       // 4. Simulate the remote participant disconnecting
       manager.handleRemoteParticipantDisconnected(senderIdentity);
@@ -529,7 +511,7 @@ describe('DataTrackIncomingManager', () => {
       const manager = new IncomingDataTrackManager();
       const managerEvents = subscribeToEvents<DataTrackIncomingManagerCallbacks>(manager, [
         'sfuUpdateSubscription',
-        'trackAvailable',
+        'trackPublished',
       ]);
 
       const senderIdentity = 'identity';
@@ -540,10 +522,11 @@ describe('DataTrackIncomingManager', () => {
       await manager.receiveSfuPublicationUpdates(
         new Map([[senderIdentity, [{ sid, pubHandle: handle, name: 'test', usesE2ee: false }]]]),
       );
-      await managerEvents.waitFor('trackAvailable');
+      await managerEvents.waitFor('trackPublished');
 
-      // 2. Subscribe to a data track
-      const subscribeRequestPromise = manager.subscribeRequest(sid);
+      // 2. Create a subscription readable stream
+      const [stream, sfuSubscriptionComplete] = manager.openSubscriptionStream(sid);
+      const reader = stream.getReader();
 
       // 3. This subscribe request should be sent along to the SFU
       const sfuUpdateSubscriptionInitEvent = await managerEvents.waitFor('sfuUpdateSubscription');
@@ -554,9 +537,8 @@ describe('DataTrackIncomingManager', () => {
       // the subscription
       manager.receivedSfuSubscriberHandles(new Map([[handle, sid]]));
 
-      // 5. Make sure that the subscription promise resolves.
-      const readableStream = await subscribeRequestPromise;
-      const reader = readableStream.getReader();
+      // 5. Wait for the subscription to be fully established
+      await sfuSubscriptionComplete;
 
       // 6. Manually cancel the readable stream
       await reader.cancel();
@@ -565,6 +547,9 @@ describe('DataTrackIncomingManager', () => {
       const sfuUpdateSubscriptionCancelEvent = await managerEvents.waitFor('sfuUpdateSubscription');
       expect(sfuUpdateSubscriptionCancelEvent.sid).toStrictEqual(sid);
       expect(sfuUpdateSubscriptionCancelEvent.subscribe).toStrictEqual(false);
+
+      // 8. Make sure the in flight stream is now complete
+      await expect(reader.read()).resolves.toStrictEqual({ value: undefined, done: true });
     });
   });
 });