@soundworks/core 4.0.0-alpha.9 → 5.0.0

package/src/client/ClientSocket.js

@@ -0,0 +1,270 @@
+import { isBrowser } from '@ircam/sc-utils';
+import WebSocket from 'isomorphic-ws';
+
+import {
+  PING_MESSAGE,
+  PONG_MESSAGE,
+} from '../common/constants.js';
+import logger from '../common/logger.js';
+import {
+  packStringMessage,
+  unpackStringMessage,
+} from '../common/sockets-utils.js';
+
+export const kSocketTerminate = Symbol('soundworks:socket-terminate');
+
+/**
+ * The ClientSocket class is a simple publish / subscribe wrapper built on top of the
+ * [isomorphic-ws](https://github.com/heineiuo/isomorphic-ws) library.
+ * An instance of `ClientSocket` is automatically created by the `soundworks.Client`
+ * (see {@link Client#socket}).
+ *
+ * _Important: In most cases, you should consider using a {@link SharedState}
+ * rather than directly using the sockets._
+ *
+ * The ClientSocket class concurrently opens two different WebSockets:
+ * - a socket configured with `binaryType = 'blob'` for JSON compatible data
+ *  types (i.e. string, number, boolean, object, array and null).
+ * - a socket configured with `binaryType= 'arraybuffer'` for efficient streaming
+ *  of binary data.
+ *
+ * Both sockets re-emits all "native" ws events ('open', 'upgrade', 'close', 'error'
+ *  and 'message'.
+ *
+ * @hideconstructor
+ */
+class ClientSocket {
+  #role = null;
+  #config = null;
+  #socketOptions = null;
+  #socket = null;
+  #listeners = new Map();
+
+  constructor(role, config, socketOptions) {
+    this.#role = role;
+    this.#config = config;
+    this.#socketOptions = socketOptions;
+  }
+
+  /**
+   * Initialize a websocket connection with the server. Automatically called
+   * during {@link Client#init}
+   *
+   * @param {string} role - Role of the client (see {@link Client#role})
+   * @param {object} config - Configuration of the sockets
+   * @private
+   */
+  async init() {
+    let { path } = this.#socketOptions;
+    // cf. https://github.com/collective-soundworks/soundworks/issues/35
+    if (this.#config.env.baseUrl) {
+      path = `${this.#config.env.baseUrl}/${path}`;
+    }
+
+    const protocol = this.#config.env.useHttps ? 'wss:' : 'ws:';
+    const port = this.#config.env.port;
+    let serverAddress;
+    let webSocketOptions;
+
+    if (isBrowser()) {
+      const hostname = window.location.hostname;
+
+      if (this.#config.env.serverAddress === '') {
+        serverAddress = hostname;
+      } else {
+        serverAddress = this.#config.env.serverAddress;
+      }
+
+      // when in https with self-signed certificates, we don't want to use
+      // the serverAddress defined in config as the socket would be blocked, so we
+      // just override serverAddress with hostname in this case
+      const localhosts = ['127.0.0.1', 'localhost'];
+
+      if (this.#config.env.useHttps && localhosts.includes(hostname)) {
+        serverAddress = window.location.hostname;
+      }
+
+      if (this.#config.env.useHttps && window.location.hostname !== serverAddress) {
+        console.warn(`ClientSocket will try to connect at ${serverAddress} while the page is accessed from ${hostname}. This can lead to socket errors, e.g. If you run the application with self-signed certificates as the certificate may not have been accepted for ${serverAddress}. In such case you should rather access the page from ${serverAddress}.`);
+      }
+
+      webSocketOptions = [];
+    } else {
+      if (this.#config.env.serverAddress === '') {
+        serverAddress = '127.0.0.1';
+      } else {
+        serverAddress = this.#config.env.serverAddress;
+      }
+
+      webSocketOptions = {
+        // handshakeTimeout: 2000,
+        // do not reject self-signed certificates
+        rejectUnauthorized: false,
+      };
+    }
+
+    let queryParams = `role=${this.#role}`;
+
+    if (this.#config.token) {
+      queryParams += `&token=${this.#config.token}`;
+    }
+
+    const url = `${protocol}//${serverAddress}:${port}/${path}?${queryParams}`;
+
+    // ----------------------------------------------------------
+    // Init socket
+    // ----------------------------------------------------------
+    return new Promise(resolve => {
+      const trySocket = async () => {
+        const ws = new WebSocket(url, webSocketOptions);
+
+        // WebSocket "native" events:
+        // - `close`: Fired when a connection with a websocket is closed.
+        // - `error`: Fired when a connection with a websocket has been closed
+        //   because of an error, such as when some data couldn't be sent.
+        // - `message`: Fired when data is received through a websocket.
+        // - `open`: Fired when a connection with a websocket is opened.
+
+        ws.addEventListener('open', openEvent => {
+          this.#socket = ws;
+
+          this.#socket.addEventListener('message', e => {
+            if (e.data === PING_MESSAGE) {
+              this.#socket.send(PONG_MESSAGE);
+              return; // do not propagate ping pong messages
+            }
+
+            // Parse incoming message, dispatch in pubsub system and propagate raw event.
+            const [channel, args] = unpackStringMessage(e.data);
+            this.#dispatchEvent(channel, ...args);
+            this.#dispatchEvent('message', e);
+          });
+
+          // Propagate other native events
+          // @note - isn't it too late for the 'upgrade' message?
+          ['close', 'error', 'upgrade'].forEach(eventName => {
+            this.#socket.addEventListener(eventName, e => this.#dispatchEvent(eventName, e));
+          });
+
+          // Forward open event and continue initialization
+          this.#dispatchEvent('open', openEvent);
+          resolve();
+        });
+
+        // cf. https://github.com/collective-soundworks/soundworks/issues/17
+        // cf. https://github.com/collective-soundworks/soundworks/issues/97
+        ws.addEventListener('error', e => {
+          ws.terminate ? ws.terminate() : ws.close();
+
+          if (e.error) {
+            const msg = `ClientSocket error - code: ${e.error.code}, message: ${e.error.message}`;
+            logger.log(msg);
+          }
+
+          // Try to reconnect in all cases. Note that if the socket has been connected,
+          // the close event will be propagated and the launcher will restart the process.
+          setTimeout(trySocket, 1000);
+        });
+      };
+
+      trySocket();
+    });
+  }
+
+  /**
+   * Removes all listeners and immediately close the two sockets. Is automatically
+   * called on `client.stop()`
+   *
+   * Is also called when a disconnection is detected by the heartbeat (note that
+   * in this case, the launcher will call `client.stop()` but the listeners are
+   * already cleared so the event will be triggered only once.
+   *
+   * @private
+   */
+  async [kSocketTerminate]() {
+    const closeListeners = this.#listeners.get('close');
+    this.removeAllListeners();
+
+    this.#socket.close();
+
+    if (closeListeners) {
+      closeListeners.forEach(listener => listener());
+    }
+
+    return Promise.resolve();
+  }
+
+  /**
+   * @param {string} channel - Channel name.
+   * @param {...*} args - Content of the message.
+   */
+  #dispatchEvent(channel, ...args) {
+    if (this.#listeners.has(channel)) {
+      const callbacks = this.#listeners.get(channel);
+      callbacks.forEach(callback => callback(...args));
+    }
+  }
+
+  /**
+   * Send messages with JSON compatible data types on a given channel.
+   *
+   * @param {string} channel - Channel name.
+   * @param {...*} args - Payload of the message. As many arguments as needed, of
+   *  JSON compatible data types (i.e. string, number, boolean, object, array and null).
+   */
+  send(channel, ...args) {
+    if (this.#socket.readyState === 1) {
+      const msg = packStringMessage(channel, ...args);
+      this.#socket.send(msg);
+    }
+  }
+
+  /**
+   * Listen messages with JSON compatible data types on a given channel.
+   *
+   * @param {string} channel - Channel name.
+   * @param {Function} callback - Callback to execute when a message is received,
+   *  arguments of the callback function will match the arguments sent using the
+   *  {@link ServerSocket#send} method.
+   */
+  addListener(channel, callback) {
+    if (!this.#listeners.has(channel)) {
+      this.#listeners.set(channel, new Set());
+    }
+
+    const callbacks = this.#listeners.get(channel);
+    callbacks.add(callback);
+  }
+
+  /**
+   * Remove a listener from JSON compatible messages on a given channel.
+   *
+   * @param {string} channel - Channel name.
+   * @param {Function} callback - Callback to remove.
+   */
+  removeListener(channel, callback) {
+    if (this.#listeners.has(channel)) {
+      const callbacks = this.#listeners.get(channel);
+      callbacks.delete(callback);
+
+      if (callbacks.size === 0) {
+        this.#listeners.delete(channel);
+      }
+    }
+  }
+
+  /**
+   * Remove all listeners of messages with JSON compatible data types.
+   *
+   * @param {string} channel - Channel name.
+   */
+  removeAllListeners(channel = null) {
+    if (channel === null) {
+      this.#listeners.clear();
+    } else if (this.#listeners.has(channel)) {
+      this.#listeners.delete(channel);
+    }
+  }
+}
+
+export default ClientSocket;

