@soundworks/core 3.7.0 → 4.0.0-alpha.0

package/{common/SharedStateManagerServer.js → src/server/StateManager.js}

@@ -1,50 +1,105 @@
-"use strict";
+import EventEmitter from 'node:events';
+
+import clonedeep from 'lodash.clonedeep';
+
+import BaseStateManager from '../common/BaseStateManager.js';
+import ParameterBag from '../common/ParameterBag.js';
+import SharedStatePrivate from '../common/SharedStatePrivate.js';
+import {
+  SERVER_ID,
+  CREATE_REQUEST,
+  CREATE_RESPONSE,
+  CREATE_ERROR,
+  DELETE_NOTIFICATION,
+  ATTACH_REQUEST,
+  ATTACH_RESPONSE,
+  ATTACH_ERROR,
+  OBSERVE_REQUEST,
+  OBSERVE_RESPONSE,
+  OBSERVE_NOTIFICATION,
+  UNOBSERVE_NOTIFICATION,
+  DELETE_SCHEMA,
+  PRIVATE_STATES,
+} from '../common/constants.js';
+import { idGenerator } from '../common/utils.js';
+
+const generateStateId = idGenerator();
+const generateRemoteId = idGenerator();
 
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.default = void 0;
-
-var _events = _interopRequireDefault(require("events"));
-
-var _ParameterBag = _interopRequireDefault(require("./ParameterBag.js"));
-
-var _lodash = _interopRequireDefault(require("lodash.clonedeep"));
-
-var _SharedStatePrivate = _interopRequireDefault(require("./SharedStatePrivate.js"));
-
-var _SharedStateManagerClient = _interopRequireDefault(require("./SharedStateManagerClient.js"));
-
-var _sharedStateUtils = require("./shared-state-utils.js");
-
-function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+/**
+ * @callback server.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
+ */
 
-const generateStateId = (0, _sharedStateUtils.idGenerator)();
-const generateRemoteId = (0, _sharedStateUtils.idGenerator)();
 /**
- * Component dedicated at managing distributed states among the application.
- * The `SharedStateManagerServer` extends the `SharedStateManagerClient` with
- * additionnal functionnalities to register schemas and handle clients.
+ * The `StateManager` allows to create new {@link server.SharedState}s, or attach
+ * to {@link server.SharedState}s created by other nodes (clients or server). It
+ * can also track all the {@link server.SharedState}s created by other nodes.
  *
- * An instance of `SharedStateManagerServer` is automatically created by the
- * `soundworks.Server` at initialization (cf. {@link server.Server#stateManager}).
+ * An instance of `StateManager` is automatically created by the `soundworks.Server`
+ * at initialization (cf. {@link server.Server#stateManager}).
  *
- * Tutorial: [https://collective-soundworks.github.io/tutorials/state-manager.html](https://collective-soundworks.github.io/tutorials/state-manager.html)
+ * Compared to the {@link client.StateManager}, the `server.StateManager` can also
+ * create and delete schemas, as well as register update hook that are executed when
+ * a state is updated.
  *
- * @memberof server
- * @extends client.SharedStateManagerClient
+ * See {@link server.Server#stateManager}
+ *
+ * Tutorial: {@link https://soundworks.dev/guide/state-manager.html}
+ *
+ * ```
+ * // server-side
+ * import { Server } from '@soundworks/server/index.js';
  *
- * @see {@link client.SharedStateManagerClient}
- * @see {@link server.SharedState}
- * @see {@link server.Server#stateManager}
+ * 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 server
+ * @extends BaseStateManager
+ * @inheritdoc
+ * @hideconstructor
  */
