@webex/plugin-meetings 3.0.0-beta.4 → 3.0.0-beta.400

package/src/recording-controller/index.ts

@@ -0,0 +1,332 @@
+import PermissionError from '../common/errors/permission';
+import {CONTROLS, HTTP_VERBS, SELF_POLICY} from '../constants';
+import MeetingRequest from '../meeting/request';
+import RecordingAction from './enums';
+import Util from './util';
+import LoggerProxy from '../common/logs/logger-proxy';
+
+/**
+ * @description Recording manages the recording functionality of the meeting object, there should only be one instantation of recording per meeting
+ * @export
+ * @private
+ * @class Recording
+ */
+export default class RecordingController {
+  /**
+   * @instance
+   * @type {MeetingRequest}
+   * @private
+   * @memberof RecordingController
+   */
+  private request: MeetingRequest;
+
+  /**
+   * @instance
+   * @type {Array}
+   * @private
+   * @memberof RecordingInfo
+   */
+  private displayHints: Array<string> = [];
+
+  /**
+   * @instance
+   * @type {Object}
+   * @private
+   * @memberof RecordingInfo
+   */
+  private selfUserPolicies: Record<SELF_POLICY, boolean>;
+
+  /**
+   * @instance
+   * @type {string}
+   * @private
+   * @memberof RecordingInfo
+   */
+  private serviceUrl: string;
+
+  /**
+   * @instance
+   * @type {string}
+   * @private
+   * @memberof RecordingInfo
+   */
+  private sessionId: string;
+
+  /**
+   * @instance
+   * @type {string}
+   * @private
+   * @memberof RecordingInfo
+   */
+  private locusUrl: string;
+
+  /**
+   * @instance
+   * @type {string}
+   * @private
+   * @memberof RecordingInfo
+   */
+  private locusId: string;
+
+  /**
+   * @param {MeetingRequest} request
+   * @param {Object} options
+   * @constructor
+   * @memberof RecordingController
+   */
+  constructor(
+    request: MeetingRequest,
+    options?: {
+      serviceUrl?: string;
+      sessionId: string;
+      locusUrl: string;
+      displayHints?: Array<string>;
+    }
+  ) {
+    this.initialize(request);
+    this.set(options);
+  }
+
+  /**
+   * @param {MeetingRequest} request
+   * @returns {void}
+   * @private
+   * @memberof RecordingController
+   */
+  private initialize(request: MeetingRequest) {
+    this.request = request;
+  }
+
+  /**
+   * @param {Object} options
+   * @returns {void}
+   * @public
+   * @memberof RecordingController
+   */
+  public set(options?: {
+    serviceUrl?: string;
+    sessionId: string;
+    locusUrl: string;
+    displayHints?: Array<string>;
+  }) {
+    this.extract(options);
+  }
+
+  /**
+   * @param {string} url
+   * @returns {void}
+   * @public
+   * @memberof RecordingController
+   */
+  public setLocusUrl(url: string) {
+    this.locusUrl = url;
+    this.locusId = Util.extractLocusId(this.locusUrl);
+  }
+
+  /**
+   * @param {Array} hints
+   * @returns {void}
+   * @public
+   * @memberof RecordingController
+   */
+  public setDisplayHints(hints: Array<string>) {
+    this.displayHints = hints;
+  }
+
+  /**
+   * @param {Object} selfUserPolicies
+   * @returns {void}
+   * @public
+   * @memberof RecordingController
+   */
+  public setUserPolicy(selfUserPolicies: Record<SELF_POLICY, boolean>) {
+    this.selfUserPolicies = selfUserPolicies;
+  }
+
+  /**
+   * @param {string} id
+   * @returns {void}
+   * @public
+   * @memberof RecordingController
+   */
+  public setSessionId(id: string) {
+    this.sessionId = id;
+  }
+
+  /**
+   * @param {string} url
+   * @returns {void}
+   * @public
+   * @memberof RecordingController
+   */
+  public setServiceUrl(url: string) {
+    this.serviceUrl = url;
+  }
+
+  /**
+   * @returns {string}
+   * @public
+   * @memberof RecordingController
+   */
+  public getLocusUrl() {
+    return this.locusUrl;
+  }
+
+  /**
+   * @returns {string}
+   * @public
+   * @memberof RecordingController
+   */
+  public getLocusId() {
+    return this.locusId;
+  }
+
+  /**
+   * @returns {string}
+   * @public
+   * @memberof RecordingController
+   */
+  public getSessionId() {
+    return this.sessionId;
+  }
+
+  /**
+   * @returns {string}
+   * @public
+   * @memberof RecordingController
+   */
+  public getServiceUrl() {
+    return this.serviceUrl;
+  }
+
+  /**
+   * @returns {Array}
+   * @public
+   * @memberof RecordingController
+   */
+  public getDisplayHints() {
+    return this.displayHints;
+  }
+
+  /**
+   * @param {Object} options
+   * @returns {void}
+   * @private
+   * @memberof RecordingController
+   */
+  private extract(options?: {
+    serviceUrl?: string;
+    sessionId: string;
+    locusUrl: string;
+    displayHints?: Array<string>;
+  }) {
+    this.setServiceUrl(options?.serviceUrl);
+    this.setSessionId(options?.sessionId);
+    this.setDisplayHints(options?.displayHints);
+    this.setLocusUrl(options?.locusUrl);
+  }
+
+  /**
+   * @param {RecordingAction} action
+   * @private
+   * @memberof RecordingController
+   * @returns {Promise}
+   */
+  private recordingService(action: RecordingAction): Promise<any> {
+    // @ts-ignore
+    return this.request.request({
+      body: {
+        meetingInfo: {
+          locusSessionId: this.sessionId,
+        },
+        recording: {
+          action: action.toLowerCase(),
+        },
+      },
+      uri: `${this.serviceUrl}/loci/${this.locusId}/recording`,
+      method: HTTP_VERBS.PUT,
+    });
+  }
+
+  /**
+   * @param {RecordingAction} action
+   * @private
+   * @memberof RecordingController
+   * @returns {Promise}
+   */
+  private recordingControls(action: RecordingAction): Promise<any> {
+    const record = Util.deriveRecordingStates(action);
+
+    LoggerProxy.logger.log(`RecordingController:index#recordingControls --> ${record}`);
+
+    // @ts-ignore
+    return this.request.request({
+      uri: `${this.locusUrl}/${CONTROLS}`,
+      body: {
+        record,
+      },
+      method: HTTP_VERBS.PATCH,
+    });
+  }
+
+  /**
+   * @param {RecordingAction} action
+   * @private
+   * @memberof RecordingController
+   * @returns {Promise}
+   */
+  private recordingFacade(action: RecordingAction): Promise<any> {
+    LoggerProxy.logger.log(
+      `RecordingController:index#recordingFacade --> recording action [${action}]`
+    );
+
+    // assumes action is proper cased (i.e., Example)
+    if (Util?.[`canUser${action}`](this.displayHints, this.selfUserPolicies)) {
+      if (this.serviceUrl) {
+        return this.recordingService(action);
+      }
+
+      return this.recordingControls(action);
+    }
+
+    return Promise.reject(
+      new PermissionError(`${action} recording not allowed, due to moderator property.`)
+    );
+  }
+
+  /**
+   * @private
+   * @memberof RecordingController
+   * @returns {Promise}
+   */
+  public startRecording(): Promise<any> {
+    return this.recordingFacade(RecordingAction.Start);
+  }
+
+  /**
+   * @private
+   * @memberof RecordingController
+   * @returns {Promise}
+   */
+  public stopRecording(): Promise<any> {
+    return this.recordingFacade(RecordingAction.Stop);
+  }
+
+  /**
+   * @private
+   * @memberof RecordingController
+   * @returns {Promise}
+   */
+  public pauseRecording(): Promise<any> {
+    return this.recordingFacade(RecordingAction.Pause);
+  }
+
+  /**
+   * @private
+   * @memberof RecordingController
+   * @returns {Promise}
+   */
+  public resumeRecording(): Promise<any> {
+    return this.recordingFacade(RecordingAction.Resume);
+  }
+}