package/src/client/{StateManager.js → ClientStateManager.js}

@@ -1,19 +1,20 @@
 import BaseStateManager from '../common/BaseStateManager.js';
 
 /**
- * @callback client.StateManager~ObserveCallback
+ * @callback ClientStateManager~ObserveCallback
  * @async
- * @param {String} schemaName - name of the schema
- * @param {Number} stateId - id of the state
- * @param {Number} nodeId - id of the node that created the state
+ * @param {String} className - Name of the shared state class.
+ * @param {Number} stateId - Id of the state.
+ * @param {Number} nodeId - Id of the node that created the state.
  */
 
 /**
- * The `StateManager` allows to create new {@link client.SharedState}s, or attach
- * to {@link client.SharedState}s created by other nodes (clients or server). It
- * can also track all the {@link client.SharedState}s created by other nodes.
+ * The `ClientStateManager` allows to create new {@link SharedState}s, or attach
+ * to {@link SharedState}s created by other nodes (clients or server) on the network.
  *
- * An instance of `StateManager` is automatically created by the `soundworks.Client`
+ * It can also observe all the {@link SharedState}s created on the network.
+ *
+ * An instance of `ClientStateManager` is automatically created by the `soundworks.Client`
  * at initialization (cf. {@link client.Client#stateManager}).
  *
  * See {@link client.Client#stateManager}
@@ -25,8 +26,8 @@ import BaseStateManager from '../common/BaseStateManager.js';
  * import { Server } from '@soundworks/server/index.js';
  *
  * const server = new Server(config);
- * // declare and register the schema of a shared state.
- * server.stateManager.registerSchema('some-global-state', {
+ * // define a class of shared state.
+ * server.stateManager.defineClass('some-global-state', {
  *   myRandom: {
  *     type: 'float',
  *     default: 0,
@@ -57,11 +58,10 @@ import BaseStateManager from '../common/BaseStateManager.js';
  * }, 1000);
  * ```
  *
- * @memberof client
  * @extends BaseStateManager
  * @inheritdoc
  * @hideconstructor
  */
