@soundworks/core 4.0.0-alpha.1 → 4.0.0-alpha.10

package/src/server/StateManager.js

@@ -1,5 +1,6 @@
 import EventEmitter from 'node:events';
 
+import { idGenerator, isString, isPlainObject } from '@ircam/sc-utils';
 import clonedeep from 'lodash.clonedeep';
 
 import BaseStateManager from '../common/BaseStateManager.js';
@@ -21,17 +22,229 @@ import {
   DELETE_SCHEMA,
   PRIVATE_STATES,
 } from '../common/constants.js';
-import { idGenerator } from '../common/utils.js';
+
 
 const generateStateId = idGenerator();
 const generateRemoteId = idGenerator();
 
+/**
+ * @typedef {object} server.StateManager~schema
+ *
+ * Description of a schema to be registered by the {@link server.StateManager#registerSchema}
+ *
+ * A schema is the blueprint, or definition from which shared states can be created.
+ *
+ * It consists of a set of key / value pairs where the key is the name of
+ * the parameter, and the value is an object describing the parameter.
+ *
+ * The value can be of any of the foolowing types:
+ * - {@link server.StateManager~schemaBooleanDefinition}
+ * - {@link server.StateManager~schemaStringDefinition}
+ * - {@link server.StateManager~schemaIntegerDefinition}
+ * - {@link server.StateManager~schemaFloatDefinition}
+ * - {@link server.StateManager~schemaEnumDefinition}
+ * - {@link server.StateManager~schemaAnyDefinition}
+ *
+ * @example
+ * const mySchema = {
+ *   triggerSound: {
+ *     type: 'boolean',
+ *     event: true,
+ *   },
+ *   volume: {
+ *     type: 'float'
+ *     default: 0,
+ *     min: -80,
+ *     max: 6,
+ *   }
+ * };
+ *
+ * server.stateManager.registerSchema('my-schema-name', mySchema);
+ */
+/**
+ * Describe a {@link server.StateManager~schema} entry of "boolean" type.
+ *
+ * @typedef {object} server.StateManager~schemaBooleanDefinition
+ * @property {string} type='boolean' - Define a boolean parameter.
+ * @property {boolean} default - Default value of the parameter.
+ * @property {boolean} [nullable=false] - Define if the parameter is nullable. If
+ *   set to `true` the parameter `default` is set to `null`.
+ * @property {boolean} [event=false] - Define if the parameter is a volatile, e.g.
+ *   set its value back to `null` after propagation. When `true`, `nullable` is
+ *   automatically set to `true` and `default` to `null`.
+ * @property {boolean} [filterChange=true] - Setting this option to `false` forces
+ *   the propagation of a parameter even when its value do not change. It
+ *   offers a kind of middle ground between the default bahavior (e.g. where
+ *   only changed values are propagated) and the behavior of the `event` option
+ *   (which has no state per se). As such, setting this options to `false` if
+ *   `event=true` does not make sens.
+ * @property {boolean} [immediate=false] - Setting this option to `true` will
+ *   trigger any change (e.g. call the `onUpdate` listeners) immediately on the
+ *   state that generate the update (i.e. calling `set`), before propagating the
+ *   change on the network. This option can be usefull in cases the network
+ *   would introduce a noticeable latency on the client. If for some reason
+ *   the value is overriden server-side (e.g. in an `updateHook`) the listeners
+ *   will be called again on when the "real" / final value will be received.
+ * @property {object} [metas={}] - Optionnal metadata of the parameter.
+ */
+/**
+ * Describe a {@link server.StateManager~schema} entry of "string" type.
+ *
+ * @typedef {object} server.StateManager~schemaStringDefinition
+ * @property {string} type='string' - Define a boolean parameter.
+ * @property {string} default - Default value of the parameter.
+ * @property {boolean} [nullable=false] - Define if the parameter is nullable. If
+ *   set to `true` the parameter `default` is set to `null`.
+ * @property {boolean} [event=false] - Define if the parameter is a volatile, e.g.
+ *   set its value back to `null` after propagation. When `true`, `nullable` is
+ *   automatically set to `true` and `default` to `null`.
+ * @property {boolean} [filterChange=true] - Setting this option to `false` forces
+ *   the propagation of a parameter even when its value do not change. It
+ *   offers a kind of middle ground between the default bahavior (e.g. where
+ *   only changed values are propagated) and the behavior of the `event` option
+ *   (which has no state per se). As such, setting this options to `false` if
+ *   `event=true` does not make sens.
+ * @property {boolean} [immediate=false] - Setting this option to `true` will
+ *   trigger any change (e.g. call the `onUpdate` listeners) immediately on the
+ *   state that generate the update (i.e. calling `set`), before propagating the
+ *   change on the network. This option can be usefull in cases the network
+ *   would introduce a noticeable latency on the client. If for some reason
+ *   the value is overriden server-side (e.g. in an `updateHook`) the listeners
+ *   will be called again on when the "real" / final value will be received.
+ * @property {object} [metas={}] - Optionnal metadata of the parameter.
+ */
+/**
+ * Describe a {@link server.StateManager~schema} entry of "integer" type.
+ *
+ * @typedef {object} server.StateManager~schemaIntegerDefinition
+ * @property {string} type='integer' - Define a boolean parameter.
+ * @property {number} default - Default value of the parameter.
+ * @property {number} [min=-Infinity] - Minimum value of the parameter.
+ * @property {number} [max=+Infinity] - Maximum value of the parameter.
+ * @property {boolean} [nullable=false] - Define if the parameter is nullable. If
+ *   set to `true` the parameter `default` is set to `null`.
+ * @property {boolean} [event=false] - Define if the parameter is a volatile, e.g.
+ *   set its value back to `null` after propagation. When `true`, `nullable` is
+ *   automatically set to `true` and `default` to `null`.
+ * @property {boolean} [filterChange=true] - Setting this option to `false` forces
+ *   the propagation of a parameter even when its value do not change. It
+ *   offers a kind of middle ground between the default bahavior (e.g. where
+ *   only changed values are propagated) and the behavior of the `event` option
+ *   (which has no state per se). As such, setting this options to `false` if
+ *   `event=true` does not make sens.
+ * @property {boolean} [immediate=false] - Setting this option to `true` will
+ *   trigger any change (e.g. call the `onUpdate` listeners) immediately on the
+ *   state that generate the update (i.e. calling `set`), before propagating the
+ *   change on the network. This option can be usefull in cases the network
+ *   would introduce a noticeable latency on the client. If for some reason
+ *   the value is overriden server-side (e.g. in an `updateHook`) the listeners
+ *   will be called again on when the "real" / final value will be received.
+ * @property {object} [metas={}] - Optionnal metadata of the parameter.
+ */
+/**
+ * Describe a {@link server.StateManager~schema} entry of "float" type.
+ *
+ * @typedef {object} server.StateManager~schemaFloatDefinition
+ * @property {string} [type='float'] - Float parameter.
+ * @property {number} default - Default value.
+ * @property {number} [min=-Infinity] - Minimum value.
+ * @property {number} [max=+Infinity] - Maximum value.
+ * @property {boolean} [nullable=false] - Define if the parameter is nullable. If
+ *   set to `true` the parameter `default` is set to `null`.
+ * @property {boolean} [event=false] - Define if the parameter is a volatile, e.g.
+ *   set its value back to `null` after propagation. When `true`, `nullable` is
+ *   automatically set to `true` and `default` to `null`.
+ * @property {boolean} [filterChange=true] - Setting this option to `false` forces
+ *   the propagation of a parameter even when its value do not change. It
+ *   offers a kind of middle ground between the default bahavior (e.g. where
+ *   only changed values are propagated) and the behavior of the `event` option
+ *   (which has no state per se). As such, setting this options to `false` if
+ *   `event=true` does not make sens.
+ * @property {boolean} [immediate=false] - Setting this option to `true` will
+ *   trigger any change (e.g. call the `onUpdate` listeners) immediately on the
+ *   state that generate the update (i.e. calling `set`), before propagating the
+ *   change on the network. This option can be usefull in cases the network
+ *   would introduce a noticeable latency on the client. If for some reason
+ *   the value is overriden server-side (e.g. in an `updateHook`) the listeners
+ *   will be called again on when the "real" / final value will be received.
+ * @property {object} [metas={}] - Optionnal metadata of the parameter.
+ */
+/**
+ * Describe a {@link server.StateManager~schema} entry of "enum" type.
+ *
+ * @typedef {object} server.StateManager~schemaEnumDefinition
+ * @property {string} [type='enum'] - Enum parameter.
+ * @property {string} default - Default value of the parameter.
+ * @property {Array} list - Possible values of the parameter.
+ * @property {boolean} [nullable=false] - Define if the parameter is nullable. If
+ *   set to `true` the parameter `default` is set to `null`.
+ * @property {boolean} [event=false] - Define if the parameter is a volatile, e.g.
+ *   set its value back to `null` after propagation. When `true`, `nullable` is
+ *   automatically set to `true` and `default` to `null`.
+ * @property {boolean} [filterChange=true] - Setting this option to `false` forces
+ *   the propagation of a parameter even when its value do not change. It
+ *   offers a kind of middle ground between the default bahavior (e.g. where
+ *   only changed values are propagated) and the behavior of the `event` option
+ *   (which has no state per se). As such, setting this options to `false` if
+ *   `event=true` does not make sens.
+ * @property {boolean} [immediate=false] - Setting this option to `true` will
+ *   trigger any change (e.g. call the `onUpdate` listeners) immediately on the
+ *   state that generate the update (i.e. calling `set`), before propagating the
+ *   change on the network. This option can be usefull in cases the network
+ *   would introduce a noticeable latency on the client. If for some reason
+ *   the value is overriden server-side (e.g. in an `updateHook`) the listeners
+ *   will be called again on when the "real" / final value will be received.
+ * @property {object} [metas={}] - Optionnal metadata of the parameter.
+ */
+/**
+ * Describe a {@link server.StateManager~schema} entry of "any" type.
+ *
+ * Note that the `any` type always return a shallow copy of the state internal
+ * value. Mutating the returned value will therefore not modify the internal state.
+ *
+ * @typedef {object} server.StateManager~schemaAnyDefinition
+ * @property {string} [type='any'] - Parameter of any type.
+ * @property {*} default - Default value of the parameter.
+ * @property {boolean} [nullable=false] - Define if the parameter is nullable. If
+ *   set to `true` the parameter `default` is set to `null`.
+ * @property {boolean} [event=false] - Define if the parameter is a volatile, e.g.
+ *   set its value back to `null` after propagation. When `true`, `nullable` is
+ *   automatically set to `true` and `default` to `null`.
+ * @property {boolean} [filterChange=true] - Setting this option to `false` forces
+ *   the propagation of a parameter even when its value do not change. It
+ *   offers a kind of middle ground between the default bahavior (e.g. where
+ *   only changed values are propagated) and the behavior of the `event` option
+ *   (which has no state per se). As such, setting this options to `false` if
+ *   `event=true` does not make sens.
+ * @property {boolean} [immediate=false] - Setting this option to `true` will
+ *   trigger any change (e.g. call the `onUpdate` listeners) immediately on the
+ *   state that generate the update (i.e. calling `set`), before propagating the
+ *   change on the network. This option can be usefull in cases the network
+ *   would introduce a noticeable latency on the client. If for some reason
+ *   the value is overriden server-side (e.g. in an `updateHook`) the listeners
+ *   will be called again on when the "real" / final value will be received.
+ * @property {object} [metas={}] - Optionnal metadata of the parameter.
+ */
+
 /**
  * @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
+ * @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
+ */
+
+/**
+ * @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.
  */
 
 /**
@@ -114,10 +327,10 @@ class StateManager extends BaseStateManager {
    *
    * This is automatically handled by the {@link server.Server} when a client connects.
    *
-   * @param {Number} nodeId - Id of the client node, as given in
+   * @param {number} nodeId - Id of the client node, as given in
    *  {@link client.StateManager}
-   * @param {Object} transport - Tranpsort mecanism to communicate with the
-   *  client. Should implement a basic EventEmitter API.
+   * @param {object} transport - Transport mecanism to communicate with the
+   *  client. Must implement a basic EventEmitter API.
    *
    * @private
    */
