@soundworks/core 4.0.0-alpha.5 → 4.0.0-alpha.6

package/.github/workflows/gh-pages.yml

@@ -0,0 +1,31 @@
+name: GH Pages
+
+on:
+  push:
+    tags:
+      - '*'
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+
+      - name: 'Install Node'
+        uses: actions/setup-node@v3.6.0
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Build Docs
+        run: npm run doc
+
+      - name: Deploy
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          folder: docs
+

package/.github/workflows/unit-tests.yml

@@ -0,0 +1,18 @@
+name: Unit Tests
+on: push
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: 'Install Node'
+        uses: actions/setup-node@v3.6.0
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: "Run Test"
+        run: npm test -- tests/**.spec.js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soundworks/core",
-  "version": "4.0.0-alpha.5",
+  "version": "4.0.0-alpha.6",
   "description": "Open-source creative coding framework for distributed applications based on Web technologies",
   "authors": [
     "Benjamin Matuszewski",
@@ -43,13 +43,12 @@
     "node": ">=16.0.0"
   },
   "scripts": {
-    "doc": "npm run jsdoc",
-    "jsdoc": "rm -Rf docs && jsdoc -c .jsdoc.json --verbose && cp -R assets docs/",
+    "doc": "rm -Rf docs && jsdoc -c .jsdoc.json --verbose && cp -R assets docs/",
     "lint": "npx eslint src",
     "test": "mocha",
     "toc": "markdown-toc -i README.md",
     "types": "rm -Rf types && tsc",
-    "version": "npm run toc && npm run doc && git add docs"
+    "version": "npm run toc"
   },
   "dependencies": {
     "@ircam/sc-gettime": "^1.0.0",
@@ -57,6 +56,7 @@
     "chalk": "^5.2.0",
     "columnify": "^1.6.0",
     "compression": "^1.7.1",
+    "cross-fetch": "^3.1.5",
     "express": "^4.18.1",
     "fast-deep-equal": "^3.1.3",
     "fast-text-encoding": "^1.0.0",
@@ -66,7 +66,6 @@
     "lodash.clonedeep": "^4.5.0",
     "lodash.merge": "^4.6.2",
     "pem": "^1.14.6",
-    "serve-static": "^1.15.0",
     "template-literal": "^1.0.4",
     "uuid": "^9.0.0",
     "window-or-global": "^1.0.1",

package/src/client/Client.js

@@ -198,6 +198,12 @@ class Client {
      */
     this.status = 'idle';
 
+    /**
+     * Token of the client if connected through HTTP authentication.
+     * @private
+     */
+    this.token = null;
+
     /** @private */
     this._onStatusChangeCallbacks = new Set();
     /** @private */