-class StateManager extends BaseStateManager {}
+class ClientStateManager extends BaseStateManager {}
 
-export default StateManager;
+export default ClientStateManager;

package/src/client/index.js

@@ -1,44 +1,41 @@
 /**
- * Client-side part of the `soundworks` framework.
- *
- * A `soundworks` client can run seamlessly in a browser or in a Node.js runtime.
- *
- * ```
- * import '@soundworks/helpers/polyfills.js';
- * import { Client } from '@soundworks/core/client.js';
- * import launcher from '@soundworks/helpers/launcher.js';
- *
- * // - General documentation: https://soundworks.dev/
- * // - API documentation:     https://soundworks.dev/api
- * // - Issue Tracker:         https://github.com/collective-soundworks/soundworks/issues
- * // - Wizard & Tools:        `npx soundworks`
- *
- * const config = window.SOUNDWORKS_CONFIG;
- *
- * async function main($container) {
- *   try {
- *     const client = new Client(config);
- *
- *     // client.pluginManager.register(pluginName, pluginFactory, {options}, [dependencies])
- *
- *     launcher.register(client, {
- *       initScreensContainer: $container,
- *       reloadOnVisibilityChange: false,
- *     });
- *
- *     await client.start();
- *
- *     $container.innerText = `client ${client.id} started`);
- *
- *   } catch(err) {
- *     console.error(err);
- *   }
- * }
+ * @license
+ * Copyright (c) 2014-present IRCAM – Centre Pompidou (France, Paris)
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+// these types must be defined here, so that they can be imported into the application
+
+/**
+ * Application configuration object.
  *
- * launcher.execute(main);
- * ```
+ * @typedef ClientAppConfig
+ * @type {object}
+ * @property {string} [name=''] - Name of the application.
+ * @property {string} [author=''] - Name of the author.
+ */
+/**
+ * Environment configuration object.
+ *
+ * @typedef ClientEnvConfig
+ * @type {objecy}
+ * @property {number} env.port - Port on which the server is listening.
+ * @property {string} env.serverAddress - Domain name or IP of the server.
+ *  Mandatory when node clients are declared
+ * @property {boolean} env.useHttps - Define is the server run in http or in https.
+ * @property {string} [env.baseUrl=''] - If running behind a proxy, base URL of the application.
+ */
+/**
+ * Configuration object for a client running in a browser runtime.
  *
- * @namespace client
+ * @typedef ClientConfig
+ * @type {object}
+ * @property {string} role - Role of the client in the application (e.g. 'player', 'controller').
+ * @property {ClientAppConfig} app - Application configuration object.
+ * @property {ClientEnvConfig} env - Environment configuration object.
  */
