feat: allow clients to accept calls before the session is established

apps/meteor/app/api/server/index.ts

@@ -22,6 +22,7 @@ import './v1/integrations';
 import './v1/invites';
 import './v1/import';
 import './v1/ldap';
+import './v1/media-calls';
 import './v1/misc';
 import './v1/permissions';
 import './v1/presence';

apps/meteor/app/api/server/v1/media-calls.ts

@@ -0,0 +1,99 @@
+import { MediaCall } from '@rocket.chat/core-services';
+import type { IMediaCall } from '@rocket.chat/core-typings';
+import type { CallAnswer, CallFeature } from '@rocket.chat/media-signaling';
+import { callFeatureList, callAnswerList } from '@rocket.chat/media-signaling';
+import {
+	ajv,
+	validateNotFoundErrorResponse,
+	validateBadRequestErrorResponse,
+	validateUnauthorizedErrorResponse,
+	validateForbiddenErrorResponse,
+} from '@rocket.chat/rest-typings';
+import type { JSONSchemaType } from 'ajv';
+
+import type { ExtractRoutesFromAPI } from '../ApiClass';
+import { API } from '../api';
+
+type MediaCallsAnswer = {
+	callId: string;
+	contractId: string;
+
+	answer: CallAnswer;
+
+	supportedFeatures?: CallFeature[];
+};
+
+const MediaCallsAnswerSchema: JSONSchemaType<MediaCallsAnswer> = {
+	type: 'object',
+	properties: {
+		callId: {
+			type: 'string',
+		},
+		contractId: {
+			type: 'string',
+		},
+		answer: {
+			type: 'string',
+			enum: callAnswerList,
+		},
+		supportedFeatures: {
+			type: 'array',
+			items: {
+				type: 'string',
+				enum: callFeatureList,
+			},
+			nullable: true,
+		},
+	},
+	required: ['callId', 'contractId', 'answer'],
+	additionalProperties: false,
+};
+
+export const isMediaCallsAnswerProps = ajv.compile<MediaCallsAnswer>(MediaCallsAnswerSchema);
+
+const mediaCallsAnswerEndpoints = API.v1.post(
+	'media-calls.answer',
+	{
+		response: {
+			200: ajv.compile<{
+				call: IMediaCall;
+			}>({
+				additionalProperties: false,
+				type: 'object',
+				properties: {
+					call: {
+						type: 'object',
+						$ref: '#/components/schemas/IMediaCall',
+						description: 'The updated call information.',
+						nullable: true,
+					},
+					success: {
+						type: 'boolean',
+						description: 'Indicates if the request was successful.',
+					},
+				},
+				required: ['call', 'success'],
+			}),
+			400: validateBadRequestErrorResponse,
+			401: validateUnauthorizedErrorResponse,
+			403: validateForbiddenErrorResponse,
+			404: validateNotFoundErrorResponse,
+		},
+		body: isMediaCallsAnswerProps,
+		authRequired: true,
+	},
+	async function action() {
+		const call = await MediaCall.answerCall(this.userId, this.bodyParams);
+
+		return API.v1.success({
+			call,
+		});
+	},
+);
+
+type MediaCallsAnswerEndpoints = ExtractRoutesFromAPI<typeof mediaCallsAnswerEndpoints>;
+
+declare module '@rocket.chat/rest-typings' {
+	// eslint-disable-next-line @typescript-eslint/naming-convention, @typescript-eslint/no-empty-interface
+	interface Endpoints extends MediaCallsAnswerEndpoints {}
+}

apps/meteor/server/services/media-call/service.ts

@@ -9,7 +9,8 @@ import type {
 } from '@rocket.chat/core-typings';
 import { Logger } from '@rocket.chat/logger';
 import { callServer, type IMediaCallServerSettings } from '@rocket.chat/media-calls';
-import { isClientMediaSignal, type ClientMediaSignal, type ServerMediaSignal } from '@rocket.chat/media-signaling';
+import type { ClientMediaSignal, ServerMediaSignal, ClientMediaSignalAnswer } from '@rocket.chat/media-signaling';
+import { isClientMediaSignal } from '@rocket.chat/media-signaling';
 import type { InsertionModel } from '@rocket.chat/model-typings';
 import { CallHistory, MediaCalls, Rooms, Users } from '@rocket.chat/models';
 import { getHistoryMessagePayload } from '@rocket.chat/ui-voip/dist/ui-kit/getHistoryMessagePayload';
@@ -39,21 +40,56 @@ export class MediaCallService extends ServiceClassInternal implements IMediaCall
 		this.configureMediaCallServer();
 	}
 
