@stream-io/video-client 1.26.1 → 1.27.0

package/dist/index.cjs.js

@@ -973,6 +973,10 @@ var ErrorCode;
      * @generated from protobuf enum value: ERROR_CODE_CALL_NOT_FOUND = 300;
      */
     ErrorCode[ErrorCode["CALL_NOT_FOUND"] = 300] = "CALL_NOT_FOUND";
+    /**
+     * @generated from protobuf enum value: ERROR_CODE_CALL_PARTICIPANT_LIMIT_REACHED = 301;
+     */
+    ErrorCode[ErrorCode["CALL_PARTICIPANT_LIMIT_REACHED"] = 301] = "CALL_PARTICIPANT_LIMIT_REACHED";
     /**
      * @generated from protobuf enum value: ERROR_CODE_REQUEST_VALIDATION_FAILED = 400;
      */
@@ -1241,6 +1245,24 @@ var AppleThermalState;
      */
     AppleThermalState[AppleThermalState["CRITICAL"] = 4] = "CRITICAL";
 })(AppleThermalState || (AppleThermalState = {}));
+/**
+ * ClientCapability defines a feature that client supports
+ *
+ * @generated from protobuf enum stream.video.sfu.models.ClientCapability
+ */
+var ClientCapability;
+(function (ClientCapability) {
+    /**
+     * @generated from protobuf enum value: CLIENT_CAPABILITY_UNSPECIFIED = 0;
+     */
+    ClientCapability[ClientCapability["UNSPECIFIED"] = 0] = "UNSPECIFIED";
+    /**
+     * Enables SFU pausing inbound video
+     *
+     * @generated from protobuf enum value: CLIENT_CAPABILITY_SUBSCRIBER_VIDEO_PAUSE = 1;
+     */
+    ClientCapability[ClientCapability["SUBSCRIBER_VIDEO_PAUSE"] = 1] = "SUBSCRIBER_VIDEO_PAUSE";
+})(ClientCapability || (ClientCapability = {}));
 // @generated message type with reflection information, may provide speed optimized methods
 class CallState$Type extends runtime.MessageType {
     constructor() {
@@ -1911,6 +1933,7 @@ var models = /*#__PURE__*/Object.freeze({
     get CallEndedReason () { return CallEndedReason; },
     CallGrants: CallGrants,
     CallState: CallState$1,
+    get ClientCapability () { return ClientCapability; },
     ClientDetails: ClientDetails,
     Codec: Codec,
     get ConnectionQuality () { return ConnectionQuality; },
@@ -2600,6 +2623,13 @@ class SfuEvent$Type extends runtime.MessageType {
                 oneof: 'eventPayload',
                 T: () => ChangePublishOptions,
             },
+            {
+                no: 28,
+                name: 'inbound_state_notification',
+                kind: 'message',
+                oneof: 'eventPayload',
+                T: () => InboundStateNotification,
+            },
         ]);
     }
 }
@@ -2907,6 +2937,17 @@ class JoinRequest$Type extends runtime.MessageType {
                 repeat: 2 /*RepeatType.UNPACKED*/,
                 T: () => SubscribeOption,
             },
+            {
+                no: 11,
+                name: 'capabilities',
+                kind: 'enum',
+                repeat: 1 /*RepeatType.PACKED*/,
+                T: () => [
+                    'stream.video.sfu.models.ClientCapability',
+                    ClientCapability,
+                    'CLIENT_CAPABILITY_',
+                ],
+            },
         ]);
     }
 }
