@soundworks/core 4.0.0-alpha.27 → 4.0.0-alpha.29

package/src/client/ClientContextManager.js

@@ -0,0 +1,115 @@
+import {
+  kClientContextStatus,
+} from './ClientContext.js';
+
+export const kClientContextManagerStart = Symbol('soundworks:client-context-manager-start');
+export const kClientContextManagerStop = Symbol('soundworks:client-context-manager-stop');
+export const kClientContextManagerRegister = Symbol('soundworks:client-context-manager-register');
+
+/** @private */
+class ContextCollection {
+  #inner = [];
+
+  constructor() {
+    this.#inner = [];
+  }
+
+  add(context) {
+    this.#inner.push(context);
+  }
+
+  has(name) {
+    return this.#inner.find(c => c.name === name) !== undefined;
+  }
+
+  get(name) {
+    return this.#inner.find(c => c.name === name);
+  }
+
+  map(func) {
+    return this.#inner.map(func);
+  }
+}
+
+/**
+ * Manage the different contexts and their lifecycle.
+ *
+ * See {@link Client#contextManager}
+ *
+ * _WARNING: In most cases, you should not have to manipulate the context manager directly._
+ *
+ * @hideconstructor
+ */
+class ClientContextManager {
+  #contexts = new ContextCollection();
+  #contextStartPromises = new Map();
+
+  /**
+   * Register the context into the manager. Is called in context constructor.
+   *
+   * @param {ClientContext} context - The context to be registered.
+   * @private
+   */
+  [kClientContextManagerRegister](context) {
+    if (this.#contexts.has(context.name)) {
+      throw new Error(`[soundworks:context-manager] Context "${context.name}" already registered`);
+    }
+
+    this.#contexts.add(context);
+  }
+
+  /**
+   * Start all registered contexts. Called during `client.start()`
+   * @private
+   */
+  async [kClientContextManagerStart]() {
+    const promises = this.#contexts.map(context => this.get(context.name));
+    await Promise.all(promises);
+  }
+
+  /**
+   * Stop all registered contexts. Called during `client.stop()`
+   * @private
+   */
+  async [kClientContextManagerStop]() {
+    const promises = this.#contexts.map(context => context.stop());
+    await Promise.all(promises);
+  }
+
+  /**
+   * Retrieve a started context from its name.
+   *
+   * _WARNING: Most of the time, you should not have to call this method manually._
+   *
+   * @param {string} contextName - Name of the context.
+   * @returns {Promise<ClientContext>}
+   */
+  async get(contextName) {
+    if (!this.#contexts.has(contextName)) {
+      throw new Error(`[soundworks:ClientContextManager] Can't get context "${contextName}", not registered`);
+    }
+
+    const context = this.#contexts.get(contextName);
+
+    if (this.#contextStartPromises.has(contextName)) {
+      const startPromise = this.#contextStartPromises.get(contextName);
+      await startPromise;
+    } else {
+      context[kClientContextStatus] = 'inited';
+
+      try {
+        const startPromise = context.start();
+        this.#contextStartPromises.set(contextName, startPromise);
+        await startPromise;
+        context[kClientContextStatus] = 'started';
+      } catch (err) {
+        context[kClientContextStatus] = 'errored';
+        throw new Error(err);
+      }
+    }
+
+    return context;
+  }
+}
+
+export default ClientContextManager;

package/src/client/{Plugin.js → ClientPlugin.js}

@@ -3,14 +3,14 @@ import BasePlugin from '../common/BasePlugin.js';
 /**
  * Callback executed when the plugin state is updated.
  *
- * @callback client.Plugin~onStateChangeCallback
- * @param {client.Plugin#state} state - Current state of the plugin.
+ * @callback ClientPlugin~onStateChangeCallback
+ * @param {ClientPlugin#state} state - Current state of the plugin.
  */
 
 /**
- * Delete the registered {@link client.Plugin~onStateChangeCallback}.
+ * Delete the registered {@link ClientPlugin~onStateChangeCallback}.
  *
- * @callback client.Plugin~deleteOnStateChangeCallback
+ * @callback ClientPlugin~deleteOnStateChangeCallback
  */
 
 /**
@@ -28,40 +28,44 @@ import BasePlugin from '../common/BasePlugin.js';
  *
  * _Creating new plugins should be considered an advanced usage._
  *
- * @memberof client
  * @extends BasePlugin
  * @inheritdoc
  */
