feat(breakout-rooms) introduce breakout rooms

They are companion rooms created in a separate MUC. The room relationship is
maintained by a Prosody plugin.

All signalling happens through the breakout rooms MUC component.
Co-authored-by: Saúl Ibarra Corretgé <saghul@jitsi.org>

JitsiConference.js

@@ -122,7 +122,7 @@ const JINGLE_SI_TIMEOUT = 5000;
  *       and so on...
  */
 export default function JitsiConference(options) {
-    if (!options.name || options.name.toLowerCase() !== options.name) {
+    if (!options.name || options.name.toLowerCase() !== options.name.toString()) {
         const errmsg
             = 'Invalid conference name (no conference name passed or it '
                 + 'contains invalid characters like capital letters)!';
@@ -765,7 +765,7 @@ JitsiConference.prototype._sendBridgeVideoTypeMessage = function(localtrack) {
  * Returns name of this conference.
  */
 JitsiConference.prototype.getName = function() {
-    return this.options.name;
+    return this.options.name.toString();
 };
 
 /**
@@ -4004,3 +4004,12 @@ JitsiConference.prototype.avModerationReject = function(mediaType, id) {
             this.room && this.isModerator() ? 'wrong media type passed' : ''}`);
     }
 };
+
+/**
+ * Returns the breakout rooms manager object.
+ *
+ * @returns {Object} the breakout rooms manager.
+ */
+JitsiConference.prototype.getBreakoutRooms = function() {
+    return this.room?.getBreakoutRooms();
+};

JitsiConferenceEventManager.js

@@ -482,6 +482,12 @@ JitsiConferenceEventManager.prototype.setupChatRoomListeners = function() {
                 conference.statistics.sendAddIceCandidateFailed(e, pc);
             });
     }
+
+    // Breakout rooms.
+    this.chatRoomForwarder.forward(XMPPEvents.BREAKOUT_ROOMS_MOVE_TO_ROOM,
+        JitsiConferenceEvents.BREAKOUT_ROOMS_MOVE_TO_ROOM);
+    this.chatRoomForwarder.forward(XMPPEvents.BREAKOUT_ROOMS_UPDATED,
+        JitsiConferenceEvents.BREAKOUT_ROOMS_UPDATED);
 };
 
 /**

JitsiConferenceEvents.js

@@ -432,3 +432,13 @@ export const AV_MODERATION_PARTICIPANT_REJECTED = 'conference.av_moderation.part
  * A new facial expression is added with its duration for a participant
  */
 export const FACIAL_EXPRESSION_ADDED = 'conference.facial_expression.added';
+
+/**
+ * Event fired when a participant is requested to join a given (breakout) room.
+ */
+export const BREAKOUT_ROOMS_MOVE_TO_ROOM = 'conference.breakout-rooms.move-to-room';
+
+/**
+ * Event fired when the breakout rooms data was updated.
+ */
+export const BREAKOUT_ROOMS_UPDATED = 'conference.breakout-rooms.updated';

modules/xmpp/BreakoutRooms.js

@@ -0,0 +1,185 @@
+import { getLogger } from '@jitsi/logger';
+import { $msg } from 'strophe.js';
+
+import XMPPEvents from '../../service/xmpp/XMPPEvents';
+
+const FEATURE_KEY = 'features/breakout-rooms';
+const BREAKOUT_ROOM_ACTIONS = {
+    ADD: `${FEATURE_KEY}/add`,
+    REMOVE: `${FEATURE_KEY}/remove`,
+    MOVE_TO_ROOM: `${FEATURE_KEY}/move-to-room`
+};
+const BREAKOUT_ROOM_EVENTS = {
+    MOVE_TO_ROOM: `${FEATURE_KEY}/move-to-room`,
+    UPDATE: `${FEATURE_KEY}/update`
+};
+
+const logger = getLogger(__filename);
+
+/**
+ * Helper class for handling breakout rooms.
+ */
+export default class BreakoutRooms {
+
+    /**
+     * Constructs lobby room.
+     *
+     * @param {ChatRoom} room the room we are in.
+     */
+    constructor(room) {
+        this.room = room;
+
+        this.room.xmpp.addListener(XMPPEvents.BREAKOUT_ROOMS_EVENT, this._handleMessages.bind(this));
+
+        this._rooms = {};
+    }
+
+    /**
+     * Creates a breakout room with the given subject.
+     *
+     * @param {string} subject - A subject for the breakout room.
+     */
+    createBreakoutRoom(subject) {
+        if (!this.isSupported() || !this.room.isModerator()) {
+            logger.error(`Cannot create breakout room - supported:${this.isSupported()}, 
+                moderator:${this.room.isModerator()}`);
+
+            return;
+        }
+
+        const message = {
+            type: BREAKOUT_ROOM_ACTIONS.ADD,
+            subject
+        };
+
+        this._sendMessage(message);
+    }
+
+    /**
+     * Removes a breakout room.
+     *
+     * @param {string} breakoutRoomJid - JID of the room to be removed.
+     */
+    removeBreakoutRoom(breakoutRoomJid) {
+        if (!this.isSupported() || !this.room.isModerator()) {
+            logger.error(`Cannot remove breakout room - supported:${this.isSupported()}, 
+                moderator:${this.room.isModerator()}`);
+
+            return;
+        }
+
+        const message = {
+            type: BREAKOUT_ROOM_ACTIONS.REMOVE,
+            breakoutRoomJid
+        };
+
+        this._sendMessage(message);
+    }
+
+    /**
+     * Sends the given participant to the given room.
+     *
+     * @param {string} participantJid - JID of the participant to be sent to a room.
+     * @param {string} roomJid - JID of the target room.
+     */
+    sendParticipantToRoom(participantJid, roomJid) {
+        if (!this.isSupported() || !this.room.isModerator()) {
+            logger.error(`Cannot send participant to room - supported:${this.isSupported()}, 
+                moderator:${this.room.isModerator()}`);
+
+            return;
+        }
+
+        const message = {
+            type: BREAKOUT_ROOM_ACTIONS.MOVE_TO_ROOM,
+            participantJid,
+            roomJid
+        };
+
+        this._sendMessage(message);
+    }
+
+    /**
+     * Whether Breakout Rooms support is enabled in the backend or not.
+     */
+    isSupported() {
+        return Boolean(this.getComponentAddress());
+    }
+
+    /**
+     * Gets the address of the Breakout Rooms XMPP component.
+     *
+     * @returns The address of the component.
+     */
+    getComponentAddress() {
+        return this.room.xmpp.breakoutRoomsComponentAddress;
+    }
+
+    /**
+     * Stores if the current room is a breakout room.
+     *
+     * @param {boolean} isBreakoutRoom - Whether this room is a breakout room.
+     */
+    _setIsBreakoutRoom(isBreakoutRoom) {
+        this._isBreakoutRoom = isBreakoutRoom;
+    }
+
+    /**
+     * Checks whether this room is a breakout room.
+     *
+     * @returns True if the room is a breakout room, false otherwise.
+     */
+    isBreakoutRoom() {
+        return this._isBreakoutRoom;
+    }
+
+    /**
+     * Sets the main room JID associated with this breakout room. Only applies when
+     * in a breakout room.
+     *
+     * @param {string} jid - The main room JID.
+     */
+    _setMainRoomJid(jid) {
+        this._mainRoomJid = jid;
+    }
+
+    /**
+     * Gets the main room's JID associated with this breakout room.
+     *
+     * @returns The main room JID.
+     */
+    getMainRoomJid() {
+        return this._mainRoomJid;
+    }
+
+    /**
+     * Handles a message for managing breakout rooms.
+     *
+     * @param {object} payload - Arbitrary data.
+     */
+    _handleMessages(payload) {
+        switch (payload.event) {
+        case BREAKOUT_ROOM_EVENTS.MOVE_TO_ROOM:
+            this.room.eventEmitter.emit(XMPPEvents.BREAKOUT_ROOMS_MOVE_TO_ROOM, payload.roomJid);
+            break;
+        case BREAKOUT_ROOM_EVENTS.UPDATE: {
+            this._rooms = payload.rooms;
+            this.room.eventEmitter.emit(XMPPEvents.BREAKOUT_ROOMS_UPDATED, payload.rooms);
+            break;
+        }
+        }
+    }
+
+    /**
+     * Helper to send a breakout rooms message to the component.
+     *
+     * @param {Object} message - Command that needs to be sent.
+     */
+    _sendMessage(message) {
+        const msg = $msg({ to: this.getComponentAddress() });
+
+        msg.c('breakout_rooms', message).up();
+
+        this.room.xmpp.connection.send(msg);
+    }
+}

modules/xmpp/ChatRoom.js

@@ -11,6 +11,7 @@ import GlobalOnErrorHandler from '../util/GlobalOnErrorHandler';
 import Listenable from '../util/Listenable';
 
 import AVModeration from './AVModeration';
+import BreakoutRooms from './BreakoutRooms';
 import Lobby from './Lobby';
 import XmppConnection from './XmppConnection';
 import Moderator from './moderator';
@@ -137,6 +138,7 @@ export default class ChatRoom extends Listenable {
             this.lobby = new Lobby(this);
         }
         this.avModeration = new AVModeration(this);
+        this.breakoutRooms = new BreakoutRooms(this);
         this.initPresenceMap(options);
         this.lastPresences = {};
         this.phoneNumber = null;
@@ -331,6 +333,19 @@ export default class ChatRoom extends Listenable {
                 this.lobby.setLobbyRoomJid(lobbyRoomField && lobbyRoomField.length ? lobbyRoomField.text() : undefined);
             }
 
+            const isBreakoutField
+                = $(result).find('>query>x[type="result"]>field[var="muc#roominfo_isbreakout"]>value');
+            const isBreakoutRoom = Boolean(isBreakoutField?.text());
+
+            this.breakoutRooms._setIsBreakoutRoom(isBreakoutRoom);
+
+            const breakoutMainRoomField
+                = $(result).find('>query>x[type="result"]>field[var="muc#roominfo_breakout_main_room"]>value');
+
+            if (breakoutMainRoomField?.length) {
+                this.breakoutRooms._setMainRoomJid(breakoutMainRoomField.text());
+            }
+
             if (membersOnly !== this.membersOnlyEnabled) {
                 this.membersOnlyEnabled = membersOnly;
                 this.eventEmitter.emit(XMPPEvents.MUC_MEMBERS_ONLY_CHANGED, membersOnly);
@@ -1709,6 +1724,12 @@ export default class ChatRoom extends Listenable {
         return this.avModeration;
     }
 
+    /**
+     * @returns {BreakoutRooms}
+     */
+    getBreakoutRooms() {
+        return this.breakoutRooms;
+    }
 
     /**
      * Returns the phone number for joining the conference.
@@ -1825,7 +1846,11 @@ export default class ChatRoom extends Listenable {
      * rejected.
      */
     leave() {
-        return new Promise((resolve, reject) => {
+        const promises = [];
+
+        this.lobby?.lobbyRoom && promises.push(this.lobby.leave());
+
+        promises.push(new Promise((resolve, reject) => {
             const timeout = setTimeout(() => onMucLeft(true), 5000);
             const eventEmitter = this.eventEmitter;
 
@@ -1848,7 +1873,9 @@ export default class ChatRoom extends Listenable {
             }
             eventEmitter.on(XMPPEvents.MUC_LEFT, onMucLeft);
             this.doLeave();
-        });
+        }));
+
+        return Promise.all(promises);
     }
 }
 

modules/xmpp/Lobby.js

@@ -84,17 +84,21 @@ export default class Lobby {
 
     /**
      * Leaves the lobby room.
-     * @private
+     *
+     * @returns {Promise}
      */
-    _leaveLobbyRoom() {
+    leave() {
         if (this.lobbyRoom) {
-            this.lobbyRoom.leave()
+            return this.lobbyRoom.leave()
                 .then(() => {
                     this.lobbyRoom = undefined;
                     logger.info('Lobby room left!');
                 })
                 .catch(() => {}); // eslint-disable-line no-empty-function
         }
+
+        return Promise.reject(
+                new Error('The lobby has already been left'));
     }
 
     /**
@@ -172,6 +176,13 @@ export default class Lobby {
                         return;
                     }
 
+                    // Check if the user is a member if any breakout room.
+                    for (const room of Object.values(this.mainRoom.getBreakoutRooms()._rooms)) {
+                        if (Object.values(room.participants).find(p => p.jid === jid)) {
+                            return;
+                        }
+                    }
+
                     // we emit the new event on the main room so we can propagate
                     // events to the conference
                     this.mainRoom.eventEmitter.emit(
@@ -223,10 +234,8 @@ export default class Lobby {
                 (roomJid, from, txt, invitePassword) => {
                     logger.debug(`Received approval to join ${roomJid} ${from} ${txt}`);
                     if (roomJid === this.mainRoom.roomjid) {
-                        // we are now allowed let's join and leave lobby
+                        // we are now allowed, so let's join
                         this.mainRoom.join(invitePassword);
-
-                        this._leaveLobbyRoom();
                     }
                 });
             this.lobbyRoom.addEventListener(
@@ -250,7 +259,7 @@ export default class Lobby {
             this.mainRoom.addEventListener(
                 XMPPEvents.MUC_JOINED,
                 () => {
-                    this._leaveLobbyRoom();
+                    this.leave();
                 });
         }
 
@@ -301,13 +310,21 @@ export default class Lobby {
             return;
         }
 
+        // Get the main room JID. If we are in a breakout room we'll use the main
+        // room's lobby.
+        let mainRoomJid = this.mainRoom.roomjid;
+
+        if (this.mainRoom.getBreakoutRooms().isBreakoutRoom()) {
+            mainRoomJid = this.mainRoom.getBreakoutRooms().getMainRoomJid();
+        }
+
         const memberRoomJid = Object.keys(this.lobbyRoom.members)
             .find(j => Strophe.getResourceFromJid(j) === id);
 
         if (memberRoomJid) {
             const jid = this.lobbyRoom.members[memberRoomJid].jid;
             const msgToSend
-                = $msg({ to: this.mainRoom.roomjid })
+                = $msg({ to: mainRoomJid })
                     .c('x', { xmlns: 'http://jabber.org/protocol/muc#user' })
                     .c('invite', { to: jid });
 

modules/xmpp/xmpp.js

@@ -453,6 +453,10 @@ export default class XMPP extends Listenable {
             if (identity.type === 'region') {
                 this.options.deploymentInfo.region = this.connection.region = identity.name;
             }
+
+            if (identity.type === 'breakout_rooms') {
+                this.breakoutRoomsComponentAddress = identity.name;
+            }
         });
 
         this._maybeSendDeploymentInfoStat(true);
@@ -645,9 +649,11 @@ export default class XMPP extends Listenable {
      * @returns {Promise} Resolves with an instance of a strophe muc.
      */
     createRoom(roomName, options, onCreateResource) {
-        // There are cases (when using subdomain) where muc can hold an uppercase part
-        let roomjid = `${this.getRoomJid(roomName, options.customDomain)}/`;
+        // Support passing the domain in a String object as part of the room name.
+        const domain = roomName.domain || options.customDomain;
 
+        // There are cases (when using subdomain) where muc can hold an uppercase part
+        let roomjid = `${this.getRoomJid(roomName, domain)}/`;
         const mucNickname = onCreateResource
             ? onCreateResource(this.connection.jid, this.authenticatedUser)
             : RandomUtil.randomHexString(8).toLowerCase();
@@ -979,7 +985,8 @@ export default class XMPP extends Listenable {
 
         if (!(from === this.speakerStatsComponentAddress
             || from === this.conferenceDurationComponentAddress
-            || from === this.avModerationComponentAddress)) {
+            || from === this.avModerationComponentAddress
+            || from === this.breakoutRoomsComponentAddress)) {
             return true;
         }
 
@@ -997,6 +1004,8 @@ export default class XMPP extends Listenable {
             this.eventEmitter.emit(XMPPEvents.CONFERENCE_TIMESTAMP_RECEIVED, parsedJson.created_timestamp);
         } else if (parsedJson[JITSI_MEET_MUC_TYPE] === 'av_moderation') {
             this.eventEmitter.emit(XMPPEvents.AV_MODERATION_RECEIVED, parsedJson);
+        } else if (parsedJson[JITSI_MEET_MUC_TYPE] === 'breakout_rooms') {
+            this.eventEmitter.emit(XMPPEvents.BREAKOUT_ROOMS_EVENT, parsedJson);
         }
 
         return true;

service/xmpp/XMPPEvents.js

@@ -281,6 +281,21 @@ const XMPPEvents = {
      */
     AV_MODERATION_PARTICIPANT_REJECTED: 'xmpp.av_moderation.participant.rejected',
 
+    /**
+     * Event fired when a participant is requested to join a given (breakout) room.
+     */
+    BREAKOUT_ROOMS_MOVE_TO_ROOM: 'xmpp.breakout-rooms.move-to-room',
+
+    /**
+     * Event fired when we receive a message for breakout rooms.
+     */
+    BREAKOUT_ROOMS_EVENT: 'xmpp.breakout-rooms.event',
+
+    /**
+     * Event fired when the breakout rooms data was updated.
+     */
+    BREAKOUT_ROOMS_UPDATED: 'xmpp.breakout-rooms.updated',
+
     // Designates an event indicating that we should join the conference with
     // audio and/or video muted.
     START_MUTED_FROM_FOCUS: 'xmpp.start_muted_from_focus',