+	public async answerCall(uid: IUser['_id'], params: Omit<ClientMediaSignalAnswer, 'type'>): Promise<IMediaCall> {
+		const { callId } = params;
+
+		const call = await MediaCalls.findOneById<Pick<IMediaCall, '_id' | 'callee' | 'acceptedAt'>>(callId, {
+			projection: { callee: 1, acceptedAt: 1 },
+		});
+		if (!call || call.callee.type !== 'user' || call.callee.id !== uid) {
+			throw new Error('not-found');
+		}
+
+		const signal: ClientMediaSignalAnswer = {
+			type: 'answer',
+			...params,
+		};
+
+		await callServer.receiveSignal(uid, signal, { throwIfSkipped: true });
+
+		const updatedCall = await MediaCalls.findOneById(callId);
+		if (!updatedCall) {
+			throw new Error('internal-error');
+		}
+
+		if (updatedCall.callee.contractId !== signal.contractId) {
+			if (updatedCall.callee.contractId) {
+				throw new Error('invalid-call-state');
+			}
+			throw new Error('internal-error');
+		}
+
+		return updatedCall;
+	}
+
 	public async processSignal(uid: IUser['_id'], signal: ClientMediaSignal): Promise<void> {
 		try {
-			callServer.receiveSignal(uid, signal);
+			await callServer.receiveSignal(uid, signal);
 		} catch (err) {
 			logger.error({ msg: 'failed to process client signal', err, signal, uid });
 		}
 	}
 
 	public async processSerializedSignal(uid: IUser['_id'], signal: string): Promise<void> {
+		let signalType: string | null = null;
+
 		try {
 			const deserialized = await this.deserializeClientSignal(signal);
+			signalType = deserialized.type;
 
-			callServer.receiveSignal(uid, deserialized);
+			await callServer.receiveSignal(uid, deserialized);
 		} catch (err) {
-			logger.error({ msg: 'failed to process client signal', err, uid });
+			logger.error({ msg: 'failed to process client signal', err, uid, type: signalType });
 		}
 	}
 

ee/packages/media-calls/src/definition/IMediaCallServer.ts

@@ -2,7 +2,7 @@ import type { IUser } from '@rocket.chat/core-typings';
 import type { Emitter } from '@rocket.chat/emitter';
 import type { ClientMediaSignal, ClientMediaSignalBody, ServerMediaSignal } from '@rocket.chat/media-signaling';
 