-class Plugin extends BasePlugin {
+class ClientPlugin extends BasePlugin {
+  #client = null;
   /**
-   * @param {client.Client} client - The soundworks client instance.
+   * @param {Client} client - A soundworks client instance.
    * @param {string} id - User defined id of the plugin as defined in
-   *  {@link client.PluginManager#register}.
+   *  {@link ClientPluginManager#register}.
    */
   constructor(client, id) {
     super(id);
 
-    /**
-     * Instance of soundworks client.
-     *
-     * @type {client.Client}
-     * @see {@link client.Client}
-     */
-    this.client = client;
+    this.#client = client;
+  }
+
+  /**
+   * Instance of soundworks client.
+   *
+   * @type {Client}
+   * @see {@link Client}
+   */
+  get client() {
+    return this.#client;
   }
 
   // @todo
   // /**
   //  * Interface method to implement if specific logic should be done when a
-  //  * {@link client.Client} enters the plugin.
+  //  * {@link Client} enters the plugin.
   //  */
   // async activate() {}
   //
   // /**
   //  * Interface method to implement if specific logic should be done when a
-  //  * {@link client.Client} exists the plugin.
+  //  * {@link Client} exists the plugin.
   //  */
   // async deactivate() {}
 }
 
-export default Plugin;
+export default ClientPlugin;

package/src/client/{PluginManager.js → ClientPluginManager.js}

@@ -1,28 +1,12 @@
 import BasePluginManager from '../common/BasePluginManager.js';
-import Plugin from './Plugin.js';
+import ClientPlugin from './ClientPlugin.js';
 import Client from './Client.js';
 
-/**
- * Callback executed when a plugin internal state is updated.
- *
- * @callback client.PluginManager~onStateChangeCallback
- * @param {object<client.Plugin#id, client.Plugin>} fullState - List of all plugins.
- * @param {client.Plugin|null} initiator - Plugin that initiated the update or `null`
- *  if the change was initiated by the state manager (i.e. when the initialization
- *  of the plugins starts).
- */
-
-/**
- * Delete the registered {@link client.PluginManager~onStateChangeCallback}.
- *
- * @callback client.PluginManager~deleteOnStateChangeCallback
- */
-
 /**
  * The `PluginManager` allows to register and retrieve `soundworks` plugins.
  *
  * Plugins should always be registered both client-side and server-side,
- * and before {@link client.Client#start} or {@link server.Server#start}
+ * and before {@link Client#start} or {@link Server#start}
  * to be properly initialized.
  *
  * In some sitautions, you might want to register the same plugin factory several times
@@ -32,7 +16,7 @@ import Client from './Client.js';
  * they expose. See [https://soundworks.dev/guide/ecosystem](https://soundworks.dev/guide/ecosystem)
  * for more informations on the available plugins.
  *
- * See {@link client.Client#pluginManager}
+ * See {@link Client#pluginManager}
  *
  * ```
  * // client-side
@@ -72,28 +56,50 @@ import Client from './Client.js';
  * }, 1000);
  * ```
  *
- * @memberof client
  * @extends BasePluginManager
  * @inheritdoc
  * @hideconstructor
  */
-class PluginManager extends BasePluginManager {
+class ClientPluginManager extends BasePluginManager {
   /**
-   * @param {client.Client} client - The soundworks client instance.
+   * @param {Client} client - The soundworks client instance.
    */
   constructor(client) {
     if (!(client instanceof Client)) {
-      throw new Error(`[soundworks.PluginManager] Invalid argument, "new PluginManager(client)" should receive an instance of "soundworks.Client" as argument`);
+      throw new Error(`[soundworks.ClientPluginManager] Invalid argument, "new ClientPluginManager(client)" should receive an instance of "soundworks.Client" as argument`);
     }
 
     super(client);
   }
 
+  /**
+   * Register a plugin into the manager.
+   *
+   * _A plugin must always be registered both on client-side and on server-side_
+   *
+   * Refer to the plugin documentation to check its options and proper way of
+   * registering it.
+   *
+   * @param {string} id - Unique id of the plugin. Enables the registration of the
+   *  same plugin factory under different ids.
+   * @param {Function} factory - Factory function that returns the Plugin class.
+   * @param {object} [options={}] - Options to configure the plugin.
+   * @param {array} [deps=[]] - List of plugins' names the plugin depends on, i.e.
+   *  the plugin initialization will start only after the plugins it depends on are
+   *  fully started themselves.
+   * @see {@link ClientPluginManager#register}
+   * @see {@link ServerPluginManager#register}
+   * @example
+   * // client-side
+   * client.pluginManager.register('user-defined-id', pluginFactory);
+   * // server-side
+   * server.pluginManager.register('user-defined-id', pluginFactory);
+   */
   register(id, factory, options = {}, deps = []) {
-    const ctor = factory(Plugin);
+    const ctor = factory(ClientPlugin);
 
-    if (!(ctor.prototype instanceof Plugin)) {
-      throw new Error(`[soundworks.PluginManager] Invalid argument, "pluginManager.register" second argument should be a factory function returning a class extending the "Plugin" base class`);
+    if (!(ctor.prototype instanceof ClientPlugin)) {
+      throw new Error(`[soundworks.ClientPluginManager] Invalid argument, "pluginManager.register" second argument should be a factory function returning a class extending the "Plugin" base class`);
     }
 
     super.register(id, ctor, options, deps);
@@ -112,21 +118,19 @@ class PluginManager extends BasePluginManager {
    * on the `onStateChange` method.
    *
    * _Note: the async API is designed to enable the dynamic creation of plugins
-   * (hopefully without brealing changes) in a future release._
-   *
-   * @param {client.Plugin#id} id - Id of the plugin as defined when registered.
-   * @returns {client.Plugin}
-   * @see {@link client.PluginManager#onStateChange}
+   * in a future release._
    *
-   * @private
+   * @param {string} id - Id of the plugin as defined when registered.
+   * @returns {Promise<ClientPlugin>}
+   * @see {@link ClientPluginManager#onStateChange}
    */
   async get(id) {
     if (this.status !== 'started') {
-      throw new Error(`[soundworks.PluginManager] Cannot get plugin before "client.init()"`);
+      throw new Error(`[soundworks.ClientPluginManager] Cannot get plugin before "client.init()"`);
     }
 
-    return super.unsafeGet(id);
+    return super.getUnsafe(id);
   }
 }
 
-export default PluginManager;
+export default ClientPluginManager;

package/src/client/{Socket.js → ClientSocket.js}

@@ -14,15 +14,15 @@ import {
 export const kSocketTerminate = Symbol('soundworks:socket-terminate');
 
 /**
- * The Socket class is a simple publish / subscribe wrapper built on top of the
+ * 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 `Socket` is automatically created by the `soundworks.Client`
- * (see {@link client.Client#socket}).
+ * 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 client.SharedState}
+ * _Important: In most cases, you should consider using a {@link SharedState}
  * rather than directly using the sockets._
  *
- * The Socket class concurrently opens two different WebSockets:
+ * 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
@@ -31,42 +31,48 @@ export const kSocketTerminate = Symbol('soundworks:socket-terminate');
  * Both sockets re-emits all "native" ws events ('open', 'upgrade', 'close', 'error'
  *  and 'message'.
  *
- * @memberof client
  * @hideconstructor
  */
-class Socket {
+class ClientSocket {
+  #role = null;
+  #config = null;
+  #socketOptions = null;
   #socket = null;
   #listeners = new Map();
 
-  constructor() {}
+  constructor(role, config, socketOptions) {
+    this.#role = role;
+    this.#config = config;
+    this.#socketOptions = socketOptions;
+  }
 
   /**
    * Initialize a websocket connection with the server. Automatically called
-   * during `client.init()`
+   * during {@link Client#init}
    *
-   * @param {string} role - Role of the client (see {@link client.Client#role})
+   * @param {string} role - Role of the client (see {@link Client#role})
    * @param {object} config - Configuration of the sockets
    * @private
    */
-  async init(role, config) {
-    let { path } = config.env.websockets;
+  async init() {
+    let { path } = this.#socketOptions;
     // cf. https://github.com/collective-soundworks/soundworks/issues/35
-    if (config.env.subpath) {
-      path = `${config.env.subpath}/${path}`;
+    if (this.#config.env.subpath) {
+      path = `${this.#config.env.subpath}/${path}`;
     }
 
-    const protocol = config.env.useHttps ? 'wss:' : 'ws:';
-    const port = config.env.port;
+    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 (config.env.serverAddress === '') {
+      if (this.#config.env.serverAddress === '') {
         serverAddress = hostname;
       } else {
-        serverAddress = config.env.serverAddress;
+        serverAddress = this.#config.env.serverAddress;
       }
 
       // when in https with self-signed certificates, we don't want to use
@@ -74,20 +80,20 @@ class Socket {
       // just override serverAddress with hostname in this case
       const localhosts = ['127.0.0.1', 'localhost'];
 
-      if (config.env.useHttps && localhosts.includes(hostname)) {
+      if (this.#config.env.useHttps && localhosts.includes(hostname)) {
         serverAddress = window.location.hostname;
       }
 
-      if (config.env.useHttps && window.location.hostname !== serverAddress) {
+      if (this.#config.env.useHttps && window.location.hostname !== serverAddress) {
         console.warn(`The WebSocket 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 (config.env.serverAddress === '') {
+      if (this.#config.env.serverAddress === '') {
         serverAddress = '127.0.0.1';
       } else {
-        serverAddress = config.env.serverAddress;
+        serverAddress = this.#config.env.serverAddress;
       }
 
       webSocketOptions = {
@@ -97,10 +103,10 @@ class Socket {
       };
     }
 
-    let queryParams = `role=${role}`;
+    let queryParams = `role=${this.#role}`;
 
-    if (config.token) {
-      queryParams += `&token=${config.token}`;
+    if (this.#config.token) {
+      queryParams += `&token=${this.#config.token}`;
     }
 
     const url = `${protocol}//${serverAddress}:${port}/${path}?${queryParams}`;
@@ -112,67 +118,51 @@ class Socket {
       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 whensome 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 => {
-          // parse incoming messages for pubsub
           this.#socket = ws;
 
           this.#socket.addEventListener('message', e => {
             if (e.data === PING_MESSAGE) {
               this.#socket.send(PONG_MESSAGE);
-              // do not propagate ping / pong messages
-              return;
+              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 "native" events
-          // `close`:
-          //   Fired when a connection with a websocket is closed.
-          //   Also available via the onclose property
-          // `error`:
-          //   Fired when a connection with a websocket has been closed because of an error,
-          //   such as whensome data couldn't be sent.
-          //   Also available via the onerror property.
-          // `message`:
-          //   Fired when data is received through a websocket.
-          //   Also available via the onmessage property.
-          // `open`:
-          //   Fired when a connection with a websocket is opened.
-          //   Also available via the onopen property.
-          [
-            'close',
-            'error',
-            'upgrade',
-            'message',
-          ].forEach(eventName => {
-            this.#socket.addEventListener(eventName, e => {
-              this.#dispatchEvent(eventName, e);
-            });
-          })
-
-          // forward open event
+          // 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);
-          // continue with raw socket
           resolve();
         });
 
         // cf. https://github.com/collective-soundworks/soundworks/issues/17
+        // cf. https://github.com/collective-soundworks/soundworks/issues/97
         ws.addEventListener('error', e => {
-          if (ws.terminate) {
-            ws.terminate();
-          } else {
-            ws.close();
-          }
+          ws.terminate ? ws.terminate() : ws.close();
 
           if (e.error) {
             const msg = `[Socket Error] code: ${e.error.code}, message: ${e.error.message}`;
             logger.log(msg);
           }
 
-          // Try 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.
+          // 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);
         });
       };
@@ -203,7 +193,6 @@ class Socket {
   }
 
   /**
-   * @param {boolean} binary - Emit to either the string or binary socket.
    * @param {string} channel - Channel name.
    * @param {...*} args - Content of the message.
    */
@@ -234,7 +223,7 @@ class Socket {
    * @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 server.Socket#send} method.
+   *  {@link ServerSocket#send} method.
    */
   addListener(channel, callback) {
     if (!this.#listeners.has(channel)) {
@@ -276,4 +265,4 @@ class Socket {
   }
 }
 
-export default Socket;
+export default ClientSocket;

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

@@ -1,7 +1,7 @@
 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
@@ -9,11 +9,11 @@ import BaseStateManager from '../common/BaseStateManager.js';
  */
 
 /**
- * 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). It
+ * can also track all the {@link SharedState}s created by other nodes.
  *
- * An instance of `StateManager` is automatically created by the `soundworks.Client`
+ * An instance of `ClientStateManager` is automatically created by the `soundworks.Client`
  * at initialization (cf. {@link client.Client#stateManager}).
  *
  * See {@link client.Client#stateManager}
@@ -57,11 +57,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

@@ -4,47 +4,23 @@
  * SPDX-License-Identifier: BSD-3-Clause
  */
 
+// this must be defined here so that we can import it into the application
 /**
- * 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);
- *   }
- * }
- *
- * launcher.execute(main);
- * ```
- *
- * @namespace client
+ * Configuration object for a client running in a browser runtime.
+ *
+ * @typedef ClientConfig
+ * @type {object}
+ * @property {string} role - Role of the client in the application (e.g. 'player', 'controller').
+ * @property {object} [app] - Application configuration object.
+ * @property {string} [app.name=''] - Name of the application.
+ * @property {string} [app.author=''] - Name of the author.
+ * @property {object} env - Environment configuration object.
+ * @property {boolean} env.useHttps - Define if the websocket should use secure connection.
+ * @property {string} env.serverAddress - Address the socket server. Mandatory for
+ *  node clients. For browser clients, use `window.location.domain` as fallback if empty.
+ * @property {number} env.port=8000 - Port of the socket server.
+ * @property {string} [env.subpath=''] - If running behind a proxy, path to the application.
  */
-export { default as Context } from './Context.js';
+
 export { default as Client } from './Client.js';
+export { default as ClientContext } from './ClientContext.js';