@soundworks/core 4.0.0-alpha.7 → 5.0.0

package/src/server/{Plugin.js → ServerPlugin.js}

@@ -1,18 +1,5 @@
 import BasePlugin from '../common/BasePlugin.js';
 
-/**
- * Callback executed when the plugin state is updated.
- *
- * @callback server.Plugin~onStateChangeCallback
- * @param {server.Plugin#state} state - Current state of the plugin.
- */
-
-/**
- * Delete the registered {@link server.Plugin~onStateChangeCallback}.
- *
- * @callback server.Plugin~deleteOnStateChangeCallback
- */
-
 /**
  * Base class to extend in order to create the server-side counterpart of a
  * `soundworks` plugin.
@@ -24,32 +11,43 @@ import BasePlugin from '../common/BasePlugin.js';
  * have both a client-side and a server-side part.
  *
  * See [https://soundworks.dev/guide/ecosystem](https://soundworks.dev/guide/ecosystem)
- * for more informations on the available plugins.
+ * for more information on the available plugins.
  *
  * _Creating new plugins should be considered an advanced usage._
  *
- * @memberof server
- * @extends BasePlugin
+ * @extends {BasePlugin}
  * @inheritdoc
  */
-class Plugin extends BasePlugin {
+class ServerPlugin extends BasePlugin {
+  #server = null;
+  #clients = new Set();
+
   /**
-   * @param {server.Server} server - The soundworks server instance.
+   * @param {Server} server - The soundworks server instance.
    * @param {string} id - User defined id of the plugin as defined in
-   *  {@link server.PluginManager#register}.
+   *  {@link ServerPluginManager#register}.
    */
   constructor(server, id) {
     super(id);
+    this.#server = server;
+  }
 
-    /**
-     * Instance of soundworks server.
-     * @type {server.Server}
-     * @see {@link server.Server}
-     */
-    this.server = server;
+  /**
+   * Instance of soundworks server.
+   * @type {Server}
+   * @see {@link Server}
+   */
+  get server() {
+    return this.#server;
+  }
 
-    /** @private */
-    this.clients = new Set();
+  /**
+   * Set of the clients registered in the plugin.
+   * @type {Set<ServerClient>}
+   * @see {@link ServerClient}
+   */
+  get clients() {
+    return this.#clients;
   }
 
   /**
@@ -57,10 +55,10 @@ class Plugin extends BasePlugin {
    * connects to the application. Override this method if you need to perform
    * some particular logic (e.g. creating a shared state) for each clients.
    *
-   * @param {server.Client} client
+   * @param {ServerClient} client
    */
   async addClient(client) {
-    this.clients.add(client);
+    this.#clients.add(client);
   }
 
   /**
@@ -68,11 +66,11 @@ class Plugin extends BasePlugin {
    * disconnects from the application. Override this method if you need to perform
    * some particular logic (e.g. creating a shared state) for each clients.
    *
-   * @param {server.Client} client
+   * @param {ServerClient} client
    */
   async removeClient(client) {
-    this.clients.delete(client);
+    this.#clients.delete(client);
   }
 }
 
-export default Plugin;
+export default ServerPlugin;

package/src/server/ServerPluginManager.js

@@ -0,0 +1,177 @@
+import BasePluginManager, {
+  kPluginManagerInstances,
+} from '../common/BasePluginManager.js';
+import ServerPlugin from './ServerPlugin.js';
+import Server from './Server.js';
+
+export const kServerPluginManagerCheckRegisteredPlugins = Symbol('soundworks:server-plugin-manager-check-registered-plugins');
+export const kServerPluginManagerAddClient = Symbol('soundworks:server-plugin-manager-add-client');
+export const kServerPluginManagerRemoveClient = Symbol('soundworks:server-plugin-manager-remove-client');
+
+/**
+ * The `PluginManager` allows to register and retrieve `soundworks` plugins.
+ *
+ * Plugins should always be registered both client-side and server-side,
+ * and before {@link Client#start} or {@link Server#start}
+ * to be properly initialized.
+ *
+ * In some situations, you might want to register the same plugin factory several times
+ * using different ids (e.g. for watching several parts of the file system, etc.).
+ *
+ * Refer to the plugins' documentation for more precise examples, and the specific API
+ * they expose. See [https://soundworks.dev/guide/ecosystem](https://soundworks.dev/guide/ecosystem)
+ * for more information on the available plugins.
+ *
+ * ```
+ * // client-side
+ * import { Client } from '@soundworks/core/client.js';
+ * import syncPlugin from '@soundworks/plugin-sync/client.js';
+ *
+ * const client = new Client(config);
+ * // register the plugin before `client.start()`
+ * client.pluginManager.register('sync', syncPlugin);
+ *
+ * await client.start();
+ *
+ * const sync = await client.pluginManager.get('sync');
+ *
+ * setInterval(() => {
+ *   // log the estimated global synced clock alongside the local clock.
+ *   console.log(sync.getSyncTime(), sync.getLocalTime());
+ * }, 1000);
+ * ```
+ *
+ * ```
+ * // server-side
+ * import { Server } from '@soundworks/core/server.js';
+ * import syncPlugin from '@soundworks/plugin-sync/server.js';
+ *
+ * const server = new Server(config);
+ * // register the plugin before `server.start()`
+ * server.pluginManager.register('sync', syncPlugin);
+ *
+ * await server.start();
+ *
+ * const sync = await server.pluginManager.get('sync');
+ *
+ * setInterval(() => {
+ *   // log the estimated global synced clock alongside the local clock.
+ *   console.log(sync.getSyncTime(), sync.getLocalTime());
+ * }, 1000);
+ * ```
+ *
+ * @extends BasePluginManager
+ * @inheritdoc
+ * @template T
+ */
+class ServerPluginManager extends BasePluginManager {
+  /** @hideconstructor */
+  constructor(server) {
+    if (!(server instanceof Server)) {
+      throw new TypeError(`Cannot construct 'ServerPluginManager': Argument 1 must be an instance of Server`);
+    }
+
+    super(server);
+  }
+
+  /** @private */
+  [kServerPluginManagerCheckRegisteredPlugins](registeredPlugins) {
+    let missingPlugins = [];
+
+    for (let id of registeredPlugins) {
+      if (!this[kPluginManagerInstances].has(id)) {
+        missingPlugins.push(id);
+      }
+    }
+
+    if (missingPlugins.length > 0) {
+      throw new DOMException(`Invalid 'ServerPluginManager' internal state: The following plugins registered on the client-side: [${missingPlugins.join(', ')}] have not been registered on the server-side. Plugins registered on the server-side are: [${Array.from(this[kPluginManagerInstances].keys()).join(', ')}].`, 'InvalidStateError');
+    }
+  }
+
+  /** @private */
+  async [kServerPluginManagerAddClient](client, registeredPlugins = []) {
+    let promises = [];
+
+    for (let pluginName of registeredPlugins) {
+      const plugin = await this.get(pluginName);
+      const promise = plugin.addClient(client);
+      promises.push(promise);
+    }
+
+    await Promise.all(promises);
+  }
+
+  /** @private */
+  async [kServerPluginManagerRemoveClient](client) {
+    let promises = [];
+
+    for (let plugin of this[kPluginManagerInstances].values()) {
+      if (plugin.clients.has(client)) {
+        promises.push(plugin.removeClient(client));
+      }
+    }
+
+    await Promise.all(promises);
+  }
+
+  /**
+   * 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 {T<ServerPlugin>} ctor - The server-side Class of the plugin.
+   * @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, ctor, options = {}, deps = []) {
+    // Note that other arguments are checked on the BasePluginManager
+    if (!ctor || !(ctor.prototype instanceof ServerPlugin)) {
+      throw new TypeError(`Cannot execute 'register' on ServerPluginManager (id: ${id}): argument 2 must be a class that extends 'ServerPlugin'`);
+    }
+
+    super.register(id, ctor, options, deps);
+  }
+
+  /**
+   * Retrieve a fully started instance of a registered plugin.
+   *
+   * Be aware that the `get` method resolves only when the plugin is fully 'started',
+   * which is what we want 99.99% of the time. As such, and to prevent the application
+   * to be stuck in some kind of Promise dead lock, this method will throw if
+   * used before `server.init()` (or `server.start()`).
+   *
+   * To handle the remaining 0.01% cases and access plugin instances during their
+   * initialization (e.g. to display initialization screen, etc.), you should rely
+   * on the `onStateChange` method.
+   *
+   * _Note: the async API is designed to enable the dynamic creation of plugins
+   * (hopefully without breaking changes) in a future release._
+   *
+   * @param {ServerPlugin#id} id - Id of the plugin as defined when registered.
+   * @returns {Promise<T<ServerPlugin>>}
+   */
+  async get(id) {
+    if (this.status !== 'started') {
+      throw new DOMException(`Cannot execute 'get' on ServerPluginManager: 'Server#init' has not been called yet`, 'NotSupportedError');
+    }
+
+    return super.getUnsafe(id);
+  }
+}
+
+export default ServerPluginManager;

package/src/server/ServerSocket.js

@@ -0,0 +1,256 @@
+import { getTime } from '@ircam/sc-utils';
+import {
+  PING_INTERVAL,
+  PING_MESSAGE,
+  PONG_MESSAGE,
+} from '../common/constants.js';
+import {
+  packStringMessage,
+  unpackStringMessage,
+} from '../common/sockets-utils.js';
+import {
+  kSocketsLatencyStatsWorker,
+  kSocketsDebugPreventHeartBeat,
+  kSocketsDeleteSocket,
+} from './ServerSockets.js';
+
+export const kSocketClientId = Symbol('soundworks:socket-client-id');
+export const kSocketTerminate = Symbol('soundworks:socket-terminate');
+
+/**
+ * Simple publish / subscribe wrapper built on top of the
+ * [ws](https://github.com/websockets/ws) library.
+ *
+ * An instance of {@link ServerSocket} is automatically created per client
+ * when it connects (see {@link SeverClient#socket}).
+ *
+ * _Important: In most cases, you should consider using a {@link SharedState}
+ * rather than directly using the Socket instance._
+ *
+ * @hideconstructor
+ */
+class ServerSocket {
+  #socket = null;
+  #sockets = null;
+  #listeners = new Map();
+  #heartbeatId = null;
+
+  constructor(ws, sockets) {
+    /**
+     * `ws` socket instance configured with `binaryType=blob` (string)
+     * @type {object}
+     */
+    this.#socket = ws;
+
+    /**
+     * Reference to the sockets object, is mainly dedicated to allow
+     * broadcasting from a given socket instance.
+     *
+     * @type {ServerSockets}
+     * @example
+     * socket.sockets.broadcast('my-room', this, 'update-value', 1);
+     */
+    this.#sockets = sockets;
+
+    // @todo - review
+    const msg = {
+      type: 'add-measurement',
+      value: {
+        ping: 0,
+        pong: 0,
+      },
+    };
+
+    let heartbeatMissed = 0;
+    // heartbeat system (run only on string socket), adapted from:
+    // https://github.com/websockets/ws#how-to-detect-and-close-broken-connections
+    this.#socket.addEventListener('message', e => {
+      if (e.data === PONG_MESSAGE) {
+        heartbeatMissed = 0;
+
+        msg.value.pong = getTime();
+        this.#sockets[kSocketsLatencyStatsWorker].postMessage(msg);
+        // do not propagate ping / pong messages
+        return;
+      }
+
+      const [channel, args] = unpackStringMessage(e.data);
+      this.#dispatchEvent(channel, ...args);
+    });
+
+    this.#heartbeatId = setInterval(() => {
+      // we didn't receive the pong message
+      if (heartbeatMissed > 0) {
+        // Emit a 'close' event to go trough all the disconnection pipeline
+        //
+        // @note - this seems to create false positive disconnections when
+        // client is busy, e.g. when loading large sound files so let's just warn
+        // until we gather more feedback
+        // cf. https://making.close.com/posts/reliable-websockets/
+        console.warn(`ClientSocket (id: ${this[kSocketClientId]}) did not respond to ping message in time (missed: ${heartbeatMissed},  interval: ${PING_INTERVAL})`);
+        // this.#dispatchEvent('close');
+        // return;
+      }
+
+      heartbeatMissed += 1;
+      msg.value.ping = getTime();
+
+      this.#socket.send(PING_MESSAGE);
+    }, PING_INTERVAL);
+
+    // for testing purpose
+    if (this.#sockets[kSocketsDebugPreventHeartBeat] === true) {
+      clearInterval(this.#heartbeatId);
+    }
+
+    // propagate "native" events
+    [
+      'close',
+      'error',
+      'message',
+      'open',
+      'ping',
+      'pong',
+      'unexpected-response',
+      'upgrade',
+    ].forEach(eventName => {
+      this.#socket.addEventListener(eventName, e => {
+        this.#dispatchEvent(eventName, e.data);
+      });
+    });
+  }
+
+  /**
+   * Dispatch an event to the listeners of the given channel.
+   * @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));
+    }
+  }
+
+  /**
+   * Removes all listeners and immediately close the web socket.
+   *
+   * Is automatically called when socket is closed on the client side or when
+   * Server is stopped
+   *
+   * @private
+   */
+  [kSocketTerminate]() {
+    // clear ping / pong interval
+    clearInterval(this.#heartbeatId);
+    // remove socket from all rooms
+    this.#sockets[kSocketsDeleteSocket](this);
+    // clear references to sockets
+    this.#sockets = null;
+    // clear all listeners
+    this.#listeners.clear();
+    // clear native listeners
+    [
+      'close',
+      'error',
+      'message',
+      'open',
+      'ping',
+      'pong',
+      'unexpected-response',
+      'upgrade',
+    ].forEach(eventName => this.#socket.removeAllListeners(eventName));
+    // terminate the socket
+    this.#socket.terminate();
+  }
+
+  /**
+   * Reference to the @link{ServerSockets} instance.
+   */
+  get sockets() {
+    return this.#sockets;
+  }
+
+  /**
+   * Ready state of the underlying socket instance.
+   *
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/readyState}
+   * @type {number}
+   */
+  get readyState() {
+    return this.#socket.readyState;
+  }
+
+  /**
+   * 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) {
+    const msg = packStringMessage(channel, ...args);
+
+    // ## Status codes:
+    // CONNECTING = 0; Socket has been created. The connection is not yet open.
+    // OPEN = 1; The connection is open and ready to communicate.
+    // CLOSING = 2; The connection is in the process of closing.
+    // CLOSED = 3; The connection is closed or couldn't be opened.
+    if (this.#socket.readyState === 1) {
+      this.#socket.send(msg, (err) => {
+        if (err) {
+          console.error(`ServerSocket failed to send message:`, channel, args, err.message);
+        }
+      });
+    }
+  }
+
+  /**
+   * 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 of messages with JSON compatible data types from 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 ServerSocket;

package/src/server/ServerSockets.js

@@ -0,0 +1,150 @@
+import querystring from 'node:querystring';
+import {
+  Worker,
+} from 'node:worker_threads';
+
+import {
+  WebSocketServer,
+} from 'ws';
+
+import {
+  kServerOnSocketConnection,
+  kServerIsValidConnectionToken,
+} from './Server.js';
+import ServerSocket, {
+  kSocketTerminate,
+} from './ServerSocket.js';
+
+// @note - fs.readFileSync creates some cwd() issues...
+import networkLatencyWorker from './audit-network-latency.worker.js';
+
+export const kSocketsStart = Symbol('soundworks:sockets-start');
+export const kSocketsStop = Symbol('soundworks:sockets-stop');
+
+export const kSocketsDeleteSocket = Symbol('soundworks:sockets-delete-socket');
+export const kSocketsLatencyStatsWorker = Symbol('soundworks:sockets-latency-stats-worker');
+export const kSocketsDebugPreventHeartBeat = Symbol('soundworks:sockets-debug-prevent-heartbeat');
+
+/**
+ * Manage all {@link ServerSocket} instances.
+ *
+ * _Important: In most cases, you should consider using a {@link SharedState}
+ * rather than directly using the ServerSocket instance._
+ */
+class ServerSockets {
+  #server = null;
+  #config = null;
+  #wsServer = null;
+  #sockets = new Set();
+
+  constructor(server, config) {
+    this.#server = server;
+    this.#config = config;
+
+    this[kSocketsLatencyStatsWorker] = null;
+    this[kSocketsDebugPreventHeartBeat] = false;
+  }
+
+  /**
+   * Initialize sockets, all sockets are added to two rooms by default:
+   * - to the room corresponding to the client `role`
+   * - to the '*' room that holds all connected sockets
+   * @private
+   */
+  async [kSocketsStart]() {
+    // Audit for network latency estimation, the worker is written in cjs so that we
+    // can make builds for Max, move back to modules once Max support modules
+    this[kSocketsLatencyStatsWorker] = new Worker(networkLatencyWorker, { eval: true });
+
+    const auditState = await this.#server.getAuditState();
+
+    auditState.onUpdate(updates => {
+      if ('averageNetworkLatencyWindow' in updates || 'averageNetworkLatencyPeriod' in updates) {
+        this[kSocketsLatencyStatsWorker].postMessage({
+          type: 'config',
+          value: {
+            averageLatencyWindow: updates.averageNetworkLatencyWindow,
+            averageLatencyPeriod: updates.averageNetworkLatencyPeriod,
+          },
+        });
+      }
+    }, true);
+
+    this[kSocketsLatencyStatsWorker].on('message', msg => {
+      if (msg.type === 'computed-average-latency') {
+        auditState.set({ averageNetworkLatency: msg.value });
+      }
+    });
+
+    // Init ws server
+    this.#wsServer = new WebSocketServer({
+      noServer: true,
+      path: `/${this.#config.path}`,
+    });
+
+    this.#wsServer.on('connection', (ws, req) => {
+      const { role, token } = querystring.parse(req.url.split('?')[1]);
+      const socket = new ServerSocket(ws, this);
+
+      this.#sockets.add(socket);
+      this.#server[kServerOnSocketConnection](role, socket, token);
+    });
+
+    // Prevent socket with protected role to connect if token is invalid
+    this.#server.httpServer.on('upgrade', async (req, socket, head) => {
+      const { role, token } = querystring.parse(req.url.split('?')[1]);
+
+      if (this.#server.isProtectedClientRole(role)) {
+        // we don't have any IP in the upgrade request object,
+        // so we just check the connection token is pending and valid
+        if (!this.#server[kServerIsValidConnectionToken](token)) {
+          socket.destroy('not allowed');
+        }
+      }
+
+      this.#wsServer.handleUpgrade(req, socket, head, (ws) => {
+        this.#wsServer.emit('connection', ws, req);
+      });
+    });
+  }
+
+  /**
+   * Terminate all existing sockets.
+   * @private
+   */
+  [kSocketsStop]() {
+    // terminate stat worker thread
+    this[kSocketsLatencyStatsWorker].terminate();
+    // terminate sockets
+    this.#sockets.forEach(socket => socket[kSocketTerminate]());
+  }
+
+  /**
+   * Remove given socket from all rooms.
+   * @private
+   */
+  [kSocketsDeleteSocket](socket) {
+    this.#sockets.delete(socket);
+  }
+
+  /** @private */
+  entries() {
+    return this.#sockets.entries();
+  }
+
+  /** @private */
+  keys() {
+    return this.#sockets.keys();
+  }
+
+  /** @private */
+  values() {
+    return this.#sockets.values();
+  }
+
+  forEach(func) {
+    return this.#sockets.forEach(func);
+  }
+}
+
+export default ServerSockets;