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

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.
@@ -28,18 +15,17 @@ import BasePlugin from '../common/BasePlugin.js';
  *
  * _Creating new plugins should be considered an advanced usage._
  *
- * @memberof server
  * @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);
@@ -48,8 +34,8 @@ class Plugin extends BasePlugin {
 
   /**
    * Instance of soundworks server.
-   * @type {server.Server}
-   * @see {@link server.Server}
+   * @type {Server}
+   * @see {@link Server}
    */
   get server() {
     return this.#server;
@@ -57,8 +43,8 @@ class Plugin extends BasePlugin {
 
   /**
    * Set of the clients registered in the plugin.
-   * @type {Set<server.Client>}
-   * @see {@link server.Client}
+   * @type {Set<ServerClient>}
+   * @see {@link ServerClient}
    */
   get clients() {
     return this.#clients;
@@ -69,7 +55,7 @@ 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);
@@ -80,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);
   }
 }
 
-export default Plugin;
+export default ServerPlugin;

package/src/server/{PluginManager.js → ServerPluginManager.js}

@@ -1,28 +1,18 @@
-import BasePluginManager from '../common/BasePluginManager.js';
-import Plugin from './Plugin.js';
+import BasePluginManager, {
+  kPluginManagerInstances,
+} from '../common/BasePluginManager.js';
+import ServerPlugin from './ServerPlugin.js';
 import Server from './Server.js';
 
