matrix-js-sdk 43.0.0 → 44.0.0

package/src/matrixrtc/IMembershipManager.ts

@@ -50,15 +50,6 @@ export interface IMembershipManager extends TypedEventEmitter<
     MembershipManagerEvent,
     MembershipManagerEventHandlerMap
 > {
-    /**
-     * If we are trying to join, or have successfully joined the session.
-     * It does not reflect if the room state is already configured to represent us being joined.
-     * It only means that the Manager should be trying to connect or to disconnect running.
-     * The Manager is still running right after isJoined becomes false to send the disconnect events.
-     * @returns true if we intend to be participating in the MatrixRTC session
-     * @deprecated This name is confusing and replaced by `isActivated()`. (Returns the same as `isActivated()`)
-     */
-    isJoined(): boolean;
     /**
      * If the manager is activated. This means it tries to do its job to join the call, resend state events...
      * It does not imply that the room state is already configured to represent being joined.
@@ -92,14 +83,10 @@ export interface IMembershipManager extends TypedEventEmitter<
 
     /**
      * Start sending all necessary events to make this user participate in the RTC session.
-     * @param fociPreferred the list of preferred foci to use in the joined RTC membership event.
-     * If multiSfuFocus is set, this is only needed if this client wants to publish to multiple transports simultaneously.
-     * @param multiSfuFocus the active focus to use in the joined RTC membership event. Setting this implies the
-     * membership manager will operate in a multi-SFU connection mode. If `undefined`, an `oldest_membership`
-     * transport selection will be used instead.
+     * @param publishedTransports the list of transports on which the member is publishing.
      * @throws can throw if it exceeds a configured maximum retry.
      */
-    join(fociPreferred: Transport[], multiSfuFocus?: Transport, onError?: (error: unknown) => void): void;
+    join(publishedTransports: Transport[], onError?: (error: unknown) => void): void;
     /**
      * Send all necessary events to make this user leave the RTC session.
      * @param timeout the maximum duration in ms until the promise is forced to resolve.

package/src/matrixrtc/LivekitTransport.ts

@@ -16,20 +16,69 @@ limitations under the License.
 
 import { type Transport } from "./types.ts";
 
-export interface LivekitTransportConfig extends Transport {
+/**
+ * @deprecated Use {@link UnstableLivekitTransport} instead, which has multiple
+ *   variants to support the migration to newer versions of MSC4195.
+ */
+export interface LivekitTransport extends Transport {
     type: "livekit";
     livekit_service_url: string;
 }
 
-export const isLivekitTransportConfig = (object: any): object is LivekitTransportConfig =>
-    object.type === "livekit" && "livekit_service_url" in object;
+/**
+ * @deprecated Use {@link isUnstableLivekitTransport} instead.
+ */
+export const isLivekitTransport = (object: unknown): object is LivekitTransport => {
+    if (typeof object !== "object" || object === null) return false;
+    const transport = object as Transport;
 
-export interface LivekitTransport extends LivekitTransportConfig {
-    livekit_alias: string;
-}
+    return transport.type === "livekit" && typeof transport.livekit_service_url === "string";
+};
+
+type WebsocketUrl = {
+    /**
+     * WebSocket URL of the LiveKit server.
+     */
+    url: string;
+};
 
-export const isLivekitTransport = (object: any): object is LivekitTransport =>
-    isLivekitTransportConfig(object) && "livekit_alias" in object;
+type ServiceUrl = {
+    /**
+     * Base URL of the LiveKit JWT service.
+     */
+    livekit_service_url: string;
+};
+
+/**
+ * Any LiveKit transport that can be advertised by a homeserver or published by
+ * a session member in unstable MSC4195 implementations: `url` only,
+ * `livekit_service_url` only, or both during the migration.
+ */
+export type UnstableLivekitTransport =
+    // Latest MSC4195 variant, with `url`. Indicates that both publishers and
+    // subscribers will use the /_matrix/client/v1/rtc/livekit/get_token
+    // endpoint.
+    | ({ type: "livekit" } & WebsocketUrl)
+    // Legacy variant, with `livekit_service_url`. Indicates that both
+    // publishers and subscribers will use the endpoints of the provided LiveKit
+    // JWT service.
+    | ({ type: "livekit" } & ServiceUrl)
+    // Transitional variant, with both `url` and `livekit_service_url`.
+    // Indicates that both publishers and subscribers may use either the
+    // /_matrix/client/v1/rtc/livekit/get_token endpoint or the provided LiveKit
+    // JWT service.
+    | ({ type: "livekit" } & WebsocketUrl & ServiceUrl);
+
+export const isUnstableLivekitTransport = (object: unknown): object is UnstableLivekitTransport => {
+    if (typeof object !== "object" || object === null) return false;
+    const transport = object as Transport;
+
+    if (transport.type !== "livekit") return false;
+    if (!("url" in transport || "livekit_service_url" in transport)) return false;
+    if ("url" in transport && typeof transport.url !== "string") return false;
+    if ("livekit_service_url" in transport && typeof transport.livekit_service_url !== "string") return false;
+    return true;
+};
 
 /**
  * @deprecated this is just needed for the old focus active / focus fields of a call membership.
@@ -37,7 +86,7 @@ export const isLivekitTransport = (object: any): object is LivekitTransport =>
  */
 export interface LivekitFocusSelection extends Transport {
     type: "livekit";
-    focus_selection: "oldest_membership" | "multi_sfu";
+    focus_selection: "multi_sfu";
 }
 /**
  * @deprecated see LivekitFocusSelection

package/src/matrixrtc/MatrixRTCSession.ts

@@ -33,6 +33,7 @@ import type {
     Status,
     IRTCNotificationContent,
     RTCCallIntent,
+    RTCCallCapability,
     Transport,
     SlotDescription,
     RtcSlotEventContent,
@@ -83,7 +84,7 @@ export type MatrixRTCSessionEventHandlerMap = {
         key: Uint8Array<ArrayBuffer>,
         encryptionKeyIndex: number,
         membership: CallMembershipIdentityParts,
-        rtcBackendIdentity: string,
+        backendIdentity: string,
     ) => void;
     [MatrixRTCSessionEvent.MembershipManagerError]: (error: unknown) => void;
     [MatrixRTCSessionEvent.DidSendCallNotification]: (
@@ -104,11 +105,16 @@ export interface SessionConfig {
      */
     callIntent?: RTCCallIntent;
 
+    /**
+     * What kinds of media this device is capable of handling for the call.
+     */
+    callCapabilities?: RTCCallCapability[];
+
     /**
      * Application-specific data to publish in our membership alongside the
-     * application `type` and `m.call.intent`: in the `application` object of
-     * an `m.rtc.member` event, or at the top level of a legacy `m.call.member`
-     * one. Keys should be namespaced. Read back through
+     * application `type`, `m.call.intent` and `capabilities`: in the `application`
+     * object of an `m.rtc.member` event, or at the top level of a legacy
+     * `m.call.member` one. Keys should be namespaced. Read back through
      * {@link CallMembership.applicationData}.
      */
     applicationData?: Record<string, unknown>;
@@ -202,12 +208,6 @@ export interface EncryptionConfig {
      *  media keys for other participants become available.
      */
     manageMediaKeys?: boolean;
-    /**
-     * The minimum time (in milliseconds) between each attempt to send encryption key(s).
-     * e.g. if this is set to 1000, then we will send at most one key event every second.
-     * @deprecated - Not used by the new encryption manager.
-     */
-    updateEncryptionKeyThrottle?: number;
 
     /**
      * Sometimes it is necessary to rotate the encryption key after a membership update.
@@ -331,16 +331,6 @@ export class MatrixRTCSession extends TypedEventEmitter<
         return this.encryptionManager?.isKeyRotationSuppressed ?? false;
     }
 
-    /**
-     * The callId (sessionId) of the call.
-     *
-     * It can be undefined since the callId is only known once the first membership joins.
-     * The callId is the property that, per definition, groups memberships into one call.
-     * @deprecated use `slotId` instead.
-     */
-    public get callId(): string | undefined {
-        return this.slotDescription?.id;
-    }
     /**
      * The slotId of the call.
      * `{application}#{appSpecificId}`
@@ -550,12 +540,12 @@ export class MatrixRTCSession extends TypedEventEmitter<
         this.initialMembershipCalculated = this.ensureRecalculateSessionMembers();
         this.setExpiryTimer();
     }
+
     /*
      * Returns true if we intend to be participating in the MatrixRTC session.
-     * This is determined by checking if the relativeExpiry has been set.
      */
     public isJoined(): boolean {
-        return this.membershipManager?.isJoined() ?? false;
+        return this.membershipManager?.isActivated() ?? false;
     }
 
     /**
@@ -582,22 +572,15 @@ export class MatrixRTCSession extends TypedEventEmitter<
      * Announces this user and device as joined to the MatrixRTC session,
      * and continues to update the membership event to keep it valid until
      * leaveRoomSession() is called
-     * This will not subscribe to updates: remember to call subscribe() separately if
-     * desired.
      * This method will return immediately and the session will be joined in the background.
      * @param ownMembershipIdentity the identity of the user and device joining the session.
      * This will be put into the content.member.
-     * @param fociPreferred the list of preferred foci to use in the joined RTC membership event.
-     * If multiSfuFocus is set, this is only needed if this client wants to publish to multiple transports simultaneously.
-     * @param multiSfuFocus the active focus to use in the joined RTC membership event. Setting this implies the
-     * membership manager will operate in a multi-SFU connection mode. If `undefined`, an `oldest_membership`
-     * transport selection will be used instead.
+     * @param publishedTransports the list of transports on which the member is publishing.
      * @param joinConfig - Additional configuration for the joined session.
      */
-    public joinRTCSession(
+    public join(
         ownMembershipIdentity: CallMembershipIdentityParts,
-        fociPreferred: Transport[],
-        multiSfuFocus?: Transport,
+        publishedTransports: Transport[],
         joinConfig?: JoinSessionConfig,
     ): void {
         if (this.isJoined()) {
@@ -632,14 +615,14 @@ export class MatrixRTCSession extends TypedEventEmitter<
                     keyBin: Uint8Array<ArrayBuffer>,
                     encryptionKeyIndex: number,
                     membership: CallMembershipIdentityParts,
-                    rtcBackendIdentity: string,
+                    backendIdentity: string,
                 ) => {
                     this.emit(
                         MatrixRTCSessionEvent.EncryptionKeyChanged,
                         keyBin,
                         encryptionKeyIndex,
                         membership,
-                        rtcBackendIdentity,
+                        backendIdentity,
                     );
                 },
                 this.logger,
@@ -650,45 +633,25 @@ export class MatrixRTCSession extends TypedEventEmitter<
         this.pendingNotificationToSend = this.joinConfig?.notificationType;
 
         // Join!
-        this.membershipManager.join(fociPreferred, multiSfuFocus, (e) => {
+        this.membershipManager.join(publishedTransports, (e) => {
             this.logger.error("MembershipManager encountered an unrecoverable error: ", e);
             this.emit(MatrixRTCSessionEvent.MembershipManagerError, e);
             this.emit(MatrixRTCSessionEvent.JoinStateChanged, this.isJoined());
         });
-        this.encryptionManager.join(joinConfig);
+        this.encryptionManager.join(joinConfig, publishedTransports);
 
         this.emit(MatrixRTCSessionEvent.JoinStateChanged, true);
     }
 
-    /**
-     *
-     * @param fociPreferred
-     * @param multiSfuFocus
-     * @param joinConfig
-     * @deprecated use the joinRTCSession method instead
-     */
-    public joinRoomSession(
-        fociPreferred: Transport[],
-        multiSfuFocus?: Transport,
-        joinConfig?: JoinSessionConfig,
-    ): void {
-        const [userId, deviceId] = [this.client.getUserId()!, this.client.getDeviceId()!];
-        // TODO this wants to become a UUID
-        const memberId = `${userId}:${deviceId}`;
-        this.joinRTCSession({ userId, deviceId, memberId }, fociPreferred, multiSfuFocus, joinConfig);
-    }
-
     /**
      * Announces this user and device as having left the MatrixRTC session
      * and stops scheduled updates.
-     * This will not unsubscribe from updates: remember to call unsubscribe() separately if
-     * desired.
      * The membership update required to leave the session will retry if it fails.
      * Without network connection the promise will never resolve.
      * A timeout can be provided so that there is a guarantee for the promise to resolve.
      * @returns Whether the membership update was attempted and did not time out.
      */
-    public async leaveRoomSession(timeout: number | undefined = undefined): Promise<boolean> {
+    public async leave(timeout?: number): Promise<boolean> {
         if (!this.isJoined()) {
             this.logger.info(`Not joined to session in room ${this.roomSubset.roomId}: ignoring leave call`);
             return false;
@@ -703,19 +666,6 @@ export class MatrixRTCSession extends TypedEventEmitter<
 
         return await leavePromise;
     }
-    /**
-     * This returns the focus in use by the oldest membership.
-     * Do not use since this might be just the focus for the oldest membership. others might use a different focus.
-     * @deprecated use `member.getTransport(session.getOldestMembership())` instead for the specific member you want to get the focus for.
-     */
-    public getFocusInUse(): Transport | undefined {
-        const oldestMembership = this.getOldestMembership();
-        return oldestMembership?.getTransport(oldestMembership);
-    }
-
-    public getOldestMembership(): CallMembership | undefined {
-        return this.memberships[0];
-    }
 
     /**
      * Get the call intent for the current call, based on what members are advertising. If one or more
@@ -767,7 +717,7 @@ export class MatrixRTCSession extends TypedEventEmitter<
                     keyInfo.key,
                     keyInfo.keyIndex,
                     keyInfo.membership,
-                    keyInfo.rtcBackendIdentity,
+                    keyInfo.backendIdentity,
                 );
             });
         });
@@ -898,15 +848,6 @@ export class MatrixRTCSession extends TypedEventEmitter<
         }
     };
 
-    /**
-     * Call this when something changed that may impacts the current MatrixRTC members in this session.
-     *
-     * @deprecated use {@link ensureRecalculateSessionMembers} instead.
-     */
-    public _onRTCSessionMemberUpdate = async (): Promise<void> => {
-        await this.ensureRecalculateSessionMembers();
-    };
-
     // Recalculations are chained onto this promise, so they never run in parallel.
     private recalculateSessionMembersPromise: Promise<void> = Promise.resolve();
 

package/src/matrixrtc/MembershipManager.ts

@@ -15,7 +15,7 @@ limitations under the License.
 */
 import { AbortError } from "p-retry";
 
-import { EventType, RelationType } from "../@types/event.ts";
+import { EventType } from "../@types/event.ts";
 import { type ISendEventResponse, type SendDelayedEventResponse } from "../@types/requests.ts";
 import { type EmptyObject } from "../@types/common.ts";
 import type { MatrixClient } from "../client.ts";
@@ -23,7 +23,14 @@ import { ConnectionError, HTTPError, MatrixError } from "../http-api/errors.ts";
 import { type Logger, logger as rootLogger } from "../logger.ts";
 import { type Room } from "../models/room.ts";
 import { type CallMembership, DEFAULT_EXPIRE_DURATION } from "./CallMembership.ts";
-import { type Transport, isMyMembership, type RTCCallIntent, Status, type SlotDescription } from "./types.ts";
+import {
+    type Transport,
+    isMyMembership,
+    type RTCCallCapability,
+    type RTCCallIntent,
+    Status,
+    type SlotDescription,
+} from "./types.ts";
 import { type MembershipConfig, type SessionConfig } from "./MatrixRTCSession.ts";
 import { type Action, ActionScheduler, type ActionUpdate } from "./MembershipManagerActionScheduler.ts";
 import { TypedEventEmitter } from "../models/typed-event-emitter.ts";
@@ -36,7 +43,6 @@ import {
 import { type RtcMembershipData, type SessionMembershipData } from "./membershipData/index.ts";
 import { computeSlotId } from "./utils.ts";
 import { deepCompare } from "../utils.ts";
-import { isLivekitTransportConfig } from "./LivekitTransport.ts";
 
 /* MembershipActionTypes:
 On Join:  ───────────────────┐   ┌───────────────(1)───────────┐
@@ -209,6 +215,7 @@ export class MembershipManager
     private activated = false;
     private readonly logger: Logger;
     protected callIntent: RTCCallIntent | undefined;
+    protected callCapabilities: RTCCallCapability[] | undefined;
     protected applicationData: Record<string, unknown> | undefined;
 
     public isActivated(): boolean {
@@ -222,23 +229,18 @@ export class MembershipManager
     /**
      * Puts the MembershipManager in a state where it tries to be joined.
      * It will send delayed events and membership events
-     * @param fociPreferred the list of preferred foci to use in the joined RTC membership event.
-     * If multiSfuFocus is set, this is only needed if this client wants to publish to multiple transports simultaneously.
-     * @param multiSfuFocus the active focus to use in the joined RTC membership event. Setting this implies the
-     * membership manager will operate in a multi-SFU connection mode. If `undefined`, an `oldest_membership`
-     * transport selection will be used instead.
+     * @param publishedTransports the list of transports on which the member is publishing.
      * @param onError This will be called once the membership manager encounters an unrecoverable error.
      * This should bubble up the the frontend to communicate that the call does not work in the current environment.
      * The original underlying error is preserved as `error.cause`, so consumers can `instanceof`-check the typed
      * cause.
      */
-    public join(fociPreferred: Transport[], multiSfuFocus?: Transport, onError?: (error: unknown) => void): void {
+    public join(publishedTransports: Transport[], onError?: (error: unknown) => void): void {
         if (this.scheduler.running) {
             this.logger.error("MembershipManager is already running. Ignoring join request.");
             return;
         }
-        this.fociPreferred = fociPreferred;
-        this.rtcTransport = multiSfuFocus;
+        this.publishedTransports = publishedTransports;
         this.leavePromiseResolvers = undefined;
         this.activated = true;
         this.oldStatus = this.status;
@@ -367,6 +369,7 @@ export class MembershipManager
         this.stateKey = this.makeMembershipStateKey(userId, deviceId);
         this.state = MembershipManager.defaultState;
         this.callIntent = joinConfig?.callIntent;
+        this.callCapabilities = joinConfig?.callCapabilities;
         this.applicationData = joinConfig?.applicationData;
         this.scheduler = new ActionScheduler((type): Promise<ActionUpdate> => {
             if (this.oldStatus) {
@@ -414,9 +417,7 @@ export class MembershipManager
     protected deviceId: string;
     protected userId: string;
     protected stateKey: string;
-    protected rtcTransport?: Transport;
-    /** @deprecated This will be removed in favor or rtcTransport becoming a list of actively used transports */
-    private fociPreferred?: Transport[];
+    protected publishedTransports: Transport[] = [];
 
     // Config:
     private delayedLeaveEventDelayMsOverride?: number;
@@ -753,6 +754,9 @@ export class MembershipManager
                 this.state.expireUpdateIterations = 1;
                 this.state.hasMemberStateEvent = true;
                 this.resetRateLimitCounter(MembershipActionType.SendJoinEvent);
+                // A successful (re-)join is a fresh membership: failures accumulated by the previous one
+                // (e.g. delayed event restarts that timed out before the server sent our leave) must not carry over.
+                this.state.networkErrorRetries.clear();
                 // An UpdateExpiry action might be left over from a previous join event.
                 // We can reach sendJoinEvent when the delayed leave event gets send by the HS.
                 // The branch where we might have a leftover UpdateExpiry action is:
@@ -1003,16 +1007,6 @@ export class MembershipManager
         const needsEmptyStringRoomFix =
             this.slotDescription.application === "m.call" && this.slotDescription.id === "ROOM";
 
-        const focusObjects: Pick<SessionMembershipData, "foci_preferred" | "focus_active"> =
-            this.rtcTransport === undefined
-                ? {
-                      focus_active: { type: "livekit", focus_selection: "oldest_membership" } as const,
-                      foci_preferred: this.fociPreferred ?? [],
-                  }
-                : {
-                      focus_active: { type: "livekit", focus_selection: "multi_sfu" } as const,
-                      foci_preferred: [this.rtcTransport, ...(this.fociPreferred ?? [])],
-                  };
         return {
             // Legacy memberships have no application object, so the
             // application's data sits at the top level, under the fields
@@ -1030,7 +1024,9 @@ export class MembershipManager
             "membershipID": `${this.userId}:${this.deviceId}`,
             expires,
             "m.call.intent": this.callIntent,
-            ...focusObjects,
+            ...(this.callCapabilities !== undefined ? { capabilities: this.callCapabilities } : {}),
+            "focus_active": { type: "livekit", focus_selection: "multi_sfu" } as const,
+            "foci_preferred": this.publishedTransports,
             ...(ownMembership !== undefined ? { created_ts: ownMembership.createdTs() } : undefined),
         };
     }
@@ -1321,30 +1317,17 @@ export class StickyEventMembershipManager extends MembershipManager {
      * @returns Only returns `RtcMembershipData`
      */
     protected makeMyMembership(): RtcMembershipData {
-        const ownMembership = this.ownMembership;
-
-        const livekitTransport = isLivekitTransportConfig(this.rtcTransport) ? this.rtcTransport : undefined;
-        const relationObject = ownMembership?.eventId
-            ? { "m.relation": { rel_type: RelationType.Reference, event_id: ownMembership?.eventId } }
-            : {};
         return {
             application: {
                 ...this.applicationData,
                 type: this.slotDescription.application,
                 ...(this.callIntent ? { "m.call.intent": this.callIntent } : {}),
+                ...(this.callCapabilities !== undefined ? { capabilities: this.callCapabilities } : {}),
             },
             slot_id: computeSlotId(this.slotDescription),
-            transports: {
-                // Make sure we do not add the alias to the transport.
-                // It is not needed in matrix2.0. The additional session information will be used to find the right alias on the sfu.
-                published: livekitTransport
-                    ? [{ type: livekitTransport.type, livekit_service_url: livekitTransport.livekit_service_url }]
-                    : [],
-                can_subscribe: ["livekit"],
-            },
+            transports: { published: this.publishedTransports, can_subscribe: ["livekit"] },
             member: { device_id: this.deviceId, user_id: this.userId, id: this.memberId },
             versions: [],
-            ...relationObject,
         };
     }
 }