@soundworks/core 3.7.0 → 4.0.0-alpha.1

package/src/client/Socket.js

@@ -0,0 +1,389 @@
+import WebSocket from 'isomorphic-ws';
+
+import {
+  packBinaryMessage,
+  unpackBinaryMessage,
+  packStringMessage,
+  unpackStringMessage,
+} from '../common/sockets-utils.js';
+import logger from '../common/logger.js';
+import { isBrowser } from '../common/utils.js';
+
+// WebSocket 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.
+
+/**
+ * The Socket 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`.
+ *
+ * _Important: In most cases, you should consider using a {@link client.SharedState} rather than
+ * sending messages directly through the sockets._
+ *
+ * The Socket class concurrently opens two different WebSockets:
+ * - a socket configured with `binaryType = 'string'` for JSON compatible string
+ *  messages.
+ * - 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'.
+ *
+ * See {@link client.Client#socket}
+ *
+ * @memberof client
+ * @hideconstructor
+ */
+class Socket {
+  constructor() {
+    /**
+     * WebSocket instance w/ string protocol, i.e. `binaryType = 'string'`.
+     *
+     * @private
+     */
+    this.ws = null;
+    /**
+     * WebSocket instance w/ binary protocol, i.e. `binaryType = 'arraybuffer'`.
+     *
+     * @private
+     */
+    this.binaryWs = null;
+    /** @private */
+    this._stringListeners = new Map();
+    /** @private */
+    this._binaryListeners = new Map();
+  }
+
+  /**
+   * Initialize a websocket connection with the server. Automatically called
+   * during `client.init()`
+   *
+   * @param {string} role - Role of the client (see {@link client.Client#role})
+   * @param {object} config - Configuration of the sockets
+   * @protected
+   * @ignore
+   */
+  async init(role, config) {
+    // unique key that allows to associate the two sockets to the same client.
+    // note: the key is only used to pair to two sockets, so its usage is very
+    // limited in time therefore a random number should hopefully be sufficient.
+    const key = (Math.random() + '').replace(/^0\./, '');
+
+    // open web sockets
+    let { path } = config.env.websockets;
+
+    // @note: keep this check
+    // backward compatibility w/ assetsDomain and websocket old config way
+    // cf. https://github.com/collective-soundworks/soundworks/issues/35
+    if (config.env.subpath) {
+      path = `${config.env.subpath}/${path}`;
+    }
+
+    let url;
+    let webSocketOptions;
+
+    if (isBrowser()) {
+      const protocol = window.location.protocol.replace(/^http?/, 'ws');
+      const { hostname, port } = window.location;
+
+      url = `${protocol}//${hostname}:${port}/${path}`;
+      webSocketOptions = [];
+    } else {
+      const protocol = config.env.useHttps ? 'wss:' : 'ws:';
+      const { serverAddress, port } = config.env;
+
+      url = `${protocol}//${serverAddress}:${port}/${path}`;
+      webSocketOptions = {
+        rejectUnauthorized: false,
+      };
+    }
+
+    const queryParams = `role=${role}&key=${key}`;
+
+    // ----------------------------------------------------------
+    // init string socket
+    // ----------------------------------------------------------
+    const stringSocketUrl = `${url}?binary=0&${queryParams}`;
+
+    await new Promise(resolve => {
+      let connectionRefusedLogged = false;
+
+      const trySocket = async () => {
+        const ws = new WebSocket(stringSocketUrl, webSocketOptions);
+
+        ws.addEventListener('open', connectEvent => {
+          // parse incoming messages for pubsub
+          this.ws = ws;
+          this.ws.addEventListener('message', e => {
+            const [channel, args] = unpackStringMessage(e.data);
+            this._emit(false, channel, ...args);
+          });
+
+          // broadcast all `WebSocket` native events
+          ['close', 'error', 'upgrade', 'message'].forEach(eventName => {
+            this.ws.addEventListener(eventName, (e) => {
+              this._emit(false, eventName, e);
+            });
+          });
+
+          // forward open event
+          this._emit(false, 'open', connectEvent);
+          // continue with raw socket
+          resolve();
+        });
+
+        // cf. https://github.com/collective-soundworks/soundworks/issues/17
+        ws.addEventListener('error', e => {
+          if (e.type === 'error' && e.error.code === 'ECONNREFUSED') {
+            if (!connectionRefusedLogged) {
+              logger.log('[soundworks.Socket] Connection refused, waiting for the server to start');
+              connectionRefusedLogged = true;
+            }
+
+            if (ws.terminate) {
+              ws.terminate();
+            } else {
+              ws.close();
+            }
+
+            setTimeout(trySocket, 1000);
+          }
+        });
+      };
+
+      trySocket();
+    });
+
+    // @todo - review/fix
+    // - the `ws.on` method only exists on node implementation, and the 'ping'
+    //   message is not received on addEventListener
+    // - there seems to be no way to access the ping event in browsers...
+    //
+    // let pingTimeoutId = null;
+    // const pingInterval = config.env.websockets.pingInterval;
+    // // detect broken connection
+    // // cf. https://github.com/websockets/ws#how-to-detect-and-close-broken-connections
+    // const heartbeat = () => {
+    //   try {
+    //     console.log('ping received');
+    //     clearTimeout(pingTimeoutId);
+
+    //   // pingTimeoutId = setTimeout(() => {
+    //   //   console.log('terminate');
+    //   //   this.terminate();
+    //   // }, pingInterval + 2000);
+    //   } catch (err) {
+    //     console.error(err);
+    //   }
+    // };
+    //
+    // this.ws.on('ping', heartbeat);
+    // this.ws.addEventListener('close', () => {
+    //   clearTimeout(pingTimeoutId);
+    // });
+
+    // heartbeat();
+
+    // ----------------------------------------------------------
+    // init binary socket
+    // ----------------------------------------------------------
+    const binarySocketUrl = `${url}?binary=1&${queryParams}`;
+
+    await new Promise(resolve => {
+      const ws = new WebSocket(binarySocketUrl, webSocketOptions);
+      ws.binaryType = 'arraybuffer';
+
+      ws.addEventListener('open', connectEvent => {
+        // parse incoming messages for pubsub
+        this.binaryWs = ws;
+        this.binaryWs.addEventListener('message', e => {
+          const [channel, data] = unpackBinaryMessage(e.data);
+          this._emit(true, channel, data);
+        });
+
+        // broadcast all `WebSocket` native events
+        ['close', 'error', 'upgrade', 'message'].forEach(eventName => {
+          this.binaryWs.addEventListener(eventName, (e) => {
+            this._emit(true, eventName, e);
+          });
+        });
+
+        // forward open event
+        this._emit(true, 'open', connectEvent);
+        resolve();
+      });
+    });
+
+    // wait for both sockets connected
+    return Promise.resolve();
+  }
+
+  /**
+   * @param {boolean} binary - Emit to either the string or binary socket.
+   * @param {string} channel - Channel name.
+   * @param {...*} args - Content of the message.
+   * @private
+   */
+  _emit(binary, channel, ...args) {
+    const listeners = binary ? this._binaryListeners : this._stringListeners;
+
+    if (listeners.has(channel)) {
+      const callbacks = listeners.get(channel);
+      callbacks.forEach(callback => callback(...args));
+    }
+  }
+
+  /**
+   * @param {Function[]} listeners - List of listeners, either for the string or binary socket.
+   * @param {string} channel - Channel name.
+   * @param {Function} callback - The function to be added to the listeners.
+   * @private
+   */
+  _addListener(listeners, channel, callback) {
+    if (!listeners.has(channel)) {
+      listeners.set(channel, new Set());
+    }
+
+    const callbacks = listeners.get(channel);
+    callbacks.add(callback);
+  }
+
+  /**
+   * @param {Function[]} listeners - List of listeners, either for the string or binary socket.
+   * @param {string} channel - Channel name.
+   * @param {Function} callback - The function to be removed from the listeners.
+   * @private
+   */
+  _removeListener(listeners, channel, callback) {
+    if (listeners.has(channel)) {
+      const callbacks = listeners.get(channel);
+      callbacks.delete(callback);
+
+      if (callbacks.size === 0) {
+        listeners.delete(channel);
+      }
+    }
+  }
+
+  /**
+   * @param {Function[]} listeners - List of listeners, either for the string or binary socket.
+   * @param {string} [channel=null] - Channel name of the listeners to remove. If null
+   *  all the listeners are cleared.
+   * @private
+   */
+  _removeAllListeners(listeners, channel = null) {
+    if (channel === null) {
+      listeners.clear();
+    } else if (listeners.has(channel)) {
+      listeners.delete(channel);
+    }
+  }
+
+  /**
+   * Send JSON compatible messages on a given channel.
+   *
+   * @param {string} channel - Channel name of the message.
+   * @param {...*} args - Message list, as many as needed, of any serializable type).
+   */
+  send(channel, ...args) {
+    const msg = packStringMessage(channel, ...args);
+    this.ws.send(msg);
+  }
+
+  /**
+   * Listen to JSON compatible messages on a given channel.
+   *
+   * @param {string} channel - Channel name of the message.
+   * @param {Function} callback - Callback to execute when a message is received.
+   */
+  addListener(channel, callback) {
+    this._addListener(this._stringListeners, channel, callback);
+  }
+
+  /**
+   * Remove a listener from JSON compatible messages on a given channel.
+   *
+   * @param {string} channel - Channel name of the message.
+   * @param {Function} callback - Callback to remove.
+   */
+  removeListener(channel, callback) {
+    this._removeListener(this._stringListeners, channel, callback);
+  }
+
+  /**
+   * Remove all listeners from JSON compatible messages on a given channel.
+   *
+   * @param {string} channel - Channel name of the message.
+   */
+  removeAllListeners(channel = null) {
+    this._removeAllListeners(this._stringListeners, channel);
+  }
+
+  /**
+   * Send binary messages on a given channel.
+   *
+   * @param {string} channel - Channel name of the message.
+   * @param {TypedArray} typedArray - Binary data to be sent.
+   */
+  sendBinary(channel, typedArray) {
+    const msg = packBinaryMessage(channel, typedArray);
+    this.binaryWs.send(msg);
+  }
+
+  /**
+   * Listen binary messages on a given channel.
+   *
+   * @param {string} channel - Channel name of the message.
+   * @param {Function} callback - Callback to execute when a message is received.
+   */
+  addBinaryListener(channel, callback) {
+    this._addListener(this._binaryListeners, channel, callback);
+  }
+
+  /**
+   * Remove a listener from binary compatible messages on a given channel
+   *
+   * @param {string} channel - Channel of the message.
+   * @param {Function} callback - Callback to cancel.
+   */
+  removeBinaryListener(channel, callback) {
+    this._removeListener(this._binaryListeners, channel, callback);
+  }
+
+  /**
+   * Remove all listeners from binary compatible messages on a given channel
+   *
+   * @param {string} channel - Channel of the message.
+   */
+  removeAllBinaryListeners(channel = null) {
+    this._removeAllListeners(this._binaryListeners, channel);
+  }
+
+  /**
+   * Removes all listeners and immediately close the two sockets.
+   */
+  async terminate() {
+    this.removeAllListeners();
+    this.removeAllBinaryListeners();
+
+    this.ws.close();
+    this.binaryWs.close();
+
+    return Promise.resolve();
+  }
+}
+
+export default Socket;