-/**
- * Callback executed when a plugin internal state is updated.
- *
- * @callback server.PluginManager~onStateChangeCallback
- * @param {object<server.Plugin#id, server.Plugin>} fullState - List of all plugins.
- * @param {server.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 server.PluginManager~onStateChangeCallback}.
- *
- * @callback server.PluginManager~deleteOnStateChangeCallback
- */
+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.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
@@ -70,12 +60,11 @@ import Server from './Server.js';
  * }, 1000);
  * ```
  *
- * @memberof server
  * @extends BasePluginManager
  * @inheritdoc
  * @hideconstructor
  */
-class PluginManager extends BasePluginManager {
+class ServerPluginManager extends BasePluginManager {
   constructor(server) {
     if (!(server instanceof Server)) {
       throw new Error(`[soundworks.PluginManager] Invalid argument, "new PluginManager(server)" should receive an instance of "soundworks.Server" as argument`);
@@ -84,64 +73,23 @@ class PluginManager extends BasePluginManager {
     super(server);
   }
 
-  register(id, factory = null, options = {}, deps = []) {
-    const ctor = factory(Plugin);
-
-    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`);
-    }
-
-    super.register(id, ctor, options, deps);
-  }
-
-  /**
-   * Retrieve an 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 brealing changes) in a future release._
-   *
-   * @param {server.Plugin#id} id - Id of the plugin as defined when registered.
-   * @returns {server.Plugin}
-   * @see {@link server.PluginManager#onStateChange}
-   *
-   * @private
-   */
-  async get(id) {
-    if (this.status !== 'started') {
-      throw new Error(`[soundworks.PluginManager] Cannot get plugin before "server.init()"`);
-    }
-
-    return super.unsafeGet(id);
-  }
-
-  // server only methods
-
-  /** private */
-  checkRegisteredPlugins(registeredPlugins) {
+  /** @private */
+  [kServerPluginManagerCheckRegisteredPlugins](registeredPlugins) {
     let missingPlugins = [];
 
     for (let id of registeredPlugins) {
-      if (!this._instances.has(id)) {
+      if (!this[kPluginManagerInstances].has(id)) {
         missingPlugins.push(id);
       }
     }
 
     if (missingPlugins.length > 0) {
-      throw new Error(`Invalid plugin list, the following plugins registered client-side: [${missingPlugins.join(', ')}] have not been registered server-side. Registered server-side plugins are: [${Array.from(this._instances.keys()).join(', ')}].`);
+      throw new Error(`Invalid plugin list, the following plugins registered client-side: [${missingPlugins.join(', ')}] have not been registered server-side. Registered server-side plugins are: [${Array.from(this[kPluginManagerInstances].keys()).join(', ')}].`);
     }
   }
 
   /** @private */
-  async addClient(client, registeredPlugins = []) {
+  async [kServerPluginManagerAddClient](client, registeredPlugins = []) {
     let promises = [];
 
     for (let pluginName of registeredPlugins) {
@@ -154,10 +102,10 @@ class PluginManager extends BasePluginManager {
   }
 
   /** @private */
-  async removeClient(client) {
+  async [kServerPluginManagerRemoveClient](client) {
     let promises = [];
 
-    for (let plugin of this._instances.values()) {
+    for (let plugin of this[kPluginManagerInstances].values()) {
       if (plugin.clients.has(client)) {
         promises.push(plugin.removeClient(client));
       }
@@ -165,6 +113,65 @@ class PluginManager extends BasePluginManager {
 
     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 {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 = null, options = {}, deps = []) {
+    const ctor = factory(ServerPlugin);
+
+    if (!(ctor.prototype instanceof ServerPlugin)) {
+      throw new Error(`[soundworks.PluginManager] Invalid argument, "pluginManager.register" second argument should be a factory function returning a class extending the "ServerPlugin" base class`);
+    }
+
+    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 brealing changes) in a future release._
+   *
+   * @param {ServerPlugin#id} id - Id of the plugin as defined when registered.
+   * @returns {ServerPlugin}
+   */
+  async get(id) {
+    if (this.status !== 'started') {
+      throw new Error(`[soundworks.PluginManager] Cannot get plugin before "server.init()"`);
+    }
+
+    return super.getUnsafe(id);
+  }
 }
 
-export default PluginManager;
+export default ServerPluginManager;

package/src/server/{Socket.js → ServerSocket.js}

@@ -12,7 +12,7 @@ import {
   kSocketsLatencyStatsWorker,
   kSocketsDebugPreventHeartBeat,
   kSocketsRemoveFromAllRooms,
-} from './Sockets.js';
+} from './ServerSockets.js';
 
 export const kSocketClientId = Symbol('soundworks:socket-client-id');
 export const kSocketTerminate = Symbol('soundworks:socket-terminate');
@@ -21,22 +21,15 @@ 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 server.Socket} is automatically created per client
- * when it connects (see {@link server.Client#socket}).
+ * 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 client.SharedState}
+ * _Important: In most cases, you should consider using a {@link SharedState}
  * rather than directly using the Socket instance._
  *
- * The Socket class contains 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.
- *
- * @memberof server
  * @hideconstructor
  */
-class Socket {
+class ServerSocket {
   #socket = null;
   #sockets = null;
   #listeners = new Map();
@@ -53,7 +46,7 @@ class Socket {
      * Reference to the sockets object, is mainly dedicated to allow
      * broadcasting from a given socket instance.
      *
-     * @type {server.Sockets}
+     * @type {ServerSockets}
      * @example
      * socket.sockets.broadcast('my-room', this, 'update-value', 1);
      */
@@ -94,7 +87,7 @@ class Socket {
         // 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(`[Socket] client (id: ${this[kSocketClientId]}) did not respond to ping message in time (missed: ${heartbeatMissed},  interval: ${PING_INTERVAL})`);
+        console.warn(`[ServerSocket] client (id: ${this[kSocketClientId]}) did not respond to ping message in time (missed: ${heartbeatMissed},  interval: ${PING_INTERVAL})`);
         // this.#dispatchEvent('close');
         // return;
       }
@@ -144,6 +137,8 @@ class Socket {
    *
    * Is automatically called when socket is closed on the client side or when
    * Server is stopped
+   *
+   * @private
    */
   [kSocketTerminate]() {
     // clear ping / pong interval
@@ -170,11 +165,11 @@ class Socket {
   }
 
   /**
-   * Reference to the @link{server.Sockets} instance.
+   * Reference to the @link{ServerSockets} instance.
    *
    * Allows for broadcasting from a given socket instance.
    *
-   * @type {server.Sockets}
+   * @type {ServerSockets}
    * @example
    * socket.sockets.broadcast('my-room', this, 'update-value', 1);
    */
@@ -182,6 +177,12 @@ class Socket {
     return this.#sockets;
   }
 
+  /**
+   * Reay 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;
   }
@@ -216,7 +217,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)) {
@@ -275,4 +276,4 @@ class Socket {
 
 }
 
-export default Socket;
+export default ServerSocket;

package/src/server/{Sockets.js → ServerSockets.js}

@@ -8,30 +8,39 @@ import {
   WebSocketServer,
 } from 'ws';
 
-import Socket, {
+import {
+  kServerOnSocketConnection,
+  kServerIsProtectedRole,
+} from './Server.js';
+import ServerSocket, {
   kSocketTerminate,
-} from './Socket.js';
+} 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 kSocketsRemoveFromAllRooms = Symbol('soundworks:sockets-remove-from-all-rooms');
 export const kSocketsLatencyStatsWorker = Symbol('soundworks:sockets-latency-stats-worker');
 export const kSocketsDebugPreventHeartBeat = Symbol('soundworks:sockets-debug-prevent-heartbeat');
 
 /**
- * Manage all {@link server.Socket} instances.
- *
- * _Important: In most cases, you should consider using a {@link client.SharedState}
- * rather than directly using the Socket instance._
+ * Manage all {@link ServerSocket} instances.
  *
- * @memberof server
+ * _Important: In most cases, you should consider using a {@link SharedState}
+ * rather than directly using the ServerSocket instance._
  */
-class Sockets {
+class ServerSockets {
+  #server = null;
+  #config = null;
   #wsServer = null;
   #rooms = new Map();
 
-  constructor() {
+  constructor(server, config) {
+    this.#server = server;
+    this.#config = config;
     // Init special `'*'` room which stores all current connections.
     this.#rooms.set('*', new Set());
 
@@ -43,15 +52,14 @@ class Sockets {
    * 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 start(server, config, onConnectionCallback) {
+  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 server.getAuditState();
+    const auditState = await this.#server.getAuditState();
 
     auditState.onUpdate(updates => {
       if ('averageNetworkLatencyWindow' in updates || 'averageNetworkLatencyPeriod' in updates) {
@@ -74,27 +82,27 @@ class Sockets {
     // Init ws server
     this.#wsServer = new WebSocketServer({
       noServer: true,
-      path: `/${config.path}`,
+      path: `/${this.#config.path}`,
     });
 
     this.#wsServer.on('connection', (ws, req) => {
       const { role, token } = querystring.parse(req.url.split('?')[1]);
-      const socket = new Socket(ws, this);
+      const socket = new ServerSocket(ws, this);
 
       socket.addToRoom('*');
       socket.addToRoom(role);
 
-      onConnectionCallback(role, socket, token);
+      this.#server[kServerOnSocketConnection](role, socket, token);
     });
 
-    // Prevent socket with protected role to connect is token is invalid
-    server.httpServer.on('upgrade', async (req, socket, head) => {
+    // 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 (server.isProtected(role)) {
+      if (this.#server[kServerIsProtectedRole](role)) {
         // we don't have any IP in the upgrade request object,
         // so we just check the connection token is pending and valid
-        if (!server.isValidConnectionToken(token)) {
+        if (!this.#server[kServerIsValidConnectionToken](token)) {
           socket.destroy('not allowed');
         }
       }
@@ -109,7 +117,7 @@ class Sockets {
    * Terminate all existing sockets.
    * @private
    */
-  terminate() {
+  [kSocketsStop]() {
     // terminate stat worker thread
     this[kSocketsLatencyStatsWorker].terminate();
     // clean sockets
@@ -119,6 +127,7 @@ class Sockets {
 
   /**
    * Remove given socket from all rooms.
+   * @private
    */
   [kSocketsRemoveFromAllRooms](socket) {
     for (let [_, room] of this.#rooms) {
@@ -129,9 +138,9 @@ class Sockets {
   /**
    * Add a socket to a room.
    *
-   * _Note that in most cases, you should use a shared state instead_
+   * _Note that in most cases, you should use a {@link SharedState} instead_
    *
-   * @param {server.Socket} socket - Socket to add to the room.
+   * @param {ServerSocket} socket - Socket to add to the room.
    * @param {String} roomId - Id of the room.
    */
   addToRoom(socket, roomId) {
@@ -146,9 +155,9 @@ class Sockets {
   /**
    * Remove a socket from a room.
    *
-   * _Note that in most cases, you should use a shared state instead_
+   * _Note that in most cases, you should use a {@link SharedState} instead_
    *
-   * @param {server.Socket} socket - Socket to remove from the room.
+   * @param {ServerSocket} socket - Socket to remove from the room.
    * @param {String} roomId - Id of the room.
    */
   removeFromRoom(socket, roomId) {
@@ -162,11 +171,11 @@ class Sockets {
    * Send a message to all clients os given room(s). If no room is specified,
    * the message is sent to all clients.
    *
-   * _Note that in most cases, you should use a shared state instead_
+   * _Note that in most cases, you should use a {@link SharedState} instead_
    *
    * @param {String|Array} roomsIds - Ids of the rooms that must receive
    *  the message. If `null` the message is sent to all clients.
-   * @param {server.Socket} excludeSocket - Optionnal socket to ignore when
+   * @param {ServerSocket} excludeSocket - Optionnal socket to ignore when
    *  broadcasting the message, typically the client at the origin of the message.
    * @param {String} channel - Channel name.
    * @param {...*} args - Payload of the message. As many arguments as needed, of
@@ -198,4 +207,4 @@ class Sockets {
   }
 }
 
-export default Sockets;
+export default ServerSockets;