livekit-client 2.18.0 → 2.18.1

package/dist/ts4.2/utils/deferrable-map.d.ts

@@ -0,0 +1,32 @@
+import type { Throws } from '@livekit/throws-transformer/throws';
+/** An error which is thrown if a {@link DeferrableMap#getDeferred} call is aborted midway
+ * through. */
+export declare class DeferrableMapAbortError extends DOMException {
+    reason: unknown;
+    constructor(message: string, reason?: unknown);
+}
+/**
+ * A Map-like container keyed by unique strings that supports the ability to wait
+ * for future keys to show up in the map.
+ *
+ * @example
+ * // An already existing key:
+ * const value = map.get("key");
+ * // Wait for a key which will be added soon:
+ * const value = await map.getDeferred("key");
+ */
+export declare class DeferrableMap<K, V> extends Map<K, V> {
+    private pending;
+    set(key: K, value: V): this;
+    get [Symbol.toStringTag](): string;
+    /**
+     * Returns the value for `key` immediately if it exists, otherwise returns a
+     * promise that resolves once `set(key, value)` is called.
+     *
+     * If an `AbortSignal` is provided and it is aborted before the key appears,
+     * the returned promise rejects with an {@link DeferrableMapAbortError}.
+     */
+    getDeferred(key: K): Promise<V>;
+    getDeferred(key: K, signal: AbortSignal): Promise<Throws<V, DeferrableMapAbortError>>;
+}
+//# sourceMappingURL=deferrable-map.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "livekit-client",
-  "version": "2.18.0",
+  "version": "2.18.1",
   "description": "JavaScript/TypeScript client SDK for LiveKit",
   "main": "./dist/livekit-client.umd.js",
   "unpkg": "./dist/livekit-client.umd.js",

package/src/api/SignalClient.test.ts