-export { default as Context } from './Context.js';
+
 export { default as Client } from './Client.js';
+export { default as ClientPlugin } from './ClientPlugin.js';
+export { default as ClientContext } from './ClientContext.js';
+export { default as version } from '../common/version.js';

package/src/common/BasePlugin.js

@@ -1,45 +1,43 @@
-import merge from 'lodash.merge';
+import merge from 'lodash/merge.js';
+
+export const kBasePluginStatus = Symbol('soundworks:base-plugin-status');
+
+/**
+ * Callback executed when the plugin state is updated.
+ *
+ * @callback pluginOnStateChangeCallback
+ * @param {BasePlugin#state} state - Current state of the plugin.
+ */
 
 /**
- * @private
+ * Delete the registered {@link pluginOnStateChangeCallback}.
+ *
+ * @callback pluginDeleteOnStateChangeCallback
  */
+
+/** @private */
 class BasePlugin {
+  #id = null;
+  #onStateChangeCallbacks = new Set();
+
   constructor(id) {
+    this.#id = id;
     /** @private */
-    this._id = id;
-    /** @private */
-    this._type = this.constructor.name;
-
-    /**
-     * Options of the plugin.
-     *
-     * @type {object}
-     */
-    this.options = {};
+    this[kBasePluginStatus] = 'idle';
 
     /**
      * Placeholder that stores internal (local) state of the plugin. The state
      * should be modified through the `propagateStateChange` method to ensure
-     * the change to be properly propagated to `onStateChange` callbacks.
+     * the change to be properly propagated to manager `onStateChange` callbacks.
      *
      * @type {object}
      * @protected
-     * @see {@link client.Plugin#onStateChange}
-     * @see {@link server.Plugin#onStateChange}
-     * @see {@link client.Plugin#propagateStateChange}
-     * @see {@link server.Plugin#propagateStateChange}
+     * @see {@link ClientPlugin#onStateChange}
+     * @see {@link ServerPlugin#onStateChange}
+     * @see {@link ClientPlugin#propagateStateChange}
+     * @see {@link ServerPlugin#propagateStateChange}
      */
     this.state = {};
-
-    /**
-     * Current status of the plugin, i.e. 'idle', 'inited', 'started', 'errored'
-     *
-     * @type {string}
-     */
-    this.status = 'idle';
-
-    /** @private */
-    this._onStateChangeCallbacks = new Set();
   }
 
   /**
@@ -47,17 +45,17 @@ class BasePlugin {
    *
    * @type {string}
    * @readonly
-   * @see {@link client.PluginManager#register}
-   * @see {@link server.PluginManager#register}
+   * @see {@link ClientPluginManager#register}
+   * @see {@link ServerPluginManager#register}
    */
   get id() {
-    return this._id;
+    return this.#id;
   }
 
   /**
    * Type of the plugin, i.e. the ClassName.
    *
-   * Usefull to do perform some logic based on certain types of plugins without
+   * Useful to do perform some logic based on certain types of plugins without
    * knowing under which `id` they have been registered. (e.g. creating some generic
    * views, etc.)
    *
@@ -65,22 +63,32 @@ class BasePlugin {
    * @readonly
    */
   get type() {
-    return this._type;
+    return this.constructor.name;
+  }
+
+  /**
+   * Current status of the plugin.
+   *
+   * @type {'idle'|'inited'|'started'|'errored'}
+   */
+  get status() {
+    return this[kBasePluginStatus];
   }
 
   /**
-   * Start the plugin. This method is automatically called during the client or
-   * server `init()` lifecyle step. After `start()` is fulfilled the plugin should
-   * be ready to use.
+   * Start the plugin.
+   *
+   * This method is automatically called during the client or server `init()` lifecycle
+   * step. After `start()` is fulfilled the plugin should be ready to use.
    *
    * @example
-   * // server-side couterpart of a plugin that creates a dedicated global shared
+   * // server-side counterpart of a plugin that creates a dedicated global shared
    * // state on which the server-side part can attach.
-   * class MyPlugin extends Plugin {
+   * class MyPlugin extends ServerPlugin {
    *   constructor(server, id) {
    *     super(server, id);
    *
-   *     this.server.stateManager.registerSchema(`my-plugin:${this.id}`, {
+   *     this.server.stateManager.defineClass(`my-plugin:${this.id}`, {
    *       someParam: {
    *         type: 'boolean',
    *         default: false,
@@ -102,17 +110,18 @@ class BasePlugin {
   async start() {}
 
   /**
-   * Stop the plugin. This method is automatically called during the client or server
-   * `stop()` lifecyle step.
+   * Stop the plugin.
+   *
+   * This method is automatically called during the client or server `stop()` lifecycle step.
    *
    * @example
-   * // server-side couterpart of a plugin that creates a dedicated global shared
-   * // state on which the server-side part can attach.
-   * class MyPlugin extends Plugin {
+   * // server-side counterpart of a plugin that creates a dedicated global shared
+   * // state on which the client-side part can attach.
+   * class MyPlugin extends ServerPlugin {
    *   constructor(server, id) {
    *     super(server, id);
    *
-   *     this.server.stateManager.registerSchema(`my-plugin:${this.id}`, {
+   *     this.server.stateManager.defineClass(`my-plugin:${this.id}`, {
    *       someParam: {
    *         type: 'boolean',
    *         default: false,
@@ -137,20 +146,17 @@ class BasePlugin {
   /**
    * Listen to the state changes propagated by {@link BasePlugin.propagateStateChange}
    *
-   * @param {client.Plugin~onStateChangeCallback|server.Plugin~onStateChangeCallback} callback -
-   *  Callback to execute when a state change is propagated.
-   * @returns {client.Plugin~deleteOnStateChangeCallback|server.Plugin~deleteOnStateChangeCallback}
-   *  Execute the function to delete the listener from the callback list.
-   * @see {@link client.Plugin#propagateStateChange}
-   * @see {@link server.Plugin#propagateStateChange}
+   * @param {pluginOnStateChangeCallback} callback - Callback to execute when a state change is propagated.
+   * @returns {pluginDeleteOnStateChangeCallback}
+   *
    * @example
    * const unsubscribe = plugin.onStateChange(pluginState => console.log(pluginState));
    * // stop listening state changes
    * unsubscribe();
    */
   onStateChange(callback) {
-    this._onStateChangeCallbacks.add(callback);
-    return () => this._onStateChangeCallbacks.delete(callback);
+    this.#onStateChangeCallbacks.add(callback);
+    return () => this.#onStateChangeCallbacks.delete(callback);
   }
 
   /**
@@ -159,14 +165,13 @@ class BasePlugin {
    * through the `PluginManager#onStateChange` listeners.
    *
    * @param {object} updates - Updates to be merged in the plugin state.
-   * @see {@link client.Plugin#onStateChange}
-   * @see {@link server.Plugin#onStateChange}
-   * @see {@link client.PluginManager#onStateChange}
-   * @see {@link server.PluginManager#onStateChange}
+   *
+   * @see {@link BasePlugin#onStateChange}
+   * @see {@link BasePluginManager#onStateChange}
    */
   propagateStateChange(updates) {
-    merge(this.state, updates);
-    this._onStateChangeCallbacks.forEach(callback => callback(this.state));
+    this.state = merge(this.state, updates);
+    this.#onStateChangeCallbacks.forEach(callback => callback(this.state));
   }
 }