@soundworks/core 4.0.0-alpha.21 → 4.0.0-alpha.23

package/CHANGELOG.md

@@ -1,9 +1,20 @@
-## v4.0.0-alpha.21 - 19/02/2025
+## v4.0.0-alpha.23 - 24/05/2025
+
+- Breaking: remove binary socket
+- Fix: do not terminate socket on missed heartbeat, which seems to create false positive, just warn instead
+- Refactor: some work toward upgrading code to es2022
+
+## v4.0.0-alpha.22 - 16/05/2025
+
+- Feat: allow configuring socket endpoint on browser clients
+- Feat: check and warn if version inconsistency between server and client
+
+## v4.0.0-alpha.21 - 6/05/2025
 
 - Fix: prevent multiple 'close' events
 - Fix: disable heartbeat check on client-side, was unstable
-- Feat(SharedState): introduce 'local' option for parameters
-- Feat(SharedState): ability to filter parameters of interest
+- Feat: introduce 'local' option for SharedState parameters
+- Feat: ability to filter parameters of interest in SharedState
 
 ## v4.0.0-alpha.20 - 19/02/2024
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soundworks/core",
-  "version": "4.0.0-alpha.21",
+  "version": "4.0.0-alpha.23",
   "description": "Open-source creative coding framework for distributed applications based on Web technologies",
   "authors": [
     "Benjamin Matuszewski",
@@ -48,40 +48,40 @@
     "test": "npx mocha",
     "test:all": "npx mocha tests/*/*.spec.js",
     "types": "rm -Rf types && tsc",
-    "postversion": "node ./misc/scripts/check-changelog.js"
+    "preversion": "node ./misc/scripts/generate-version-file.js $npm_new_version",
+    "postversion": "node ./misc/scripts/check-changelog.js && git commit -am \"$npm_new_version\" --allow-empty"
   },
   "dependencies": {
-    "@ircam/sc-utils": "^1.3.2",
+    "@ircam/sc-utils": "^1.3.3",
     "chalk": "^5.3.0",
     "columnify": "^1.6.0",
     "compression": "^1.7.1",
-    "express": "^4.18.1",
+    "express": "^4.19.2",
     "fast-deep-equal": "^3.1.3",
-    "fast-text-encoding": "^1.0.0",
     "isomorphic-ws": "^5.0.0",
     "keyv": "^4.5.4",
-    "keyv-file": "^0.3.0",
+    "keyv-file": "^0.3.1",
     "lodash": "^4.17.21",
     "pem": "^1.14.8",
     "template-literal": "^1.0.4",
     "uuid": "^9.0.1",
-    "ws": "^8.15.0"
+    "ws": "^8.17.0"
   },
   "devDependencies": {
     "@ircam/eslint-config": "^1.3.0",
-    "chai": "^4.3.10",
+    "chai": "^5.1.1",
     "chai-shallow-deep-equal": "^1.4.6",
     "commitizen": "^4.2.5",
     "cz-conventional-changelog": "^3.3.0",
     "docdash": "^2.0.2",
-    "dotenv": "^16.3.1",
-    "eslint": "^8.55.0",
-    "eslint-plugin-jsdoc": "^46.9.0",
-    "jsdoc": "^4.0.0",
-    "mocha": "^10.2.0",
-    "puppeteer": "^21.6.0",
+    "dotenv": "^16.4.5",
+    "eslint": "^8.0.0",
+    "eslint-plugin-jsdoc": "^48.2.5",
+    "jsdoc": "^4.0.3",
+    "mocha": "^10.4.0",
+    "puppeteer": "^22.9.0",
     "tcp-ping": "^0.1.1",
-    "typescript": "^5.3.3"
+    "typescript": "^5.4.5"
   },
   "optionalDependencies": {
     "bufferutil": "^4.0.5",

package/src/client/Client.js

@@ -2,8 +2,11 @@ import { isBrowser, isPlainObject } from '@ircam/sc-utils';
 
 import ContextManager from './ContextManager.js';
 import PluginManager from './PluginManager.js';
-import Socket from './Socket.js';
+import Socket, {
+  kSocketTerminate,
+} from './Socket.js';
 import StateManager from './StateManager.js';
+
 import {
   CLIENT_HANDSHAKE_REQUEST,
   CLIENT_HANDSHAKE_RESPONSE,
@@ -11,11 +14,15 @@ import {
   AUDIT_STATE_NAME,
 } from '../common/constants.js';
 import logger from '../common/logger.js';
+import version from '../common/version.js';
+
+// for testing purposes
+export const kClientVersionTest = Symbol('soundworks:client-version-test');
 
 /**
  * Configuration object for a client running in a browser runtime.
  *
- * @typedef BrowserClientConfig
+ * @typedef ClientConfig
  * @memberof client
  * @type {object}
  * @property {string} role - Role of the client in the application (e.g. 'player', 'controller').
@@ -23,24 +30,10 @@ import logger from '../common/logger.js';
  * @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 {boolean} env.useHttps - Define if the websocket should use secure connection.
+ * @property {boolean} [env.serverAddress=''] - Address the socket server. Mandatory for
+ *  node clients. For browser clients, use `window.location.domain` as fallback if empty.
+ * @property {boolean} env.port - Port of the socket server.
  * @property {string} [env.websockets={}] - Configuration options for websockets.
  * @property {string} [env.subpath=''] - If running behind a proxy, path to the application.
  */
@@ -65,9 +58,24 @@ import logger from '../common/logger.js';
  * @memberof client
  */
 class Client {
+  #version = null;
+  #role = null;
+  #config = null;
+  #id = null;
+  #uuid = null;
+  #target = null;
+  #socket = null;
+  #contextManager = null;
+  #pluginManager = null;
+  #stateManager = null;
+  #status = 'idle';
+  // Token of the client if connected through HTTP authentication.
+  #token = null;
+  #onStatusChangeCallbacks = new Set();
+  #auditState = null;
+
   /**
-   * @param {client.BrowserClientConfig|client.NodeClientConfig} config -
-   *  Configuration of the soundworks client.
+   * @param {client.ClientConfig} config - Configuration of the soundworks client.
    * @throws Will throw if the given config object is invalid.
    */
   constructor(config) {
@@ -104,114 +112,168 @@ class Client {
       }
     }
 
-    /**
-     * 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 = {};
     }
 
     // minimal configuration for websockets
-    this.config.env.websockets = Object.assign({
+    this.#config.env.websockets = Object.assign({
       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 = new StateManager();
-
-    /**
-     * 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;
+    this.#version = version;
+    // allow override though config for testing
+    if (config[kClientVersionTest]) {
+      this.#version = config[kClientVersionTest];
+    }
 
-    /** @private */
-    this._onStatusChangeCallbacks = new Set();
-    /** @private */
-    this._auditState = null;
+    this.#role = config.role;
+    this.#target = isBrowser() ? 'browser' : 'node';
+    this.#socket = new Socket();
+    this.#contextManager = new ContextManager();
+    this.#pluginManager = new PluginManager(this);
+    this.#stateManager = new StateManager();
+    this.#status = 'idle';
 
     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 {client.ClientConfig}
+   */
+  get config() {
+    return this.#config;
+  }
+
+  /**
+   * Session id of the client.
+   *
+   * Incremeted positive integer generated and retrieved by the server during
+   * `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.Client#init}.
+   * @type {string}
+   */
+  get uuid() {
+    return this.#uuid;
+  }
+
+
+  /**
+   * Runtime platform on which the client is executed, i.e. 'browser' or 'node'.
+   *
+   * @type {string}
+   */
+  get target() {
+    return this.#target;
+  }
+
+  /**
+   * Instance of the {@link client.Socket} class.
+   *
+   * @see {@link client.Socket}
+   * @type {client.Socket}
+   */
+  get socket() {
+    return this.#socket;
+  }
+
+  /**
+   * 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}
+   */
+  get contextManager() {
+    return this.#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}
+   */
+  get pluginManager() {
+    return this.#pluginManager;
+  }
+
+  /**
+   * 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}
+   */
+  get stateManager() {
+    return this.#stateManager;
+  }
+
+  /**
+   * Status of the client, 'idle', 'inited', 'started' or 'errored'.
+   *
+   * @type {string}
+   */
+  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.#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);
+  }
+
   /**
    * 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
@@ -239,22 +301,26 @@ class Client {
    * await client.start();
    */
   async init() {
-    // init socket communications (string and binary)
-    await this.socket.init(this.role, this.config);
+    // init socket communications
+    await this.#socket.init(this.#role, this.#config);
 
     // 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.warnVersionDiscepancies(this.#role, this.#version, version);
+          }
 
           resolve();
         });
 
-        this.socket.addListener(CLIENT_HANDSHAKE_ERROR, (err) => {
+        this.#socket.addListener(CLIENT_HANDSHAKE_ERROR, (err) => {
           let msg = ``;
 
           switch (err.type) {
@@ -265,41 +331,38 @@ class Client {
               msg = `[soundworks:Client] ${err.message}`;
               break;
             default:
-              msg = `Undefined error`;
+              msg = `[soundworks:Client] Undefined error: ${err.message}`;
               break;
           }
 
-          this.socket.terminate();
+          // These are development errors, we can just hang. If we terminate the
+          // socket, a reload is triggered by the launcher which is bad in terms of 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.init(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.init(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.start();
 
-    await this._dispatchStatus('inited');
+    await this.#dispatchStatus('inited');
   }
 
   /**
@@ -319,24 +382,16 @@ class Client {
    * await client.start();
    */
   async start() {
-    if (this.status === 'idle') {
+    if (this.#status === 'idle') {
       await this.init();
     }
 
-    if (this.status === 'started') {
+    if (this.#status === 'started') {
       throw new Error(`[soundworks:Server] Cannot call "client.start()" twice`);
     }
 
-    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.start();
+    await this.#dispatchStatus('started');
   }
 
   /**
@@ -356,15 +411,15 @@ class Client {
    * await client.stop();
    */
   async stop() {
-    if (this.status !== 'started') {
+    if (this.#status !== 'started') {
       throw new Error(`[soundworks:Client] Cannot "client.stop()" before "client.start()"`);
     }
 
-    await this.contextManager.stop();
-    await this.pluginManager.stop();
-    await this.socket.terminate();
+    await this.#contextManager.stop();
+    await this.#pluginManager.stop();
+    await this.#socket[kSocketTerminate]();
 
-    await this._dispatchStatus('stopped');
+    await this.#dispatchStatus('stopped');
   }
 
   /**
@@ -385,47 +440,37 @@ class Client {
    * auditState.onUpdate(() => console.log(auditState.getValues()), true);
    */
   async getAuditState() {
-    if (this.status === 'idle') {
+    if (this.#status === 'idle') {
       throw new Error(`[soundworks.Client] Cannot access audit state before "client.init()"`);
     }
 
-    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.#onStatusChangeCallbacks.add(callback);
+    return () => this.#onStatusChangeCallbacks.delete(callback);
   }
 }
 
+Object.defineProperties(Client.prototype, {
+  [Symbol.toStringTag]: {
+    __proto__: null,
+    writable: false,
+    enumerable: false,
+    configurable: true,
+    value: 'Client',
+  },
+});
+
 export default Client;