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

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.7",
   "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/PluginManager.js

@@ -83,7 +83,7 @@ class PluginManager extends BasePluginManager {
    */
   constructor(client) {
     if (!(client instanceof Client)) {
-      throw new Error(`[soundworks.PluginManager] Invalid argument, "new PluginManager(client)" should receive an instance of "soundworks.Client as argument"`);
+      throw new Error(`[soundworks.PluginManager] Invalid argument, "new PluginManager(client)" should receive an instance of "soundworks.Client" as argument`);
     }
 
     super(client);

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/BasePlugin.js

@@ -5,26 +5,10 @@ import merge from 'lodash.merge';
  */
 class BasePlugin {
   constructor(id) {
-    /**
-     * User defined ID of the plugin.
-     *
-     * @type {string}
-     * @see {@link client.PluginManager#register}
-     * @see {@link server.PluginManager#register}
-     */
-    this.id = id;
-
-    /**
-     * Type of the plugin, i.e. the ClassName.
-     *
-     * Usefull to do perform some logic based on certain types of plugins without
-     * knowing under which `id` they have been registered. (e.g. creating some generic
-     * views, etc.)
-     *
-     * @type {string}
-     * @readonly
-     */
-    this.type = this.constructor.name;
+    /** @private */
+    this._id = id;
+    /** @private */
+    this._type = this.constructor.name;
 
     /**
      * Options of the plugin.
@@ -58,6 +42,32 @@ class BasePlugin {
     this._onStateChangeCallbacks = new Set();
   }
 
+  /**
+   * User defined ID of the plugin.
+   *
+   * @type {string}
+   * @readonly
+   * @see {@link client.PluginManager#register}
+   * @see {@link server.PluginManager#register}
+   */
+  get id() {
+    return this._id;
+  }
+
+  /**
+   * Type of the plugin, i.e. the ClassName.
+   *
+   * Usefull to do perform some logic based on certain types of plugins without
+   * knowing under which `id` they have been registered. (e.g. creating some generic
+   * views, etc.)
+   *
+   * @type {string}
+   * @readonly
+   */
+  get type() {
+    return this._type;
+  }
+
   /**
    * Start the plugin. This method is automatically called during the client or
    * server `init()` lifecyle step. After `start()` is fulfilled the plugin should

package/src/common/BasePluginManager.js

@@ -13,7 +13,7 @@ class BasePluginManager {
     /** @private */
     this._node = node;
     /** @private */
-    this._registeredPlugins = new Map();
+    this._dependencies = new Map();
     /** @private */
     this._instances = new Map();
     /** @private */
@@ -67,11 +67,29 @@ class BasePluginManager {
       throw new Error(`[soundworks.PluginManager] Invalid argument, "pluginManager.register" fourth optionnal argument should be an array`);
     }
 
-    if (this._registeredPlugins.has(id)) {
-      throw new Error(`[soundworks:PluginManager] Plugin "${id}" of type "${ctor.name}" already registered`);
+    if (this._instances.has(id)) {
+      throw new Error(`[soundworks:PluginManager] Plugin "${id}" already registered`);
     }
 
-    this._registeredPlugins.set(id, { ctor, options, deps });
+    // we instanciate the plugin here, so that a plugin can register another one
+    // in its own constructor.
+    //
+    // the dependencies must be created first, so that the instance can call
+    // addDependency in its constructor
+    this._dependencies.set(id, deps);
+
+    const instance = new ctor(this._node, id, options);
+    this._instances.set(id, instance);
+  }
+
+  /**
+   * Manually add a dependency to a given plugin. Usefull to require a plugin
+   * within a plugin
+   *
+   */
+  addDependency(pluginId, dependencyId) {
+    const deps = this._dependencies.get(pluginId);
+    deps.push(dependencyId);
   }
 
   /**
@@ -79,7 +97,7 @@ class BasePluginManager {
    * @returns {string[]}
    */
   getRegisteredPlugins() {
-    return Array.from(this._registeredPlugins.keys());
+    return Array.from(this._instances.keys());
   }
 
   /**
@@ -96,16 +114,14 @@ class BasePluginManager {
 
     this.status = 'inited';
     // instanciate all plugins
-    for (let [id, { ctor, options }] of this._registeredPlugins.entries()) {
-      const instance = new ctor(this._node, id, options);
-      this._instances.set(id, instance);
+    for (let [id, instance] of this._instances.entries()) {
       instance.onStateChange(_values => this._propagateStateChange(instance));
     }
 
     // propagate all 'idle' statuses before start
     this._propagateStateChange();
 
-    const promises = Array.from(this._registeredPlugins.keys()).map(id => this.unsafeGet(id));
+    const promises = Array.from(this._instances.keys()).map(id => this.unsafeGet(id));
 
     try {
       await Promise.all(promises);
@@ -125,8 +141,8 @@ class BasePluginManager {
 
   /**
    * Retrieve an fully started instance of a registered plugin, without checking
-   * that the pluginManager is started. This is important for starting the plugin
-   * manager itself.
+   * that the pluginManager has started. This is required for starting the plugin
+   * manager itself and to require a plugin from within another plugin
    *
    * @private
    */
@@ -135,7 +151,7 @@ class BasePluginManager {
       throw new Error(`[soundworks.PluginManager] Invalid argument, "pluginManager.get(name)" argument should be a string`);
     }
 
-    if (!this._registeredPlugins.has(id)) {
+    if (!this._instances.has(id)) {
       throw new Error(`[soundworks:PluginManager] Cannot get plugin "${id}", plugin is not registered`);
     }
 
@@ -144,7 +160,7 @@ class BasePluginManager {
     // to dynamically register and launch plugins at runtime.
     //
     // if (!this._instances.has(id)) {
-    //   const { ctor, options } = this._registeredPlugins.get(id);
+    //   const { ctor, options } = this._dependencies.get(id);
     //   const instance = new ctor(this._node, id, options);
     //   this._instances.set(id, instance);
     // }
@@ -152,7 +168,7 @@ class BasePluginManager {
     const instance = this._instances.get(id);
 
     // recursively get the dependency chain
-    const { deps } = this._registeredPlugins.get(id);
+    const deps = this._dependencies.get(id);
     const promises = deps.map(id => this.unsafeGet(id));
 
     await Promise.all(promises);

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;