@soundworks/core 4.0.0-alpha.4 → 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/README.md

@@ -1,4 +1,4 @@
-# `soundworks`
+# soundworks
 
 [![npm version](https://badge.fury.io/js/@soundworks%2Fcore.svg)](https://badge.fury.io/js/@soundworks%2Fcore)
 [![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)
@@ -21,7 +21,7 @@ npx @soundworks/create@latest
 
 ![./assets/soundworks-create-min.gif](./assets/soundworks-create-min.gif)
 
-See [https://soundworks.dev/guides/getting-started.html](https://soundworks.dev/guides/getting-started.html) for more informations on the wizard and how to start with `soundworks`.
+See [https://soundworks.dev/tutorials/getting-started.html](https://soundworks.dev/tutorials/getting-started.html) for more informations on the wizard and how to start with `soundworks`.
 
 <!--
 ## Documentation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soundworks/core",
-  "version": "4.0.0-alpha.4",
+  "version": "4.0.0-alpha.6",
   "description": "Open-source creative coding framework for distributed applications based on Web technologies",
   "authors": [
     "Benjamin Matuszewski",
@@ -43,30 +43,29 @@
     "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",
+    "@ircam/sc-utils": "^1.0.1",
     "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",
-    "is-plain-obj": "^4.1.0",
     "isomorphic-ws": "^5.0.0",
     "keyv": "^4.2.2",
     "keyv-file": "^0.2.0",
     "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",
@@ -81,7 +80,7 @@
     "docdash": "^2.0.1",
     "dotenv": "^16.0.3",
     "eslint": "^8.32.0",
-    "eslint-plugin-jsdoc": "^39.6.4",
+    "eslint-plugin-jsdoc": "^40.0.0",
     "generate-changelog": "^1.8.0",
     "jsdoc": "^4.0.0",
     "markdown-toc": "^1.2.0",

package/src/client/Client.js

@@ -1,4 +1,4 @@
-import isPlainObject from 'is-plain-obj';
+import { isBrowser, isPlainObject } from '@ircam/sc-utils';
 
 import ContextManager from './ContextManager.js';
 import PluginManager from './PluginManager.js';
@@ -10,7 +10,6 @@ import {
   CLIENT_HANDSHAKE_ERROR,
   AUDIT_STATE_NAME,
 } from '../common/constants.js';
-import { isBrowser } from '../common/utils.js';
 import logger from '../common/logger.js';
 
 /**
@@ -199,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 */
@@ -241,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();
         });
@@ -251,7 +257,7 @@ class Client {
         this.socket.addListener(CLIENT_HANDSHAKE_ERROR, (err) => {
           let msg = ``;
 
-          switch(err.type) {
+          switch (err.type) {
             case 'invalid-client-type':
               msg = `[soundworks:Client] ${err.message}`;
               break;
@@ -275,7 +281,7 @@ class Client {
 
         this.socket.send(CLIENT_HANDSHAKE_REQUEST, payload);
       });
-    } catch(err) {
+    } catch (err) {
       throw new Error(err);
     }
 

package/src/client/Context.js

@@ -209,7 +209,7 @@ class Context {
         const reqId = storeRequestPromise(resolve, reject);
         this.client.socket.send(CONTEXT_ENTER_REQUEST, reqId, this.name);
       });
-    } catch(err) {
+    } catch (err) {
       throw new Error(err);
     }
   }
@@ -243,7 +243,7 @@ class Context {
         const reqId = storeRequestPromise(resolve, reject);
         this.client.socket.send(CONTEXT_EXIT_REQUEST, reqId, this.name);
       });
-    } catch(err) {
+    } catch (err) {
       throw new Error(err);
     }
   }

package/src/client/ContextManager.js

@@ -78,7 +78,7 @@ class ContextManager {
         this._contextStartPromises.set(contextName, startPromise);
         await startPromise;
         context.status = 'started';
-      } catch(err) {
+      } catch (err) {
         context.status = 'errored';
         throw new Error(err);
       }

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,3 +1,5 @@
+import { isBrowser } from '@ircam/sc-utils';
+import fetch from 'cross-fetch';
 import WebSocket from 'isomorphic-ws';
 
 import {
@@ -7,7 +9,6 @@ import {
   unpackStringMessage,
 } from '../common/sockets-utils.js';
 import logger from '../common/logger.js';
-import { isBrowser } from '../common/utils.js';
 
 // WebSocket events:
 //
@@ -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/BasePluginManager.js

@@ -1,7 +1,6 @@
-import isPlainObject from 'is-plain-obj';
+import { isPlainObject, isString } from '@ircam/sc-utils';
 
 import logger from './logger.js';
-import { isString } from './utils.js';
 
 /**
  * Shared functionnality between server-side and client-size plugin manager
@@ -111,9 +110,9 @@ class BasePluginManager {
     try {
       await Promise.all(promises);
       this.status = 'started';
-    } catch(err) {
+    } catch (err) {
       this.status = 'errored';
-      throw new Error(err);
+      throw err; // throw initial error
     }
   }
 
@@ -170,7 +169,7 @@ class BasePluginManager {
         this._instanceStartPromises.set(id, startPromise);
 
         await startPromise;
-      } catch(err) {
+      } catch (err) {
         errored = true;
         this._propagateStateChange(instance, 'errored');
         throw err;

package/src/common/BaseSharedState.js

@@ -1,3 +1,4 @@
+import { isPlainObject } from '@ircam/sc-utils';
 import ParameterBag from './ParameterBag.js';
 import {
   DELETE_REQUEST,
@@ -34,7 +35,7 @@ class BaseSharedState {
     try {
       /** @private */
       this._parameters = new ParameterBag(schema, initValues);
-    } catch(err) {
+    } catch (err) {
       console.error(err.stack);
 
       throw new Error(`Error creating or attaching state "${schemaName}" w/ values:\n
@@ -137,7 +138,6 @@ ${JSON.stringify(initValues, null, 2)}`);
       this._client.transport.addListener(`${DETACH_ERROR}-${this.id}`, (reqId, msg) => {
         rejectRequest(reqId, msg);
       });
-
     }
   }
 
@@ -149,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`);
     };
   }
 
@@ -255,16 +255,23 @@ ${JSON.stringify(initValues, null, 2)}`);
    * const updates = await state.set({ myParam: Math.random() });
    */
   async set(updates, context = null) {
+    if (!isPlainObject(updates)) {
+      throw new ReferenceError(`[SharedState] State "${this.schemaName}": state.set(updates[, context]) should receive an object as first parameter`);
+    }
+
+    if (context !== null && !isPlainObject(context)) {
+      throw new ReferenceError(`[SharedState] State "${this.schemaName}": state.set(updates[, context]) should receive an object as second parameter`);
+    }
+
     // handle immediate option
     const immediateNewValues = {};
     const immediateOldValues = {};
     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(`[stateManager] 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
@@ -303,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
@@ -327,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.
    *
@@ -407,14 +451,14 @@ ${JSON.stringify(initValues, null, 2)}`);
     if (this._isOwner) {
       return this.detach();
     } else {
-      throw new Error(`[stateManager] can delete state "${this.schemaName}", only owner of the state (i.e. the node that "create[d]" it) can delete it`);
+      throw new Error(`[SharedState] Cannot delete state "${this.schemaName}", only the owner of the state (i.e. the node that created it) can delete the state. Use "detach" instead.`);
     }
   }
 
   /**
    * 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`)
@@ -449,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) {
@@ -462,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;