feat: custom ice servers in join config (#2906)

Co-authored-by: Kaustubh Kumar <[email protected]>

packages/hms-video-store/src/index.ts

@@ -53,6 +53,7 @@ export type {
   HMSQuizLeaderboardResponse,
   HMSQuizLeaderboardSummary,
   HMSTranscriptionInfo,
+  HMSICEServer,
 } from './internal';
 
 export { EventBus } from './events/EventBus';

packages/hms-video-store/src/interfaces/config.ts

@@ -5,6 +5,13 @@ import InitialSettings from './settings';
  * @link https://docs.100ms.live/javascript/v2/features/preview
  * @link https://docs.100ms.live/javascript/v2/features/join
  */
+
+export type HMSICEServer = {
+  urls: string[];
+  userName?: string;
+  password?: string;
+};
+
 export interface HMSConfig {
   /**
    * the name of the peer, can be later accessed via peer.name and can also be changed mid call.
@@ -53,10 +60,14 @@ export interface HMSConfig {
    */
   autoManageVideo?: boolean;
   /**
-   * if this flag is enabled, wake lock will be acquired automatically(if supported) when joining the room, so the device
+   * if this flag is enabled, wake lock will be acquired automatically (if supported) when joining the room, so the device
    * will be kept awake.
    */
   autoManageWakeLock?: boolean;
+  /**
+   * use custom STUN/TURN servers for media connection (advanced)
+   */
+  iceServers?: HMSICEServer[];
 }
 
 export interface HMSMidCallPreviewConfig {

packages/hms-video-store/src/sdk/index.ts

@@ -424,6 +424,7 @@ export class HMSSdk implements HMSInterface {
           this.localPeer!.peerId,
           { name: config.userName, metaData: config.metaData || '' },
           config.autoVideoSubscribe,
+          config.iceServers,
         )
         .then((initConfig: InitConfig | void) => {
           initSuccessful = true;

packages/hms-video-store/src/signal/init/index.ts

@@ -1,6 +1,8 @@
 import { InitConfig } from './models';
 import { ErrorFactory } from '../../error/ErrorFactory';
 import { HMSAction } from '../../error/HMSAction';
+import { HMSICEServer } from '../../interfaces';
+import { transformIceServerConfig } from '../../utils/ice-server-config';
 import HMSLogger from '../../utils/logger';
 
 const TAG = '[InitService]';
@@ -26,26 +28,26 @@ export default class InitService {
     userAgent,
     initEndpoint = 'https://prod-init.100ms.live',
     region = '',
+    iceServers,
   }: {
     token: string;
     peerId: string;
     userAgent: string;
     initEndpoint?: string;
     region?: string;
+    iceServers?: HMSICEServer[];
   }): Promise<InitConfig> {
     HMSLogger.d(TAG, `fetchInitConfig: initEndpoint=${initEndpoint} token=${token} peerId=${peerId} region=${region} `);
     const url = getUrl(initEndpoint, peerId, userAgent, region);
     try {
       const response = await fetch(url, {
-        headers: {
-          Authorization: `Bearer ${token}`,
-        },
+        headers: { Authorization: `Bearer ${token}` },
       });
       try {
         const config = await response.clone().json();
         this.handleError(response, config);
         HMSLogger.d(TAG, `config is ${JSON.stringify(config, null, 2)}`);
-        return transformInitConfig(config);
+        return transformInitConfig(config, iceServers);
       } catch (err) {
         const text = await response.text();
         HMSLogger.e(TAG, 'json error', (err as Error).message, text);
@@ -78,9 +80,12 @@ export function getUrl(endpoint: string, peerId: string, userAgent: string, regi
   }
 }
 
-export function transformInitConfig(config: any): InitConfig {
+export function transformInitConfig(config: any, iceServers?: HMSICEServer[]): InitConfig {
   return {
     ...config,
-    rtcConfiguration: { ...config.rtcConfiguration, iceServers: config.rtcConfiguration?.ice_servers },
+    rtcConfiguration: {
+      ...config.rtcConfiguration,
+      iceServers: transformIceServerConfig(config.rtcConfiguration?.ice_servers, iceServers),
+    },
   };
 }

packages/hms-video-store/src/transport/index.ts

@@ -23,7 +23,7 @@ import { ErrorFactory } from '../error/ErrorFactory';
 import { HMSAction } from '../error/HMSAction';
 import { HMSException } from '../error/HMSException';
 import { EventBus } from '../events/EventBus';
-import { HMSRole } from '../interfaces';
+import { HMSICEServer, HMSRole } from '../interfaces';
 import { HMSLocalStream } from '../media/streams/HMSLocalStream';
 import { HMSLocalTrack, HMSLocalVideoTrack, HMSTrack } from '../media/tracks';
 import { TrackState } from '../notification-manager';
@@ -397,8 +397,9 @@ export default class HMSTransport {
     peerId: string,
     customData: { name: string; metaData: string },
     autoSubscribeVideo = false,
+    iceServers?: HMSICEServer[],
   ): Promise<InitConfig | void> {
-    const initConfig = await this.connect(token, endpoint, peerId, customData, autoSubscribeVideo);
+    const initConfig = await this.connect(token, endpoint, peerId, customData, autoSubscribeVideo, iceServers);
     this.state = TransportState.Preview;
     this.observer.onStateChange(this.state);
     return initConfig;
@@ -447,6 +448,7 @@ export default class HMSTransport {
     peerId: string,
     customData: { name: string; metaData: string },
     autoSubscribeVideo = false,
+    iceServers?: HMSICEServer[],
   ): Promise<InitConfig | void> {
     this.setTransportStateForConnect();
     this.joinParameters = new JoinParameters(
@@ -456,9 +458,10 @@ export default class HMSTransport {
       customData.metaData,
       endpoint,
       autoSubscribeVideo,
+      iceServers,
     );
     try {
-      const response = await this.internalConnect(token, endpoint, peerId);
+      const response = await this.internalConnect(token, endpoint, peerId, iceServers);
       return response;
     } catch (error) {
       const shouldRetry =
@@ -474,7 +477,7 @@ export default class HMSTransport {
 
       if (shouldRetry) {
         const task = async () => {
-          await this.internalConnect(token, endpoint, peerId);
+          await this.internalConnect(token, endpoint, peerId, iceServers);
           return Boolean(this.initConfig && this.initConfig.endpoint);
         };
 
@@ -898,7 +901,7 @@ export default class HMSTransport {
     }
   }
 
-  private async internalConnect(token: string, initEndpoint: string, peerId: string) {
+  private async internalConnect(token: string, initEndpoint: string, peerId: string, iceServers?: HMSICEServer[]) {
     HMSLogger.d(TAG, 'connect: started ⏰');
     const connectRequestedAt = new Date();
     try {
@@ -908,6 +911,7 @@ export default class HMSTransport {
         peerId,
         userAgent: this.store.getUserAgent(),
         initEndpoint,
+        iceServers,
       });
       const room = this.store.getRoom();
       if (room) {
@@ -1093,6 +1097,7 @@ export default class HMSTransport {
         this.joinParameters!.authToken,
         this.joinParameters!.endpoint,
         this.joinParameters!.peerId,
+        this.joinParameters!.iceServers,
       );
     }
 

packages/hms-video-store/src/transport/models/JoinParameters.ts

@@ -1,3 +1,5 @@
+import { HMSICEServer } from '../../interfaces';
+
 export class JoinParameters {
   constructor(
     public authToken: string,
@@ -6,5 +8,6 @@ export class JoinParameters {
     public data: string = '',
     public endpoint: string = 'https://prod-init.100ms.live/init',
     public autoSubscribeVideo: boolean = false,
+    public iceServers?: HMSICEServer[],
   ) {}
 }

packages/hms-video-store/src/utils/ice-server-config.ts

@@ -0,0 +1,11 @@
+import { HMSICEServer } from '../interfaces';
+
+export const transformIceServerConfig = (defaultConfig?: RTCIceServer[], iceServers?: HMSICEServer[]) => {
+  if (!iceServers || iceServers.length === 0) {
+    return defaultConfig;
+  }
+  const transformedIceServers = iceServers.map(server => {
+    return { urls: server.urls, credentialType: 'password', credential: server.password, username: server.userName };
+  });
+  return transformedIceServers;
+};

packages/react-sdk/src/hooks/usePreviewJoin.ts

@@ -1,6 +1,7 @@
 import { useCallback, useMemo } from 'react';
 import {
   HMSConfigInitialSettings,
+  HMSICEServer,
   HMSPreviewConfig,
   HMSRoomState,
   selectIsConnectedToRoom,
@@ -51,6 +52,11 @@ export interface usePreviewInput {
    * will be kept awake.
    */
   autoManageWakeLock?: boolean;
+
+  /**
+   * use custom STUN/TURN servers for media connection (advanced)
+   */
+  iceServers?: HMSICEServer[];
 }
 
 export interface usePreviewResult {
@@ -90,6 +96,7 @@ export const usePreviewJoin = ({
   asRole,
   autoManageVideo,
   autoManageWakeLock,
+  iceServers,
 }: usePreviewInput): usePreviewResult => {
   const actions = useHMSActions();
   const roomState = useHMSStore(selectRoomState);
@@ -108,6 +115,7 @@ export const usePreviewJoin = ({
       captureNetworkQualityInPreview,
       autoManageVideo,
       autoManageWakeLock,
+      iceServers,
     };
   }, [
     name,
@@ -119,6 +127,7 @@ export const usePreviewJoin = ({
     asRole,
     autoManageVideo,
     autoManageWakeLock,
+    iceServers,
   ]);
 
   const preview = useCallback(async () => {

yarn.lock

@@ -17981,4 +17981,4 @@ [email protected]:
 zustand@^3.6.2:
   version "3.7.2"
   resolved "https://registry.yarnpkg.com/zustand/-/zustand-3.7.2.tgz#7b44c4f4a5bfd7a8296a3957b13e1c346f42514d"
-  integrity sha512-PIJDIZKtokhof+9+60cpockVOq05sJzHCriyvaLBmEJixseQ1a5Kdov6fWZfWOu5SK9c+FhH1jU0tntLxRJYMA==
+  integrity sha512-PIJDIZKtokhof+9+60cpockVOq05sJzHCriyvaLBmEJixseQ1a5Kdov6fWZfWOu5SK9c+FhH1jU0tntLxRJYMA==