package/src/client/StateManager.js

@@ -0,0 +1,67 @@
+import BaseStateManager from '../common/BaseStateManager.js';
+
+/**
+ * @callback client.StateManager~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
+ */
+
+/**
+ * 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.
+ *
+ * An instance of `StateManager` is automatically created by the `soundworks.Client`
+ * at initialization (cf. {@link client.Client#stateManager}).
+ *
+ * See {@link client.Client#stateManager}
+ *
+ * Tutorial: {@link https://soundworks.dev/guide/state-manager.html}
+ *
+ * ```
+ * // server-side
+ * 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', {
+ *   myRandom: {
+ *     type: 'float',
+ *     default: 0,
+ *   }
+ * });
+ *
+ * await server.start();
+ *
+ * // create a global state server-side
+ * const globalState = await server.stateManager.create('some-global-state');
+ * // listen and react to the changes made by the clients
+ * globalState.onUpdate(updates => console.log(updates));
+ * ```
+ *
+ * ```
+ * // client-side
+ * import { Client } from '@soundworks/client.index.js';
+ *
+ * const client = new Client(config);
+ * await client.start();
+ *
+ * // attach to the global state created by the server
+ * const globalState = await client.stateManager.attach('some-global-state');
+ *
+ * // update the value of a `myRandom` parameter every seconds
+ * setInterval(() => {
+ *   globalState.set({ myRandom: Math.random() });
+ * }, 1000);
+ * ```
+ *
+ * @memberof client
+ * @extends BaseStateManager
+ * @inheritdoc
+ * @hideconstructor
+ */
+class StateManager extends BaseStateManager {}
+
+export default StateManager;