package/src/recording-controller/util.ts

@@ -0,0 +1,75 @@
+import {DISPLAY_HINTS, SELF_POLICY} from '../constants';
+import RecordingAction from './enums';
+import MeetingUtil from '../meeting/util';
+
+const canUserStart = (
+  displayHints: Array<string>,
+  userPolicies: Record<SELF_POLICY, boolean>
+): boolean =>
+  displayHints.includes(DISPLAY_HINTS.RECORDING_CONTROL_START) &&
+  MeetingUtil.selfSupportsFeature(SELF_POLICY.SUPPORT_NETWORK_BASED_RECORD, userPolicies);
+
+const canUserPause = (
+  displayHints: Array<string>,
+  userPolicies: Record<SELF_POLICY, boolean>
+): boolean =>
+  displayHints.includes(DISPLAY_HINTS.RECORDING_CONTROL_PAUSE) &&
+  MeetingUtil.selfSupportsFeature(SELF_POLICY.SUPPORT_NETWORK_BASED_RECORD, userPolicies);
+
+const canUserResume = (
+  displayHints: Array<string>,
+  userPolicies: Record<SELF_POLICY, boolean>
+): boolean =>
+  displayHints.includes(DISPLAY_HINTS.RECORDING_CONTROL_RESUME) &&
+  MeetingUtil.selfSupportsFeature(SELF_POLICY.SUPPORT_NETWORK_BASED_RECORD, userPolicies);
+
+const canUserStop = (
+  displayHints: Array<string>,
+  userPolicies: Record<SELF_POLICY, boolean>
+): boolean =>
+  displayHints.includes(DISPLAY_HINTS.RECORDING_CONTROL_STOP) &&
+  MeetingUtil.selfSupportsFeature(SELF_POLICY.SUPPORT_NETWORK_BASED_RECORD, userPolicies);
+
+const extractLocusId = (url: string) => {
+  return url?.split('/').pop();
+};
+
+const deriveRecordingStates = (action: RecordingAction): {recording: boolean; paused: boolean} => {
+  let recording;
+  let paused;
+
+  switch (action) {
+    case RecordingAction.Start:
+      recording = true;
+      paused = false;
+      break;
+    case RecordingAction.Stop:
+      recording = false;
+      paused = false;
+      break;
+    case RecordingAction.Resume:
+      recording = true;
+      paused = false;
+      break;
+    case RecordingAction.Pause:
+      recording = true;
+      paused = true;
+      break;
+    default:
+      throw new Error(`Recording state cannot be derived from invalid action: ${action}`);
+  }
+
+  return {
+    recording,
+    paused,
+  };
+};
+
+export default {
+  canUserStart,
+  canUserPause,
+  canUserResume,
+  canUserStop,
+  deriveRecordingStates,
+  extractLocusId,
+};