-import type { InternalCallParams } from './common';
+import type { InternalCallParams, SignalProcessingOptions } from './common';
 
 export type MediaCallServerEvents = {
 	callUpdated: { callId: string; dtmf?: ClientMediaSignalBody<'dtmf'> };
@@ -41,7 +41,7 @@ export interface IMediaCallServer {
 	updateCallHistory(params: { callId: string }): void;
 
 	// functions that are run on events
-	receiveSignal(fromUid: IUser['_id'], signal: ClientMediaSignal): void;
+	receiveSignal(fromUid: IUser['_id'], signal: ClientMediaSignal, options?: SignalProcessingOptions): Promise<void>;
 	receiveCallUpdate(params: { callId: string; dtmf?: ClientMediaSignalBody<'dtmf'> }): void;
 
 	// extra functions available to the service

ee/packages/media-calls/src/definition/common.ts

@@ -28,3 +28,9 @@ export class CallRejectedError extends Error {
 		super(message || 'call-rejected');
 	}
 }
+
+export type SignalProcessingOptions = {
+	// Some signals can be safely skipped when they are not relevant to the current call state, but
+	// if the signal was received via REST, we shouldn't return success without processing anything, so we throw an error instead
+	throwIfSkipped?: boolean;
+};

ee/packages/media-calls/src/internal/SignalProcessor.ts

@@ -10,7 +10,7 @@ import type {
 } from '@rocket.chat/media-signaling';
 import { MediaCalls } from '@rocket.chat/models';
 
-import type { InternalCallParams } from '../definition/common';
+import type { InternalCallParams, SignalProcessingOptions } from '../definition/common';
 import { logger } from '../logger';
 import { mediaCallDirector } from '../server/CallDirector';
 import { UserActorAgent } from './agents/UserActorAgent';
@@ -29,7 +29,7 @@ export class GlobalSignalProcessor {
 		this.emitter = new Emitter();
 	}
 
-	public async processSignal(uid: IUser['_id'], signal: ClientMediaSignal): Promise<void> {
+	public async processSignal(uid: IUser['_id'], signal: ClientMediaSignal, options: SignalProcessingOptions): Promise<void> {
 		switch (signal.type) {
 			case 'register':
 				return this.processRegisterSignal(uid, signal);
@@ -38,7 +38,7 @@ export class GlobalSignalProcessor {
 		}
 
 		if ('callId' in signal) {
-			return this.processCallSignal(uid, signal);
+			return this.processCallSignal(uid, signal, options);
 		}
 
 		logger.error({ msg: 'Unrecognized media signal', signal: stripSensitiveDataFromSignal(signal) });
@@ -55,6 +55,7 @@ export class GlobalSignalProcessor {
 	private async processCallSignal(
 		uid: IUser['_id'],
 		signal: Exclude<ClientMediaSignal, ClientMediaSignalRegister | ClientMediaSignalRequestCall>,
+		{ throwIfSkipped }: SignalProcessingOptions,
 	): Promise<void> {
 		try {
 			const call = await MediaCalls.findOneById(signal.callId);
@@ -90,6 +91,9 @@ export class GlobalSignalProcessor {
 
 			// Ignore signals from different sessions if the actor is already signed
 			if (!skipContractCheck && callActor.contractId && callActor.contractId !== signal.contractId) {
+				if (throwIfSkipped) {
+					throw new Error('invalid-contract');
+				}
 				return;
 			}
 
@@ -99,7 +103,14 @@ export class GlobalSignalProcessor {
 			const { [role]: agent } = agents;
 
 			if (!(agent instanceof UserActorAgent)) {
-				throw new Error('Actor agent is not prepared to process signals');
+				logger.error({
+					msg: 'Actor agent is not prepared to process signals',
+					method: 'processSignal',
+					signal: stripSensitiveDataFromSignal(signal),
+					isCaller,
+					isCallee,
+				});
+				throw new Error('internal-error');
 			}
 
 			await agent.processSignal(call, signal);

ee/packages/media-calls/src/internal/agents/CallSignalProcessor.ts

@@ -20,6 +20,7 @@ import type {
 import { MediaCallChannels, MediaCallNegotiations, MediaCalls } from '@rocket.chat/models';
 
 import type { IMediaCallAgent } from '../../definition/IMediaCallAgent';
+import type { SignalProcessingOptions } from '../../definition/common';
 import { logger } from '../../logger';
 import { mediaCallDirector } from '../../server/CallDirector';
 import { getMediaCallServer } from '../../server/injection';
@@ -58,6 +59,8 @@ export class UserActorSignalProcessor {
 
 	public readonly ignored: boolean;
 
+	private throwIfSkipped: boolean;
+
 	constructor(
 		protected readonly agent: IMediaCallAgent,
 		protected readonly call: IMediaCall,
@@ -67,6 +70,7 @@ export class UserActorSignalProcessor {
 
 		this.signed = Boolean(actor.contractId && actor.contractId === channel.contractId);
 		this.ignored = Boolean(actor.contractId && actor.contractId !== channel.contractId);
+		this.throwIfSkipped = false;
 	}
 
 	public async requestWebRTCOffer(params: { negotiationId: string }): Promise<void> {
@@ -80,7 +84,7 @@ export class UserActorSignalProcessor {
 		});
 	}
 
-	public async processSignal(signal: ClientMediaSignal): Promise<void> {
+	public async processSignal(signal: ClientMediaSignal, options: SignalProcessingOptions = {}): Promise<void> {
 		if (signal.type !== 'local-state') {
 			logger.debug({
 				msg: 'UserActorSignalProcessor.processSignal',
@@ -90,6 +94,8 @@ export class UserActorSignalProcessor {
 			});
 		}
 
+		this.throwIfSkipped = options.throwIfSkipped || false;
+
 		// The code will only reach this point if one of the following conditions are true:
 		// 1. the signal came from the exact user session where the caller initiated the call
 		// 2. the signal came from the exact user session where the callee accepted the call
@@ -290,13 +296,11 @@ export class UserActorSignalProcessor {
 	}
 
 	protected async clientHasRejected(): Promise<void> {
-		if (!this.isCallPending()) {
+		if (!this.validatePendingCallee()) {
 			return;
 		}
 
-		if (this.role === 'callee') {
-			return mediaCallDirector.hangup(this.call, this.agent, 'rejected');
-		}
+		return mediaCallDirector.hangup(this.call, this.agent, 'rejected');
 	}
 
 	protected async clientIsUnavailable(): Promise<void> {
@@ -309,13 +313,11 @@ export class UserActorSignalProcessor {
 	}
 
 	protected async clientHasAccepted(supportedFeatures: CallFeature[]): Promise<void> {
-		if (!this.isCallPending()) {
+		if (!this.validatePendingCallee()) {
 			return;
 		}
 
-		if (this.role === 'callee') {
-			await mediaCallDirector.acceptCall(this.call, this.agent, { calleeContractId: this.contractId, supportedFeatures });
-		}
+		await mediaCallDirector.acceptCall(this.call, this.agent, { calleeContractId: this.contractId, supportedFeatures });
 	}
 
 	protected async clientIsActive(): Promise<void> {
@@ -338,6 +340,24 @@ export class UserActorSignalProcessor {
 		return ['active', 'hangup'].includes(this.call.state);
 	}
 
+	protected validatePendingCallee(): boolean {
+		if (this.role !== 'callee') {
+			if (this.throwIfSkipped) {
+				throw new Error('invalid-call-role');
+			}
+			return false;
+		}
+
+		if (!this.isCallPending()) {
+			if (this.throwIfSkipped) {
+				throw new Error('invalid-call-state');
+			}
+			return false;
+		}
+
+		return true;
+	}
+
 	private async reviewLocalState(signal: ClientMediaSignalLocalState): Promise<void> {
 		if (!this.signed) {
 			return;