[WDA-2386] Softphone state machine

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wazo/sdk",
-  "version": "0.43.9",
+  "version": "1.0.0-alpha.20",
   "description": "Wazo's JavaScript Software Development Kit.",
   "main": "index.js",
   "types": "lib/types/index.d.ts",
@@ -59,7 +59,8 @@
     "reconnecting-websocket": "^4.4.0",
     "sdp-transform": "^2.14.2",
     "sip.js": "^0.21.2",
-    "webrtc-adapter": "^8.2.3"
+    "webrtc-adapter": "^8.2.3",
+    "xstate": "^5.13.2"
   },
   "devDependencies": {
     "@babel/core": "^7.24.4",

src/__tests__/__voice__/call.test.ts

@@ -0,0 +1,193 @@
+/* eslint-disable no-underscore-dangle */
+import { Inviter, UserAgent, type URI } from 'sip.js';
+
+import softphone from '../../voice/softphone';
+import Call from '../../voice/call';
+import { Actions, EstablishedStates, EstablishedSubStates, States } from '../../state-machine/call-state-machine';
+import { Actions as SoftphoneActions } from '../../state-machine/softphone-state-machine';
+import ApiCall from '../../domain/Call';
+
+import InvalidStateTransition from '../../domain/InvalidStateTransition';
+
+const uaOptions = {
+  logBuiltinEnabled: false,
+  transportOptions: {
+    traceSip: false,
+    wsServers: 'ws://localhost',
+  },
+};
+
+jest.mock('../..', () => ({
+  __esModule: true,
+  default: {
+    Auth: {
+      getHost: jest.fn(() => 'my-stack.io'),
+      getSession: jest.fn(() => ({
+        displayName: () => 'John Doe',
+        primaryWebRtcLine: () => ({}),
+      })),
+    },
+  },
+}));
+
+jest.mock('../../web-rtc-client', () => jest.fn().mockImplementation(() => ({
+  answer: jest.fn(() => Promise.resolve()),
+  mute: jest.fn(() => Promise.resolve()),
+  hold: jest.fn(() => Promise.resolve()),
+  unhold: jest.fn(() => Promise.resolve()),
+  hangup: jest.fn(() => Promise.resolve()),
+  register: jest.fn(() => Promise.resolve()),
+  onCallEnded: jest.fn(() => Promise.resolve()),
+  setOnHeartbeatTimeout: jest.fn(() => Promise.resolve()),
+  setOnHeartbeatCallback: jest.fn(() => Promise.resolve()),
+  on: jest.fn(),
+})));
+
+const ua = new UserAgent(uaOptions);
+const sipCall = new Inviter(ua, UserAgent.makeURI('sip:1234@my.stack.io') as URI);
+
+softphone.connect();
+// @ts-ignore: private method
+softphone._sendAction(SoftphoneActions.REGISTER_DONE);
+
+const invalidStateTransition = (state: string, action: string) => new InvalidStateTransition(`Invalid state transition from ${state} with action ${action}`, state, action);
+
+describe('Call', () => {
+  describe('parsing an API call', () => {
+    it('Should parse an API call and transform it to a Call instance', async () => {
+      const apiCall = new ApiCall({
+        id: '1234',
+        sipCallId: 'abcd',
+        isCaller: false,
+        isVideo: true,
+        recording: true,
+        callerName: '',
+        callerNumber: '',
+        calleeName: '',
+        calleeNumber: '0123423223',
+        dialedExtension: '',
+        lineId: null,
+        muted: true,
+        onHold: false,
+        startingTime: new Date(),
+        status: 'Up',
+        talkingToIds: [],
+      });
+      const call = Call.parseCall(apiCall);
+
+      expect(call.recording).toBeTruthy();
+      expect(call.id).toBe(apiCall.sipCallId);
+      expect(call.apiId).toBe(apiCall.id);
+      expect(call.number).toBe(apiCall.calleeNumber);
+      expect(call.answerTime).toStrictEqual(undefined);
+      expect(call.creationTime).toStrictEqual(apiCall.startingTime);
+      expect(call.isMuted()).toBeTruthy();
+      expect(call.state).toStrictEqual({
+        [States.ESTABLISHED]: {
+          [EstablishedStates.ONGOING]: {},
+          [EstablishedSubStates.MUTE]: EstablishedStates.MUTED,
+          [EstablishedSubStates.HOLD]: EstablishedStates.UN_HELD,
+        },
+      });
+      expect(call.isEstablished()).toBeTruthy();
+    });
+  });
+
+  describe('accept', () => {
+    it('Should throw an error when accepting a not ringing call', async () => {
+      const call = new Call(sipCall, softphone);
+
+      await expect(call.accept()).rejects.toThrowError(invalidStateTransition(States.IDLE, Actions.ACCEPT));
+    });
+
+    it('Should throw an error when the softphone is not registered', async () => {
+      const call = new Call(sipCall, softphone);
+      // @ts-ignore: private method
+      call._sendAction(Actions.INCOMING_CALL);
+      // @ts-ignore: private method
+      softphone._sendAction(SoftphoneActions.TRANSPORT_CLOSED);
+
+      await expect(call.accept()).rejects.toThrowError(invalidStateTransition(States.RINGING, Actions.ACCEPT));
+
+      // Revert softphone state
+      softphone.connect();
+      // @ts-ignore: private method
+      softphone._sendAction(SoftphoneActions.REGISTER_DONE);
+    });
+
+    it('Should not throw an error when accepting a not ringing call', async () => {
+      const call = new Call(sipCall, softphone);
+      // @ts-ignore: private method
+      call._sendAction(Actions.INCOMING_CALL);
+
+      await call.accept();
+      expect(softphone.client.answer).toHaveBeenCalled();
+    });
+  });
+
+  describe('hangup', () => {
+    it('Should throw an error when terminating a non established call', async () => {
+      const call = new Call(sipCall, softphone);
+
+      await expect(call.hangup()).rejects.toThrowError(invalidStateTransition(States.IDLE, Actions.HANGUP));
+    });
+
+    it('Should not throw an error when terminating an established call', async () => {
+      const call = new Call(sipCall, softphone);
+      // @ts-ignore: private method
+      call._sendAction(Actions.MAKE_CALL);
+      // @ts-ignore: private method
+      call._sendAction(Actions.REMOTLY_ACCEPTED);
+
+      await call.hangup();
+      expect(softphone.client.hangup).toHaveBeenCalled();
+    });
+  });
+
+  describe('state propagation', () => {
+    it('Should update the call state in events', (done) => {
+      const call = new Call(sipCall, softphone);
+      // @ts-ignore: private method
+      call._sendAction(Actions.MAKE_CALL);
+
+      call.on('remotelyAccepted', () => {
+        expect(call.state).toStrictEqual({
+          [States.ESTABLISHED]: {
+            [EstablishedStates.ONGOING]: {},
+            [EstablishedSubStates.MUTE]: EstablishedStates.UN_MUTED,
+            [EstablishedSubStates.HOLD]: EstablishedStates.UN_HELD,
+          },
+        });
+        done();
+      });
+
+      call.onAccepted();
+    });
+  });
+
+  describe('Multiple sub state', () => {
+    it('Should mute and hold a call', () => {
+      const call = new Call(sipCall, softphone);
+      // @ts-ignore: private method
+      call._sendAction(Actions.MAKE_CALL);
+
+      expect(call.isMuted()).toBeFalsy();
+      expect(call.isHeld()).toBeFalsy();
+
+      // @ts-ignore: private method
+      call._sendAction(Actions.REMOTLY_ACCEPTED);
+
+      call.mute();
+      expect(call.isMuted()).toBeTruthy();
+      expect(call.isHeld()).toBeFalsy();
+
+      call.hold();
+      expect(call.isMuted()).toBeTruthy();
+      expect(call.isHeld()).toBeTruthy();
+
+      call.resume();
+      expect(call.isMuted()).toBeTruthy();
+      expect(call.isHeld()).toBeFalsy();
+    });
+  });
+});

src/__tests__/__voice__/softphone.test.ts

@@ -0,0 +1,82 @@
+import { Softphone } from '../../voice/softphone';
+import { Actions, States } from '../../state-machine/softphone-state-machine';
+
+import Wazo from '../..';
+import InvalidStateTransition from '../../domain/InvalidStateTransition';
+
+const server = 'my.stack.io';
+const displayName = 'John Doe';
+const webRtcLine = {};
+const session = {
+  uuid: '1234',
+  displayName: jest.fn(() => displayName),
+  primaryWebRtcLine: jest.fn(() => webRtcLine),
+};
+
+jest.mock('../..', () => ({
+  __esModule: true,
+  default: {
+    Auth: {
+      getHost: jest.fn(() => server),
+      getSession: jest.fn(() => session),
+    },
+  },
+}));
+
+jest.mock('../../web-rtc-client', () => jest.fn().mockImplementation(() => ({
+  register: jest.fn(() => Promise.resolve()),
+  unregister: jest.fn(() => Promise.resolve()),
+  setOnHeartbeatTimeout: jest.fn(() => Promise.resolve()),
+  setOnHeartbeatCallback: jest.fn(() => Promise.resolve()),
+  on: jest.fn(),
+  INVITE: 'invite',
+})));
+
+const invalidStateTransition = (state: string, action: string) => new InvalidStateTransition(`Invalid state transition from ${state} with action ${action}`, state, action);
+
+describe('Softphone', () => {
+  describe('connect', () => {
+    it('Should retrieve information from Wazo.Auth', () => {
+      const instance = new Softphone();
+      jest.spyOn(instance, 'connectWithCredentials');
+      instance.connect({});
+
+      expect(Wazo.Auth.getHost).toHaveBeenCalled();
+      expect(Wazo.Auth.getSession).toHaveBeenCalled();
+      expect(instance.connectWithCredentials).toHaveBeenCalledWith(server, webRtcLine, displayName, { userUuid: session.uuid });
+      expect(instance.client.on).toHaveBeenCalledWith('invite', expect.anything());
+    });
+
+    it('Should throw an error when already connected', async () => {
+      const instance = new Softphone();
+      instance.softphoneActor.send({ type: Actions.REGISTER });
+
+      await expect(instance.connect({})).rejects.toThrowError(invalidStateTransition(States.REGISTERING, Actions.REGISTER));
+    });
+
+    it('Should not allow to register twice', async () => {
+      const instance = new Softphone();
+      instance.connect({});
+
+      await expect(instance.connect({})).rejects.toThrowError(invalidStateTransition(States.REGISTERING, Actions.REGISTER));
+    });
+  });
+
+  describe('disconnect', () => {
+    it('Should throw an error when not connected', async () => {
+      const instance = new Softphone();
+
+      await expect(instance.disconnect()).rejects.toThrowError(invalidStateTransition(States.UNREGISTERED, Actions.UNREGISTER));
+    });
+
+    it('Should unregister the client', async () => {
+      const instance = new Softphone();
+      instance.connect({});
+      instance.softphoneActor.send({ type: Actions.REGISTER_DONE });
+
+      await instance.disconnect();
+
+      expect(instance.client.unregister).toHaveBeenCalled();
+    });
+  });
+});

src/checker/checks/webrtc-transport.ts

@@ -1,9 +1,9 @@
 import WebRTCClient from '../../web-rtc-client';
-import { WazoSession } from '../../domain/types';
+import { SipCall } from '../../domain/types';
 
 export default {
   name: 'WebRTC Transport (WS) ~30s',
-  check: (server: string, session: WazoSession): Promise<void> => new Promise((resolve, reject) => {
+  check: (server: string, session: SipCall): Promise<void> => new Promise((resolve, reject) => {
     const [host, port = 443] = server.split(':');
 
     const client = new WebRTCClient({

src/checker/checks/webrtc.ts

@@ -1,4 +1,5 @@
 /* global MediaStream */
+import { getSipCallId } from '../../utils/sdp';
 import WebRTCClient from '../../web-rtc-client';
 
 export default {
@@ -35,7 +36,7 @@ export default {
     client.on(client.REGISTERED, () => {
       const sipSession = client.call('*10');
 
-      if (!sipSession || !client.getSipSessionId(sipSession)) {
+      if (!sipSession || !getSipCallId(sipSession)) {
         return handleError('Unable to make call through WebRTC');
       }
 

src/domain/CallSession.ts

@@ -2,7 +2,7 @@ import { SessionState } from 'sip.js/lib/api/session-state';
 import Call from './Call';
 import newFrom from '../utils/new-from';
 import updateFrom from '../utils/update-from';
-import { WazoSession } from './types';
+import { SipCall } from './types';
 
 type CallSessionArguments = {
   answered: boolean;
@@ -32,7 +32,7 @@ type CallSessionArguments = {
   screensharing: boolean;
   recording: boolean;
   recordingPaused: boolean;
-  sipSession?: WazoSession;
+  sipSession?: SipCall;
   conference: boolean;
 };
 export default class CallSession {
@@ -96,7 +96,7 @@ export default class CallSession {
 
   recordingPaused: boolean;
 
-  sipSession: WazoSession | undefined;
+  sipSession: SipCall | undefined;
 
   conference: boolean;
 

src/domain/InvalidState.ts

@@ -0,0 +1,13 @@
+class InvalidState extends Error {
+
+  state: string;
+
+  constructor(message: string, state: string) {
+    super(message);
+
+    this.state = state;
+  }
+
+}
+
+export default InvalidState;

src/domain/InvalidStateTransition.ts

@@ -0,0 +1,17 @@
+class InvalidStateTransition extends Error {
+
+  state: string;
+
+  action: string;
+
+  constructor(message: string, action: string, state: string) {
+    super(message);
+
+    this.action = action;
+
+    this.state = state;
+  }
+
+}
+
+export default InvalidStateTransition;