@@ -3352,6 +3393,48 @@ class CallEnded$Type extends runtime.MessageType {
  * @generated MessageType for protobuf message stream.video.sfu.event.CallEnded
  */
 const CallEnded = new CallEnded$Type();
+// @generated message type with reflection information, may provide speed optimized methods
+class InboundStateNotification$Type extends runtime.MessageType {
+    constructor() {
+        super('stream.video.sfu.event.InboundStateNotification', [
+            {
+                no: 1,
+                name: 'inbound_video_states',
+                kind: 'message',
+                repeat: 2 /*RepeatType.UNPACKED*/,
+                T: () => InboundVideoState,
+            },
+        ]);
+    }
+}
+/**
+ * @generated MessageType for protobuf message stream.video.sfu.event.InboundStateNotification
+ */
+const InboundStateNotification = new InboundStateNotification$Type();
+// @generated message type with reflection information, may provide speed optimized methods
+class InboundVideoState$Type extends runtime.MessageType {
+    constructor() {
+        super('stream.video.sfu.event.InboundVideoState', [
+            { no: 1, name: 'user_id', kind: 'scalar', T: 9 /*ScalarType.STRING*/ },
+            { no: 2, name: 'session_id', kind: 'scalar', T: 9 /*ScalarType.STRING*/ },
+            {
+                no: 3,
+                name: 'track_type',
+                kind: 'enum',
+                T: () => [
+                    'stream.video.sfu.models.TrackType',
+                    TrackType,
+                    'TRACK_TYPE_',
+                ],
+            },
+            { no: 4, name: 'paused', kind: 'scalar', T: 8 /*ScalarType.BOOL*/ },
+        ]);
+    }
+}
+/**
+ * @generated MessageType for protobuf message stream.video.sfu.event.InboundVideoState
+ */
+const InboundVideoState = new InboundVideoState$Type();
 
 var events = /*#__PURE__*/Object.freeze({
     __proto__: null,
@@ -3372,6 +3455,8 @@ var events = /*#__PURE__*/Object.freeze({
     HealthCheckResponse: HealthCheckResponse,
     ICERestart: ICERestart,
     ICETrickle: ICETrickle,
+    InboundStateNotification: InboundStateNotification,
+    InboundVideoState: InboundVideoState,
     JoinRequest: JoinRequest,
     JoinResponse: JoinResponse,
     LeaveCallRequest: LeaveCallRequest,
@@ -3796,6 +3881,7 @@ const sfuEventKinds = {
     participantUpdated: undefined,
     participantMigrationComplete: undefined,
     changePublishOptions: undefined,
+    inboundStateNotification: undefined,
 };
 const isSfuEvent = (eventName) => {
     return Object.prototype.hasOwnProperty.call(sfuEventKinds, eventName);
@@ -3804,12 +3890,12 @@ class Dispatcher {
     constructor() {
         this.logger = getLogger(['Dispatcher']);
         this.subscribers = {};
-        this.dispatch = (message, logTag = '0') => {
+        this.dispatch = (message, tag = '0') => {
             const eventKind = message.eventPayload.oneofKind;
             if (!eventKind)
                 return;
             const payload = message.eventPayload[eventKind];
-            this.logger('debug', `Dispatching ${eventKind}, tag=${logTag}`, payload);
+            this.logger('debug', `Dispatching ${eventKind}, tag=${tag}`, payload);
             const listeners = this.subscribers[eventKind];
             if (!listeners)
                 return;
@@ -4326,6 +4412,24 @@ const hasScreenShareAudio = (p) => p.publishedTracks.includes(TrackType.SCREEN_S
  * @param p the participant.
  */
 const isPinned = (p) => !!p.pin && (p.pin.isLocalPin || p.pin.pinnedAt > 0);
+/**
+ * Check if a participant has a paused track of the specified type.
+ *
+ * @param p the participant to check.
+ * @param videoTrackType the type of video track to check for ('videoTrack' or 'screenShareTrack').
+ */
+const hasPausedTrack = (p, videoTrackType) => {
+    if (!p.pausedTracks)
+        return false;
+    const trackType = videoTrackType === 'videoTrack'
+        ? TrackType.VIDEO
+        : videoTrackType === 'screenShareTrack'
+            ? TrackType.SCREEN_SHARE
+            : undefined;
+    if (!trackType)
+        return false;
+    return p.pausedTracks.includes(trackType);
+};
 
 /**
  * A comparator which sorts participants by the fact that they are the dominant speaker or not.
@@ -4728,17 +4832,17 @@ class CallState {
          *
          * @param sessionId the session ID of the participant to update.
          * @param participant the participant to update or add.
+         * @param patch an optional patch to apply to the participant.
          */
-        this.updateOrAddParticipant = (sessionId, participant) => {
+        this.updateOrAddParticipant = (sessionId, participant, patch) => {
             return this.setParticipants((participants) => {
                 let add = true;
                 const nextParticipants = participants.map((p) => {
                     if (p.sessionId === sessionId) {
                         add = false;
-                        return {
-                            ...p,
-                            ...participant,
-                        };
+                        const updated = { ...p, ...participant };
+                        const thePatch = typeof patch === 'function' ? patch(updated) : patch;
+                        return Object.assign(updated, thePatch);
                     }
                     return p;
                 });
@@ -5812,7 +5916,7 @@ const aggregate = (stats) => {
     return report;
 };
 
-const version = "1.26.1";
+const version = "1.27.0";
 const [major, minor, patch] = version.split('.');
 let sdkInfo = {
     type: SdkType.PLAIN_JAVASCRIPT,
@@ -6421,7 +6525,7 @@ class BasePeerConnection {
     /**
      * Constructs a new `BasePeerConnection` instance.
      */
-    constructor(peerType, { sfuClient, connectionConfig, state, dispatcher, onReconnectionNeeded, logTag, enableTracing, iceRestartDelay = 2500, }) {
+    constructor(peerType, { sfuClient, connectionConfig, state, dispatcher, onReconnectionNeeded, tag, enableTracing, iceRestartDelay = 2500, }) {
         this.isIceRestarting = false;
         this.isDisposed = false;
         this.trackIdToTrackType = new Map();
@@ -6645,13 +6749,12 @@ class BasePeerConnection {
         this.onReconnectionNeeded = onReconnectionNeeded;
         this.logger = getLogger([
             peerType === PeerType.SUBSCRIBER ? 'Subscriber' : 'Publisher',
-            logTag,
+            tag,
         ]);
         this.pc = this.createPeerConnection(connectionConfig);
         this.stats = new StatsTracer(this.pc, peerType, this.trackIdToTrackType);
         if (enableTracing) {
-            const tag = `${logTag}-${peerType === PeerType.SUBSCRIBER ? 'sub' : 'pub'}`;
-            this.tracer = new Tracer(tag);
+            this.tracer = new Tracer(`${tag}-${peerType === PeerType.SUBSCRIBER ? 'sub' : 'pub'}`);
             this.tracer.trace('create', {
                 url: sfuClient.edgeName,
                 ...connectionConfig,
@@ -7523,8 +7626,8 @@ class Subscriber extends BasePeerConnection {
 }
 
 const createWebSocketSignalChannel = (opts) => {
-    const { endpoint, onMessage, logTag } = opts;
-    const logger = getLogger(['SfuClientWS', logTag]);
+    const { endpoint, onMessage, tag } = opts;
+    const logger = getLogger(['SfuClientWS', tag]);
     logger('debug', 'Creating signaling WS channel:', endpoint);
     const ws = new WebSocket(endpoint);
     ws.binaryType = 'arraybuffer'; // do we need this?
@@ -7774,7 +7877,7 @@ class StreamSfuClient {
     /**
      * Constructs a new SFU client.
      */
-    constructor({ dispatcher, credentials, sessionId, logTag, joinResponseTimeout = 5000, onSignalClose, streamClient, enableTracing, }) {
+    constructor({ dispatcher, credentials, sessionId, cid, tag, joinResponseTimeout = 5000, onSignalClose, streamClient, enableTracing, }) {
         /**
          * A buffer for ICE Candidates that are received before
          * the Publisher and Subscriber Peer Connections are ready to handle them.
@@ -7804,7 +7907,7 @@ class StreamSfuClient {
          * A controller to abort the current requests.
          */
         this.abortController = new AbortController();
-        this.createWebSocket = () => {
+        this.createWebSocket = (params) => {
             const eventsToTrace = {
                 callEnded: true,
                 changePublishQuality: true,
@@ -7812,10 +7915,11 @@ class StreamSfuClient {
                 connectionQualityChanged: true,
                 error: true,
                 goAway: true,
+                inboundStateNotification: true,
             };
             this.signalWs = createWebSocketSignalChannel({
-                logTag: this.logTag,
-                endpoint: `${this.credentials.server.ws_endpoint}?tag=${this.logTag}`,
+                tag: this.tag,
+                endpoint: `${this.credentials.server.ws_endpoint}?${new URLSearchParams(params).toString()}`,
                 onMessage: (message) => {
                     this.lastMessageTimestamp = new Date();
                     this.scheduleConnectionCheck();
@@ -7823,7 +7927,7 @@ class StreamSfuClient {
                     if (eventsToTrace[eventKind]) {
                         this.tracer?.trace(eventKind, message);
                     }
-                    this.dispatcher.dispatch(message, this.logTag);
+                    this.dispatcher.dispatch(message, this.tag);
                 },
             });
             this.signalReady = makeSafePromise(Promise.race([
@@ -7938,7 +8042,7 @@ class StreamSfuClient {
             });
             this.migrateAwayTimeout = setTimeout(() => {
                 unsubscribe();
-                task.reject(new Error(`Migration (${this.logTag}) failed to complete in ${timeout}ms`));
+                task.reject(new Error(`Migration (${this.tag}) failed to complete in ${timeout}ms`));
             }, timeout);
             return task.promise;
         };
@@ -8038,10 +8142,10 @@ class StreamSfuClient {
         const { server, token } = credentials;
         this.edgeName = server.edge_name;
         this.joinResponseTimeout = joinResponseTimeout;
-        this.logTag = logTag;
-        this.logger = getLogger(['SfuClient', logTag]);
+        this.tag = tag;
+        this.logger = getLogger(['SfuClient', tag]);
         this.tracer = enableTracing
-            ? new Tracer(`${logTag}-${this.edgeName}`)
+            ? new Tracer(`${tag}-${this.edgeName}`)
             : undefined;
         this.rpc = createSignalClient({
             baseUrl: server.url,
@@ -8070,7 +8174,13 @@ class StreamSfuClient {
                 this.networkAvailableTask?.resolve();
             }
         });
-        this.createWebSocket();
+        this.createWebSocket({
+            attempt: tag,
+            user_id: streamClient.user?.id || '',
+            api_key: streamClient.key,
+            user_session_id: this.sessionId,
+            cid,
+        });
     }
     get isHealthy() {
         return (this.signalWs.readyState === WebSocket.OPEN &&
@@ -8230,6 +8340,36 @@ const watchCallGrantsUpdated = (state) => {
     };
 };
 
+/**
+ * Adds unique values to an array.
+ *
+ * @param arr the array to add to.
+ * @param values the values to add.
+ */
+const pushToIfMissing = (arr, ...values) => {
+    for (const v of values) {
+        if (!arr.includes(v)) {
+            arr.push(v);
+        }
+    }
+    return arr;
+};
+/**
+ * Removes values from an array if they are present.
+ *
+ * @param arr the array to remove from.
+ * @param values the values to remove.
+ */
+const removeFromIfPresent = (arr, ...values) => {
+    for (const v of values) {
+        const index = arr.indexOf(v);
+        if (index !== -1) {
+            arr.splice(index, 1);
+        }
+    }
+    return arr;
+};
+
 const watchConnectionQualityChanged = (dispatcher, state) => {
     return dispatcher.on('connectionQualityChanged', (e) => {
         const { connectionQualityUpdates } = e;
@@ -8296,6 +8436,29 @@ const watchPinsUpdated = (state) => {
         state.setServerSidePins(pins);
     };
 };
+/**
+ * Watches for inbound state notifications and updates the paused tracks
+ *
+ * @param state the call state to update.
+ */
+const watchInboundStateNotification = (state) => {
+    return function onInboundStateNotification(e) {
+        const { inboundVideoStates } = e;
+        const current = state.getParticipantLookupBySessionId();
+        const patches = {};
+        for (const { sessionId, trackType, paused } of inboundVideoStates) {
+            const pausedTracks = [...(current[sessionId]?.pausedTracks ?? [])];
+            if (paused) {
+                pushToIfMissing(pausedTracks, trackType);
+            }
+            else {
+                removeFromIfPresent(pausedTracks, trackType);
+            }
+            patches[sessionId] = { pausedTracks };
+        }
+        state.updateParticipants(patches);
+    };
+};
 
 /**
  * An event handler that handles soft mutes.
@@ -8332,21 +8495,6 @@ const handleRemoteSoftMute = (call) => {
     });
 };
 
-/**
- * Adds unique values to an array.
- *
- * @param arr the array to add to.
- * @param values the values to add.
- */
-const pushToIfMissing = (arr, ...values) => {
-    for (const v of values) {
-        if (!arr.includes(v)) {
-            arr.push(v);
-        }
-    }
-    return arr;
-};
-
 /**
  * An event responder which handles the `participantJoined` event.
  */
@@ -8428,11 +8576,14 @@ const watchTrackUnpublished = (state) => {
         if (e.participant) {
             const orphanedTracks = reconcileOrphanedTracks(state, e.participant);
             const participant = Object.assign(e.participant, orphanedTracks);
-            state.updateOrAddParticipant(sessionId, participant);
+            state.updateOrAddParticipant(sessionId, participant, (p) => ({
+                pausedTracks: p.pausedTracks?.filter((t) => t !== type),
+            }));
         }
         else {
             state.updateParticipant(sessionId, (p) => ({
                 publishedTracks: p.publishedTracks.filter((t) => t !== type),
+                pausedTracks: p.pausedTracks?.filter((t) => t !== type),
             }));
         }
     };
@@ -8524,6 +8675,7 @@ const registerEventHandlers = (call, dispatcher) => {
         watchDominantSpeakerChanged(dispatcher, state),
         call.on('callGrantsUpdated', watchCallGrantsUpdated(state)),
         call.on('pinsUpdated', watchPinsUpdated(state)),
+        call.on('inboundStateNotification', watchInboundStateNotification(state)),
         handleRemoteSoftMute(call),
     ];
     if (call.ringing) {
@@ -11257,6 +11409,12 @@ class Call {
          */
         this.leaveCallHooks = new Set();
         this.streamClientEventHandlers = new Map();
+        /**
+         * A list of capabilities that the client supports and are enabled.
+         */
+        this.clientCapabilities = new Set([
+            ClientCapability.SUBSCRIBER_VIDEO_PAUSE,
+        ]);
         /**
          * Sets up the call instance.
          *
@@ -11665,14 +11823,27 @@ class Call {
                 throw new Error(`Illegal State: call.join() shall be called only once`);
             }
             this.state.setCallingState(exports.CallingState.JOINING);
+            // we will count the number of join failures per SFU.
+            // once the number of failures reaches 2, we will piggyback on the `migrating_from`
+            // field to force the coordinator to provide us another SFU
+            const sfuJoinFailures = new Map();
+            const joinData = data;
             maxJoinRetries = Math.max(maxJoinRetries, 1);
             for (let attempt = 0; attempt < maxJoinRetries; attempt++) {
                 try {
                     this.logger('trace', `Joining call (${attempt})`, this.cid);
-                    return await this.doJoin(data);
+                    await this.doJoin(data);
+                    delete joinData.migrating_from;
+                    break;
                 }
                 catch (err) {
                     this.logger('warn', `Failed to join call (${attempt})`, this.cid);
+                    const sfuId = this.credentials?.server.edge_name || '';
+                    const failures = (sfuJoinFailures.get(sfuId) || 0) + 1;
+                    sfuJoinFailures.set(sfuId, failures);
+                    if (failures >= 2) {
+                        joinData.migrating_from = sfuId;
+                    }
                     if (attempt === maxJoinRetries - 1) {
                         // restore the previous call state if the join-flow fails
                         this.state.setCallingState(callingState);
@@ -11722,7 +11893,8 @@ class Call {
             const isWsHealthy = !!previousSfuClient?.isHealthy;
             const sfuClient = performingRejoin || performingMigration || !isWsHealthy
                 ? new StreamSfuClient({
-                    logTag: String(++this.sfuClientTag),
+                    tag: String(this.sfuClientTag++),
+                    cid: this.cid,
                     dispatcher: this.dispatcher,
                     credentials: this.credentials,
                     streamClient: this.streamClient,
@@ -11764,6 +11936,7 @@ class Call {
                         reconnectDetails,
                         preferredPublishOptions,
                         preferredSubscribeOptions,
+                        capabilities: Array.from(this.clientCapabilities),
                     });
                     this.currentPublishOptions = publishOptions;
                     this.fastReconnectDeadlineSeconds = fastReconnectDeadlineSeconds;
@@ -11936,7 +12109,7 @@ class Call {
                 dispatcher: this.dispatcher,
                 state: this.state,
                 connectionConfig,
-                logTag: String(this.sfuClientTag),
+                tag: sfuClient.tag,
                 enableTracing,
                 onReconnectionNeeded: (kind, reason) => {
                     this.reconnect(kind, reason).catch((err) => {
@@ -11958,7 +12131,7 @@ class Call {
                     state: this.state,
                     connectionConfig,
                     publishOptions,
-                    logTag: String(this.sfuClientTag),
+                    tag: sfuClient.tag,
                     enableTracing,
                     onReconnectionNeeded: (kind, reason) => {
                         this.reconnect(kind, reason).catch((err) => {
@@ -13122,6 +13295,22 @@ class Call {
         this.setDisconnectionTimeout = (timeoutSeconds) => {
             this.disconnectionTimeoutSeconds = timeoutSeconds;
         };
+        /**
+         * Enables the provided client capabilities.
+         */
+        this.enableClientCapabilities = (...capabilities) => {
+            for (const capability of capabilities) {
+                this.clientCapabilities.add(capability);
+            }
+        };
+        /**
+         * Disables the provided client capabilities.
+         */
+        this.disableClientCapabilities = (...capabilities) => {
+            for (const capability of capabilities) {
+                this.clientCapabilities.delete(capability);
+            }
+        };
         this.type = type;
         this.id = id;
         this.cid = `${type}:${id}`;
@@ -13287,7 +13476,6 @@ class StableWSConnection {
         this.onmessage = (wsID, event) => {
             if (this.wsID !== wsID)
                 return;
-            this._log('onmessage() - onmessage callback', { event, wsID });
             const data = typeof event.data === 'string'
                 ? JSON.parse(event.data)
                 : null;
@@ -14301,7 +14489,7 @@ class StreamClient {
         this.getUserAgent = () => {
             if (!this.cachedUserAgent) {
                 const { clientAppIdentifier = {} } = this.options;
-                const { sdkName = 'js', sdkVersion = "1.26.1", ...extras } = clientAppIdentifier;
+                const { sdkName = 'js', sdkVersion = "1.27.0", ...extras } = clientAppIdentifier;
                 this.cachedUserAgent = [
                     `stream-video-${sdkName}-v${sdkVersion}`,
                     ...Object.entries(extras).map(([key, value]) => `${key}=${value}`),
@@ -14931,6 +15119,7 @@ exports.getVideoDevices = getVideoDevices;
 exports.getVideoStream = getVideoStream;
 exports.getWebRTCInfo = getWebRTCInfo;
 exports.hasAudio = hasAudio;
+exports.hasPausedTrack = hasPausedTrack;
 exports.hasScreenShare = hasScreenShare;
 exports.hasScreenShareAudio = hasScreenShareAudio;
 exports.hasVideo = hasVideo;