@@ -146,9 +359,11 @@ class StateManager extends BaseStateManager {
           client.transport.emit(CREATE_RESPONSE, reqId, stateId, remoteId, schemaName, sendedSchema, currentValues);
 
           this._observers.forEach(observer => {
-            observer.transport.emit(OBSERVE_NOTIFICATION, [schemaName, stateId, nodeId]);
+            if (observer.id !== nodeId) {
+              observer.transport.emit(OBSERVE_NOTIFICATION, schemaName, stateId, nodeId);
+            }
           });
-        } catch(err) {
+        } catch (err) {
           client.transport.emit(CREATE_ERROR, reqId, err.message);
           console.error(err.message);
         }
@@ -215,7 +430,7 @@ class StateManager extends BaseStateManager {
         const { schemaName, id, _creatorId } = state;
         // only track application states
         // (e.g. do not propagate infos about audit state)
-        if (!PRIVATE_STATES.includes(schemaName)) {
+        if (!PRIVATE_STATES.includes(schemaName) && _creatorId !== client.id) {
           statesInfos.push([schemaName, id, _creatorId]);
         }
       });
@@ -237,7 +452,7 @@ class StateManager extends BaseStateManager {
    *
    * This is automatically handled by the {@link server.Server} when a client disconnects.
    *
-   * @param {Number} nodeId - Id of the client node, as given in
+   * @param {number} nodeId - Id of the client node, as given in
    *  {@link client.StateManager}
    *
    * @private
@@ -280,7 +495,7 @@ class StateManager extends BaseStateManager {
    * Register a schema from which shared states (cf. {@link common.SharedState})
    * can be instanciated.
    *
-   * @param {String} schemaName - Name of the schema.
+   * @param {string} schemaName - Name of the schema.
    * @param {server.StateManager~schema} schema - Data structure
    *  describing the states that will be created from this schema.
    *
@@ -302,10 +517,18 @@ class StateManager extends BaseStateManager {
    * })
    */
   registerSchema(schemaName, schema) {
+    if (!isString(schemaName)) {
+      throw new Error(`[stateManager.registerSchema] Invalid schema name "${schemaName}", should be a string`);
+    }
+
     if (this._schemas.has(schemaName)) {
       throw new Error(`[stateManager.registerSchema] cannot register schema with name: "${schemaName}", schema name already exists`);
     }
 
+    if (!isPlainObject(schema)) {
+      throw new Error(`[stateManager.registerSchema] Invalid schema, should be an object`);
+    }
+
     ParameterBag.validateSchema(schema);
 
     this._schemas.set(schemaName, clonedeep(schema));
@@ -315,11 +538,12 @@ class StateManager extends BaseStateManager {
 
   /**
    * Delete a schema and all associated states.
+   *
    * When a schema is deleted, all states created from this schema are deleted
    * as well, therefore all attached clients are detached and the `onDetach`
    * and `onDelete` callbacks are called on the related states.
    *
-   * @param {String} schemaName - Name of the schema.
+   * @param {string} schemaName - Name of the schema.
    */
   deleteSchema(schemaName) {
     // @note: deleting schema
@@ -344,19 +568,6 @@ class StateManager extends BaseStateManager {
     this._hooksBySchemaName.delete(schemaName);
   }
 
-  /**
-   * @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.
-   */
-
   /**
    * Register a function for a given schema (e.g. will be applied on all states
    * created from this schema) that will be executed before the update values
@@ -369,7 +580,7 @@ class StateManager extends BaseStateManager {
    * 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 `onUpdate`).
    *
-   * @param {String} schemaName - Kind of states on which applying the hook.
+   * @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.
    *
@@ -404,7 +615,6 @@ class StateManager extends BaseStateManager {
 
     return () => hooks.delete(updateHook);
   }
-
 }
 
 export default StateManager;

package/src/server/crypto.js

@@ -0,0 +1,38 @@
+import crypto from 'node:crypto';
+import { v4 as uuidv4 } from 'uuid';
+
+// adapted from https://dev.to/jobizil/encrypt-and-decrypt-data-in-nodejs-using-aes-256-cbc-2l6d
+// generate a new key and init vector each time the server restart, we don't need
+// any persistency here
+const secretKey = uuidv4();
+const secretIv = uuidv4();
+const encryptionMethod = 'aes-256-cbc';
+
+const key = crypto
+  .createHash('sha512')
+  .update(secretKey)
+  .digest('hex')
+  .substring(0, 32);
+
+const encryptionIV = crypto
+  .createHash('sha512')
+  .update(secretIv)
+  .digest('hex')
+  .substring(0, 16);
+
+
+export function encryptData(obj) {
+  const data = JSON.stringify(obj);
+  const cipher = crypto.createCipheriv(encryptionMethod, key, encryptionIV)
+  return Buffer.from(
+    cipher.update(data, 'utf8', 'hex') + cipher.final('hex')
+  ).toString('base64')
+}
+
+export function decryptData(encryptedData) {
+  const buff = Buffer.from(encryptedData, 'base64')
+  const decipher = crypto.createDecipheriv(encryptionMethod, key, encryptionIV)
+
+  const decrypted = `${decipher.update(buff.toString('utf8'), 'hex', 'utf8')}${decipher.final('utf8')}`
+  return JSON.parse(decrypted);
+}

package/src/server/index.js

@@ -1,23 +1,3 @@
-/**
- * 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.
  *

package/src/common/utils.js

@@ -1,22 +0,0 @@
-// https://stackoverflow.com/questions/17575790/environment-detection-node-js-or-browser
-export const isBrowser = new Function('try {return this===window;}catch(e){ return false;}');
-
-export function* idGenerator() {
-  for (let i = 0; true; i++) {
-    if (i === Number.MAX_SAFE_INTEGER) {
-      i = 0;
-    }
-
-    yield i;
-  }
-}
-
-export function isString(val) {
-  return (typeof val === 'string' || val instanceof String);
-}
-
-export function isFunction(func) {
-  return Object.prototype.toString.call(func) == '[object Function]' ||
-    Object.prototype.toString.call(func) == '[object AsyncFunction]';
-}
-