livekit-client 2.17.3 → 2.18.1

package/src/room/data-track/incoming/pipeline.ts

@@ -0,0 +1,121 @@
+import type { Throws } from '@livekit/throws-transformer/throws';
+import type { BaseE2EEManager } from '../../../e2ee/E2eeManager';
+import { LoggerNames, getLogger } from '../../../logger';
+import DataTrackDepacketizer, { DataTrackDepacketizerDropError } from '../depacketizer';
+import type { DataTrackFrameInternal } from '../frame';
+import { DataTrackPacket } from '../packet';
+import { type DataTrackInfo } from '../types';
+
+const log = getLogger(LoggerNames.DataTracks);
+
+/**
+ * Options for creating a {@link IncomingDataTrackPipeline}.
+ */
+type Options = {
+  info: DataTrackInfo;
+  publisherIdentity: string;
+  e2eeManager: BaseE2EEManager | null;
+};
+
+/**
+ * Pipeline for an individual data track subscription.
+ */
+export default class IncomingDataTrackPipeline {
+  private publisherIdentity: string;
+
+  private e2eeManager: BaseE2EEManager | null;
+
+  private depacketizer: DataTrackDepacketizer;
+
+  /**
+   * Creates a new pipeline with the given options.
+   */
+  constructor(options: Options) {
+    const hasProvider = options.e2eeManager !== null;
+    if (options.info.usesE2ee !== hasProvider) {
+      // @throws-transformer ignore - this should be treated as a "panic" and not be caught
+      throw new Error(
+        'IncomingDataTrackPipeline: DataTrackInfo.usesE2ee must match presence of decryptionProvider',
+      );
+    }
+
+    const depacketizer = new DataTrackDepacketizer();
+
+    this.publisherIdentity = options.publisherIdentity;
+    this.e2eeManager = options.e2eeManager ?? null;
+    this.depacketizer = depacketizer;
+  }
+
+  updateE2eeManager(e2eeManager: BaseE2EEManager | null) {
+    this.e2eeManager = e2eeManager;
+  }
+
+  async processPacket(
+    packet: DataTrackPacket,
+  ): Promise<Throws<DataTrackFrameInternal | null, DataTrackDepacketizerDropError>> {
+    const frame = this.depacketize(packet);
+    if (!frame) {
+      return null;
+    }
+
+    const decrypted = await this.decryptIfNeeded(frame);
+    if (!decrypted) {
+      return null;
+    }
+
+    return decrypted;
+  }
+
+  /**
+   * Depacketize the given frame, log if a drop occurs.
+   */
+  private depacketize(
+    packet: DataTrackPacket,
+  ): Throws<DataTrackFrameInternal | null, DataTrackDepacketizerDropError> {
+    let frame: DataTrackFrameInternal | null;
+    try {
+      frame = this.depacketizer.push(packet);
+    } catch (err) {
+      // In a future version, use this to maintain drop statistics.
+      // FIXME: is this a good idea?
+      log.warn(`Data frame depacketize error: ${err}`);
+      return null;
+    }
+    return frame;
+  }
+
+  /**
+   * Decrypt the frame's payload if E2EE is enabled for this track.
+   */
+  private async decryptIfNeeded(
+    frame: DataTrackFrameInternal,
+  ): Promise<DataTrackFrameInternal | null> {
+    const e2eeManager = this.e2eeManager;
+
+    if (!e2eeManager) {
+      return frame;
+    }
+
+    const e2ee = frame.extensions?.e2ee ?? null;
+    if (!e2ee) {
+      log.error('Missing E2EE meta');
+      return null;
+    }
+
+    let result;
+    try {
+      result = await e2eeManager.handleEncryptedData(
+        frame.payload,
+        e2ee.iv,
+        this.publisherIdentity,
+        e2ee.keyIndex,
+      );
+    } catch (err) {
+      log.error(`Error decrypting packet: ${err}`);
+      return null;
+    }
+
+    frame.payload = result.payload;
+    return frame;
+  }
+}

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

