livekit-client 2.19.1 → 2.20.0

package/src/{packetTrailer → frameMetadata}/utils.ts

@@ -1,25 +1,25 @@
 import { PacketTrailerFeature } from '@livekit/protocol';
 import { isInsertableStreamSupported } from '../e2ee/utils';
 import { isScriptTransformSupportedForWorker } from '../room/utils';
-import type { PacketTrailerOptions } from './PacketTrailerManager';
-import type { PacketTrailerPublishOptions } from './types';
+import type { FrameMetadataOptions } from './FrameMetadataManager';
+import type { FrameMetadataPublishOptions } from './types';
 
-export function shouldUsePacketTrailerScriptTransform() {
+export function shouldUseFrameMetadataScriptTransform() {
   return isScriptTransformSupportedForWorker();
 }
 
-export function isPacketTrailerSupported(options?: PacketTrailerOptions) {
+export function isFrameMetadataSupported(options?: FrameMetadataOptions) {
   return (
-    !!options?.worker && (isInsertableStreamSupported() || shouldUsePacketTrailerScriptTransform())
+    !!options?.worker && (isInsertableStreamSupported() || shouldUseFrameMetadataScriptTransform())
   );
 }
 
-export function hasPacketTrailerPublishOptions(options?: PacketTrailerPublishOptions): boolean {
+export function hasFrameMetadataPublishOptions(options?: FrameMetadataPublishOptions): boolean {
   return !!(options?.timestamp || options?.frameId);
 }
 
-export function getPacketTrailerFeatures(
-  options?: PacketTrailerPublishOptions,
+export function getFrameMetadataFeatures(
+  options?: FrameMetadataPublishOptions,
 ): PacketTrailerFeature[] {
   const features: PacketTrailerFeature[] = [];
   if (options?.timestamp) {
@@ -31,14 +31,14 @@ export function getPacketTrailerFeatures(
   return features;
 }
 
-export function getPacketTrailerPublishOptions(
+export function getFrameMetadataPublishOptions(
   features?: PacketTrailerFeature[],
-): PacketTrailerPublishOptions | undefined {
+): FrameMetadataPublishOptions | undefined {
   if (!features || features.length === 0) {
     return undefined;
   }
 
-  const options: PacketTrailerPublishOptions = {};
+  const options: FrameMetadataPublishOptions = {};
   if (features.includes(PacketTrailerFeature.PTF_USER_TIMESTAMP)) {
     options.timestamp = true;
   }

package/src/{packetTrailer/worker/packetTrailer.worker.ts → frameMetadata/worker/frameMetadata.worker.ts}

@@ -1,11 +1,11 @@
-import { appendPacketTrailerToEncodedFrame, processPacketTrailer } from '../packetTrailer';
+import { appendPacketTrailerToEncodedFrame, processPacketTrailer } from '../frameMetadata';
 import type {
+  FrameMetadataPublishOptions,
   PTMetadataMessage,
   PTScriptTransformOptions,
   PTWorkerMessage,
-  PacketTrailerPublishOptions,
 } from '../types';
-import { hasPacketTrailerPublishOptions } from '../utils';
+import { hasFrameMetadataPublishOptions } from '../utils';
 
 /**
  * Holds the trackId currently associated with a pipeline. A mutable
@@ -97,9 +97,9 @@ function setupDecodeTransform(
 function setupEncodeTransform(
   readable: ReadableStream,
   writable: WritableStream,
-  packetTrailer?: PacketTrailerPublishOptions,
+  packetTrailer?: FrameMetadataPublishOptions,
 ) {
-  if (!hasPacketTrailerPublishOptions(packetTrailer)) {
+  if (!hasFrameMetadataPublishOptions(packetTrailer)) {
     readable.pipeTo(writable).catch(() => {});
     return;
   }

package/src/{packetTrailer → frameMetadata}/worker/tsconfig.json

@@ -8,7 +8,10 @@
       "ES2018.Promise",
       "WebWorker",
       "ES2021.WeakRef",
-      "DOM.AsyncIterable"
+      "DOM.AsyncIterable",
+      "ES2020.BigInt",
+      "ES2018.AsyncIterable",
+      "ES2018.AsyncGenerator"
     ]
   }
 }

package/src/index.ts

@@ -64,11 +64,22 @@ import {
 import { getBrowser } from './utils/browserParser';
 
 export { RpcError, type RpcInvocationData, type PerformRpcParams } from './room/rpc';
-export type { PacketTrailerMetadata, PacketTrailerPublishOptions } from './packetTrailer/types';
+export type {
+  FrameMetadata,
+  FrameMetadataPublishOptions,
+  /** @deprecated Use {@link FrameMetadata} instead. */
+  PacketTrailerMetadata,
+  /** @deprecated Use {@link FrameMetadataPublishOptions} instead. */
+  PacketTrailerPublishOptions,
+} from './frameMetadata/types';
 export {
+  FrameMetadataManager,
+  /** @deprecated Use {@link FrameMetadataManager} instead. */
   PacketTrailerManager,
+  type FrameMetadataOptions,
+  /** @deprecated Use {@link FrameMetadataOptions} instead. */
   type PacketTrailerOptions,
-} from './packetTrailer/PacketTrailerManager';
+} from './frameMetadata/FrameMetadataManager';
 
 export * from './connectionHelper/ConnectionCheck';
 export * from './connectionHelper/checks/Checker';

package/src/options.ts

@@ -1,5 +1,5 @@
 import type { E2EEOptions } from './e2ee/types';
-import type { PacketTrailerOptions } from './packetTrailer/PacketTrailerManager';
+import type { FrameMetadataOptions } from './frameMetadata/FrameMetadataManager';
 import type { ReconnectPolicy } from './room/ReconnectPolicy';
 import type {
   AudioCaptureOptions,
@@ -103,10 +103,15 @@ export interface InternalRoomOptions {
 
   /**
    * @experimental
-   * Options for enabling packet trailers on video tracks.
-   * Packet trailers carry frame-level metadata such as user timestamps and frame IDs.
+   * Options for enabling frame metadata on video tracks.
+   * Frame metadata carries frame-level information such as user timestamps and frame IDs.
    */
-  packetTrailer?: PacketTrailerOptions;
+  frameMetadata?: FrameMetadataOptions;
+
+  /**
+   * @deprecated Use {@link InternalRoomOptions.frameMetadata} instead.
+   */
+  packetTrailer?: FrameMetadataOptions;
 
   /**
    * will attempt to connect via single peer connection mode.

package/src/room/PCTransport.ts

@@ -498,6 +498,10 @@ export default class PCTransport extends (EventEmitter as new () => TypedEmitter
     return this.pc.getStats();
   }
 
+  getMaxMessageSize() {
+    return this._pc?.sctp?.maxMessageSize;
+  }
+
   async getConnectedAddress(): Promise<string | undefined> {
     if (!this._pc) {
       return;

package/src/room/PCTransportManager.ts

@@ -310,6 +310,10 @@ export class PCTransportManager {
     return matchingTransceiver?.mid;
   }
 
+  getMaxPublisherMessageSize() {
+    return this.publisher.getMaxMessageSize();
+  }
+
   addPublisherTrack(track: MediaStreamTrack) {
     return this.publisher.addTrack(track);
   }

package/src/room/RTCEngine.test.ts

@@ -1,6 +1,8 @@
+import { DataPacket, DataPacket_Kind, UserPacket } from '@livekit/protocol';
 import { afterEach, describe, expect, it, vi } from 'vitest';
-import RTCEngine from './RTCEngine';
+import RTCEngine, { DataChannelKind } from './RTCEngine';
 import { roomOptionDefaults } from './defaults';
+import { PublishDataError } from './errors';
 
 describe('RTCEngine', () => {
   const originalRTCRtpSender = window.RTCRtpSender;
@@ -56,12 +58,12 @@ describe('RTCEngine', () => {
     ).makeRTCConfiguration();
   }
 
-  function setupPacketTrailerSender(engine: RTCEngine, sender: RTCRtpSender, opts = {}) {
+  function setupFrameMetadataSender(engine: RTCEngine, sender: RTCRtpSender, opts = {}) {
     (
       engine as unknown as {
-        setupPacketTrailerSender: (sender: RTCRtpSender, opts?: unknown) => void;
+        setupFrameMetadataSender: (sender: RTCRtpSender, opts?: unknown) => void;
       }
-    ).setupPacketTrailerSender(sender, opts);
+    ).setupFrameMetadataSender(sender, opts);
   }
 
   it('does not enable encoded insertable streams without E2EE or a packet trailer worker', () => {
@@ -128,7 +130,7 @@ describe('RTCEngine', () => {
       createEncodedStreams,
     } as unknown as RTCRtpSender;
 
-    setupPacketTrailerSender(engine, sender);
+    setupFrameMetadataSender(engine, sender);
 
     expect(createEncodedStreams).not.toHaveBeenCalled();
   });
@@ -145,7 +147,7 @@ describe('RTCEngine', () => {
       createEncodedStreams,
     } as unknown as RTCRtpSender;
 
-    setupPacketTrailerSender(engine, sender);
+    setupFrameMetadataSender(engine, sender);
 
     expect(createEncodedStreams).not.toHaveBeenCalled();
   });
@@ -165,7 +167,7 @@ describe('RTCEngine', () => {
       createEncodedStreams,
     } as unknown as RTCRtpSender;
 
-    setupPacketTrailerSender(engine, sender, { packetTrailer: { timestamp: true, frameId: true } });
+    setupFrameMetadataSender(engine, sender, { packetTrailer: { timestamp: true, frameId: true } });
 
     expect(createEncodedStreams).toHaveBeenCalledTimes(1);
     expect(worker.postMessage).toHaveBeenCalledWith(
@@ -185,7 +187,9 @@ describe('RTCEngine', () => {
     stubScriptTransformSupport();
 
     const transform = {};
-    const RTCRtpScriptTransform = vi.fn(() => transform);
+    const RTCRtpScriptTransform = vi.fn(function () {
+      return transform;
+    });
     Object.defineProperty(window, 'RTCRtpScriptTransform', {
       configurable: true,
       value: RTCRtpScriptTransform,
@@ -207,7 +211,7 @@ describe('RTCEngine', () => {
       createEncodedStreams,
     } as unknown as RTCRtpSender;
 
-    setupPacketTrailerSender(engine, sender, { packetTrailer: { timestamp: true } });
+    setupFrameMetadataSender(engine, sender, { packetTrailer: { timestamp: true } });
 
     expect(RTCRtpScriptTransform).toHaveBeenCalledWith(worker, {
       kind: 'encode',
@@ -216,4 +220,134 @@ describe('RTCEngine', () => {
     expect((sender as unknown as { transform: unknown }).transform).toBe(transform);
     expect(createEncodedStreams).not.toHaveBeenCalled();
   });
+
+  describe('sendDataPacket', () => {
+    const MAX_DATA_PACKET_SIZE = 64 * 1024 - 1; // 65535 bytes (64 KB - 1)
+    function stubConnectedEngine(
+      engine: RTCEngine,
+      maxDataPacketSize: number = MAX_DATA_PACKET_SIZE,
+    ) {
+      const send = vi.fn();
+      Object.assign(engine as unknown as Record<string, unknown>, {
+        ensurePublisherConnected: vi.fn().mockResolvedValue(undefined),
+        waitForBufferStatusLow: vi.fn().mockResolvedValue(undefined),
+        updateAndEmitDCBufferStatus: vi.fn(),
+        dataChannelForKind: vi.fn(() => ({ send })),
+        pcManager: {
+          getMaxPublisherMessageSize: vi.fn(() => maxDataPacketSize),
+        },
+      });
+      return send;
+    }
+
+    it('rejects packets larger than the max data packet size', async () => {
+      const engine = new RTCEngine(roomOptionDefaults);
+      const send = stubConnectedEngine(engine);
+
+      // The serialized packet includes protobuf framing on top of the payload, so a payload at the
+      // limit is already guaranteed to exceed it once serialized.
+      const packet = new DataPacket({
+        kind: DataPacket_Kind.RELIABLE,
+        value: {
+          case: 'user',
+          value: new UserPacket({ payload: new Uint8Array(MAX_DATA_PACKET_SIZE) }),
+        },
+      });
+
+      await expect(engine.sendDataPacket(packet, DataChannelKind.RELIABLE)).rejects.toBeInstanceOf(
+        PublishDataError,
+      );
+      expect(send).not.toHaveBeenCalled();
+    });
+
+    it('does not reject packets if the max data packet size is 0', async () => {
+      const engine = new RTCEngine(roomOptionDefaults);
+      const send = stubConnectedEngine(engine, 0);
+
+      const packet = new DataPacket({
+        kind: DataPacket_Kind.RELIABLE,
+        value: {
+          case: 'user',
+          value: new UserPacket({ payload: new Uint8Array(100) }),
+        },
+      });
+
+      // Sending the packet should succeed, there isn't a size limit
+      await expect(
+        engine.sendDataPacket(packet, DataChannelKind.RELIABLE),
+      ).resolves.toBeUndefined();
+      expect(send).toHaveBeenCalledTimes(1);
+    });
+
+    it('sends packets within the max data packet size', async () => {
+      const engine = new RTCEngine(roomOptionDefaults);
+      const send = stubConnectedEngine(engine);
+
+      const packet = new DataPacket({
+        kind: DataPacket_Kind.RELIABLE,
+        value: {
+          case: 'user',
+          value: new UserPacket({ payload: new Uint8Array(1024) }),
+        },
+      });
+
+      await expect(
+        engine.sendDataPacket(packet, DataChannelKind.RELIABLE),
+      ).resolves.toBeUndefined();
+      expect(send).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('handleDataChannelClose', () => {
+    function stubCloseEnv(
+      engine: RTCEngine,
+      { closed, publisherState }: { closed: boolean; publisherState: RTCPeerConnectionState },
+    ) {
+      const error = vi.fn();
+      Object.assign(engine as unknown as Record<string, unknown>, {
+        _isClosed: closed,
+        log: { error },
+        pcManager: {
+          publisher: { getConnectionState: () => publisherState },
+        },
+      });
+      return error;
+    }
+
+    function fireClose(engine: RTCEngine, kind: DataChannelKind) {
+      (
+        engine as unknown as {
+          handleDataChannelClose: (kind: DataChannelKind) => () => void;
+        }
+      ).handleDataChannelClose(kind)();
+    }
+
+    it('logs an error when a publisher channel closes while connected', () => {
+      const engine = new RTCEngine(roomOptionDefaults);
+      const error = stubCloseEnv(engine, { closed: false, publisherState: 'connected' });
+
+      fireClose(engine, DataChannelKind.RELIABLE);
+
+      expect(error).toHaveBeenCalledOnce();
+      expect(error.mock.calls[0][0]).toContain('RELIABLE');
+    });
+
+    it('stays quiet when the engine is already closed', () => {
+      const engine = new RTCEngine(roomOptionDefaults);
+      const error = stubCloseEnv(engine, { closed: true, publisherState: 'connected' });
+
+      fireClose(engine, DataChannelKind.RELIABLE);
+
+      expect(error).not.toHaveBeenCalled();
+    });
+
+    it('stays quiet when the publisher PC is no longer connected', () => {
+      const engine = new RTCEngine(roomOptionDefaults);
+      const error = stubCloseEnv(engine, { closed: false, publisherState: 'closed' });
+
+      fireClose(engine, DataChannelKind.RELIABLE);
+
+      expect(error).not.toHaveBeenCalled();
+    });
+  });
 });