package/src/roap/index.ts

@@ -0,0 +1,288 @@
+// @ts-ignore
+import {StatelessWebexPlugin} from '@webex/webex-core';
+
+import {ROAP} from '../constants';
+import LoggerProxy from '../common/logs/logger-proxy';
+
+import RoapRequest from './request';
+import TurnDiscovery, {TurnDiscoveryResult} from './turnDiscovery';
+import Meeting from '../meeting';
+import MeetingUtil from '../meeting/util';
+import Metrics from '../metrics';
+import BEHAVIORAL_METRICS from '../metrics/constants';
+
+export {
+  type TurnDiscoveryResult,
+  type TurnServerInfo,
+  type TurnDiscoverySkipReason,
+} from './turnDiscovery';
+
+/**
+ * Roap options
+ * @typedef {Object} RoapOptions
+ * @property {String} sdp
+ * @property {Meeting} meeting
+ * @property {Number} seq
+ * @property {Number} tieBreaker
+ *  @property {Boolean} reconnect
+ */
+
+/**
+ * @typedef {Object} SeqOptions
+ * @property {String} correlationId
+ * @property {String} mediaId
+ * @property {Number} seq
+ */
+
+/**
+ * @class Roap
+ * @export
+ * @private
+ */
+export default class Roap extends StatelessWebexPlugin {
+  attrs: any;
+  lastRoapOffer: any;
+  options: any;
+  roapHandler: any;
+  roapRequest: any;
+  turnDiscovery: TurnDiscovery;
+
+  /**
+   *
+   * @param {Object} attrs
+   * @param {Object} options
+   */
+  constructor(attrs: any, options: any) {
+    super({}, options);
+    /**
+     * @instance
+     * @type {Object}
+     * @private
+     * @memberof Roap
+     */
+    this.attrs = attrs;
+    /**
+     * @instance
+     * @type {Object}
+     * @private
+     * @memberof Roap
+     */
+    this.options = options;
+    /**
+     * The Roap Request Server Proxy Object
+     * @instance
+     * @type {RoapRequest}
+     * @private
+     * @memberof Roap
+     */
+    // @ts-ignore
+    this.roapRequest = new RoapRequest({}, options);
+
+    this.turnDiscovery = new TurnDiscovery(this.roapRequest);
+  }
+
+  /**
+   *
+   * @param {SeqOptions} options
+   * @returns {null}
+   * @memberof Roap
+   */
+  public sendRoapOK(options: any) {
+    return Promise.resolve().then(() => {
+      // @ts-ignore
+      const meeting = this.webex.meetings.meetingCollection.getByKey(
+        'correlationId',
+        options.correlationId
+      );
+      const roapMessage = {
+        messageType: ROAP.ROAP_TYPES.OK,
+        version: ROAP.ROAP_VERSION,
+        seq: options.seq,
+      };
+
+      LoggerProxy.logger.log(`Roap:index#sendRoapOK --> ROAP OK sending with seq ${options.seq}`);
+
+      return this.roapRequest
+        .sendRoap({
+          roapMessage,
+          locusSelfUrl: meeting.selfUrl,
+          mediaId: options.mediaId,
+          meetingId: meeting.id,
+          locusMediaRequest: meeting.locusMediaRequest,
+        })
+        .then(() => {
+          LoggerProxy.logger.log(`Roap:index#sendRoapOK --> ROAP OK sent with seq ${options.seq}`);
+        });
+    });
+  }
+
+  /**
+   * Sends a ROAP answer...
+   * @param {SeqOptions} options
+   * @param {Boolean} options.audioMuted
+   * @param {Boolean} options.videoMuted
+   * @returns {Promise}
+   * @memberof Roap
+   */
+  public sendRoapAnswer(options: any) {
+    // @ts-ignore
+    const meeting = this.webex.meetings.meetingCollection.getByKey(
+      'correlationId',
+      options.correlationId
+    );
+    const roapMessage = {
+      messageType: ROAP.ROAP_TYPES.ANSWER,
+      sdps: [options.sdp],
+      version: ROAP.ROAP_VERSION,
+      seq: options.seq,
+    };
+
+    return this.roapRequest.sendRoap({
+      roapMessage,
+      locusSelfUrl: meeting.selfUrl,
+      mediaId: options.mediaId,
+      meetingId: meeting.id,
+      locusMediaRequest: meeting.locusMediaRequest,
+    });
+  }
+
+  /**
+   * Sends a ROAP error...
+   * @param {Object} options
+   * @returns {Promise}
+   * @memberof Roap
+   */
+  sendRoapError(options) {
+    // @ts-ignore
+    const meeting = this.webex.meetings.meetingCollection.getByKey(
+      'correlationId',
+      options.correlationId
+    );
+    const roapMessage = {
+      messageType: ROAP.ROAP_TYPES.ERROR,
+      version: ROAP.ROAP_VERSION,
+      errorType: options.errorType,
+      seq: options.seq,
+    };
+
+    return this.roapRequest
+      .sendRoap({
+        roapMessage,
+        locusSelfUrl: meeting.selfUrl,
+        mediaId: options.mediaId,
+        meetingId: meeting.id,
+        locusMediaRequest: meeting.locusMediaRequest,
+      })
+      .then(() => {
+        LoggerProxy.logger.log(
+          `Roap:index#sendRoapError --> ROAP ERROR sent with seq ${options.seq}`
+        );
+      });
+  }
+
+  /**
+   * sends a roap media request
+   * @param {RoapOptions} options
+   * @returns {Promise}
+   * @memberof Roap
+   */
+  sendRoapMediaRequest(options: any) {
+    const {meeting, seq, sdp, tieBreaker} = options;
+    const roapMessage = {
+      messageType: ROAP.ROAP_TYPES.OFFER,
+      sdps: [sdp],
+      version: ROAP.ROAP_VERSION,
+      seq,
+      tieBreaker,
+      headers: ['includeAnswerInHttpResponse', 'noOkInTransaction'],
+    };
+
+    // The only time we want to send an empty media id is when we are reconnecting, because this way we tell Locus
+    // that it needs to create a new confluence, but when reconnecting we always send TURN_DISCOVERY_REQUEST first,
+    // so we don't need to ever send an empty media id here
+    const sendEmptyMediaId = false;
+
+    return this.roapRequest
+      .sendRoap({
+        roapMessage,
+        locusSelfUrl: meeting.selfUrl,
+        mediaId: sendEmptyMediaId ? '' : meeting.mediaId,
+        meetingId: meeting.id,
+        preferTranscoding: !meeting.isMultistream,
+        locusMediaRequest: meeting.locusMediaRequest,
+        ipVersion: MeetingUtil.getIpVersion(meeting.webex),
+      })
+      .then(({locus, mediaConnections}) => {
+        if (mediaConnections) {
+          meeting.updateMediaConnections(mediaConnections);
+        }
+
+        let roapAnswer;
+
+        if (mediaConnections?.[0]?.remoteSdp) {
+          const remoteSdp = JSON.parse(mediaConnections[0].remoteSdp);
+
+          if (remoteSdp.roapMessage) {
+            const {
+              seq: answerSeq,
+              messageType,
+              sdps,
+              errorType,
+              errorCause,
+              headers,
+            } = remoteSdp.roapMessage;
+
+            roapAnswer = {
+              seq: answerSeq,
+              messageType,
+              sdp: sdps[0],
+              errorType,
+              errorCause,
+              headers,
+            };
+          }
+        }
+
+        if (!roapAnswer) {
+          Metrics.sendBehavioralMetric(BEHAVIORAL_METRICS.ROAP_HTTP_RESPONSE_MISSING, {
+            correlationId: meeting.correlationId,
+            messageType: 'ANSWER',
+            isMultistream: meeting.isMultistream,
+          });
+        }
+
+        return {locus, roapAnswer};
+      });
+  }
+
+  /**
+   * Performs a TURN server discovery procedure, which involves exchanging
+   * some roap messages with the server. This exchange has to be done before
+   * any other roap messages are sent
+   *
+   * @param {Meeting} meeting
+   * @param {Boolean} isReconnecting should be set to true if this is a new
+   *                                 media connection just after a reconnection
+   * @param {Boolean} [isForced]
+   * @returns {Promise}
+   */
+  doTurnDiscovery(
+    meeting: Meeting,
+    isReconnecting: boolean,
+    isForced?: boolean
+  ): Promise<TurnDiscoveryResult> {
+    return this.turnDiscovery.doTurnDiscovery(meeting, isReconnecting, isForced);
+  }
+
+  generateTurnDiscoveryRequestMessage(meeting: Meeting, isForced: boolean) {
+    return this.turnDiscovery.generateTurnDiscoveryRequestMessage(meeting, isForced);
+  }
+
+  handleTurnDiscoveryHttpResponse(meeting: Meeting, httpResponse: object) {
+    return this.turnDiscovery.handleTurnDiscoveryHttpResponse(meeting, httpResponse);
+  }
+
+  abortTurnDiscovery() {
+    return this.turnDiscovery.abort();
+  }
+}