@@ -0,0 +1,22 @@
+import type Participant from '../../participant/Participant';
+import type RemoteDataTrack from '../RemoteDataTrack';
+import { type DataTrackSid } from '../types';
+
+/** Request sent to the SFU to update the subscription for a data track. */
+export type EventSfuUpdateSubscription = {
+  /** Identifier of the affected track. */
+  sid: DataTrackSid;
+  /** Whether to subscribe or unsubscribe. */
+  subscribe: boolean;
+};
+
+/** A track has been published by a remote participant and is available to be subscribed to. */
+export type EventTrackAvailable = {
+  track: RemoteDataTrack;
+};
+
+/** A track has been unpublished by a remote participant and can no longer be subscribed to. */
+export type EventTrackUnavailable = {
+  sid: DataTrackSid;
+  publisherIdentity: Participant['identity'];
+};

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

@@ -1,31 +1,76 @@
 /* eslint-disable @typescript-eslint/no-unused-vars */
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+  type DecryptDataResponseMessage,
+  type EncryptDataResponseMessage,
+  LocalDataTrack,
+} from '../../..';
+import { type BaseE2EEManager } from '../../../e2ee/E2eeManager';
 import { subscribeToEvents } from '../../../utils/subscribeToEvents';
-import { EncryptionProvider } from '../e2ee';
+import RTCEngine from '../../RTCEngine';
+import Room from '../../Room';
 import { DataTrackHandle } from '../handle';
 import { DataTrackPacket, FrameMarker } from '../packet';
 import OutgoingDataTrackManager, {
-  DataTrackOutgoingManagerCallbacks,
+  type DataTrackOutgoingManagerCallbacks,
   Descriptor,
 } from './OutgoingDataTrackManager';
 import { DataTrackPublishError } from './errors';
 
