Allow sending notification events when starting a call

Author: robintown

spec/unit/matrixrtc/MatrixRTCSession.spec.ts

@@ -340,7 +340,7 @@ describe("MatrixRTCSession", () => {
                     };
                 });
             });
-            sendEventMock = jest.fn();
+            sendEventMock = jest.fn().mockResolvedValue(undefined);
             client.sendStateEvent = sendStateEventMock;
             client._unstable_sendDelayedStateEvent = sendDelayedStateMock;
             client.sendEvent = sendEventMock;
@@ -369,6 +369,51 @@ describe("MatrixRTCSession", () => {
             expect(sess!.isJoined()).toEqual(true);
         });
 
+        it("sends a notification when starting a call", async () => {
+            // Simulate a join, including the update to the room state
+            sess!.joinRoomSession([mockFocus], mockFocus, { notifyType: "ring" });
+            await Promise.race([sentStateEvent, new Promise((resolve) => setTimeout(resolve, 5000))]);
+            mockRoomState(mockRoom, [{ ...membershipTemplate, user_id: client.getUserId()! }]);
+            sess!.onRTCSessionMemberUpdate();
+
+            expect(client.sendEvent).toHaveBeenCalledWith(mockRoom!.roomId, EventType.CallNotify, {
+                "application": "m.call",
+                "m.mentions": { user_ids: [], room: true },
+                "notify_type": "ring",
+                "call_id": "",
+            });
+        });
+
+        it("doesn't send a notification when joining an existing call", async () => {
+            // Add another member to the call so that it is considered an existing call
+            mockRoomState(mockRoom, [membershipTemplate]);
+            sess!.onRTCSessionMemberUpdate();
+
+            // Simulate a join, including the update to the room state
+            sess!.joinRoomSession([mockFocus], mockFocus, { notifyType: "ring" });
+            await Promise.race([sentStateEvent, new Promise((resolve) => setTimeout(resolve, 5000))]);
+            mockRoomState(mockRoom, [membershipTemplate, { ...membershipTemplate, user_id: client.getUserId()! }]);
+            sess!.onRTCSessionMemberUpdate();
+
+            expect(client.sendEvent).not.toHaveBeenCalled();
+        });
+
+        it("doesn't send a notification when someone else starts the call faster than us", async () => {
+            // Simulate a join, including the update to the room state
+            sess!.joinRoomSession([mockFocus], mockFocus, { notifyType: "ring" });
+            await Promise.race([sentStateEvent, new Promise((resolve) => setTimeout(resolve, 5000))]);
+            // But this time we want to simulate a race condition in which we receive a state event
+            // from someone else, starting the call before our own state event has been sent
+            mockRoomState(mockRoom, [membershipTemplate]);
+            sess!.onRTCSessionMemberUpdate();
+            mockRoomState(mockRoom, [membershipTemplate, { ...membershipTemplate, user_id: client.getUserId()! }]);
+            sess!.onRTCSessionMemberUpdate();
+
+            // We assume that the responsibility to send a notification, if any, lies with the other
+            // participant that won the race
+            expect(client.sendEvent).not.toHaveBeenCalled();
+        });
+
         it("sends a membership event when joining a call", async () => {
             const realSetTimeout = setTimeout;
             jest.useFakeTimers();

src/matrixrtc/MatrixRTCSession.ts

@@ -28,7 +28,7 @@ import { MembershipManager } from "./NewMembershipManager.ts";
 import { EncryptionManager, type IEncryptionManager } from "./EncryptionManager.ts";
 import { LegacyMembershipManager } from "./LegacyMembershipManager.ts";
 import { logDurationSync } from "../utils.ts";
-import { type Statistics } from "./types.ts";
+import { type Statistics, type CallNotifyType, isMyMembership } from "./types.ts";
 import { RoomKeyTransport } from "./RoomKeyTransport.ts";
 import type { IMembershipManager } from "./IMembershipManager.ts";
 import {
@@ -65,6 +65,15 @@ export type MatrixRTCSessionEventHandlerMap = {
     ) => void;
     [MatrixRTCSessionEvent.MembershipManagerError]: (error: unknown) => void;
 };
+
+export interface SessionConfig {
+    /**
+     * What kind of notification to send when starting the session.
+     * @default `undefined` (no notification)
+     */
+    notifyType?: CallNotifyType;
+}
+
 // The names follow these principles:
 // - we use the technical term delay if the option is related to delayed events.
 // - we use delayedLeaveEvent if the option is related to the delayed leave event.
@@ -167,7 +176,7 @@ export interface EncryptionConfig {
      */
     useKeyDelay?: number;
 }
-export type JoinSessionConfig = MembershipConfig & EncryptionConfig;
+export type JoinSessionConfig = SessionConfig & MembershipConfig & EncryptionConfig;
 
 /**
  * A MatrixRTCSession manages the membership & properties of a MatrixRTC session.
@@ -181,7 +190,15 @@ export class MatrixRTCSession extends TypedEventEmitter<
     private encryptionManager?: IEncryptionManager;
     // The session Id of the call, this is the call_id of the call Member event.
     private _callId: string | undefined;
+    private joinConfig?: SessionConfig;
     private logger: Logger;
+
+    /**
+     * Whether we're trying to join the session but still waiting for room state
+     * to reflect our own membership.
+     */
+    private joining = false;
+
     /**
      * This timeout is responsible to track any expiration. We need to know when we have to start
      * to ignore other call members. There is no callback for this. This timeout will always be configured to
@@ -429,6 +446,11 @@ export class MatrixRTCSession extends TypedEventEmitter<
             );
         }
 
+        this.joinConfig = joinConfig;
+        const userId = this.client.getUserId()!;
+        const deviceId = this.client.getDeviceId()!;
+        this.joining = !this.memberships.some((m) => isMyMembership(m, userId, deviceId));
+
         // Join!
         this.membershipManager!.join(fociPreferred, fociActive, (e) => {
             this.logger.error("MembershipManager encountered an unrecoverable error: ", e);
@@ -458,11 +480,11 @@ export class MatrixRTCSession extends TypedEventEmitter<
 
         this.logger.info(`Leaving call session in room ${this.roomSubset.roomId}`);
 
+        this.joining = false;
         this.encryptionManager!.leave();
-
         const leavePromise = this.membershipManager!.leave(timeout);
-        this.emit(MatrixRTCSessionEvent.JoinStateChanged, false);
 
+        this.emit(MatrixRTCSessionEvent.JoinStateChanged, false);
         return await leavePromise;
     }
 
@@ -545,6 +567,22 @@ export class MatrixRTCSession extends TypedEventEmitter<
         }
     }
 
+    /**
+     * Sends a notification corresponding to the configured notify type.
+     */
+    private sendCallNotify(): void {
+        if (this.joinConfig?.notifyType !== undefined) {
+            this.client
+                .sendEvent(this.roomSubset.roomId, EventType.CallNotify, {
+                    "application": "m.call",
+                    "m.mentions": { user_ids: [], room: true },
+                    "notify_type": this.joinConfig.notifyType,
+                    "call_id": this.callId!,
+                })
+                .catch((e) => this.logger.error("Failed to send call notification", e));
+        }
+    }
+
     /**
      * Call this when the Matrix room members have changed.
      */
@@ -583,6 +621,15 @@ export class MatrixRTCSession extends TypedEventEmitter<
             });
 
             void this.membershipManager?.onRTCSessionMemberUpdate(this.memberships);
+
+            const userId = this.client.getUserId()!;
+            const deviceId = this.client.getDeviceId()!;
+            if (this.joining && this.memberships.some((m) => isMyMembership(m, userId, deviceId))) {
+                this.joining = false;
+                // If we're the first member in the call, we're responsible for
+                // sending the notification event
+                if (oldMemberships.length === 0) this.sendCallNotify();
+            }
         }
         // This also needs to be done if `changed` = false
         // A member might have updated their fingerprint (created_ts)