@soundworks/core 4.0.0-alpha.13 → 4.0.0-alpha.15

package/src/common/BaseStateManager.js

@@ -1,6 +1,7 @@
-import { isString, isFunction } from '@ircam/sc-utils';
+import { isString, isFunction, isPlainObject } from '@ircam/sc-utils';
 import SharedState from './BaseSharedState.js';
 import SharedStateCollection from './BaseSharedStateCollection.js';
+import PromiseStore from './PromiseStore.js';
 import {
   CREATE_REQUEST,
   CREATE_RESPONSE,
@@ -10,15 +11,11 @@ import {
   ATTACH_ERROR,
   OBSERVE_REQUEST,
   OBSERVE_RESPONSE,
+  OBSERVE_ERROR,
   OBSERVE_NOTIFICATION,
   UNOBSERVE_NOTIFICATION,
   DELETE_SCHEMA,
 } from './constants.js';
-import {
-  storeRequestPromise,
-  resolveRequest,
-  rejectRequest,
-} from './promise-store.js';
 
 /**
  * @private
@@ -32,10 +29,13 @@ class BaseStateManager {
   constructor(id, transport) {
     this.client = { id, transport };
 
-    this._statesById = new Map();
-    this._observeListeners = new Map(); // Map <callback, filterSchemaName>
-    this._cachedSchemas = new Map();
-    this._observeRequestCallbacks = new Map();
+    this._statesById = new Map(); // <id, state>
+    this._cachedSchemas = new Map(); // <shemaName, definition>
+
+    this._observeListeners = new Set(); // Set <[observedSchemaName, callback, options]>
+    this._observeRequestCallbacks = new Map(); // Map <reqId, [observedSchemaName, callback, options]>
+
+    this._promiseStore = new PromiseStore();
 
     // ---------------------------------------------
     // CREATE
@@ -53,11 +53,11 @@ class BaseStateManager {
       const state = new SharedState(stateId, remoteId, schemaName, schema, this.client, true, this, initValues);
       this._statesById.set(state.id, state);
 
-      resolveRequest(reqId, state);
+      this._promiseStore.resolve(reqId, state);
     });
 
     this.client.transport.addListener(CREATE_ERROR, (reqId, msg) => {
-      rejectRequest(reqId, msg);
+      this._promiseStore.reject(reqId, msg);
     });
 
     // ---------------------------------------------
@@ -77,11 +77,11 @@ class BaseStateManager {
       const state = new SharedState(stateId, remoteId, schemaName, schema, this.client, false, this, currentValues);
       this._statesById.set(state.id, state);
 
-      resolveRequest(reqId, state);
+      this._promiseStore.resolve(reqId, state);
     });
 
     this.client.transport.addListener(ATTACH_ERROR, (reqId, msg) => {
-      rejectRequest(reqId, msg);
+      this._promiseStore.reject(reqId, msg);
     });
 
     // ---------------------------------------------
@@ -90,11 +90,18 @@ class BaseStateManager {
     this.client.transport.addListener(OBSERVE_RESPONSE, async (reqId, ...list) => {
       // retrieve the callback that have been stored in observe to make sure
       // we don't call another callback that may have been registered earlier.
-      const [callback, filterSchemaName] = this._observeRequestCallbacks.get(reqId);
+      const observeInfos = this._observeRequestCallbacks.get(reqId);
+      const [observedSchemaName, callback, options] = observeInfos;
+
+      // move observeInfos from `_observeRequestCallbacks` to `_observeListeners`
+      // to guarantee order of execution, @see not in `.observe`
       this._observeRequestCallbacks.delete(reqId);
+      this._observeListeners.add(observeInfos);
 
       const promises = list.map(([schemaName, stateId, nodeId]) => {
-        if (filterSchemaName === '*' || filterSchemaName === schemaName) {
+        const filter = this._filterObserve(observedSchemaName, schemaName, nodeId, options);
+
+        if (!filter) {
           return callback(schemaName, stateId, nodeId);
         } else {
           return Promise.resolve();
@@ -104,19 +111,29 @@ class BaseStateManager {
       await Promise.all(promises);
 
       const unsubscribe = () => {
-        this._observeListeners.delete(callback);
-        // no more listeners, we can stop receiving notification from the server
+        this._observeListeners.delete(observeInfos);
+
+        // no more listeners, we can stop receiving notifications from the server
         if (this._observeListeners.size === 0) {
           this.client.transport.emit(UNOBSERVE_NOTIFICATION);
         }
       };
 
-      resolveRequest(reqId, unsubscribe);
+      this._promiseStore.resolve(reqId, unsubscribe);
+    });
+
+    // Observe error can occur if observed schema name does not exists
+    this.client.transport.addListener(OBSERVE_ERROR, (reqId, msg) => {
+      this._observeRequestCallbacks.delete(reqId);
+      this._promiseStore.reject(reqId, msg);
     });
 
     this.client.transport.addListener(OBSERVE_NOTIFICATION, (schemaName, stateId, nodeId) => {
-      this._observeListeners.forEach((filterSchemaName, callback) => {
-        if (filterSchemaName === '*' || filterSchemaName === schemaName) {
+      this._observeListeners.forEach(observeInfos => {
+        const [observedSchemaName, callback, options] = observeInfos;
+        const filter = this._filterObserve(observedSchemaName, schemaName, nodeId, options);
+
+        if (!filter) {
           callback(schemaName, stateId, nodeId);
         }
       });
@@ -130,6 +147,21 @@ class BaseStateManager {
     });
   }
 
+  /** @private */
+  _filterObserve(observedSchemaName, schemaName, creatorId, options) {
+    let filter = true;
+    // schema name filter filer
+    if (observedSchemaName === null || observedSchemaName === schemaName) {
+      filter = false;
+    }
+    // filter state created by client if excludeLocal is true
+    if (options.excludeLocal === true && creatorId === this.client.id) {
+      filter = true;
+    }
+
+    return filter;
+  }
+
   /**
    * Create a `SharedState` instance from a registered schema.
    *
@@ -144,7 +176,7 @@ class BaseStateManager {
    */
   async create(schemaName, initValues = {}) {
     return new Promise((resolve, reject) => {
-      const reqId = storeRequestPromise(resolve, reject);
+      const reqId = this._promiseStore.add(resolve, reject, 'create-create');
       const requireSchema = this._cachedSchemas.has(schemaName) ? false : true;
       this.client.transport.emit(CREATE_REQUEST, reqId, schemaName, requireSchema, initValues);
     });
@@ -167,7 +199,7 @@ class BaseStateManager {
   async attach(schemaName, stateId = null) {
     return new Promise((resolve, reject) => {
       // @todo - add a timeout
-      const reqId = storeRequestPromise(resolve, reject);
+      const reqId = this._promiseStore.add(resolve, reject, 'attach-request');
       const requireSchema = this._cachedSchemas.has(schemaName) ? false : true;
       this.client.transport.emit(ATTACH_REQUEST, reqId, schemaName, stateId, requireSchema);
     });
@@ -180,20 +212,31 @@ class BaseStateManager {
    * control over them from a single point.
    *
    * Notes:
-   * - The states that are created by the same node are not propagated through
-   * the observe callback.
-   * - The order of execution is not guaranted, i.e. an state attached in the
-   * `observe` callback could be created before the `async create` method resolves.
+   * - The order of execution is not guaranted between nodes, i.e. an state attached
+   * in the `observe` callback could be created before the `async create` method resolves.
+   * - Filtering, i.e. `observedSchemaName` and `options.excludeLocal` are handled
+   * on the node side, the server just notify all state creation activity and
+   * the node executes the given callbacks according to the different filter rules.
+   * Such strategy allows to share the observe notifications between all observers.
    *
-   * @param {String} [schemaName] - optionnal schema name to filter the observed
+   * Alternative signatures:
+   * - .observe(callback)
+   * - .observe(schemaName, callback)
+   * - .observe(callback, options)
+   * - .observe(schemaName, callback, options)
+   *
+   * @param {string} [schemaName] - optionnal schema name to filter the observed
    *  states.
    * @param {server.StateManager~ObserveCallback|client.StateManager~ObserveCallback}
    *  callback - Function to be called when a new state is created on the network.
+   * @param {object} options - Options.
+   * @param {boolean} [options.excludeLocal = false] - If set to true, exclude states
+   *  created locallly, i.e. by the same node, from the collection.
    * @returns {Promise<Function>} - Returns a Promise that resolves when the given
    *  callback as been executed on each existing states. The promise value is a
    *  function which allows to stop observing the states on the network.
    * @example
-   * client.stateManager.observe(async (schemaName, stateId, nodeId) => {
+   * client.stateManager.observe(async (schemaName, stateId) => {
    *   if (schemaName === 'something') {
    *     const state = await this.client.stateManager.attach(schemaName, stateId);
    *     console.log(state.getValues());
@@ -204,50 +247,127 @@ class BaseStateManager {
   // handle this way and the network overhead is very low for observe notifications:
   // i.e. schemaName, stateId, nodeId
   async observe(...args) {
-    let filterSchemaName;
+
+    const defaultOptions = {
+      excludeLocal: false,
+    };
+
+    let observedSchemaName;
     let callback;
+    let options;
 
-    if (args.length === 1) {
-      filterSchemaName = '*';
-      callback = args[0];
+    switch (args.length) {
+      case 1: {
+        // variation: .observe(callback)
+        if (!isFunction(args[0])) {
+          throw new TypeError(`[stateManager] Invalid arguments, argument 1 should be a function"`);
+        }
 
-      if (!isFunction(callback)) {
-        throw new Error(`[stateManager] Invalid arguments, valid signatures are "stateManager.observe(callback)" or "stateManager.observe(schemaName, callback)"`);
+        observedSchemaName = null;
+        callback = args[0];
+        options = defaultOptions;
+        break;
       }
-    } else if (args.length === 2) {
-      filterSchemaName = args[0];
-      callback = args[1];
+      case 2: {
+        // variation: .observe(schemaName, callback)
+        if (isString(args[0])) {
+          if (!isFunction(args[1])) {
+            throw new TypeError(`[stateManager] Invalid arguments, argument 2 should be a function"`);
+          }
+
+          observedSchemaName = args[0];
+          callback = args[1];
+          options = defaultOptions;
+
+        // variation: .observe(callback, options) API
+        } else if (isFunction(args[0])) {
+          if (!isPlainObject(args[1])) {
+            throw new TypeError(`[stateManager] Invalid arguments, argument 2 should be an object"`);
+          }
+
+          observedSchemaName = null;
+          callback = args[0];
+          options = Object.assign(defaultOptions, args[1]);
+
+        } else {
+          throw new Error(`[stateManager] Invalid signature, refer to the StateManager.observe documentation"`);
+        }
 
-      if (!isString(filterSchemaName) || !isFunction(callback)) {
-        throw new Error(`[stateManager] Invalid arguments, valid signatures are "stateManager.observe(callback)" or "stateManager.observe(schemaName, callback)"`);
+        break;
+      }
+      case 3: {
+        // variation: .observe(schemaName, callback, options)
+        if (!isString(args[0])) {
+          throw new TypeError(`[stateManager] Invalid arguments, argument 1 should be a string"`);
+        }
+
+        if (!isFunction(args[1])) {
+          throw new TypeError(`[stateManager] Invalid arguments, argument 2 should be a function"`);
+        }
+
+        if (!isPlainObject(args[2])) {
+          throw new TypeError(`[stateManager] Invalid arguments, argument 2 should be an object"`);
+        }
+
+        observedSchemaName = args[0];
+        callback = args[1];
+        options = Object.assign(defaultOptions, args[2]);
+
+        break;
+      }
+      // throw in all other cases
+      default: {
+        throw new Error(`[stateManager] Invalid signature, refer to the StateManager.observe documentation"`);
       }
-    } else {
-      throw new Error(`[stateManager] Invalid arguments, valid signatures are "stateManager.observe(callback)" or "stateManager.observe(schemaName, callback)"`);
     }
 
     // resend request to get updated list of states
     return new Promise((resolve, reject) => {
-      const reqId = storeRequestPromise(resolve, reject);
+      const reqId = this._promiseStore.add(resolve, reject, 'observe-request');
       // store the callback for execution on the response. the returned Promise
       // is fullfiled once callback has been executed with each existing states
-      this._observeRequestCallbacks.set(reqId, [callback, filterSchemaName]);
-      // store the callback for execution on subsequent notifications
-      this._observeListeners.set(callback, filterSchemaName);
-
-      this.client.transport.emit(OBSERVE_REQUEST, reqId);
+      const observeInfos = [observedSchemaName, callback, options];
+      this._observeRequestCallbacks.set(reqId, observeInfos);
+
+      // NOTE: do not store in `_observeListeners` yet as it can produce race
+      // conditions, e.g.:
+      // ```
+      // await client.stateManager.observe(async (schemaName, stateId, nodeId) => {});
+      // // client now receives OBSERVE_NOTIFICATIONS
+      // await otherClient.stateManager.create('a');
+      // // second observer added in between
+      // client.stateManager.observe(async (schemaName, stateId, nodeId) => {});
+      // ````
+      // OBSERVE_NOTIFICATION is received before the OBSERVE_RESPONSE, then the
+      // second observer is called twice:
+      // - OBSERVE_RESPONSE 1 []
+      // - OBSERVE_NOTIFICATION [ 'a', 1, 0 ]
+      // - OBSERVE_NOTIFICATION [ 'a', 1, 0 ] // this should not happen
+      // - OBSERVE_RESPONSE 1 [ [ 'a', 1, 0 ] ]
+      //
+      // cf. unit test `observe should properly behave in race condition`
+
+      this.client.transport.emit(OBSERVE_REQUEST, reqId, observedSchemaName);
     });
   }
 
   /**
-   * Returns a collection of all the states created from the schema name. Except
-   * the ones created by the current node.
+   * Returns a collection of all the states created from the schema name.
    *
    * @param {string} schemaName - Name of the schema.
+   * @param {object} options - Options.
+   * @param {boolean} [options.excludeLocal = false] - If set to true, exclude states
+   *  created locallly, i.e. by the same node, from the collection.
    * @returns {server.SharedStateCollection|client.SharedStateCollection}
    */
-  async getCollection(schemaName) {
-    const collection = new SharedStateCollection(this, schemaName);
-    await collection._init();
+  async getCollection(schemaName, options) {
+    const collection = new SharedStateCollection(this, schemaName, options);
+
+    try {
+      await collection._init();
+    } catch (err) {
+      throw new Error(`Cannot create collection, schema "${schemaName}" does not exists`);
+    }
 
     return collection;
   }

package/src/common/ParameterBag.js

@@ -1,4 +1,4 @@
-import cloneDeep from 'lodash.clonedeep';
+import cloneDeep from 'lodash/cloneDeep.js';
 import equal from 'fast-deep-equal';
 
 export const sharedOptions = {
@@ -394,30 +394,34 @@ class ParameterBag {
   getSchema(name = null) {
     if (name === null) {
       return this._schema;
-    } else {
-      if (!this.has(name)) {
-        throw new ReferenceError(`[SharedState] Cannot get schema description of undefined parameter "${name}"`);
-      }
+    }
 
-      return this._schema[name];
+    if (!this.has(name)) {
+      throw new ReferenceError(`[SharedState] Cannot get schema description of undefined parameter "${name}"`);
     }
+
+    return this._schema[name];
   }
 
   // return the default value, if initValue has been given, return init values
   getInitValues() {
     const initValues = {};
+
     for (let [name, def] of Object.entries(this._schema)) {
       initValues[name] = def.initValue;
     }
+
     return initValues;
   }
 
   // return the default value, if initValue has been given, return init values
   getDefaults() {
     const defaults = {};
+
     for (let [name, def] of Object.entries(this._schema)) {
-      defaults[name] = def.defaults;
+      defaults[name] = def.default;
     }
+
     return defaults;
   }
 }

package/src/common/PromiseStore.js

@@ -0,0 +1,41 @@
+import { idGenerator } from '@ircam/sc-utils';
+
+const generateRequestId = idGenerator();
+
+export default class PromiseStore {
+  constructor(name) {
+    this.name = name;
+    this.store = new Map();
+  }
+
+  add(resolve, reject, type) {
+    const reqId = generateRequestId.next().value;
+    this.store.set(reqId, { resolve, reject, type });
+
+    return reqId;
+  }
+
+  resolve(reqId, data) {
+    const { resolve } = this.store.get(reqId);
+    this.store.delete(reqId);
+
+    resolve(data);
+  }
+
+  reject(reqId, msg) {
+    const { reject } = this.store.get(reqId);
+    this.store.delete(reqId);
+
+    reject(new Error(msg));
+  }
+
+  // reject all pendeing request
+  flush() {
+    for (let [_reqId, entry] of this.store) {
+      const { reject, type } = entry;
+      reject(new Error(`[${this.name}] Discard promise "${type}", cannot resolve`));
+    }
+
+    this.store.clear();
+  }
+}

package/src/common/SharedStatePrivate.js

@@ -89,49 +89,46 @@ class SharedStatePrivate {
         }
 
         if (hasUpdates) {
-          // send response to requester
-          // client.transport.emit(`${UPDATE_RESPONSE}-${this.id}-${remoteId}`, reqId, filteredUpdates);
-
-          // @note: we propagate server-side last, because as the server transport
-          // is synchronous it can break ordering if a subscription function makes
-          // itself an update in reaction to an update, therefore network messages
-          // order would be broken,
-
-          // we need to handle cases where:
-          // client state (client.id: 2) sends a request
-          // server attached state (client.id: -1) spot a problem and overrides the value
-          // we want the remote client (id: 2) to receive in the right order:
+          // We need to handle cases where:
+          // - client state (client.id: 2) sends a request
+          // - server attached state (client.id: -1) spot a problem and overrides the value
+          // We want the remote client (id: 2) to receive in the right order:
           // * 1. the value it requested,
           // * 2. the value overriden by the server-side attached state (id: -1)
+          //
+          // such problem is now better solved with the the upateHook system, none
+          // nonetheway we don't want to introduce inconsistencies here
+          //
+          // Then we propagate server-side last, because as the server transport
+          // is synchronous it can break ordering if a subscription function makes
+          // itself an update in reaction to an update. Propagating to server last
+          // alllows to maintain network messages order consistent.
 
-          // this problem could be solved properly with a reducer system:
-          // if (dirty) {
-          //   -> call (async) reducer
-          //   -> get values from reducer
-          //.  -> dispatch to everybody
-          // }
+          // @note - remoteId correspond to unique remote state id
+
+          // propagate RESPONSE to the client that originates the request if not the server
+          if (client.id !== -1) {
+            client.transport.emit(`${UPDATE_RESPONSE}-${this.id}-${remoteId}`, reqId, filteredUpdates, context);
+          }
 
-          for (let [peerRemoteId, peer] of this._attachedClients.entries()) {
-            // propagate notification to all other attached clients except server
+          // propagate NOTIFICATION to all other attached clients except server
+          for (let [peerRemoteId, peer] of this._attachedClients) {
             if (remoteId !== peerRemoteId && peer.id !== -1) {
               peer.transport.emit(`${UPDATE_NOTIFICATION}-${this.id}-${peerRemoteId}`, filteredUpdates, context);
             }
           }
 
-          if (client.id !== -1) {
+          // propagate RESPONSE to server if it is the requester
+          if (client.id === -1) {
             client.transport.emit(`${UPDATE_RESPONSE}-${this.id}-${remoteId}`, reqId, filteredUpdates, context);
           }
 
-          for (let [peerRemoteId, peer] of this._attachedClients.entries()) {
-            // propagate notification to server
+          // propagate NOTIFICATION other attached state that belongs to server
+          for (let [peerRemoteId, peer] of this._attachedClients) {
             if (remoteId !== peerRemoteId && peer.id === -1) {
               peer.transport.emit(`${UPDATE_NOTIFICATION}-${this.id}-${peerRemoteId}`, filteredUpdates, context);
             }
           }
-
-          if (client.id === -1) {
-            client.transport.emit(`${UPDATE_RESPONSE}-${this.id}-${remoteId}`, reqId, filteredUpdates, context);
-          }
         } else {
           // propagate back to the requester that the update has been aborted
           // ignore all other attached clients.

package/src/common/constants.js

@@ -21,6 +21,7 @@ export const DETACH_ERROR = 's:dt:err';
 
 export const OBSERVE_REQUEST = 's:o:req';
 export const OBSERVE_RESPONSE = 's:o:res';
+export const OBSERVE_ERROR = 's:o:err';
 export const OBSERVE_NOTIFICATION = 's:o:not';
 
 export const UNOBSERVE_NOTIFICATION = 's:uo:not';
@@ -47,5 +48,5 @@ export const CLIENT_HANDSHAKE_RESPONSE = 'cl:h:res';
 export const CLIENT_HANDSHAKE_ERROR = 'cl:h:err';
 
 // audit state schema name
-export const AUDIT_STATE_NAME = 's:c:audit';
+export const AUDIT_STATE_NAME = 'p:s:audit';
 export const PRIVATE_STATES = [AUDIT_STATE_NAME];

package/src/common/sockets-utils.js

@@ -1,8 +1,7 @@
 import 'fast-text-encoding';
-import root from 'window-or-global';
 
-const encoder = new root.TextEncoder('utf-8');
-const decoder = new root.TextDecoder('utf-8');
+const encoder = new TextEncoder('utf-8');
+const decoder = new TextDecoder('utf-8');
 
 const types = [
   'Int8Array',
@@ -57,7 +56,7 @@ export function unpackBinaryMessage(buffer /* arraybuffer */) {
   const channel = decoder.decode(channelBuffer);
   const type = types[typeIndex];
   // slice (copy) the underlying ArrayBuffer to create a clean TypedArray
-  const data = new root[type](buffer.slice(startOffset));
+  const data = new globalThis[type](buffer.slice(startOffset));
 
   return [channel, data];
 }

package/src/server/Server.js

@@ -5,14 +5,13 @@ import path from 'node:path';
 import os from 'node:os';
 import { X509Certificate, createPrivateKey } from 'node:crypto';
 
-import { getTime } from '@ircam/sc-gettime';
-import { isPlainObject, idGenerator } from '@ircam/sc-utils';
+import { isPlainObject, idGenerator, getTime } from '@ircam/sc-utils';
 import chalk from 'chalk';
 import compression from 'compression';
 import express from 'express';
 import Keyv from 'keyv';
 import { KeyvFile } from 'keyv-file';
-import merge from 'lodash.merge';
+import merge from 'lodash/merge.js';
 import pem from 'pem';
 import compile from 'template-literal';
 

package/src/server/SharedStateCollection.js

@@ -15,8 +15,11 @@ import BaseSharedStateCollection from '../common/BaseSharedStateCollection.js';
 
 /**
  * The `SharedStateCollection` interface represent a collection of all states
- * created from a given schema name on the network, at the execption of the ones
- * created by the current node.
+ * created from a given schema name on the network.
+ *
+ * It can optionnaly exclude the states created by the current node.
+ *
+ * See {@link server.StateManager#getCollection} for factory method API
  *
  * ```
  * const collection = await server.stateManager.getCollection('my-schema');

package/src/server/Socket.js

@@ -1,4 +1,4 @@
-import { getTime } from '@ircam/sc-gettime';
+import { getTime } from '@ircam/sc-utils';
 import {
   packBinaryMessage,
   unpackBinaryMessage,