@@ -240,9 +246,10 @@ class Client {
     try {
       await new Promise((resolve, reject) => {
         // wait for handshake response before starting stateManager and pluginManager
-        this.socket.addListener(CLIENT_HANDSHAKE_RESPONSE, async ({ id, uuid }) => {
+        this.socket.addListener(CLIENT_HANDSHAKE_RESPONSE, async ({ id, uuid, token }) => {
           this.id = id;
           this.uuid = uuid;
+          this.token = token;
 
           resolve();
         });

package/src/client/SharedStateCollection.js

@@ -0,0 +1,35 @@
+import BaseSharedStateCollection from '../common/BaseSharedStateCollection.js';
+
+// this file exists only for documentation purposesSharedStateCollection.js
+
+/**
+ * @callback client.SharedStateCollection~onUpdateCallback
+ * @param {client.SharedState} state - State that triggered the update.
+ * @param {Object} newValues - Key / value pairs of the updates that have been
+ *  applied to the state.
+ * @param {Object} oldValues - Key / value pairs of the updated params before
+ *  the updates has been applied to the state.
+ * @param {Mixed} [context=null] - Optionnal context object that has been passed
+ *  with the values updates in the `set` call.
+ */
+
+/**
+ * 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.
+ *
+ * ```
+ * const collection = await client.stateManager.getCollection('my-schema');
+ * const allValues = collection.getValues();
+ * collection.onUpdate((state, newValues, oldValues, context) => {
+ *   // do something
+ * });
+ * ```
+ * @memberof client
+ * @extends BaseSharedStateCollection
+ * @inheritdoc
+ * @hideconstructor
+ */
+class SharedStateCollection extends BaseSharedStateCollection {}
+
+export default SharedStateCollection;

package/src/client/Socket.js

@@ -1,4 +1,5 @@
 import { isBrowser } from '@ircam/sc-utils';
+import fetch from 'cross-fetch';
 import WebSocket from 'isomorphic-ws';
 
 import {
@@ -110,7 +111,11 @@ class Socket {
       };
     }
 
-    const queryParams = `role=${role}&key=${key}`;
+    let queryParams = `role=${role}&key=${key}`;
+
+    if (config.token) {
+      queryParams += `&token=${config.token}`;
+    }
 
     // ----------------------------------------------------------
     // init string socket
@@ -146,19 +151,22 @@ class Socket {
 
         // cf. https://github.com/collective-soundworks/soundworks/issues/17
         ws.addEventListener('error', e => {
-          if (e.type === 'error' && e.error.code === 'ECONNREFUSED') {
-            if (!connectionRefusedLogged) {
-              logger.log('[soundworks.Socket] Connection refused, waiting for the server to start');
-              connectionRefusedLogged = true;
-            }
-
+          if (e.type === 'error') {
             if (ws.terminate) {
               ws.terminate();
             } else {
               ws.close();
             }
 
-            setTimeout(trySocket, 1000);
+            // for node clients, retry connection
+            if (e.error && e.error.code === 'ECONNREFUSED') {
+              if (!connectionRefusedLogged) {
+                logger.log('[soundworks.Socket] Connection refused, waiting for the server to start');
+                connectionRefusedLogged = true;
+              }
+
+              setTimeout(trySocket, 1000);
+            }
           }
         });
       };

package/src/common/BaseSharedState.js

@@ -138,7 +138,6 @@ ${JSON.stringify(initValues, null, 2)}`);
       this._client.transport.addListener(`${DETACH_ERROR}-${this.id}`, (reqId, msg) => {
         rejectRequest(reqId, msg);
       });
-
     }
   }
 
@@ -150,7 +149,7 @@ ${JSON.stringify(initValues, null, 2)}`);
     // Monkey patch detach so it throws if called twice. Doing nothing blocks
     // the process on a second `detach` call as the Promise never resolves
     this.detach = () => {
-      throw new Error(`[stateManager] State "${this.schemaName} (${this.id})" already detached, cannot detach twice`);
+      throw new Error(`[SharedState] State "${this.schemaName} (${this.id})" already detached, cannot detach twice`);
     };
   }
 
@@ -270,10 +269,9 @@ ${JSON.stringify(initValues, null, 2)}`);
     let propagateNow = false;
 
     for (let name in updates) {
-      // throw early (client-side and not only server-side) if parameter is undefined
-      if (!this._parameters.has(name)) {
-        throw new ReferenceError(`[SharedState] State "${this.schemaName}": cannot set value of undefined parameter "${name}"`);
-      }
+      // try to coerce value early, so that eventual errors are triggered early
+      // on the node requesting the update
+      const _ = this._parameters.coerceValue(name, updates[name]);
 
       // @note: general idea...
       // if immediate=true
@@ -312,21 +310,41 @@ ${JSON.stringify(initValues, null, 2)}`);
   }
 
   /**
-   * Get the value of a paramter of the state.
+   * Get the value of a parameter of the state. If the parameter is of `any` type,
+   * a deep copy is returned.
    *
    * @param {string} name - Name of the param.
    * @throws Throws if `name` does not correspond to an existing field
    *  of the state.
    * @return {mixed}
    * @example
-   * const value = state.get('name');
+   * const value = state.get('paramName');
    */
   get(name) {
     return this._parameters.get(name);
   }
 
   /**
-   * Get all the key / value pairs of the state.
+   * 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 param.
+   * @throws Throws if `name` does not correspond to an existing field
+   *  of the state.
+   * @return {mixed}
+   * @example
+   * const value = state.getUnsafe('paramName');
+   */
+  getUnsafe(name) {
+    return this._parameters.getUnsafe(name);
+  }
+
+  /**
+   * Get all the key / value pairs of the state. If a parameter is of `any`
+   * type, a deep copy is made.
    *
    * @return {object}
    * @example
@@ -336,6 +354,23 @@ ${JSON.stringify(initValues, null, 2)}`);
     return this._parameters.getValues();
   }
 
+  /**
+   * Get all the key / value pairs of the state. If a parameter is of `any`
+   * type, a deep copy is made.
+   * 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}
+   * @example
+   * const values = state.getValues();
+   */
+  getValuesUnsafe() {
+    return this._parameters.getValuesUnsafe();
+  }
+
   /**
    * Get the schema from which the state has been created.
    *
@@ -423,7 +458,7 @@ ${JSON.stringify(initValues, null, 2)}`);
   /**
    * Subscribe to state updates.
    *
-   * @param {client.SharedState~onUpdateCallback|client.SharedState~onUpdateCallback} callback
+   * @param {client.SharedState~onUpdateCallback|server.SharedState~onUpdateCallback} callback
    *  Callback to execute when an update is applied on the state.
    * @param {Boolean} [executeListener=false] - Execute the callback immediately
    *  with current state values. (`oldValues` will be set to `{}`, and `context` to `null`)
@@ -458,8 +493,8 @@ ${JSON.stringify(initValues, null, 2)}`);
   /**
    * Register a function to execute when detaching from the state
    *
-   * @param {Function} callback - callback to execute when detaching from the state.
-   *   wether the client as called `detach`, or the state has been deleted by its
+   * @param {Function} callback - Callback to execute when detaching from the state.
+   *   Whether the client as called `detach`, or the state has been deleted by its
    *   creator.
    */
   onDetach(callback) {
@@ -471,7 +506,7 @@ ${JSON.stringify(initValues, null, 2)}`);
    * Register a function to execute when the state is deleted. Only called if the
    * node was the creator of the state. Is called after `onDetach`
    *
-   * @param {Function} callback - callback to execute when the state is deleted.
+   * @param {Function} callback - Callback to execute when the state is deleted.
    */
   onDelete(callback) {
     this._onDeleteCallbacks.add(callback);

package/src/common/BaseSharedStateCollection.js

@@ -0,0 +1,179 @@
+/**
+ * @private
+ */
+class BaseSharedStateCollection {
+  constructor(stateManager, schemaName) {
+    this._stateManager = stateManager;
+    this._schemaName = schemaName;
+    this._states = [];
+    this._onUpdateCallbacks = new Set();
+    this._onAttachCallbacks = new Set();
+    this._onDetachCallbacks = new Set();
+    this._unobserve = null;
+  }
+
+  async _init() {
+    this._unobserve = await this._stateManager.observe(this._schemaName, async (schemaName, stateId, nodeId) => {
+      const state = await this._stateManager.attach(schemaName, stateId);
+
+      this._states.push(state);
+
+      state.onDetach(() => {
+        const index = this._states.indexOf(state);
+        this._states.splice(index, 1);
+
+        this._onDetachCallbacks.forEach(callback => callback(state));
+      });
+
+      state.onUpdate((newValues, oldValues, context) => {
+        Array.from(this._onUpdateCallbacks).forEach(callback => {
+          callback(state, newValues, oldValues, context);
+        });
+      });
+
+      this._onAttachCallbacks.forEach(callback => callback(state));
+    });
+  }
+
+  /**
+   * Size of the collection
+   * @type {number}
+   */
+  get length() {
+    return this._states.length;
+  }
+
+  /**
+   * Detach from the collection, i.e. detach all underlying shared states.
+   * @type {number}
+   */
+  async detach() {
+    this._unobserve();
+
+    const promises = Array.from(this._states).map(state => state.detach());
+    await Promise.all(promises);
+
+    this._onUpdateCallbacks.clear();
+    this._onDetachCallbacks.clear();
+  }
+
+  /**
+   * Return the current values of all the states in the collection.
+   * @return {Object[]}
+   */
+  getValues() {
+    return this._states.map(state => state.getValues());
+  }
+
+  /**
+   * Return the current param value of all the states in the collection.
+   *
+   * @param {String} name - Name of the parameter
+   * @return {any[]}
+   */
+  get(name) {
+    return this._states.map(state => state.get(name));
+  }
+
+  /**
+   * Subscribe to any state update of the collection.
+   *
+   * @param {server.SharedStateCollection~onUpdateCallback|client.SharedStateCollection~onUpdateCallback}
+   *  callback - Callback to execute when an update is applied on a state.
+   * @param {Boolean} [executeListener=false] - Execute the callback immediately
+   *  for all underlying states with current state values. (`oldValues` will be
+   *  set to `{}`, and `context` to `null`)
+   * @returns {Function} - Function that delete the registered listener.
+   */
+  onUpdate(callback, executeListener = false) {
+    this._onUpdateCallbacks.add(callback);
+
+    if (executeListener === true) {
+      this._states.forEach(state => {
+        const currentValues = state.getValues();
+        const oldValues = {};
+        const context = null;
+
+        callback(state, currentValues, oldValues, context);
+      });
+    }
+
+    return () => this._onUpdateCallbacks.delete(callback);
+  }
+
+  /**
+   * Register a function to execute when a state is added to the collection.
+   *
+   * @param {Function} callback - callback to execute  when a state is added to
+   *   the collection.
+   */
+  onAttach(callback) {
+    this._onAttachCallbacks.add(callback);
+  }
+
+  /**
+   * Register a function to execute when a state is removed from the collection.
+   *
+   * @param {Function} callback - callback to execute  when a state is removed
+   *   from the collection.
+   */
+  onDetach(callback) {
+    this._onDetachCallbacks.add(callback);
+  }
+
+  /**
+   * Execute the given function once for each states of the collection (see `Array.forEach`).
+   *
+   * @param {Function} func - A function to execute for each element in the array.
+   *  Its return value is discarded.
+   */
+  forEach(func) {
+    this._states.forEach(func);
+  }
+
+  /**
+   * Creates a new array populated with the results of calling a provided function
+   * on every state of the collection (see `Array.map`).
+   *
+   * @param {Function} func - A function to execute for each element in the array.
+   *  Its return value is added as a single element in the new array.
+   */
+  map(func) {
+    return this._states.map(func);
+  }
+
+  /**
+   * Creates a shallow copy of a portion of the collection, filtered down to just
+   * the estates that pass the test implemented by the provided function (see `Array.filter`).
+   *
+   * @param {Function} func - A function to execute for each element in the array.
+   *  It should return a truthy to keep the element in the resulting array, and a f
+   *  alsy value otherwise.
+   */
+  filter(func) {
+    return this._states.filter(func);
+  }
+
+  /**
+   * Sort the elements of the collection in place (see `Array.sort`).
+   *
+   * @param {Function} func - Function that defines the sort order.
+   */
+  sort(func) {
+    this._states.sort(func);
+  }
+
+  /**
+   * Returns the first element of the collection that satisfies the provided testing
+   * function. If no values satisfy the testing function, undefined is returned.
+   *
+   * @param {Function} func - Function to execute for each element in the array.
+   *  It should return a truthy value to indicate a matching element has been found.
+   * @return {}
+   */
+  find(func) {
+    return this._states.find(func);
+  }
+}
+
+export default BaseSharedStateCollection;

package/src/common/BaseStateManager.js

@@ -1,4 +1,6 @@
+import { isString, isFunction } from '@ircam/sc-utils';
 import SharedState from './BaseSharedState.js';
+import SharedStateCollection from './BaseSharedStateCollection.js';
 import {
   CREATE_REQUEST,
   CREATE_RESPONSE,
@@ -31,7 +33,7 @@ class BaseStateManager {
     this.client = { id, transport };
 
     this._statesById = new Map();
-    this._observeListeners = new Set();
+    this._observeListeners = new Map(); // Map <callback, filterSchemaName>
     this._cachedSchemas = new Map();
     this._observeRequestCallbacks = new Map();
 
@@ -88,28 +90,35 @@ 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 = this._observeRequestCallbacks.get(reqId);
+      const [callback, filterSchemaName] = this._observeRequestCallbacks.get(reqId);
       this._observeRequestCallbacks.delete(reqId);
 
       const promises = list.map(([schemaName, stateId, nodeId]) => {
-        return callback(schemaName, stateId, nodeId);
+        if (filterSchemaName === '*' || filterSchemaName === schemaName) {
+          return callback(schemaName, stateId, nodeId);
+        } else {
+          return Promise.resolve();
+        }
       });
 
       await Promise.all(promises);
 
       const unsubscribe = () => {
         this._observeListeners.delete(callback);
-
+        // no more listeners, we can stop receiving notification from the server
         if (this._observeListeners.size === 0) {
           this.client.transport.emit(UNOBSERVE_NOTIFICATION);
         }
       };
+
       resolveRequest(reqId, unsubscribe);
     });
 
-    this.client.transport.addListener(OBSERVE_NOTIFICATION, (...list) => {
-      list.forEach(([schemaName, stateId, nodeId]) => {
-        this._observeListeners.forEach(callback => callback(schemaName, stateId, nodeId));
+    this.client.transport.addListener(OBSERVE_NOTIFICATION, (schemaName, stateId, nodeId) => {
+      this._observeListeners.forEach((filterSchemaName, callback) => {
+        if (filterSchemaName === '*' || filterSchemaName === schemaName) {
+          callback(schemaName, stateId, nodeId);
+        }
       });
     });
 
@@ -170,12 +179,16 @@ class BaseStateManager {
    * the state of all other clients of the application, to monitor them and/or take
    * control over them from a single point.
    *
-   * @todo Optionnal schema name
+   * Note that the states that are created by the same node are not propagated through
+   * the observe callback.
+   *
+   * @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.
-   * @returns {Promise<Function>} - Return a Promise that resolves when the callback
-   *  as been executed for the first time. The promise value is a function which
-   *  allows to stop observing the network.
+   * @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) => {
    *   if (schemaName === 'something') {
@@ -184,16 +197,57 @@ class BaseStateManager {
    *   }
    * });
    */
-  async observe(callback) {
-    this._observeListeners.add(callback);
-    // store function
+  // note: all filtering is done only on client-side as it is really more simple to
+  // handle this way and the network overhead is very low for observe notifications:
+  // i.e. schemaName, stateId, nodeId
+  async observe(...args) {
+    let filterSchemaName;
+    let callback;
+
+    if (args.length === 1) {
+      filterSchemaName = '*';
+      callback = args[0];
+
+      if (!isFunction(callback)) {
+        throw new Error(`[stateManager] Invalid arguments, valid signatures are "stateManager.observe(callback)" or "stateManager.observe(schemaName, callback)"`);
+      }
+    } else if (args.length === 2) {
+      filterSchemaName = args[0];
+      callback = args[1];
+
+      if (!isString(filterSchemaName) || !isFunction(callback)) {
+        throw new Error(`[stateManager] Invalid arguments, valid signatures are "stateManager.observe(callback)" or "stateManager.observe(schemaName, callback)"`);
+      }
+    } 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);
-      // store the callback to be executed on the response
-      this._observeRequestCallbacks.set(reqId, callback);
+      // 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);
     });
   }
+
+  /**
+   * Returns a collection of all the states created from the schema name. Except
+   * the ones created by the current node.
+   *
+   * @param {string} schemaName - Name of the schema.
+   * @returns {server.SharedStateCollection|client.SharedStateCollection}
+   */
+  async getCollection(schemaName) {
+    const collection = new SharedStateCollection(this, schemaName);
+    await collection._init();
+
+    return collection;
+  }
 }
 
 export default BaseStateManager;

package/src/common/ParameterBag.js

@@ -17,7 +17,7 @@ export const types = {
     },
     coerceFunction: (name, def, value) => {
       if (typeof value !== 'boolean') {
-        throw new TypeError(`[SharedState] 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(`[SharedState] 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(`[SharedState] 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(`[SharedState] 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(`[SharedState] Invalid value for enum param "${name}": ${value}`);
+        throw new TypeError(`[SharedState] Invalid value "${value}" for enum parameter "${name}"`);
       }
 
 
@@ -241,7 +241,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 +256,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.
@@ -277,39 +297,66 @@ 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(`[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(`[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 unexpected behavior where the
+    // 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') {

package/src/server/Client.js

@@ -43,6 +43,12 @@ class Client {
      * @type {server.Socket}
      */
     this.socket = socket;
+
+    /**
+     * Is set in server._onSocketConnection
+     * @private
+     */
+    this.token = null;
   }
 }
 

package/src/server/Server.js

@@ -5,7 +5,8 @@ import path from 'node:path';
 import os from 'node:os';
 import { X509Certificate, createPrivateKey } from 'node:crypto';
 
-import { isPlainObject } from '@ircam/sc-utils';
+import { getTime } from '@ircam/sc-gettime';
+import { isPlainObject, idGenerator } from '@ircam/sc-utils';
 import chalk from 'chalk';
 import compression from 'compression';
 import express from 'express';
@@ -16,6 +17,7 @@ import pem from 'pem';
 import compile from 'template-literal';
 
 import auditSchema from './audit-schema.js';
+import { encryptData, decryptData } from './crypto.js';
 import Client from './Client.js';
 import ContextManager from './ContextManager.js';
 import PluginManager from './PluginManager.js';
@@ -29,6 +31,7 @@ import {
   AUDIT_STATE_NAME,
 } from '../common/constants.js';
 
+
 let _dbNamespaces = new Set();
 
 /**
@@ -73,6 +76,8 @@ const DEFAULT_CONFIG = {
   },
 };
 
+const TOKEN_VALID_DURATION = 20; // sec
+
 // set terminal title
 /** @private */
 function setTerminalTitle(server) {
@@ -156,8 +161,8 @@ class Server {
       throw new Error(`[soundworks:Server] Invalid argument for Server constructor, config should be an object`);
     }
     /**
-     * Given config object merged with the following defaults:
-     * ```
+     * @description Given config object merged with the following defaults:
+     * @example
      * {
      *   env: {
      *     type: 'development',
@@ -178,7 +183,6 @@ class Server {
      *     clients: {},
      *   }
      * }
-     * ```
      */
     this.config = merge({}, DEFAULT_CONFIG, config);
 
@@ -236,8 +240,10 @@ class Server {
      * // expose assets located in the `soundfiles` directory on the network
      * server.router.use('/soundfiles', express.static('soundfiles')));
      */
-    this.router = express.Router();
-    // compression (must be set before serve-static)
+    // @note: we use express() instead of express.Router() because all 404 and
+    // error stuff is handled by default
+    this.router = express();
+    // compression (must be set before express.static())
     this.router.use(compression());
 
     /**
@@ -313,6 +319,10 @@ class Server {
     this._onStatusChangeCallbacks = new Set();
     /** @private */
     this._auditState = null;
+    /** @private */
+    this._pendingConnectionTokens = new Set();
+    /** @private */
+    this._trustedClients = new Set();
 
     // register audit state schema
     this.stateManager.registerSchema(AUDIT_STATE_NAME, auditSchema);
@@ -357,11 +367,24 @@ class Server {
 
     // basic http authentication
     if (this.config.env.auth) {
+      const ids = idGenerator();
+
       const soundworksAuth = (req, res, next) => {
+        let role = null;
+
+        for (let [_role, config] of Object.entries(this.config.app.clients)) {
+          if (req.path === config.route) {
+            role = _role;
+          }
+        }
 
-        const isProtected  = this.config.env.auth.clients
-          .map(type => req.path.endsWith(`/${type}`))
-          .reduce((acc, value) => acc || value, false);
+        // route that are not client entry points just pass through the middleware
+        if (role === null) {
+          next();
+          return;
+        }
+
+        const isProtected  = this.isProtected(role);
 
         if (isProtected) {
           // authentication middleware
@@ -373,17 +396,34 @@ class Server {
           // verify login and password are set and correct
           if (login && password && login === auth.login && password === auth.password) {
             // -> access granted...
+            // generate token for web socket to check connections
+            const id = ids.next().value;
+            const ip = req.ip;
+            const time = getTime();
+            const token = { id, ip, time };
+            const encryptedToken = encryptData(token);
+
+            this._pendingConnectionTokens.add(encryptedToken);
+
+            setTimeout(() => {
+              this._pendingConnectionTokens.delete(encryptedToken);
+            }, TOKEN_VALID_DURATION * 1000);
+
+            // pass to the response object to be send to the client
+            res.swToken = encryptedToken;
+
             return next();
           }
 
-          // -> access denied...
+          // show login / password modal
           res.writeHead(401, {
             'WWW-Authenticate':'Basic',
             'Content-Type':'text/plain',
           });
+
           res.end('Authentication required.');
         } else {
-          // route not protected
+          // route is not protected
           return next();
         }
       };
@@ -593,7 +633,7 @@ Invalid certificate files, please check your:
     await this.sockets.start(
       this,
       this.config.env.websockets,
-      (role, socket) => this._onSocketConnection(role, socket),
+      (...args) => this._onSocketConnection(...args),
     );
 
     // ------------------------------------------------------------
@@ -712,6 +752,8 @@ Invalid certificate files, please check your:
       route += `${role}`;
     }
 
+    this.config.app.clients[role].route = route;
+
     // define template filename: `${role}.html` or `default.html`
     const {
       templatePath,
@@ -745,6 +787,12 @@ Invalid certificate files, please check your:
     const soundworksClientHandler = (req, res) => {
       const data = clientConfigFunction(role, this.config, req);
 
+      // if the client has gone through the connection middleware (add succedeed),
+      // add the token to the data object
+      if (res.swToken) {
+        data.token = res.swToken;
+      }
+
       // CORS / COOP / COEP headers for `crossOriginIsolated pages,
       // enables `sharedArrayBuffers` and high precision timers
       // cf. https://web.dev/why-coop-coep/
@@ -759,6 +807,7 @@ Invalid certificate files, please check your:
       const appIndex = tmpl(data);
       res.end(appIndex);
     };
+
     // http request
     router.get(route, soundworksClientHandler);
 
@@ -770,18 +819,38 @@ Invalid certificate files, please check your:
    * Socket connection callback.
    * @private
    */
-  _onSocketConnection(role, socket) {
+  _onSocketConnection(role, socket, connectionToken) {
     const client = new Client(role, socket);
     const roles = Object.keys(this.config.app.clients);
 
+    // this has been validated
+    if (this.isProtected(role) && this.isValidConnectionToken(connectionToken)) {
+      const { ip } = decryptData(connectionToken);
+      const newData = {
+        ip: ip,
+        id: client.id,
+      };
+
+      const newToken = encryptData(newData);
+
+      client.token = newToken;
+
+      this._pendingConnectionTokens.delete(connectionToken);
+      this._trustedClients.add(client);
+    }
+
     socket.addListener('close', async () => {
-      // do nothin if client type was invalid
+      // do nothing if client role is invalid
       if (roles.includes(role)) {
         // decrement audit state counter
         const numClients = this._auditState.get('numClients');
         numClients[role] -= 1;
         this._auditState.set({ numClients });
 
+        // delete token
+        if (this._trustedClients.has(client)) {
+          this._trustedClients.delete(client);
+        }
         // clean context manager, await before cleaning state manager
         await this.contextManager.removeClient(client);
         // remove client from pluginManager
@@ -834,8 +903,8 @@ Invalid certificate files, please check your:
       // add client to context manager
       await this.contextManager.addClient(client);
 
-      const { id, uuid } = client;
-      socket.send(CLIENT_HANDSHAKE_RESPONSE, { id, uuid });
+      const { id, uuid, token } = client;
+      socket.send(CLIENT_HANDSHAKE_RESPONSE, { id, uuid, token });
     });
   }
 
@@ -912,6 +981,27 @@ Invalid certificate files, please check your:
    * you should rely on these defaults._
    */
   useDefaultApplicationTemplate() {
+    const buildDirectory = path.join('.build', 'public');
+
+    const useMinifiedFile = {};
+    const roles = Object.keys(this.config.app.clients);
+
+    roles.forEach(role => {
+      if (this.config.env.type === 'production') {
+        // check if minified file exists
+        const minifiedFilePath = path.join(buildDirectory, `${role}.min.js`);
+
+        if (fs.existsSync(minifiedFilePath)) {
+          useMinifiedFile[role] = true;
+        } else {
+          console.log(chalk.yellow(`    > Minified file not found for client "${role}", falling back to normal build file (use \`npm run build:production && npm start\` to use minified files)`));
+          useMinifiedFile[role] = false;
+        }
+      } else {
+        useMinifiedFile[role] = false;
+      }
+    });
+
     this._applicationTemplateOptions = {
       templateEngine: { compile },
       templatePath: path.join('.build', 'server', 'tmpl'),
@@ -926,13 +1016,14 @@ Invalid certificate files, please check your:
             type: config.env.type,
             websockets: config.env.websockets,
             subpath: config.env.subpath,
+            useMinifiedFile: useMinifiedFile[role],
           },
         };
       },
     };
 
     this.router.use(express.static('public'));
-    this.router.use('/build', express.static(path.join('.build', 'public')));
+    this.router.use('/build', express.static(buildDirectory));
   }
 
   /**
@@ -968,6 +1059,81 @@ Invalid certificate files, please check your:
 
     return this._auditState;
   }
+
+  /** @private */
+  isProtected(role) {
+    if (this.config.env.auth && Array.isArray(this.config.env.auth.clients)) {
+      return this.config.env.auth.clients.includes(role);
+    }
+
+    return false;
+  }
+
+  /** @private */
+  isValidConnectionToken(token) {
+    // token should be in pending token list
+    if (!this._pendingConnectionTokens.has(token)) {
+      return false;
+    }
+
+    // check the token is not too old
+    const data = decryptData(token);
+    const now = getTime();
+
+    // token is valid only for 30 seconds (this is arbitrary)
+    if (now > data.time + TOKEN_VALID_DURATION) {
+      // delete the token, is too old
+      this._pendingConnectionTokens.delete(token);
+      return false;
+    } else {
+      return true;
+    }
+  }
+
+  /**
+   * Check if the given client is trusted, i.e. config.env.type == 'production'
+   * and the client is protected behind a password.
+   *
+   * @param {server.Client} client - Client to be tested
+   * @returns {Boolean}
+   */
+  isTrustedClient(client) {
+    if (this.config.env.type !== 'production') {
+      return true;
+    } else {
+      return this._trustedClients.has(client);
+    }
+  }
+
+  /**
+   * Check if the token from a client is trusted, i.e. config.env.type == 'production'
+   * and the client is protected behind a password.
+   *
+   * @param {Number} clientId - Id of the client
+   * @param {Number} clientIp - Ip of the client
+   * @param {String} token - Token to be tested
+   * @returns {Boolean}
+   */
+  // for stateless interactions, e.g. POST files
+  isTrustedToken(clientId, clientIp, token) {
+    if (this.config.env.type !== 'production') {
+      return true;
+    } else {
+      for (let client of this._trustedClients) {
+        if (client.id === clientId && client.token === token) {
+          // check that given token is consistent with client ip and id
+          const { id, ip } = decryptData(client.token);
+
+          if (clientId === id && clientIp === ip) {
+            return true;
+          }
+        }
+
+      }
+
+      return false;
+    }
+  }
 }
 
 export default Server;

package/src/server/SharedStateCollection.js

@@ -0,0 +1,36 @@
+import BaseSharedStateCollection from '../common/BaseSharedStateCollection.js';
+
+// this file exists only for documentation purposesSharedStateCollection.js
+
+/**
+ * @callback server.SharedStateCollection~onUpdateCallback
+ * @param {server.SharedState} state - State that triggered the update.
+ * @param {Object} newValues - Key / value pairs of the updates that have been
+ *  applied to the state.
+ * @param {Object} oldValues - Key / value pairs of the updated params before
+ *  the updates has been applied to the state.
+ * @param {Mixed} [context=null] - Optionnal context object that has been passed
+ *  with the values updates in the `set` call.
+ */
+
+/**
+ * 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.
+ *
+ * ```
+ * const collection = await server.stateManager.getCollection('my-schema');
+ * const allValues = collection.getValues();
+ * collection.onUpdate((state, newValues, oldValues, context) => {
+ *   // do something
+ * });
+ * ```
+ * @memberof server
+ * @extends BaseSharedStateCollection
+ * @inheritdoc
+ * @hideconstructor
+ */
+class SharedStateCollection extends BaseSharedStateCollection {}
+
+export default SharedStateCollection;
+

package/src/server/Sockets.js

@@ -2,9 +2,9 @@ import { Worker } from 'node:worker_threads';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import querystring from 'querystring';
 import { WebSocketServer } from 'ws';
 import WebSocket from 'ws';
-import querystring from 'querystring';
 
 import Socket from './Socket.js';
 
@@ -69,13 +69,13 @@ class Sockets {
 
     // init ws server
     this._wss = new WebSocketServer({
-      server: server.httpServer,
+      noServer: true,
       path: `/${config.path}`, // @note - update according to existing config files (aka cosima-apps)
     });
 
     this._wss.on('connection', (ws, req) => {
       const queryString = querystring.decode(req.url.split('?')[1]);
-      const { role, key } = queryString;
+      const { role, key, token } = queryString;
       const binary = !!(parseInt(queryString.binary));
 
       if (binary) {
@@ -96,8 +96,29 @@ class Sockets {
         socket.addToRoom('*');
         socket.addToRoom(role);
 
-        onConnectionCallback(role, socket);
+        onConnectionCallback(role, socket, token);
+      }
+    });
+
+    // check if client can connect
+    server.httpServer.on('upgrade', async (req, socket, head) => {
+      const queryString = querystring.decode(req.url.split('?')[1]);
+
+      const { role, token } = queryString;
+
+      if (server.isProtected(role)) {
+        // we don't have any ip in the upgrade request, so we just check the
+        // connection token is pending
+        const allowed = server.isValidConnectionToken(token);
+
+        if (!allowed) {
+          socket.destroy('not allowed');
+        }
       }
+
+      this._wss.handleUpgrade(req, socket, head, (ws) => {
+        this._wss.emit('connection', ws, req);
+      });
     });
   }
 

package/src/server/StateManager.js

@@ -359,7 +359,9 @@ 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) {
           client.transport.emit(CREATE_ERROR, reqId, err.message);
@@ -428,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]);
         }
       });

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/.github/workflows/main.yml

@@ -1,15 +0,0 @@
-name: "Unit Tests"
-on: push
-
-jobs:
-    test:
-        runs-on: ubuntu-latest
-        steps:
-            - name: Checkout
-              uses: actions/checkout@v3.3.0
-            - name: 'Install Node'
-              uses: actions/setup-node@v3.6.0
-            - name: Install dependencies
-              run: npm install 
-            - name: "Run Test"
-              run: npm test -- tests/**.spec.js