-
-class SharedStateManagerServer extends _SharedStateManagerClient.default {
+class StateManager extends BaseStateManager {
   constructor() {
     // acts as a client of itself locally
-    const localClientId = -1;
-    const localTransport = new _events.default();
+    const localClientId = SERVER_ID;
+    const localTransport = new EventEmitter();
+
     super(localClientId, localTransport);
+
     this._clientByNodeId = new Map();
     this._serverStatesById = new Map();
     this._schemas = new Map();
@@ -53,67 +108,61 @@ class SharedStateManagerServer extends _SharedStateManagerClient.default {
 
     this.addClient(localClientId, localTransport);
   }
+
   /**
-   * Add a client. This is automatically handle by `soundworks` when a client
-   * connects.
+   * Add a client to the manager.
+   *
+   * This is automatically handled by the {@link server.Server} when a client connects.
    *
    * @param {Number} nodeId - Id of the client node, as given in
-   *  {@link client.SharedStateManagerClient}
+   *  {@link client.StateManager}
    * @param {Object} transport - Tranpsort mecanism to communicate with the
    *  client. Should implement a basic EventEmitter API.
    *
    * @private
    */
-
-
   addClient(nodeId, transport) {
-    const client = {
-      id: nodeId,
-      transport
-    };
+    const client = { id: nodeId, transport };
+    this._clientByNodeId.set(nodeId, client);
 
-    this._clientByNodeId.set(nodeId, client); // ---------------------------------------------
+    // ---------------------------------------------
     // CREATE
     // ---------------------------------------------
-
-
-    client.transport.addListener(_sharedStateUtils.CREATE_REQUEST, (reqId, schemaName, requireSchema, initValues = {}) => {
+    client.transport.addListener(CREATE_REQUEST, (reqId, schemaName, requireSchema, initValues = {}) => {
       if (this._schemas.has(schemaName)) {
         try {
           const schema = this._schemas.get(schemaName);
-
           const stateId = generateStateId.next().value;
-          const remoteId = generateRemoteId.next().value; // id, schemaName, schema, manager, initValues = {}
-
-          const state = new _SharedStatePrivate.default(stateId, schemaName, schema, this, initValues);
+          const remoteId = generateRemoteId.next().value;
+          // id, schemaName, schema, manager, initValues = {}
+          const state = new SharedStatePrivate(stateId, schemaName, schema, this, initValues);
 
           state._attachClient(remoteId, client, true); // attach client to the state
-
-
           this._serverStatesById.set(stateId, state);
 
           const currentValues = state._parameters.getValues();
-
           const sendedSchema = requireSchema ? schema : null;
-          client.transport.emit(_sharedStateUtils.CREATE_RESPONSE, reqId, stateId, remoteId, schemaName, sendedSchema, currentValues);
+
+          client.transport.emit(CREATE_RESPONSE, reqId, stateId, remoteId, schemaName, sendedSchema, currentValues);
 
           this._observers.forEach(observer => {
-            observer.transport.emit(_sharedStateUtils.OBSERVE_NOTIFICATION, [schemaName, stateId, nodeId]);
+            observer.transport.emit(OBSERVE_NOTIFICATION, [schemaName, stateId, nodeId]);
           });
-        } catch (err) {
-          client.transport.emit(_sharedStateUtils.CREATE_ERROR, reqId, err.message);
+        } catch(err) {
+          client.transport.emit(CREATE_ERROR, reqId, err.message);
           console.error(err.message);
         }
       } else {
         const msg = `Cannot create state "${schemaName}", schema does not exists`;
         console.error(msg);
-        client.transport.emit(_sharedStateUtils.CREATE_ERROR, reqId, msg);
+        client.transport.emit(CREATE_ERROR, reqId, msg);
       }
-    }); // ---------------------------------------------
+    });
+
+    // ---------------------------------------------
     // ATTACH (when creator, is attached by default)
     // ---------------------------------------------
-
-    client.transport.addListener(_sharedStateUtils.ATTACH_REQUEST, (reqId, schemaName, stateId = null, requireSchema = true) => {
+    client.transport.addListener(ATTACH_REQUEST, (reqId, schemaName, stateId = null, requireSchema = true) => {
       if (this._schemas.has(schemaName)) {
         let state = null;
 
@@ -137,63 +186,68 @@ class SharedStateManagerServer extends _SharedStateManagerClient.default {
           // several times to the same state.
           // i.e. same state -> several remote attach on the same node
           const remoteId = generateRemoteId.next().value;
-
           const schema = this._schemas.get(schemaName);
-
           const currentValues = state._parameters.getValues();
 
-          state._attachClient(remoteId, client, false); // send schema for client-side instanciation
-
-
+          state._attachClient(remoteId, client, false);
+          // send schema for client-side instanciation
           const sendedSchema = requireSchema ? schema : null;
-          client.transport.emit(_sharedStateUtils.ATTACH_RESPONSE, reqId, state.id, remoteId, schemaName, sendedSchema, currentValues);
+          client.transport.emit(ATTACH_RESPONSE, reqId, state.id, remoteId, schemaName, sendedSchema, currentValues);
         } else {
           const msg = `Cannot attach, no existing state for schema "${schemaName}" with stateId: "${stateId}"`;
-          client.transport.emit(_sharedStateUtils.ATTACH_ERROR, reqId, msg);
+          client.transport.emit(ATTACH_ERROR, reqId, msg);
           console.error(msg);
         }
       } else {
         const msg = `Cannot attach, schema "${schemaName}" does not exists`;
-        client.transport.emit(_sharedStateUtils.ATTACH_ERROR, reqId, msg);
+        client.transport.emit(ATTACH_ERROR, reqId, msg);
         console.error(msg);
       }
-    }); // ---------------------------------------------
+    });
+
+    // ---------------------------------------------
     // OBSERVE PEERS (be notified when a state is created, lazy)
     // ---------------------------------------------
-
-    client.transport.addListener(_sharedStateUtils.OBSERVE_REQUEST, reqId => {
+    client.transport.addListener(OBSERVE_REQUEST, reqId => {
       const statesInfos = [];
 
       this._serverStatesById.forEach(state => {
-        const {
-          schemaName,
-          id,
-          _creatorId
-        } = state;
-        statesInfos.push([schemaName, id, _creatorId]);
+        const { schemaName, id, _creatorId } = state;
+        // only track application states
+        // (e.g. do not propagate infos about audit state)
+        if (!PRIVATE_STATES.includes(schemaName)) {
+          statesInfos.push([schemaName, id, _creatorId]);
+        }
       });
 
-      client.transport.emit(_sharedStateUtils.OBSERVE_RESPONSE, reqId, ...statesInfos);
-
+      // add client to observers first because if some (sync) server side
+      // callback throws, the client would never be added to the list
       this._observers.add(client);
+
+      client.transport.emit(OBSERVE_RESPONSE, reqId, ...statesInfos);
+    });
+
+    client.transport.addListener(UNOBSERVE_NOTIFICATION, () => {
+      this._observers.delete(client);
     });
   }
+
   /**
-   * Remove a client. This is automatically handle by `soundworks` when a client
-   * connects.
+   * Remove a client from the manager. Clean all created or attached states.
+   *
+   * This is automatically handled by the {@link server.Server} when a client disconnects.
    *
    * @param {Number} nodeId - Id of the client node, as given in
-   *  {@link client.SharedStateManagerClient}
+   *  {@link client.StateManager}
    *
    * @private
    */
-
-
   removeClient(nodeId) {
     for (let [_id, state] of this._serverStatesById.entries()) {
-      let deleteState = false; // define if the client is the creator of the state, in which case
-      // everybody must delete it
+      let deleteState = false;
 
+      // define if the client is the creator of the state, in which case
+      // everybody must delete it
       for (let [remoteId, attachedClient] of state._attachedClients.entries()) {
         if (nodeId === attachedClient.id && remoteId === state._creatorRemoteId) {
           deleteState = true;
@@ -208,31 +262,30 @@ class SharedStateManagerServer extends _SharedStateManagerClient.default {
         if (deleteState) {
           if (remoteId !== state._creatorRemoteId) {
             // send notification to other attached nodes
-            attachedClient.transport.emit(`${_sharedStateUtils.DELETE_NOTIFICATION}-${state.id}-${remoteId}`);
+            attachedClient.transport.emit(`${DELETE_NOTIFICATION}-${state.id}-${remoteId}`);
           }
 
           this._serverStatesById.delete(state.id);
         }
       }
-    } // if is an observer, delete it
-
+    }
 
+    // if is an observer, delete it
     const client = this._clientByNodeId.get(nodeId);
-
     this._observers.delete(client);
-
     this._clientByNodeId.delete(nodeId);
   }
+
   /**
    * Register a schema from which shared states (cf. {@link common.SharedState})
    * can be instanciated.
    *
    * @param {String} schemaName - Name of the schema.
-   * @param {server.SharedStateManagerServer~schema} schema - Data structure
+   * @param {server.StateManager~schema} schema - Data structure
    *  describing the states that will be created from this schema.
    *
-   * @see {@link server.SharedStateManagerServer#create}
-   * @see {@link client.SharedStateManagerClient#create}
+   * @see {@link server.StateManager#create}
+   * @see {@link client.StateManager#create}
    *
    * @example
    * server.stateManager.registerSchema('my-schema', {
@@ -248,20 +301,18 @@ class SharedStateManagerServer extends _SharedStateManagerClient.default {
    *   }
    * })
    */
-
-
   registerSchema(schemaName, schema) {
     if (this._schemas.has(schemaName)) {
       throw new Error(`[stateManager.registerSchema] cannot register schema with name: "${schemaName}", schema name already exists`);
     }
 
-    _ParameterBag.default.validateSchema(schema);
-
-    this._schemas.set(schemaName, (0, _lodash.default)(schema)); // create hooks list
-
+    ParameterBag.validateSchema(schema);
 
+    this._schemas.set(schemaName, clonedeep(schema));
+    // create hooks list
     this._hooksBySchemaName.set(schemaName, new Set());
   }
+
   /**
    * Delete a schema and all associated states.
    * When a schema is deleted, all states created from this schema are deleted
@@ -270,40 +321,39 @@ class SharedStateManagerServer extends _SharedStateManagerClient.default {
    *
    * @param {String} schemaName - Name of the schema.
    */
-
-
   deleteSchema(schemaName) {
     // @note: deleting schema
     for (let [_id, state] of this._serverStatesById.entries()) {
       if (state.schemaName === schemaName) {
         for (let [remoteId, attached] of state._attachedClients.entries()) {
           state._detachClient(remoteId, attached);
-
-          attached.transport.emit(`${_sharedStateUtils.DELETE_NOTIFICATION}-${state.id}-${remoteId}`);
+          attached.transport.emit(`${DELETE_NOTIFICATION}-${state.id}-${remoteId}`);
         }
 
         this._serverStatesById.delete(this.id);
       }
-    } // clear schema cache of all connected clients
-
+    }
 
+    // clear schema cache of all connected clients
     for (let client of this._clientByNodeId.values()) {
-      client.transport.emit(`${_sharedStateUtils.DELETE_SCHEMA}`, schemaName);
+      client.transport.emit(`${DELETE_SCHEMA}`, schemaName);
     }
 
-    this._schemas.delete(schemaName); // delete registered hooks
-
-
+    this._schemas.delete(schemaName);
+    // delete registered hooks
     this._hooksBySchemaName.delete(schemaName);
   }
+
   /**
-   * @callback server.SharedStateManagerServer~updateHook
+   * @callback server.StateManager~updateHook
+   * @async
    *
    * @param {Object} updates - Update object as given on a set callback, or
    *  result of the previous hook
    * @param {Object} currentValues - Current values of the state.
    * @param {Object} [context=null] - Optionnal context passed by the creator
    *  of the update.
+   *
    * @return {Object} The "real" updates to be applied on the state.
    */
 
@@ -317,11 +367,20 @@ class SharedStateManagerServer extends _SharedStateManagerClient.default {
    * The hook is associated to every state of its kind (i.e. schemaName) and
    * executed on every update (call of `set`). Note that the hooks are executed
    * server-side regarless the node on which `set` has been called and before
-   * the "actual" update of the state (e.g. before the call of `subscribe`).
+   * the "actual" update of the state (e.g. before the call of `onUpdate`).
+   *
+   * @param {String} schemaName - Kind of states on which applying the hook.
+   * @param {server.StateManager~updateHook} updateHook - Function
+   *   called between the `set` call and the actual update.
+   *
+   * @returns {Fuction} deleteHook - Handler that deletes the hook when executed.
    *
    * @example
-   * server.stateManager.registerSchema('hooked', schema);
-   * server.stateManager.registerUpdateHook('hooked', (updates, currentValues) => {
+   * server.stateManager.registerSchema('hooked', {
+   *   name: { type: 'string', default: null, nullable: true },
+   *   name: { numUpdates: 'integer', default: 0 },
+   * });
+   * server.stateManager.registerUpdateHook('hooked', updates => {
    *   return {
    *     ...updates
    *     numUpdates: currentValues.numUpdates + 1,
@@ -331,15 +390,9 @@ class SharedStateManagerServer extends _SharedStateManagerClient.default {
    * const state = await server.stateManager.create('hooked');
    *
    * await state.set({ name: 'test' });
-   * state.getValues();
-   * // > { name: 'test', numUpdates: 1 };
-   *
-   * @param {String} schemaName - Kind of states on which applying the hook.
-   * @param {server.SharedStateManagerServer~updateHook} updateHook - Function
-   *   called between the `set` call and the actual update.
+   * const values = state.getValues();
+   * assert.deepEqual(result, { name: 'test', numUpdates: 1 });
    */
-
-
   registerUpdateHook(schemaName, updateHook) {
     // throw error if schemaName has not been registered
     if (!this._schemas.has(schemaName)) {
@@ -347,12 +400,11 @@ class SharedStateManagerServer extends _SharedStateManagerClient.default {
     }
 
     const hooks = this._hooksBySchemaName.get(schemaName);
-
     hooks.add(updateHook);
+
     return () => hooks.delete(updateHook);
   }
 
 }
 
-var _default = SharedStateManagerServer;
-exports.default = _default;
+export default StateManager;

package/src/server/audit-network-latency.worker.js

@@ -0,0 +1,57 @@
+import { parentPort } from 'node:worker_threads';
+
+import { getTime } from '@ircam/sc-gettime';
+
+let stack = [];
+let averageLatencyWindow = 5;
+let averageLatencyPeriod = 2;
+
+let intervalId = null;
+let meanLatency = 0;
+
+parentPort.on('message', msg => {
+  switch (msg.type) {
+    case 'config': {
+      averageLatencyWindow = msg.value.averageLatencyWindow;
+      averageLatencyPeriod = msg.value.averageLatencyPeriod;
+
+      // launch compute in its own loop so that the number of computation is
+      // decoupled from the number of connected clients
+      clearInterval(intervalId);
+      intervalId = setInterval(computeAverageLatency, averageLatencyPeriod * 1000);
+      break;
+    }
+    case 'add-measurement': {
+      // compute latency considering ping and pong time are equal
+      const entry = msg.value;
+      entry.latency = (entry.pong - entry.ping) / 2;
+      // add new measure to the stack
+      stack.push(entry);
+    }
+  }
+});
+
+function computeAverageLatency() {
+  const now = getTime();
+  // remove old measurements from stack
+  stack = stack.filter(entry => entry.pong >= now - averageLatencyWindow);
+
+  // prevent dividing by zero, just return last computed value
+  if (stack.length === 0) {
+    parentPort.postMessage({
+      type: 'computed-average-latency',
+      value: meanLatency,
+    });
+  } else {
+    // compute mean
+    let sum = 0;
+    stack.forEach(entry => sum += entry.latency);
+
+    meanLatency = sum / stack.length;
+    // send result to main thread
+    parentPort.postMessage({
+      type: 'computed-average-latency',
+      value: meanLatency,
+    });
+  }
+}

package/src/server/audit-schema.js

@@ -0,0 +1,42 @@
+/**
+ * Internal schema used to audit the application.
+ */
+export default {
+  /**
+   * Number of connected clients by role.
+   *
+   * @example
+   * {
+   *   player: 12,
+   *   controller: 1,
+   * }
+   */
+  numClients: {
+    type: 'any',
+    default: {},
+  },
+
+  /**
+   * Average latency in seconds computed from ping/pong.
+   */
+  averageNetworkLatency: {
+    type: 'float',
+    default: 0,
+  },
+
+  /**
+   * Time window in second used to compute the average latency. Defaults to 5
+   */
+  averageNetworkLatencyWindow: {
+    type: 'float',
+    default: 5,
+  },
+
+  /**
+   * Period in second at which the average latency is computed. Defaults to 2
+   */
+  averageNetworkLatencyPeriod: {
+    type: 'float',
+    default: 2,
+  },
+};

package/src/server/index.js

@@ -0,0 +1,45 @@
+/**
+ * Configuration object for the server.
+ *
+ * @typedef ServerConfig
+ * @memberof server
+ * @type {object}
+ * @property {object} [app] - Application configration object.
+ * @property {object} app.clients - Definition of the application clients.
+ * @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.port - Port on which the server is listening.
+ * @property {boolean} env.useHttps - Define is the server run in http or in https.
+ * @property {boolean} [env.httpsInfos={}] - Path to cert files for https.
+ * @property {boolean} env.serverAddress - Domain name or IP of the server.
+ *  Mandatory if node clients are defined
+ * @property {string} [env.websockets={}] - Configuration options for websockets.
+ * @property {string} [env.subpath=''] - If running behind a proxy, path to the application.
+ */
+
+/**
+ * Server-side part of the *soundworks* framework.
+ *
+ * ```
+ * import '@soundworks/helpers/polyfills.js';
+ * import { Server } from '@soundworks/core/server.js';
+ * import { loadConfig } from '../utils/load-config.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 = loadConfig(process.env.ENV, import.meta.url);
+ *
+ * const server = new Server(config);
+ * server.setDefaultTemplateConfig();
+ *
+ * await server.start();
+ * ```
+ *
+ * @namespace server
+ */
+export { default as Server } from './Server.js';
+export { default as Context } from './Context.js';

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "include": ["src/**/*.js"],
+
+  "compilerOptions": {
+    // Tells TypeScript to read JS files, as
+    // normally they are ignored as source files
+    "allowJs": true,
+    // Generate d.ts files
+    "declaration": true,
+    // This compiler run should
+    // only output d.ts files
+    "emitDeclarationOnly": true,
+    // Types should go into this directory.
+    // Removing this would place the .d.ts files
+    // next to the .js files
+    "outDir": "types",
+    // go to js file when using IDE functions like
+    // "Go to Definition" in VSCode
+    "declarationMap": true
+  }
+}