-/** A fake "encryption" provider used for test purposes. Adds a prefix to the payload. */
-const PrefixingEncryptionProvider: EncryptionProvider = {
-  encrypt(payload: Uint8Array) {
+/** Fake encryption provider for testing e2ee data track features. */
+export class PrefixingEncryptionProvider implements BaseE2EEManager {
+  isEnabled = true;
+
+  isDataChannelEncryptionEnabled = true;
+
+  setup(_room: Room) {}
+
+  setupEngine(_engine: RTCEngine) {}
+
+  setParticipantCryptorEnabled(_enabled: boolean, _participantIdentity: string) {}
+
+  setSifTrailer(_trailer: Uint8Array) {}
+
+  on(_event: any, _listener: any): this {
+    return this;
+  }
+
+  /** A fake "encryption" provider used for test purposes. Adds a prefix to the payload. */
+  async encryptData(data: Uint8Array): Promise<EncryptDataResponseMessage['data']> {
     const prefix = new Uint8Array([0xde, 0xad, 0xbe, 0xef]);
 
-    const output = new Uint8Array(prefix.length + payload.length);
+    const output = new Uint8Array(prefix.length + data.length);
     output.set(prefix, 0);
-    output.set(payload, prefix.length);
+    output.set(data, prefix.length);
 
     return {
+      uuid: crypto.randomUUID(),
       payload: output,
       iv: new Uint8Array(12), // Just leaving this empty, is this a bad idea?
       keyIndex: 0,
     };
-  },
-};
+  }
+
+  /** A fake "decryption" provider used for test purposes. Assumes the payload is prefixed with
+   * 0xdeafbeef, which is stripped off. */
+  async handleEncryptedData(
+    payload: Uint8Array,
+    _iv: Uint8Array,
+    _participantIdentity: string,
+    _keyIndex: number,
+  ): Promise<DecryptDataResponseMessage['data']> {
+    if (payload[0] !== 0xde || payload[1] !== 0xad || payload[2] !== 0xbe || payload[3] !== 0xef) {
+      throw new Error(
+        `PrefixingEncryptionProvider: first four bytes of payload were not 0xdeadbeef, found ${payload.slice(0, 4)}`,
+      );
+    }
+
+    return {
+      uuid: crypto.randomUUID(),
+      payload: payload.slice(4),
+    };
+  }
+}
 
 describe('DataTrackOutgoingManager', () => {
   it('should test track publishing (ok case)', async () => {
@@ -34,8 +79,11 @@ describe('DataTrackOutgoingManager', () => {
       'sfuPublishRequest',
     ]);
 
+    const localDataTrack = new LocalDataTrack({ name: 'test' }, manager);
+    expect(localDataTrack.isPublished()).toStrictEqual(false);
+
     // 1. Publish a data track
-    const publishRequestPromise = manager.publishRequest({ name: 'test' });
+    const publishRequestPromise = localDataTrack.publish();
 
     // 2. This publish request should be sent along to the SFU
     const sfuPublishEvent = await managerEvents.waitFor('sfuPublishRequest');
@@ -55,7 +103,7 @@ describe('DataTrackOutgoingManager', () => {
     });
 
     // Make sure that the original input event resolves.
-    const localDataTrack = await publishRequestPromise;
+    await publishRequestPromise;
     expect(localDataTrack.isPublished()).toStrictEqual(true);
   });
 
@@ -66,7 +114,8 @@ describe('DataTrackOutgoingManager', () => {
     ]);
 
     // 1. Publish a data track
-    const publishRequestPromise = manager.publishRequest({ name: 'test' });
+    const localDataTrack = new LocalDataTrack({ name: 'test' }, manager);
+    const publishRequestPromise = localDataTrack.publish();
 
     // 2. This publish request should be sent along to the SFU
     const sfuPublishEvent = await managerEvents.waitFor('sfuPublishRequest');
@@ -78,7 +127,9 @@ describe('DataTrackOutgoingManager', () => {
     });
 
     // Make sure that the rejection bubbles back to the caller
-    expect(publishRequestPromise).rejects.toThrowError('Data track publication limit reached');
+    await expect(publishRequestPromise).rejects.toThrowError(
+      'Data track publication limit reached',
+    );
   });
 
   it('should test track publishing (cancellation half way through)', async () => {
@@ -90,7 +141,8 @@ describe('DataTrackOutgoingManager', () => {
 
     // 1. Publish a data track
     const controller = new AbortController();
-    const publishRequestPromise = manager.publishRequest({ name: 'test' }, controller.signal);
+    const localDataTrack = new LocalDataTrack({ name: 'test' }, manager);
+    const publishRequestPromise = localDataTrack.publish(controller.signal);
 
     // 2. This publish request should be sent along to the SFU
     const sfuPublishEvent = await managerEvents.waitFor('sfuPublishRequest');
@@ -107,7 +159,96 @@ describe('DataTrackOutgoingManager', () => {
     expect(sfuUnpublishEvent.handle).toStrictEqual(handle);
 
     // 5. Make sure cancellation is bubbled up as an error to stop further execution
-    expect(publishRequestPromise).rejects.toStrictEqual(DataTrackPublishError.cancelled());
+    await expect(publishRequestPromise).rejects.toStrictEqual(DataTrackPublishError.cancelled());
+  });
+
+  it('should test track publishing (cancellation before it starts)', async () => {
+    const manager = new OutgoingDataTrackManager();
+    const managerEvents = subscribeToEvents<DataTrackOutgoingManagerCallbacks>(manager, [
+      'sfuPublishRequest',
+      'sfuUnpublishRequest',
+    ]);
+
+    // Publish a data track
+    const localDataTrack = new LocalDataTrack({ name: 'test' }, manager);
+    const publishRequestPromise = localDataTrack.publish(AbortSignal.abort(/* already aborted */));
+
+    // Make sure cancellation is immediately bubbled up
+    await expect(publishRequestPromise).rejects.toStrictEqual(DataTrackPublishError.cancelled());
+
+    // And there were no pending sfu publish requests sent
+    expect(managerEvents.areThereBufferedEvents('sfuPublishRequest')).toBe(false);
+  });
+
+  it('should test track publishing, unpublishing, and republishing again', async () => {
+    const manager = new OutgoingDataTrackManager();
+    const managerEvents = subscribeToEvents<DataTrackOutgoingManagerCallbacks>(manager, [
+      'sfuPublishRequest',
+      'sfuUnpublishRequest',
+    ]);
+
+    // 1. Create a local data track
+    const localDataTrack = new LocalDataTrack({ name: 'test' }, manager);
+    expect(localDataTrack.isPublished()).toStrictEqual(false);
+
+    // 2. Publish it
+    const publishRequestPromise = localDataTrack.publish();
+
+    // 3. This publish request should be sent along to the SFU
+    const sfuPublishEvent = await managerEvents.waitFor('sfuPublishRequest');
+    expect(sfuPublishEvent.name).toStrictEqual('test');
+    expect(sfuPublishEvent.usesE2ee).toStrictEqual(false);
+    const handle = sfuPublishEvent.handle;
+
+    // 4. Respond to the SFU publish request with an OK response
+    manager.receivedSfuPublishResponse(handle, {
+      type: 'ok',
+      data: {
+        sid: 'bogus-sid',
+        pubHandle: sfuPublishEvent.handle,
+        name: 'test',
+        usesE2ee: false,
+      },
+    });
+
+    // Make sure that the original input event resolves.
+    await publishRequestPromise;
+
+    // 5. Now the data track should be published
+    expect(localDataTrack.isPublished()).toStrictEqual(true);
+
+    // 6. Unpublish the data track
+    const unpublishRequestPromise = localDataTrack.unpublish();
+    const sfuUnpublishEvent = await managerEvents.waitFor('sfuUnpublishRequest');
+    manager.receivedSfuUnpublishResponse(sfuUnpublishEvent.handle);
+    await unpublishRequestPromise;
+
+    // 7. Now the data track should be unpublished
+    expect(localDataTrack.isPublished()).toStrictEqual(false);
+
+    // 8. Now, republish the track and make sure that be done a second time
+    const publishRequestPromise2 = localDataTrack.publish();
+    const sfuPublishEvent2 = await managerEvents.waitFor('sfuPublishRequest');
+    expect(sfuPublishEvent2.name).toStrictEqual('test');
+    expect(sfuPublishEvent2.usesE2ee).toStrictEqual(false);
+    const handle2 = sfuPublishEvent2.handle;
+    manager.receivedSfuPublishResponse(handle2, {
+      type: 'ok',
+      data: {
+        sid: 'bogus-sid',
+        pubHandle: sfuPublishEvent2.handle,
+        name: 'test',
+        usesE2ee: false,
+      },
+    });
+    await publishRequestPromise2;
+
+    // 9. Ensure that the track is published again
+    expect(localDataTrack.isPublished()).toStrictEqual(true);
+
+    // 10. Also ensure that the handle used on the second publish attempt differs from the first
+    // publish attempt.
+    expect(handle).not.toStrictEqual(handle2);
   });
 
   it.each([
@@ -187,18 +328,17 @@ describe('DataTrackOutgoingManager', () => {
         ]),
       );
       const managerEvents = subscribeToEvents<DataTrackOutgoingManagerCallbacks>(manager, [
-        'packetsAvailable',
+        'packetAvailable',
       ]);
 
-      const localDataTrack = manager.createLocalDataTrack(5)!;
-      expect(localDataTrack).not.toStrictEqual(null);
+      const localDataTrack = LocalDataTrack.withExplicitHandle({ name: 'track name' }, manager, 5);
 
       // Kick off sending the bytes...
-      localDataTrack.tryPush(inputBytes);
+      localDataTrack.tryPush({ payload: inputBytes });
 
       // ... and make sure the corresponding events are emitted to tell the SFU to send the packets
       for (const outputPacketJson of outputPacketsJson) {
-        const packetBytes = await managerEvents.waitFor('packetsAvailable');
+        const packetBytes = await managerEvents.waitFor('packetAvailable');
         const [packet] = DataTrackPacket.fromBinary(packetBytes.bytes);
 
         expect(packet.toJSON()).toStrictEqual(outputPacketJson);
@@ -208,15 +348,16 @@ describe('DataTrackOutgoingManager', () => {
 
   it('should send e2ee encrypted datatrack payload', async () => {
     const manager = new OutgoingDataTrackManager({
-      encryptionProvider: PrefixingEncryptionProvider,
+      e2eeManager: new PrefixingEncryptionProvider(),
     });
     const managerEvents = subscribeToEvents<DataTrackOutgoingManagerCallbacks>(manager, [
       'sfuPublishRequest',
-      'packetsAvailable',
+      'packetAvailable',
     ]);
 
     // 1. Publish a data track
-    const publishRequestPromise = manager.publishRequest({ name: 'test' });
+    const localDataTrack = new LocalDataTrack({ name: 'test' }, manager);
+    const publishRequestPromise = localDataTrack.publish();
 
     // 2. This publish request should be sent along to the SFU
     const sfuPublishEvent = await managerEvents.waitFor('sfuPublishRequest');
@@ -236,14 +377,14 @@ describe('DataTrackOutgoingManager', () => {
     });
 
     // Get the connected local data track
-    const localDataTrack = await publishRequestPromise;
+    await publishRequestPromise;
     expect(localDataTrack.isPublished()).toStrictEqual(true);
 
     // Kick off sending the payload bytes
-    localDataTrack.tryPush(new Uint8Array([0x01, 0x02, 0x03, 0x04, 0x05]));
+    localDataTrack.tryPush({ payload: new Uint8Array([0x01, 0x02, 0x03, 0x04, 0x05]) });
 
     // Make sure the packet that was sent was encrypted with the PrefixingEncryptionProvider
-    const packetBytes = await managerEvents.waitFor('packetsAvailable');
+    const packetBytes = await managerEvents.waitFor('packetAvailable');
     const [packet] = DataTrackPacket.fromBinary(packetBytes.bytes);
 
     expect(packet.toJSON()).toStrictEqual({
@@ -311,6 +452,76 @@ describe('DataTrackOutgoingManager', () => {
     expect(manager.getDescriptor(5)).toStrictEqual(null);
   });
 
+  it('should test a full reconnect', async () => {
+    const pubHandle = 5;
+    // Create a manager prefilled with a descriptor
+    const manager = OutgoingDataTrackManager.withDescriptors(
+      new Map([
+        [
+          DataTrackHandle.fromNumber(5),
+          Descriptor.active(
+            {
+              sid: 'bogus-sid',
+              pubHandle,
+              name: 'test',
+              usesE2ee: false,
+            },
+            null,
+          ),
+        ],
+      ]),
+    );
+    const managerEvents = subscribeToEvents<DataTrackOutgoingManagerCallbacks>(manager, [
+      'sfuPublishRequest',
+      'packetAvailable',
+      'sfuUnpublishRequest',
+    ]);
+    const localDataTrack = LocalDataTrack.withExplicitHandle({ name: 'track name' }, manager, 5);
+
+    // Make sure the descriptor is in there
+    expect(manager.getDescriptor(5)?.type).toStrictEqual('active');
+
+    // Simulate a full reconnect, which means that any published tracks will need to be republished.
+    manager.sfuWillRepublishTracks();
+
+    // Even though behind the scenes the SFU publications are not active, the user should still see
+    // it as "published", sfu reconnects are an implementation detail
+    expect(localDataTrack.isPublished()).toStrictEqual(true);
+
+    // But, even though `isPublished` is true, pushing data should drop (no sfu to send them to!)
+    await expect(() =>
+      localDataTrack.tryPush({ payload: new Uint8Array([0x01, 0x02, 0x03, 0x04, 0x05]) }),
+    ).rejects.toThrowError('Frame was dropped');
+
+    // 2. This publish request should be sent along to the SFU
+    const sfuPublishEvent = await managerEvents.waitFor('sfuPublishRequest');
+    expect(sfuPublishEvent.name).toStrictEqual('test');
+    expect(sfuPublishEvent.usesE2ee).toStrictEqual(false);
+    const handle = sfuPublishEvent.handle;
+    expect(handle).toStrictEqual(pubHandle);
+
+    // 3. Respond to the SFU publish request with an OK response
+    manager.receivedSfuPublishResponse(handle, {
+      type: 'ok',
+      data: {
+        sid: 'bogus-sid-REPUBLISHED',
+        pubHandle: sfuPublishEvent.handle,
+        name: 'test',
+        usesE2ee: false,
+      },
+    });
+
+    // After all this, the local data track should still be published
+    expect(localDataTrack.isPublished()).toStrictEqual(true);
+
+    // And the sid should be the new value
+    expect(localDataTrack.info!.sid).toStrictEqual('bogus-sid-REPUBLISHED');
+
+    // And now that the tracks are backed by the SFU again, pushes should function!
+    await localDataTrack.tryPush({ payload: new Uint8Array([0x01, 0x02, 0x03, 0x04, 0x05]) });
+    await managerEvents.waitFor('packetAvailable');
+  });
+
   it('should query currently active descriptors', async () => {
     // Create a manager prefilled with a descriptor
     const manager = OutgoingDataTrackManager.withDescriptors(
@@ -378,7 +589,9 @@ describe('DataTrackOutgoingManager', () => {
     const shutdownPromise = manager.shutdown();
 
     // The pending data track should be cancelled
-    expect(pendingDescriptor.completionFuture.promise).rejects.toThrowError('Room disconnected');
+    await expect(pendingDescriptor.completionFuture.promise).rejects.toThrowError(
+      'Room disconnected',
+    );
 
     // And the active data track should be requested to be unpublished
     const unpublishEvent = await managerEvents.waitFor('sfuUnpublishRequest');