@soundworks/core 4.0.0-alpha.2 → 4.0.0-alpha.21

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 = {
@@ -17,7 +17,7 @@ export const types = {
     },
     coerceFunction: (name, def, value) => {
       if (typeof value !== 'boolean') {
-        throw new TypeError(`[stateManager] Invalid value for boolean param "${name}": ${value}`);
+        throw new TypeError(`[SharedState] Invalid value "${value}" for boolean parameter "${name}"`);
       }
 
       return value;
@@ -30,7 +30,7 @@ export const types = {
     },
     coerceFunction: (name, def, value) => {
       if (typeof value !== 'string') {
-        throw new TypeError(`[stateManager] Invalid value for string param "${name}": ${value}`);
+        throw new TypeError(`[SharedState] Invalid value "${value}" for string parameter "${name}"`);
       }
 
       return value;
@@ -63,7 +63,7 @@ export const types = {
     },
     coerceFunction: (name, def, value) => {
       if (!(typeof value === 'number' && Math.floor(value) === value)) {
-        throw new TypeError(`[stateManager] Invalid value for integer param "${name}": ${value}`);
+        throw new TypeError(`[SharedState] Invalid value "${value}" for integer parameter "${name}"`);
       }
 
       return Math.max(def.min, Math.min(def.max, value));
@@ -96,7 +96,7 @@ export const types = {
     },
     coerceFunction: (name, def, value) => {
       if (typeof value !== 'number' || value !== value) { // reject NaN
-        throw new TypeError(`[stateManager] Invalid value for float param "${name}": ${value}`);
+        throw new TypeError(`[SharedState] Invalid value "${value}" for float parameter "${name}"`);
       }
 
       return Math.max(def.min, Math.min(def.max, value));
@@ -109,7 +109,7 @@ export const types = {
     },
     coerceFunction: (name, def, value) => {
       if (def.list.indexOf(value) === -1) {
-        throw new TypeError(`[stateManager] Invalid value for enum param "${name}": ${value}`);
+        throw new TypeError(`[SharedState] Invalid value "${value}" for enum parameter "${name}"`);
       }
 
 
@@ -139,11 +139,11 @@ class ParameterBag {
       const def = schema[name];
 
       if (!Object.prototype.hasOwnProperty.call(def, 'type')) {
-        throw new TypeError(`[stateManager] Invalid schema definition - param "${name}": "type" key is required`);
+        throw new TypeError(`[StateManager.registerSchema] Invalid schema definition - param "${name}": "type" key is required`);
       }
 
       if (!Object.prototype.hasOwnProperty.call(types, def.type)) {
-        throw new TypeError(`[stateManager] Invalid schema definition - param "${name}": "{ type: '${def.type}' }" does not exists`);
+        throw new TypeError(`[StateManager.registerSchema] Invalid schema definition - param "${name}": "{ type: '${def.type}' }" does not exists`);
       }
 
       const required = types[def.type].required;
@@ -152,7 +152,7 @@ class ParameterBag {
         if (def.event === true && key === 'default') {
           // do nothing, default is always null for `event` params
         } else if (!Object.prototype.hasOwnProperty.call(def, key)) {
-          throw new TypeError(`[stateManager] Invalid schema definition - param "${name}" (type "${def.type}"): "${key}" key is required`);
+          throw new TypeError(`[StateManager.registerSchema] Invalid schema definition - param "${name}" (type "${def.type}"): "${key}" key is required`);
         }
       });
     }
@@ -160,7 +160,7 @@ class ParameterBag {
 
   constructor(schema, initValues = {}) {
     if (!schema) {
-      throw new Error(`[stateManager] schema is mandatory`);
+      throw new Error(`[ParameterBag] schema is mandatory`);
     }
 
     schema = cloneDeep(schema);
@@ -193,7 +193,7 @@ class ParameterBag {
     // make shure initValues make sens according to the given schema
     for (let name in initValues) {
       if (!Object.prototype.hasOwnProperty.call(schema, name)) {
-        throw new ReferenceError(`[stateManager] init value defined for undefined param "${name}"`);
+        throw new ReferenceError(`[StateManager.create] init value defined for undefined param "${name}"`);
       }
     }
 
@@ -226,7 +226,6 @@ class ParameterBag {
 
       this._schema[name].initValue = initValue;
       this._values[name] = initValue;
-
     }
   }
 
@@ -241,7 +240,8 @@ class ParameterBag {
   }
 
   /**
-   * Return values of all parameters as a flat object.
+   * Return values of all parameters as a flat object. If a parameter is of `any`
+   * type, a deep copy is made.
    *
    * @return {object}
    */
@@ -255,6 +255,25 @@ class ParameterBag {
     return values;
   }
 
+  /**
+   * Return values of all parameters as a flat object. Similar to `getValues` but
+   * returns a reference to the underlying value in case of `any` type. May be
+   * usefull if the underlying value is big (e.g. sensors recordings, etc.) and
+   * deep cloning expensive. Be aware that if changes are made on the returned
+   * object, the state of your application will become inconsistent.
+   *
+   * @return {object}
+   */
+  getValuesUnsafe() {
+    let values = {};
+
+    for (let name in this._values) {
+      values[name] = this.getUnsafe(name);
+    }
+
+    return values;
+  }
+
   /**
    * Return the value of the given parameter. If the parameter is of `any` type,
    * a deep copy is returned.
@@ -264,10 +283,12 @@ class ParameterBag {
    */
   get(name) {
     if (!this.has(name)) {
-      throw new ReferenceError(`[stateManager] Cannot get value of undefined parameter "${name}"`);
+      throw new ReferenceError(`[SharedState] Cannot get value of undefined parameter "${name}"`);
     }
 
     if (this._schema[name].type === 'any') {
+      // we return a deep copy of the object as we don't want the client code to
+      // be able to modify our underlying data.
       return cloneDeep(this._values[name]);
     } else {
       return this._values[name];
@@ -275,35 +296,72 @@ class ParameterBag {
   }
 
   /**
-   * Set the value of a parameter. If the value of the parameter is updated
-   * (aka if previous value is different from new value) all registered
-   * callbacks are registered.
+   * Similar to `get` but returns a reference to the underlying value in case of
+   * `any` type. May be usefull if the underlying value is big (e.g. sensors
+   * recordings, etc.) and deep cloning expensive. Be aware that if changes are
+   * made on the returned object, the state of your application will become
+   * inconsistent.
    *
    * @param {string} name - Name of the parameter.
+   * @return {Mixed} - Value of the parameter.
+   */
+  getUnsafe(name) {
+    if (!this.has(name)) {
+      throw new ReferenceError(`[SharedState] Cannot get value of undefined parameter "${name}"`);
+    }
+
+    return this._values[name];
+  }
+
+  /**
+   * Check that the value is valid according to the schema and return it coerced
+   * to the schema definition
+   *
+   * @param {String} name - Name of the parameter.
    * @param {Mixed} value - Value of the parameter.
-   * @param {boolean} [forcePropagation=false] - if true, propagate value even
-   *    if the value has not changed.
-   * @return {Array} - [new value, updated flag].
    */
-  set(name, value) {
+  coerceValue(name, value) {
     if (!this.has(name)) {
-      throw new ReferenceError(`[stateManager] Cannot set value of undefined parameter "${name}"`);
+      throw new ReferenceError(`[SharedState] Cannot set value of undefined parameter "${name}"`);
     }
 
     const def = this._schema[name];
-    const { coerceFunction } = types[def.type];
 
     if (value === null && def.nullable === false) {
-      throw new TypeError(`[stateManager] Invalid value for ${def.type} param "${name}": value is null and param is not nullable`);
+      throw new TypeError(`[SharedState] Invalid value for ${def.type} param "${name}": value is null and param is not nullable`);
     } else if (value === null && def.nullable === true) {
       value = null;
     } else {
+      const { coerceFunction } = types[def.type];
       value = coerceFunction(name, def, value);
     }
 
+    return value;
+  }
+
+  /**
+   * Set the value of a parameter. If the value of the parameter is updated
+   * (aka if previous value is different from new value) all registered
+   * callbacks are registered.
+   *
+   * @param {string} name - Name of the parameter.
+   * @param {Mixed} value - Value of the parameter.
+   * @return {Array} - [new value, updated flag].
+   */
+  set(name, value) {
+    value = this.coerceValue(name, value);
     const currentValue = this._values[name];
     const updated = !equal(currentValue, value);
 
+    // we store a deep copy of the object as we don't want the client to be able
+    // to modify our underlying data, which leads to unexpected behavior where the
+    // deep equal check to returns true, and therefore the update is not triggered.
+    // @see tests/common.state-manager.spec.js
+    // 'should copy stored value for "any" type to have a predictable behavior'
+    if (this._schema[name].type === 'any') {
+      value = cloneDeep(value);
+    }
+
     this._values[name] = value;
 
     // return tuple so that the state manager can handle the `filterChange` option
@@ -335,30 +393,34 @@ class ParameterBag {
   getSchema(name = null) {
     if (name === null) {
       return this._schema;
-    } else {
-      if (!this.has(name)) {
-        throw new ReferenceError(`[stateManager] 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,53 @@
+import { idGenerator } from '@ircam/sc-utils';
+
+export default class PromiseStore {
+  constructor(name) {
+    this.name = name;
+    this.store = new Map();
+    this.generateRequestId = idGenerator();
+  }
+
+  add(resolve, reject, type, localParams) {
+    const reqId = this.generateRequestId.next().value;
+    this.store.set(reqId, { resolve, reject, type, localParams });
+
+    return reqId;
+  }
+
+  resolve(reqId, data) {
+    if (this.store.has(reqId)) {
+      const { resolve, localParams } = this.store.get(reqId);
+      this.store.delete(reqId);
+
+      // re-merge local params into network response
+      if (localParams !== undefined) {
+        Object.assign(data, localParams);
+      }
+
+      resolve(data);
+    } else {
+      throw new Error(`[${this.name}] cannot resolve request id (${reqId}), id does not exist`);
+    }
+  }
+
+  reject(reqId, msg) {
+    if (this.store.has(reqId)) {
+      const { reject } = this.store.get(reqId);
+      this.store.delete(reqId);
+
+      reject(new Error(msg));
+    } else {
+      throw new Error(`[${this.name}] cannot reject request id (${reqId}), id does not exist`);
+    }
+  }
+
+  // reject all pending 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

@@ -11,9 +11,29 @@ import {
   UPDATE_NOTIFICATION,
 } from '../common/constants.js';
 
+/**
+ * Filter update object according to filter list.
+ * Return identity is filter is null
+ * @param {object} updates
+ * @param {array|null} filter
+ */
+function filterUpdates(updates, filter) {
+  if (filter === null) {
+    return updates;
+  }
+
+  return filter.reduce((acc, key) => {
+    if (key in updates) {
+      acc[key] = updates[key];
+    }
+    return acc;
+  }, {});
+}
+
 /**
  * The "real" state, this instance is kept private by the server.StateManager.
- * It cannot be accessed without a SharedState proxy
+ * It can only be accessed through a SharedState proxy.
+ *
  * @private
  */
 class SharedStatePrivate {
@@ -29,8 +49,9 @@ class SharedStatePrivate {
     this._creatorId = null;
   }
 
-  _attachClient(remoteId, client, isOwner = false) {
-    this._attachedClients.set(remoteId, client);
+  _attachClient(remoteId, client, isOwner, filter) {
+    const clientInfos = { client, isOwner, filter };
+    this._attachedClients.set(remoteId, clientInfos);
 
     if (isOwner) {
       this._creatorRemoteId = remoteId;
@@ -59,20 +80,11 @@ class SharedStatePrivate {
       }
 
       if (hookAborted === false) {
-        const filteredUpdates = {};
+        let acknowledgedUpdates = {};
         let hasUpdates = false;
 
         for (let name in updates) {
-          // from v3.1.0 - the `filteredUpdates` check is made using 'fast-deep-equal'
-          //    cf. https://github.com/epoberezkin/fast-deep-equal
-          //    therefore unchanged objects are not considered changed
-          //    nor propagated anymore.
-          // until v3.0.4 - we checked the `schema[name].type === 'any'`, to always consider
-          //    objects as dirty, because if the state is attached locally, we
-          //    compare the Object instances instead of their values.
-          //    @note - this should be made more robust but how?
           const [newValue, changed] = this._parameters.set(name, updates[name]);
-
           // if `filterChange` is set to `false` we don't check if the value
           // has been changed or not, it is always propagated to client states
           const { event, filterChange } = this._parameters.getSchema(name);
@@ -83,55 +95,83 @@ class SharedStatePrivate {
           }
 
           if ((filterChange && changed) || !filterChange) {
-            filteredUpdates[name] = newValue;
+            acknowledgedUpdates[name] = newValue;
             hasUpdates = true;
           }
         }
 
         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:
+          // Normal case
+          //
+          // 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.
+          //
+          // @note - remoteId correspond to unique remote state id
 
-          // this problem could be solved properly with a reducer system:
-          // if (dirty) {
-          //   -> call (async) reducer
-          //   -> get values from reducer
-          //.  -> dispatch to everybody
-          // }
+          // propagate RESPONSE to the client that originates the request if not the server
+          if (client.id !== -1) {
+            // no need to filter updates on requested, is blocked on client-side
+            client.transport.emit(
+              `${UPDATE_RESPONSE}-${this.id}-${remoteId}`,
+              reqId, acknowledgedUpdates, context,
+            );
+          }
+
+          // propagate NOTIFICATION to all attached clients except server
+          for (let [peerRemoteId, clientInfos] of this._attachedClients) {
+            const peer = clientInfos.client;
 
-          for (let [peerRemoteId, peer] of this._attachedClients.entries()) {
-            // propagate notification to all other attached clients except server
             if (remoteId !== peerRemoteId && peer.id !== -1) {
-              peer.transport.emit(`${UPDATE_NOTIFICATION}-${this.id}-${peerRemoteId}`, filteredUpdates, context);
+              const filter = clientInfos.filter;
+              const filteredUpdates = filterUpdates(acknowledgedUpdates, filter);
+
+              // propagate only if there something left after applying the filter
+              if (Object.keys(filteredUpdates).length > 0) {
+                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);
+          // propagate RESPONSE to server if it is the requester
+          if (client.id === -1) {
+            // no need to filter updates on requested, is blocked on client-side
+            client.transport.emit(
+              `${UPDATE_RESPONSE}-${this.id}-${remoteId}`,
+              reqId, acknowledgedUpdates, context,
+            );
           }
 
-          for (let [peerRemoteId, peer] of this._attachedClients.entries()) {
-            // propagate notification to server
+          // propagate NOTIFICATION to other state attached on the server
+          for (let [peerRemoteId, clientInfos] of this._attachedClients) {
+            const peer = clientInfos.client;
+
             if (remoteId !== peerRemoteId && peer.id === -1) {
-              peer.transport.emit(`${UPDATE_NOTIFICATION}-${this.id}-${peerRemoteId}`, filteredUpdates, context);
+              const filter = clientInfos.filter;
+              const filteredUpdates = filterUpdates(acknowledgedUpdates, filter);
+
+              if (Object.keys(filteredUpdates).length > 0) {
+                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.
@@ -152,14 +192,15 @@ class SharedStatePrivate {
     if (isOwner) {
       // delete only if creator
       client.transport.addListener(`${DELETE_REQUEST}-${this.id}-${remoteId}`, (reqId) => {
-        this._manager._serverStatesById.delete(this.id);
+        this._manager._sharedStatePrivateById.delete(this.id);
         // --------------------------------------------------------------------
         // WARNING - MAKE SURE WE DON'T HAVE PROBLEM W/ THAT
         // --------------------------------------------------------------------
         // @todo - propagate server-side last, because if a subscription function sends a
         // message to a client, network messages order are kept coherent
         // this._subscriptions.forEach(func => func(updated));
-        for (let [remoteId, attached] of this._attachedClients.entries()) {
+        for (let [remoteId, clientInfos] of this._attachedClients) {
+          const attached = clientInfos.client;
           this._detachClient(remoteId, attached);
 
           if (remoteId === this._creatorRemoteId) {

package/src/common/constants.js

@@ -1,6 +1,14 @@
 // id of the server when owner of a state
 export const SERVER_ID = -1;
 
+export const PING_INTERVAL = 10 * 1000;
+export const PING_LATENCY_TOLERANCE = 1000;
+export const PING_MESSAGE = 'h:ping';
+export const PONG_MESSAGE = 'h:pong';
+
+// batched transport channel
+export const BATCHED_TRANSPORT_CHANNEL = 'b:t';
+
 // shared states channels
 export const CREATE_REQUEST = 's:c:req';
 export const CREATE_RESPONSE = 's:c:res';
@@ -21,6 +29,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';
@@ -32,6 +41,10 @@ export const UPDATE_NOTIFICATION = 's:u:not';
 
 export const DELETE_SCHEMA = 's:d:s';
 
+export const GET_SCHEMA_REQUEST = 's:s:req';
+export const GET_SCHEMA_RESPONSE = 's:s:res';
+export const GET_SCHEMA_ERROR = 's:s:err';
+
 // context channels
 export const CONTEXT_ENTER_REQUEST = 'c:en:req';
 export const CONTEXT_ENTER_RESPONSE = 'c:en:res';
@@ -47,5 +60,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/Client.js

@@ -1,7 +1,6 @@
+import { idGenerator } from '@ircam/sc-utils';
 import { v4 as uuid } from 'uuid';
 
-import { idGenerator } from '../common/utils.js';
-
 const generateId = idGenerator();
 
 /**
@@ -44,6 +43,12 @@ class Client {
      * @type {server.Socket}
      */
     this.socket = socket;
+
+    /**
+     * Is set in server._onSocketConnection
+     * @private
+     */
+    this.token = null;
   }
 }
 

package/src/server/ContextManager.js

@@ -114,7 +114,7 @@ class ContextManager {
         this._contextStartPromises.set(contextName, startPromise);
         await startPromise;
         context.status = 'started';
-      } catch(err) {
+      } catch (err) {
         context.status = 'errored';
         throw new Error(err);
       }
@@ -144,7 +144,7 @@ class ContextManager {
       let context;
       try {
         context = await this.get(contextName);
-      } catch(err) {
+      } catch (err) {
         client.socket.send(
           CONTEXT_ENTER_ERROR,
           reqId,
@@ -185,7 +185,7 @@ class ContextManager {
         await context.enter(client);
 
         client.socket.send(CONTEXT_ENTER_RESPONSE, reqId, contextName);
-      } catch(err) {
+      } catch (err) {
         client.socket.send(CONTEXT_ENTER_ERROR, reqId, contextName, err.message);
       }
     });
@@ -207,7 +207,7 @@ class ContextManager {
         try {
           await context.exit(client);
           client.socket.send(CONTEXT_EXIT_RESPONSE, reqId, contextName);
-        } catch(err) {
+        } catch (err) {
           client.socket.send(CONTEXT_EXIT_ERROR, reqId, contextName, err.message);
         }
       } else {

package/src/server/PluginManager.js

@@ -78,7 +78,7 @@ import Server from './Server.js';
 class PluginManager 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"`);
+      throw new Error(`[soundworks.PluginManager] Invalid argument, "new PluginManager(server)" should receive an instance of "soundworks.Server" as argument`);
     }
 
     super(server);