package/src/client/index.js

@@ -0,0 +1,77 @@
+/**
+ * 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.
+ */
+
+/**
+ * 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
+ */
+export { default as Context } from './Context.js';
+export { default as Client } from './Client.js';

package/src/common/BasePlugin.js

@@ -0,0 +1,163 @@
+import merge from 'lodash.merge';
+
+/**
+ * @private
+ */
+class BasePlugin {
+  constructor(id) {
+    /**
+     * User defined ID of the plugin.
+     *
+     * @type {string}
+     * @see {@link client.PluginManager#register}
+     * @see {@link server.PluginManager#register}
+     */
+    this.id = id;
+
+    /**
+     * Type of the plugin, i.e. the ClassName.
+     *
+     * Usefull 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.)
+     *
+     * @type {string}
+     * @readonly
+     */
+    this.type = this.constructor.name;
+
+    /**
+     * Options of the plugin.
+     *
+     * @type {object}
+     */
+    this.options = {};
+
+    /**
+     * 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.
+     *
+     * @type {object}
+     * @protected
+     * @see {@link client.Plugin#onStateChange}
+     * @see {@link server.Plugin#onStateChange}
+     * @see {@link client.Plugin#propagateStateChange}
+     * @see {@link server.Plugin#propagateStateChange}
+     */
+    this.state = {};
+
+    /**
+     * Current status of the plugin, i.e. 'idle', 'inited', 'started', 'errored'
+     *
+     * @type {string}
+     */
+    this.status = 'idle';
+
+    /** @private */
+    this._onStateChangeCallbacks = new Set();
+  }
+
+  /**
+   * 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.
+   *
+   * @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 {
+   *   constructor(server, id) {
+   *     super(server, id);
+   *
+   *     this.server.stateManager.registerSchema(`my-plugin:${this.id}`, {
+   *       someParam: {
+   *         type: 'boolean',
+   *         default: false,
+   *       },
+   *       // ...
+   *     });
+   *   }
+   *
+   *   async start() {
+   *     await super.start()
+   *     this.sharedState = await this.server.stateManager.create(`my-plugin:${this.id}`);
+   *   }
+   *
+   *   async stop() {
+   *     await this.sharedState.delete();
+   *   }
+   * }
+   */
+  async start() {}
+
+  /**
+   * Stop the plugin. This method is automatically called during the client or server
+   * `stop()` lifecyle 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 {
+   *   constructor(server, id) {
+   *     super(server, id);
+   *
+   *     this.server.stateManager.registerSchema(`my-plugin:${this.id}`, {
+   *       someParam: {
+   *         type: 'boolean',
+   *         default: false,
+   *       },
+   *       // ...
+   *     });
+   *   }
+   *
+   *   async start() {
+   *     await super.start()
+   *     this.sharedState = await this.server.stateManager.create(`my-plugin:${this.id}`);
+   *     this.sharedState.onUpdate(updates => this.doSomething(updates));
+   *   }
+   *
+   *   async stop() {
+   *     await this.sharedState.delete();
+   *   }
+   * }
+   */
+  async stop() {}
+
+  /**
+   * 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}
+   * @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);
+  }
+
+  /**
+   * Apply updates to the plugin state and propagate the updated state to the
+   * `onStateChange` listeners. The state changes will also be propagated
+   * 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}
+   */
+  propagateStateChange(updates) {
+    merge(this.state, updates);
+    this._onStateChangeCallbacks.forEach(callback => callback(this.state));
+  }
+}
+
+export default BasePlugin;