@soundworks/core 4.0.0-alpha.7 → 5.0.0

package/src/client/Client.js

@@ -1,9 +1,22 @@
-import { isBrowser, isPlainObject } from '@ircam/sc-utils';
+import { isBrowser, isPlainObject, isString } from '@ircam/sc-utils';
+
+import ClientContextManager, {
+  kClientContextManagerStart,
+  kClientContextManagerStop,
+} from './ClientContextManager.js';
+import ClientPluginManager from './ClientPluginManager.js';
+import {
+  kPluginManagerStart,
+  kPluginManagerStop,
+} from '../common/BasePluginManager.js';
+import ClientSocket, {
+  kSocketTerminate,
+} from './ClientSocket.js';
+import ClientStateManager from './ClientStateManager.js';
+import {
+  kStateManagerInit,
+} from '../common/BaseStateManager.js';
 
-import ContextManager from './ContextManager.js';
-import PluginManager from './PluginManager.js';
-import Socket from './Socket.js';
-import StateManager from './StateManager.js';
 import {
   CLIENT_HANDSHAKE_REQUEST,
   CLIENT_HANDSHAKE_RESPONSE,
@@ -11,78 +24,68 @@ import {
   AUDIT_STATE_NAME,
 } from '../common/constants.js';
 import logger from '../common/logger.js';
+import VERSION from '../common/version.js';
 
-/**
- * Configuration object for a client running in a browser runtime.
- *
- * @typedef BrowserClientConfig
- * @memberof client
- * @type {object}
- * @property {string} role - Role of the client in the application (e.g. 'player', 'controller').
- * @property {object} [app] - Application configration object.
- * @property {string} [app.name=''] - Name of the application.
- * @property {string} [app.author=''] - Name of the author.
- * @property {object} [env] - Environment configration object.
- * @property {string} [env.websockets={}] - Configuration options for websockets.
- * @property {string} [env.subpath=''] - If running behind a proxy, path to the application.
- */
-
-/**
- * Configuration object for a client running in a node runtime.
- *
- * @typedef NodeClientConfig
- * @memberof client
- * @type {object}
- * @property {string} role - Role of the client in the application (e.g. 'player', 'controller').
- * @property {object} [app] - Application configration object.
- * @property {string} [app.name=''] - Name of the application.
- * @property {string} [app.author=''] - Name of the author.
- * @property {object} env - Environment configration object.
- * @property {boolean} env.serverAddress - Domain name or IP of the server.
- * @property {boolean} env.useHttps - Define is the server run in http or in https.
- * @property {boolean} env.port - Port on which the server is listening.
- * @property {string} [env.websockets={}] - Configuration options for websockets.
- * @property {string} [env.subpath=''] - If running behind a proxy, path to the application.
- */
+// for testing purposes
+export const kClientVersionTest = Symbol('soundworks:client-version-test');
+export const kClientOnStatusChangeCallbacks = Symbol('soundworks:client-on-status-change-callbacks');
 
 /**
  * The `Client` class is the main entry point for the client-side of a soundworks
  * application.
  *
- * A `Client` instance allows to access soundworks components such as {@link client.StateManager},
- * {@link client.PluginManager},{@link client.Socket} or {@link client.ContextManager}.
- * Its is also responsible for handling the initialization lifecycles of the different
- * soundworks components.
+ * A `soundworks` client can run seamlessly in a browser or in a Node.js runtime.
+ *
+ * It provides an access to the different soundworks components such as the {@link ClientStateManager},
+ * {@link ClientPluginManager}, {@link ClientSocket} and the {@link ClientContextManager}.
  *
  * ```
  * import { Client } from '@soundworks/core/client.js';
- * // create a new soundworks `Client` instance
- * const client = new Client({ role: 'player' });
- * // init and start the client
+ * // create a `Client` instance
+ * const client = new Client({
+ *   role: 'player',
+ *   env: {
+ *     useHttps: false,
+ *     serverAddress: 'localhost',
+ *     port: 8000,
+ *   },
+ * });
+ * // start the client
  * await client.start();
  * ```
- *
- * @memberof client
  */
 class Client {
+  #config = null;
+  #version = null;
+  #role = null;
+  #id = null;
+  #uuid = null;
+  #token = null;
+  #runtime = null;
+  #socket = null;
+  #contextManager = null;
+  #pluginManager = null;
+  #stateManager = null;
+  #status = 'idle';
+  #auditState = null;
+
   /**
-   * @param {client.BrowserClientConfig|client.NodeClientConfig} config -
-   *  Configuration of the soundworks client.
+   * @param {ClientConfig} config - Configuration of the soundworks client.
    * @throws Will throw if the given config object is invalid.
    */
   constructor(config) {
     if (!isPlainObject(config)) {
-      throw new Error(`[soundworks:Client] Invalid argument for Client constructor, config should be an object`);
+      throw new Error(`Cannot construct Client: argument 1 must be an object`);
     }
 
-    if (!('role' in config)) {
-      throw new Error('[soundworks:Client] Invalid config object, "config.role" should be defined');
+    if (!('role' in config) || !isString(config.role)) {
+      throw new Error('Cannot construct Client: Invalid ClientConfig object: Property "role" must be a string');
     }
 
-    // for node clients env.https is requires to open the websocket
+    // for node clients env.https is required to open the websocket
     if (!isBrowser()) {
       if (!('env' in config)) {
-        throw new Error('[soundworks:Client] Invalid config object, "config.env" { useHttps, serverAddress, port } should be defined');
+        throw new Error(`Cannot construct Client: The 'env' property with type 'ClientEnvConfig' must be defined`);
       }
 
       let missing = [];
@@ -100,125 +103,197 @@ class Client {
       }
 
       if (missing.length) {
-        throw new Error(`[soundworks:Client] Invalid config object, "config.env" is missing: ${missing.join(', ')}`);
+        throw new Error(`Cannot construct Client: Invalid 'env' property of type 'ClientEnvConfig': Fields ${missing.join(', ')} are missing`);
       }
     }
 
-    /**
-     * Role of the client in the application.
-     *
-     * @type {string}
-     */
-    this.role = config.role;
-
-    /**
-     * Configuration object.
-     *
-     * @type {client.BrowserClientConfig|client.NodeClientConfig}
-     */
-    this.config = config;
-
-    if (!this.config.env) {
-      this.config.env = {};
+    this.#config = config;
+
+    if (!this.#config.env) {
+      this.#config.env = {};
+    }
+
+    this.#version = VERSION;
+    // allow override though config for testing
+    if (config[kClientVersionTest]) {
+      this.#version = config[kClientVersionTest];
     }
 
-    // minimal configuration for websockets
-    this.config.env.websockets = Object.assign({
+    this.#role = config.role;
+    this.#runtime = isBrowser() ? 'browser' : 'node';
+    this.#socket = new ClientSocket(this.#role, this.#config, {
       path: 'socket',
-      pingInterval: 5000,
-    }, config.env.websockets);
-
-    /**
-     * Session id of the client (incremeted positive number), generated and
-     * retrieved by the server during `client.init`. The counter is reset when
-     * the server restarts.
-     *
-     * @type {number}
-     */
-    this.id = null;
-
-    /**
-     * Unique session uuid of the client (uuidv4), generated and retrieved by
-     * the server during {@link client.Client#init}.
-     *
-     * @type {string}
-     */
-    this.uuid = null;
-
-    /**
-     * Instance of the {@link client.Socket} class that handle websockets communications with
-     * the server.
-     *
-     * @see {@link client.Socket}
-     * @type {client.Socket}
-     */
-    this.socket = new Socket();
-
-    /**
-     * Runtime platform on which the client is executed, i.e. 'browser' or 'node'.
-     *
-     * @type {string}
-     */
-    this.target = isBrowser() ? 'browser' : 'node';
-
-    /**
-     * Instance of the {@link client.ContextManager} class.
-     *
-     * The context manager can be safely used after `client.init()` has been fulfilled.
-     *
-     * @see {@link client.ContextManager}
-     * @type {client.ContextManager}
-     */
-    this.contextManager = new ContextManager();
-
-    /**
-     * Instance of the {@link client.PluginManager} class.
-     *
-     * The context manager can be safely used after `client.init()` has been fulfilled.
-     *
-     * @see {@link client.PluginManager}
-     * @type {client.PluginManager}
-     */
-    this.pluginManager = new PluginManager(this);
-
-    /**
-     * Instance of the {@link client.StateManager} class.
-     *
-     * The context manager can be safely used after `client.init()` has been fulfilled.
-     *
-     * @see {@link client.StateManager}
-     * @type {client.StateManager}
-     */
-    this.stateManager = null;
-
-    /**
-     * Status of the client, 'idle', 'inited', 'started' or 'errored'.
-     *
-     * @type {string}
-     */
-    this.status = 'idle';
-
-    /**
-     * Token of the client if connected through HTTP authentication.
-     * @private
-     */
-    this.token = null;
-
-    /** @private */
-    this._onStatusChangeCallbacks = new Set();
-    /** @private */
-    this._auditState = null;
+      retryConnectionRefusedTimeout: 1000,
+    });
+    this.#contextManager = new ClientContextManager();
+    this.#pluginManager = new ClientPluginManager(this);
+    this.#stateManager = new ClientStateManager();
+    this.#status = 'idle';
+
+    this[kClientOnStatusChangeCallbacks] = new Set();
 
     logger.configure(!!config.env.verbose);
   }
 
+  /**
+   * Package version.
+   *
+   * @type {string}
+   */
+  get version() {
+    return this.#version;
+  }
+
+  /**
+   * Role of the client in the application.
+   *
+   * @type {string}
+   */
+  get role() {
+    return this.#role;
+  }
+
+  /**
+   * Configuration object.
+   *
+   * @type {ClientConfig}
+   */
+  get config() {
+    return this.#config;
+  }
+
+  /**
+   * Session id of the client.
+   *
+   * Incremented positive integer generated and retrieved by the server during
+   * {@link Client#init}. The counter is reset when the server restarts.
+   *
+   * @type {number}
+   */
+  get id() {
+    return this.#id;
+  }
+
+  /**
+   * Unique session uuid of the client (uuidv4).
+   *
+   * Generated and retrieved by the server during {@link Client#init}.
+   * @type {string}
+   */
+  get uuid() {
+    return this.#uuid;
+  }
+
+  /**
+   * Authentication token generated by the server.
+   *
+   * Only set if client has gone through authentication process and is considered trusted.
+   *
+   * Generated and retrieved by the server during {@link Client#init}.
+   * @type {string}
+   */
+  get token() {
+    return this.#token;
+  }
+
+  /**
+   * Runtime platform on which the client is executed, i.e. 'browser' or 'node'.
+   *
+   * @type {'node'|'browser'}
+   */
+  get runtime() {
+    return this.#runtime;
+  }
+
+  /**
+   * @deprecated Use {@link Client#runtime} instead.
+   */
+  get target() {
+    logger.deprecated('Client#target', 'Client#runtime', '4.0.0-alpha.29');
+    return this.runtime;
+  }
+
+  /**
+   * Instance of the {@link client.Socket} class.
+   *
+   * @see {@link ClientSocket}
+   * @type {ClientSocket}
+   */
+  get socket() {
+    return this.#socket;
+  }
+
+  /**
+   * Instance of the {@link ClientContextManager} class.
+   *
+   * The context manager can be safely used after `client.init()` has been fulfilled.
+   *
+   * @see {@link ClientContextManager}
+   * @type {ClientContextManager}
+   */
+  get contextManager() {
+    return this.#contextManager;
+  }
+
+  /**
+   * Instance of the {@link ClientPluginManager} class.
+   *
+   * The context manager can be safely used after `client.init()` has been fulfilled.
+   *
+   * @see {@link ClientPluginManager}
+   * @type {ClientPluginManager}
+   */
+  get pluginManager() {
+    return this.#pluginManager;
+  }
+
+  /**
+   * Instance of the {@link ClientStateManager} class.
+   *
+   * The context manager can be safely used after `client.init()` has been fulfilled.
+   *
+   * @see {@link ClientStateManager}
+   * @type {ClientStateManager}
+   */
+  get stateManager() {
+    return this.#stateManager;
+  }
+
+  /**
+   * Status of the client.
+   *
+   * @type {'idle'|'inited'|'started'|'errored'}
+   */
+  get status() {
+    return this.#status;
+  }
+
+  /** @private */
+  async #dispatchStatus(status) {
+    this.#status = status;
+
+    // if node target and launched in a child process, forward status to parent process
+    if (this.#runtime === 'node' && process.send !== undefined) {
+      process.send(`soundworks:client:${status}`);
+    }
+
+    // execute all callbacks in parallel
+    const promises = [];
+
+    for (let callback of this[kClientOnStatusChangeCallbacks]) {
+      promises.push(callback(status));
+    }
+
+    await Promise.all(promises);
+  }
+
   /**
    * The `init` method is part of the initialization lifecycle of the `soundworks`
-   * client. Most of the time, the `init` method will be implicitly called by the
-   * {@link client.Client#start} method.
+   * client. Most of the time, this method will be implicitly executed by the
+   * {@link Client#start} method.
    *
    * In some situations you might want to call this method manually, in such cases
-   * the method should be called before the {@link client.Client#start} method.
+   * the method should be called before the {@link Client#start} method.
    *
    * What it does:
    * - connect the sockets to be server
@@ -226,89 +301,81 @@ class Client {
    * - launch the state manager
    * - initialize all registered plugin
    *
-   * After `await client.init()` is fulfilled, the {@link client.Client#stateManager},
-   * the {@link client.Client#pluginManager} and the {@link client.Client#socket}
+   * After `await client.init()` is fulfilled, the {@link Client#stateManager},
+   * the {@link Client#pluginManager} and the {@link Client#socket}
    * can be safely used.
    *
    * @example
    * import { Client } from '@soundworks/core/client.js'
    *
    * const client = new Client(config);
-   * // optionnal explicit call of `init` before `start`
+   * // optional explicit call of `init` before `start`
    * await client.init();
    * await client.start();
    */
   async init() {
-    // init socket communications (string and binary)
-    await this.socket.init(this.role, this.config);
+    if (this.#status !== 'idle') {
+      throw new DOMException(`Cannot execute 'init' on Client: Lifecycle methods must be called in following order: init, start, stop`, 'InvalidAccessError');
+    }
+
+    // init socket communications
+    await this.#socket.init();
 
     // we need the try/catch block to change the promise rejection into proper error
     try {
       await new Promise((resolve, reject) => {
         // wait for handshake response before starting stateManager and pluginManager
-        this.socket.addListener(CLIENT_HANDSHAKE_RESPONSE, async ({ id, uuid, token }) => {
-          this.id = id;
-          this.uuid = uuid;
-          this.token = token;
+        this.#socket.addListener(CLIENT_HANDSHAKE_RESPONSE, async ({ id, uuid, token, version }) => {
+          this.#id = id;
+          this.#uuid = uuid;
+          this.#token = token;
+
+          if (version !== this.#version) {
+            logger.warnVersionDiscrepancies(this.#role, this.#version, version);
+          }
 
           resolve();
         });
 
-        this.socket.addListener(CLIENT_HANDSHAKE_ERROR, (err) => {
-          let msg = ``;
-
-          switch (err.type) {
-            case 'invalid-client-type':
-              msg = `[soundworks:Client] ${err.message}`;
-              break;
-            case 'invalid-plugin-list':
-              msg = `[soundworks:Client] ${err.message}`;
-              break;
-            default:
-              msg = `Undefined error`;
-              break;
-          }
-
-          this.socket.terminate();
+        this.#socket.addListener(CLIENT_HANDSHAKE_ERROR, (err) => {
+          let msg = `Cannot execute 'init' on Client: ${err.message}`;
+          // These are development errors, we can just hang. If we terminate the
+          // socket, a reload is triggered by the launcher which is not good DX.
           reject(msg);
         });
 
         // send handshake request
         const payload = {
-          role: this.role,
-          registeredPlugins: this.pluginManager.getRegisteredPlugins(),
+          role: this.#role,
+          version: this.#version,
+          registeredPlugins: this.#pluginManager.getRegisteredPlugins(),
         };
 
-        this.socket.send(CLIENT_HANDSHAKE_REQUEST, payload);
+        this.#socket.send(CLIENT_HANDSHAKE_REQUEST, payload);
       });
-    } catch (err) {
-      throw new Error(err);
+    } catch (msg) {
+      throw new Error(msg);
     }
 
-    // ------------------------------------------------------------
-    // CREATE STATE MANAGER
-    // ------------------------------------------------------------
-    this.stateManager = new StateManager(this.id, {
-      emit: this.socket.send.bind(this.socket), // need to alias this
-      addListener: this.socket.addListener.bind(this.socket),
-      removeAllListeners: this.socket.removeAllListeners.bind(this.socket),
+    // init state manager
+    this.#stateManager[kStateManagerInit](this.id, {
+      emit: this.#socket.send.bind(this.#socket), // need to alias this
+      addListener: this.#socket.addListener.bind(this.#socket),
+      removeAllListeners: this.#socket.removeAllListeners.bind(this.#socket),
     });
 
-    // ------------------------------------------------------------
-    // INIT PLUGIN MANAGER
-    // ------------------------------------------------------------
-    await this.pluginManager.start();
+    await this.#pluginManager[kPluginManagerStart]();
 
-    await this._dispatchStatus('inited');
+    await this.#dispatchStatus('inited');
   }
 
   /**
    * The `start` method is part of the initialization lifecycle of the `soundworks`
-   * client. The `start` method will implicitly call the {@link client.Client#init}
-   * method if it has not been called manually.
+   * client. This method will implicitly execute {@link Client#init} method if it
+   * has not been called manually.
    *
    * What it does:
-   * - implicitly call {@link client.Client#init} if not done manually
+   * - implicitly call {@link Client#init} if not done manually
    * - start all created contexts. For that to happen, you will have to call `client.init`
    * manually and instantiate the contexts between `client.init()` and `client.start()`
    *
@@ -319,31 +386,24 @@ class Client {
    * await client.start();
    */
   async start() {
-    if (this.status === 'idle') {
+    // lazily call init for convenience
+    if (this.#status === 'idle') {
       await this.init();
     }
 
-    if (this.status === 'started') {
-      throw new Error(`[soundworks:Server] Cannot call "client.start()" twice`);
+    if (this.#status !== 'inited') {
+      throw new DOMException(`Cannot execute 'start' on Client: Lifecycle methods must be called in following order: init, start, stop`, 'InvalidAccessError');
     }
 
-    if (this.status !== 'inited') {
-      throw new Error(`[soundworks:Server] Cannot "client.start()" before "client.init()"`);
-    }
-
-    // ------------------------------------------------------------
-    // START CONTEXT MANAGER
-    // ------------------------------------------------------------
-    await this.contextManager.start();
-
-    await this._dispatchStatus('started');
+    await this.#contextManager[kClientContextManagerStart]();
+    await this.#dispatchStatus('started');
   }
 
   /**
    * Stops all started contexts, plugins and terminates the socket connections.
    *
    * In most situations, you might not need to call this method. However, it can
-   * be usefull for unit testing or similar situations where you want to create
+   * be useful for unit testing or similar situations where you want to create
    * and delete several clients in the same process.
    *
    * @example
@@ -356,76 +416,66 @@ class Client {
    * await client.stop();
    */
   async stop() {
-    if (this.status !== 'started') {
-      throw new Error(`[soundworks:Client] Cannot "client.stop()" before "client.start()"`);
+    if (this.#status !== 'started') {
+      throw new DOMException(`Cannot execute 'stop' on Client: Lifecycle methods must be called in following order: init, start, stop`, 'InvalidAccessError');
     }
 
-    await this.contextManager.stop();
-    await this.pluginManager.stop();
-    await this.socket.terminate();
+    await this.#contextManager[kClientContextManagerStop]();
+    await this.#pluginManager[kPluginManagerStop]();
+    await this.#socket[kSocketTerminate]();
 
-    await this._dispatchStatus('stopped');
+    await this.#dispatchStatus('stopped');
   }
 
   /**
    * Attach and retrieve the global audit state of the application.
    *
-   * The audit state is a {@link client.SharedState} instance that keeps track of
-   * global informations about the application such as, the number of connected
-   * clients, network latency estimation, etc. It is usefull for controller client
+   * The audit state is a {@link SharedState} instance that keeps track of
+   * global information about the application such as, the number of connected
+   * clients, network latency estimation, etc. It is useful for controller client
    * roles to give the user an overview about the state of the application.
    *
    * The audit state is lazily attached to the client only if this method is called.
    *
-   * @returns {Promise<client.SharedState>}
+   * @returns {Promise<SharedState>}
    * @throws Will throw if called before `client.init()`
-   * @see {@link client.SharedState}
+   * @see {@link SharedState}
    * @example
    * const auditState = await client.getAuditState();
    * auditState.onUpdate(() => console.log(auditState.getValues()), true);
    */
   async getAuditState() {
-    if (this.status === 'idle') {
-      throw new Error(`[soundworks.Client] Cannot access audit state before "client.init()"`);
+    if (this.#status === 'idle') {
+      throw new DOMException(`Cannot execute 'getAuditState' on Server: 'init' must be called first`, 'InvalidAccessError');
     }
 
-    if (this._auditState === null) {
-      this._auditState = await this.stateManager.attach(AUDIT_STATE_NAME);
+    if (this.#auditState === null) {
+      this.#auditState = await this.#stateManager.attach(AUDIT_STATE_NAME);
     }
 
-    return this._auditState;
+    return this.#auditState;
   }
 
   /**
    * Listen for the status change ('inited', 'started', 'stopped') of the client.
    *
    * @param {Function} callback - Listener to the status change.
-   * @returns {Function} Delete the listener.
+   * @returns {Function} Function that delete the listener when executed.
    */
   onStatusChange(callback) {
-    this._onStatusChangeCallbacks.add(callback);
-
-    return () => this._onStatusChangeCallbacks.delete(callback);
-  }
-
-  /** @private */
-  async _dispatchStatus(status) {
-    this.status = status;
-
-    // if node target and launched in a child process, forward status to parent process
-    if (this.target === 'node' && process.send !== undefined) {
-      process.send(`soundworks:client:${status}`);
-    }
-
-    // execute all callbacks in parallel
-    const promises = [];
-
-    for (let callback of this._onStatusChangeCallbacks) {
-      promises.push(callback(status));
-    }
-
-    await Promise.all(promises);
+    this[kClientOnStatusChangeCallbacks].add(callback);
+    return () => this[kClientOnStatusChangeCallbacks].delete(callback);
   }
 }
 
+Object.defineProperties(Client.prototype, {
+  [Symbol.toStringTag]: {
+    __proto__: null,
+    writable: false,
+    enumerable: false,
+    configurable: true,
+    value: 'Client',
+  },
+});
+
 export default Client;