@@ -300,8 +300,10 @@ describe('SignalClient.connect', () => {
 
   describe('Failure Case - WebSocket Connection Errors', () => {
     it('should reject with NotAllowed error for 4xx HTTP status', async () => {
+      const openedPromise = Promise.reject(new Error('Connection failed'));
+      openedPromise.catch(() => {}); // prevent unhandled rejection before join attaches its handler
       mockWebSocketStream({
-        opened: Promise.reject(new Error('Connection failed')),
+        opened: openedPromise,
         readyState: 3,
       });
 
@@ -321,8 +323,10 @@ describe('SignalClient.connect', () => {
     });
 
     it('should reject with ServerUnreachable when fetch fails', async () => {
+      const openedPromise = Promise.reject(new Error('Connection failed'));
+      openedPromise.catch(() => {}); // prevent unhandled rejection before join attaches its handler
       mockWebSocketStream({
-        opened: Promise.reject(new Error('Connection failed')),
+        opened: openedPromise,
         readyState: 3,
       });
 
@@ -338,9 +342,10 @@ describe('SignalClient.connect', () => {
 
     it('should handle ConnectionError from WebSocket rejection', async () => {
       const customError = ConnectionError.internal('Custom error', { status: 500 });
-
+      const openedPromise = Promise.reject(customError);
+      openedPromise.catch(() => {}); // prevent unhandled rejection before join attaches its handler
       mockWebSocketStream({
-        opened: Promise.reject(customError),
+        opened: openedPromise,
         readyState: 3,
       });
 

package/src/api/SignalClient.ts

@@ -5,7 +5,9 @@ import {
   ClientInfo,
   ConnectionQualityUpdate,
   ConnectionSettings,
+  DataTrackSubscriberHandles,
   DisconnectReason,
+  Encryption_Type,
   JoinRequest,
   JoinResponse,
   LeaveRequest,
@@ -14,6 +16,8 @@ import {
   MuteTrackRequest,
   ParticipantInfo,
   Ping,
+  PublishDataTrackRequest,
+  PublishDataTrackResponse,
   ReconnectReason,
   ReconnectResponse,
   RequestResponse,
@@ -35,6 +39,10 @@ import {
   TrackPublishedResponse,
   TrackUnpublishedResponse,
   TrickleRequest,
+  UnpublishDataTrackRequest,
+  UnpublishDataTrackResponse,
+  UpdateDataSubscription,
+  UpdateDataSubscription_Update,
   UpdateLocalAudioTrack,
   UpdateParticipantMetadata,
   UpdateSubscription,
@@ -42,13 +50,16 @@ import {
   UpdateVideoLayers,
   VideoLayer,
   WrappedJoinRequest,
+  WrappedJoinRequest_Compression,
   protoInt64,
 } from '@livekit/protocol';
 import log, { LoggerNames, getLogger } from '../logger';
+import type { DataTrackHandle } from '../room/data-track/handle';
+import { type DataTrackSid } from '../room/data-track/types';
 import { ConnectionError } from '../room/errors';
 import CriticalTimers from '../room/timers';
 import type { LoggerOptions } from '../room/types';
-import { getClientInfo, isReactNative, sleep } from '../room/utils';
+import { getClientInfo, isCompressionStreamSupported, isReactNative, sleep } from '../room/utils';
 import { AsyncQueue } from '../utils/AsyncQueue';
 import { type WebSocketConnection, WebSocketStream } from './WebSocketStream';
 import {
@@ -174,6 +185,14 @@ export class SignalClient {
 
   onMediaSectionsRequirement?: (requirement: MediaSectionsRequirement) => void;
 
+  onPublishDataTrackResponse?: (event: PublishDataTrackResponse) => void;
+
+  onUnPublishDataTrackResponse?: (event: UnpublishDataTrackResponse) => void;
+
+  onDataTrackSubscriberHandles?: (event: DataTrackSubscriberHandles) => void;
+
+  onJoined?: (event: JoinResponse) => void;
+
   connectOptions?: ConnectOpts;
 
   ws?: WebSocketStream;
@@ -248,12 +267,13 @@ export class SignalClient {
     opts: SignalOptions,
     abortSignal?: AbortSignal,
     useV0Path: boolean = false,
+    publisherOffer?: SessionDescription,
   ): Promise<JoinResponse> {
     // during a full reconnect, we'd want to start the sequence even if currently
     // connected
     this.state = SignalConnectionState.CONNECTING;
     this.options = opts;
-    const res = await this.connect(url, token, opts, abortSignal, useV0Path);
+    const res = await this.connect(url, token, opts, abortSignal, useV0Path, publisherOffer);
     return res as JoinResponse;
   }
 
@@ -296,6 +316,7 @@ export class SignalClient {
     abortSignal?: AbortSignal,
     /** setting this to true results in dual peer connection mode being used */
     useV0Path: boolean = false,
+    publisherOffer?: SessionDescription,
   ): Promise<JoinResponse | ReconnectResponse | undefined> {
     const unlock = await this.connectionLock.lock();
 
@@ -305,7 +326,7 @@ export class SignalClient {
     const clientInfo = getClientInfo();
     const params = useV0Path
       ? createConnectionParams(token, clientInfo, opts)
-      : createJoinRequestConnectionParams(token, clientInfo, opts);
+      : await createJoinRequestConnectionParams(token, clientInfo, opts, publisherOffer);
     const rtcUrl = createRtcUrl(url, params, useV0Path).toString();
     const validateUrl = createValidateUrl(rtcUrl).toString();
 
@@ -437,8 +458,9 @@ export class SignalClient {
             return;
           }
 
-          // Handle join response - set up ping configuration
+          // Handle join response
           if (firstSignalResponse.message?.case === 'join') {
+            // Set up ping configuration
             this.pingTimeoutDuration = firstSignalResponse.message.value.pingTimeout;
             this.pingIntervalDuration = firstSignalResponse.message.value.pingInterval;
 
@@ -449,6 +471,10 @@ export class SignalClient {
                 interval: this.pingIntervalDuration,
               });
             }
+
+            if (this.onJoined) {
+              this.onJoined(firstSignalResponse.message.value);
+            }
           }
 
           // Handle successful connection
@@ -685,7 +711,40 @@ export class SignalClient {
     });
   }
 
-  async sendRequest(message: SignalMessage, fromQueue: boolean = false) {
+  sendPublishDataTrackRequest(handle: DataTrackHandle, name: string, usesE2ee: boolean) {
+    return this.sendRequest({
+      case: 'publishDataTrackRequest',
+      value: new PublishDataTrackRequest({
+        pubHandle: handle,
+        name: name,
+        encryption: usesE2ee ? Encryption_Type.GCM : Encryption_Type.NONE,
+      }),
+    });
+  }
+
+  sendUnPublishDataTrackRequest(handle: DataTrackHandle) {
+    return this.sendRequest({
+      case: 'unpublishDataTrackRequest',
+      value: new UnpublishDataTrackRequest({ pubHandle: handle }),
+    });
+  }
+
+  sendUpdateDataSubscription(sid: DataTrackSid, subscribe: boolean) {
+    return this.sendRequest({
+      case: 'updateDataSubscription',
+      value: new UpdateDataSubscription({
+        // FIXME: consider refactoring to allow caller to pass an array of events through
+        updates: [
+          new UpdateDataSubscription_Update({
+            trackSid: sid,
+            subscribe,
+          }),
+        ],
+      }),
+    });
+  }
+
+  private async sendRequest(message: SignalMessage, fromQueue: boolean = false) {
     // capture all requests while reconnecting and put them in a queue
     // unless the request originates from the queue, then don't enqueue again
     const canQueue = !fromQueue && !canPassThroughQueue(message);
@@ -827,6 +886,18 @@ export class SignalClient {
       if (this.onMediaSectionsRequirement) {
         this.onMediaSectionsRequirement(msg.value);
       }
+    } else if (msg.case === 'publishDataTrackResponse') {
+      if (this.onPublishDataTrackResponse) {
+        this.onPublishDataTrackResponse(msg.value);
+      }
+    } else if (msg.case === 'unpublishDataTrackResponse') {
+      if (this.onUnPublishDataTrackResponse) {
+        this.onUnPublishDataTrackResponse(msg.value);
+      }
+    } else if (msg.case === 'dataTrackSubscriberHandles') {
+      if (this.onDataTrackSubscriberHandles) {
+        this.onDataTrackSubscriberHandles(msg.value);
+      }
     } else {
       this.log.debug('unsupported message', { ...this.logContext, msgCase: msg.case });
     }
@@ -1125,11 +1196,12 @@ function createConnectionParams(
   return params;
 }
 
-function createJoinRequestConnectionParams(
+async function createJoinRequestConnectionParams(
   token: string,
   info: ClientInfo,
   opts: ConnectOpts,
-): URLSearchParams {
+  publisherOffer?: SessionDescription,
+): Promise<URLSearchParams> {
   const params = new URLSearchParams();
   params.set('access_token', token);
 
@@ -1141,14 +1213,49 @@ function createJoinRequestConnectionParams(
     }),
     reconnect: !!opts.reconnect,
     participantSid: opts.sid ? opts.sid : undefined,
+    publisherOffer: publisherOffer,
   });
   if (opts.reconnectReason) {
     joinRequest.reconnectReason = opts.reconnectReason;
   }
+  const joinRequestBytes = joinRequest.toBinary();
+  let requestBytes: Uint8Array;
+  let compression: WrappedJoinRequest_Compression;
+  if (isCompressionStreamSupported()) {
+    const stream = new CompressionStream('gzip');
+    const writer = stream.writable.getWriter();
+    writer.write(new Uint8Array(joinRequestBytes));
+    writer.close();
+    const chunks: Uint8Array[] = [];
+    const reader = stream.readable.getReader();
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      chunks.push(value);
+    }
+    const totalLength = chunks.reduce((acc, chunk) => acc + chunk.length, 0);
+    const result = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+      result.set(chunk, offset);
+      offset += chunk.length;
+    }
+    requestBytes = result;
+    compression = WrappedJoinRequest_Compression.GZIP;
+  } else {
+    requestBytes = joinRequestBytes;
+    compression = WrappedJoinRequest_Compression.NONE;
+  }
   const wrappedJoinRequest = new WrappedJoinRequest({
-    joinRequest: joinRequest.toBinary(),
+    joinRequest: requestBytes,
+    compression,
   });
-  params.set('join_request', btoa(new TextDecoder('utf-8').decode(wrappedJoinRequest.toBinary())));
+  const wrappedBytes = wrappedJoinRequest.toBinary();
+  const bytesToBase64 = (bytes: Uint8Array) => {
+    const binString = Array.from(bytes, (byte) => String.fromCodePoint(byte)).join('');
+    return btoa(binString);
+  };
+  params.set('join_request', bytesToBase64(wrappedBytes).replace(/\+/g, '-').replace(/\//g, '_'));
 
   return params;
 }

package/src/e2ee/constants.ts

@@ -37,6 +37,7 @@ export const KEY_PROVIDER_DEFAULTS: KeyProviderOptions = {
   ratchetWindowSize: 8,
   failureTolerance: DECRYPTION_FAILURE_TOLERANCE,
   keyringSize: 16,
+  keySize: 128,
 } as const;
 
 export const MAX_SIF_COUNT = 100;

package/src/e2ee/types.ts

@@ -183,6 +183,12 @@ export type KeyProviderOptions = {
   ratchetWindowSize: number;
   failureTolerance: number;
   keyringSize: number;
+  /**
+   * Size of the encryption key in bits.
+   * Defaults to 128. Note that 128 is currently the only value
+   * supported by non-web SDKs.
+   */
+  keySize: 128 | 256;
 };
 
 export type KeyInfo = {

package/src/e2ee/utils.ts

@@ -1,5 +1,6 @@
 import { type DataPacket, EncryptedPacketPayload } from '@livekit/protocol';
 import { ENCRYPTION_ALGORITHM } from './constants';
+import type { KeyProviderOptions } from './types';
 
 export function isE2EESupported() {
   return isInsertableStreamSupported() || isScriptTransformSupported();
@@ -92,8 +93,8 @@ function getAlgoOptions(algorithmName: string, salt: string) {
  * Derives a set of keys from the master key.
  * See https://tools.ietf.org/html/draft-omara-sframe-00#section-4.3.1
  */
-export async function deriveKeys(material: CryptoKey, salt: string) {
-  const algorithmOptions = getAlgoOptions(material.algorithm.name, salt);
+export async function deriveKeys(material: CryptoKey, options: KeyProviderOptions) {
+  const algorithmOptions = getAlgoOptions(material.algorithm.name, options.ratchetSalt);
 
   // https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/deriveKey#HKDF
   // https://developer.mozilla.org/en-US/docs/Web/API/HkdfParams
@@ -102,7 +103,7 @@ export async function deriveKeys(material: CryptoKey, salt: string) {
     material,
     {
       name: ENCRYPTION_ALGORITHM,
-      length: 128,
+      length: options.keySize,
     },
     false,
     ['encrypt', 'decrypt'],

package/src/e2ee/worker/DataCryptor.ts

@@ -93,10 +93,7 @@ export class DataCryptor {
             // if not, it might be that a different frame has already ratcheted and we try with that one first
             ratchetResult = await keys.ratchetKey(keyIndex, false);
 
-            ratchetedKeySet = await deriveKeys(
-              ratchetResult.cryptoKey,
-              keys.keyProviderOptions.ratchetSalt,
-            );
+            ratchetedKeySet = await deriveKeys(ratchetResult.cryptoKey, keys.keyProviderOptions);
           }
 
           const decryptedData = await DataCryptor.decrypt(

package/src/e2ee/worker/FrameCryptor.ts

@@ -603,10 +603,7 @@ export class FrameCryptor extends BaseFrameCryptor {
             // if not, it might be that a different frame has already ratcheted and we try with that one first
             ratchetResult = await this.keys.ratchetKey(keyIndex, false);
 
-            ratchetedKeySet = await deriveKeys(
-              ratchetResult.cryptoKey,
-              this.keyProviderOptions.ratchetSalt,
-            );
+            ratchetedKeySet = await deriveKeys(ratchetResult.cryptoKey, this.keyProviderOptions);
           }
 
           const frame = await this.decryptFrame(encodedFrame, keyIndex, initialMaterial || keySet, {

package/src/e2ee/worker/ParticipantKeyHandler.ts

@@ -173,7 +173,7 @@ export class ParticipantKeyHandler extends (EventEmitter as new () => TypedEvent
     ratchetedResult: RatchetResult | null = null,
     updateCurrentKeyIndex = true,
   ) {
-    const keySet = await deriveKeys(material, this.keyProviderOptions.ratchetSalt);
+    const keySet = await deriveKeys(material, this.keyProviderOptions);
     const newIndex = keyIndex >= 0 ? keyIndex % this.cryptoKeyRing.length : this.currentKeyIndex;
     workerLogger.debug(`setting new key with index ${keyIndex}`, {
       usage: material.usages,

package/src/index.ts

@@ -11,10 +11,8 @@ import DefaultReconnectPolicy from './room/DefaultReconnectPolicy';
 import type { ReconnectContext, ReconnectPolicy } from './room/ReconnectPolicy';
 import Room, { ConnectionState, type RoomEventCallbacks } from './room/Room';
 import * as attributes from './room/attribute-typings';
-// FIXME: remove this import in a follow up data track pull request.
-import './room/data-track/incoming/IncomingDataTrackManager';
-// FIXME: remove this import in a follow up data track pull request.
-import './room/data-track/outgoing/OutgoingDataTrackManager';
+import LocalDataTrack from './room/data-track/LocalDataTrack';
+import RemoteDataTrack, { type DataTrackSubscribeOptions } from './room/data-track/RemoteDataTrack';
 import LocalParticipant from './room/participant/LocalParticipant';
 import Participant, {
   ConnectionQuality,
@@ -142,6 +140,8 @@ export {
   isVideoTrack,
   isLocalParticipant,
   isRemoteParticipant,
+  LocalDataTrack,
+  RemoteDataTrack,
 };
 export type {
   AudioAnalyserOptions,
@@ -158,6 +158,7 @@ export type {
   RoomEventCallbacks,
   ParticipantEventCallbacks,
   PublicationEventCallbacks,
+  DataTrackSubscribeOptions,
 };
 export { DataTrackPacket, type DataTrackPacketHeader } from './room/data-track/packet';
 export {
@@ -165,5 +166,6 @@ export {
   type DataTrackUserTimestampExtension,
   type DataTrackE2eeExtension,
 } from './room/data-track/packet/extensions';
+export { type DataChannelKind } from './room/RTCEngine';
 
 export { LocalTrackRecorder } from './room/track/record';

package/src/room/PCTransport.ts

@@ -55,6 +55,8 @@ export default class PCTransport extends EventEmitter {
 
   private offerLock: Mutex;
 
+  private pendingInitialOffer?: RTCSessionDescriptionInit;
+
   pendingCandidates: RTCIceCandidateInit[] = [];
 
   restartingIce: boolean = false;
@@ -163,6 +165,16 @@ export default class PCTransport extends EventEmitter {
       this.remoteStereoMids = stereoMids;
       this.remoteNackMids = nackMids;
     } else if (sd.type === 'answer') {
+      if (this.pendingInitialOffer) {
+        const initialOffer = this.pendingInitialOffer;
+        this.pendingInitialOffer = undefined;
+        const sdpParsed = parse(initialOffer.sdp ?? '');
+        sdpParsed.media.forEach((media) => {
+          ensureIPAddrMatchVersion(media);
+        });
+        this.log.debug('setting pending initial offer before processing answer', this.logContext);
+        await this.setMungedSDP(initialOffer, write(sdpParsed));
+      }
       const sdpParsed = parse(sd.sdp ?? '');
       sdpParsed.media.forEach((media) => {
         const mid = getMidString(media.mid!);
@@ -255,6 +267,31 @@ export default class PCTransport extends EventEmitter {
     }
   }, debounceInterval);
 
+  async createInitialOffer() {
+    const unlock = await this.offerLock.lock();
+    try {
+      if (this.pc.signalingState !== 'stable') {
+        this.log.warn(
+          'signaling state is not stable, cannot create initial offer',
+          this.logContext,
+        );
+        return;
+      }
+      const offerId = this.latestOfferId + 1;
+      this.latestOfferId = offerId;
+      const offer = await this.pc.createOffer();
+      this.pendingInitialOffer = { sdp: offer.sdp, type: offer.type };
+      const sdpParsed = parse(offer.sdp ?? '');
+      sdpParsed.media.forEach((media) => {
+        ensureIPAddrMatchVersion(media);
+      });
+      offer.sdp = write(sdpParsed);
+      return { offer, offerId };
+    } finally {
+      unlock();
+    }
+  }
+
   async createAndSendOffer(options?: RTCOfferOptions) {
     const unlock = await this.offerLock.lock();
 
@@ -268,7 +305,10 @@ export default class PCTransport extends EventEmitter {
         this.restartingIce = true;
       }
 
-      if (this._pc && this._pc.signalingState === 'have-local-offer') {
+      if (
+        this._pc &&
+        (this._pc.signalingState === 'have-local-offer' || this.pendingInitialOffer)
+      ) {
         // we're waiting for the peer to accept our offer, so we'll just wait
         // the only exception to this is when ICE restart is needed
         const currentSD = this._pc.remoteDescription;

package/src/room/PCTransportManager.ts

@@ -72,7 +72,7 @@ export class PCTransportManager {
     return this._mode;
   }
 
-  constructor(rtcConfig: RTCConfiguration, mode: PCMode, loggerOptions: LoggerOptions) {
+  constructor(mode: PCMode, loggerOptions: LoggerOptions, rtcConfig?: RTCConfiguration) {
     this.log = getLogger(loggerOptions.loggerName ?? LoggerNames.PCManager);
     this.loggerOptions = loggerOptions;