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

package/.eslintrc

@@ -1,7 +1,6 @@
 {
   "extends": [
     "@ircam",
-    "plugin:jsdoc/recommended"
   ],
   "settings": {
     "jsdoc": {

package/.jsdoc

@@ -0,0 +1,57 @@
+{
+  "source": {
+    "include": [
+      "misc/assets/DOC.md",
+      "src/client",
+      "src/server",
+      "src/common"
+    ]
+  },
+  "plugins": [
+    "plugins/markdown"
+  ],
+  "opts": {
+    "projectTitle": "Soundworks",
+    "destination": "./docs",
+    "encoding": "utf8",
+    "template": "./node_modules/docdash"
+  },
+  "templates": {
+    "default": {
+      "useLongnameInNav": true
+    },
+    "footer": ""
+  },
+  "docdash": {
+    "sectionOrder": [
+      "Namespaces",
+      "Classes",
+      "Modules",
+      "Externals",
+      "Events",
+      "Mixins",
+      "Tutorials",
+      "Interfaces"
+    ],
+    "scripts": [
+      "assets/custom.css"
+    ],
+    "meta": {
+        "title": "soundworks",
+        "description": "Documentation of soundworks, a full-stack JavaScript framework for distributed WebAudio and multimedia applications"
+    },
+    "search": true,
+    "menu": {
+      "Website": {
+        "href":"http://soundworks.dev/",
+        "target":"_blank",
+        "class":"menu-item"
+      },
+      "Github": {
+        "href": "https://github.com/collective-soundworks/soundworks",
+        "target":"_blank",
+        "class":"menu-item"
+      }
+    }
+  }
+}

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+## v4.0.0-alpha.20 - 19/02/2024
+
+- Refactor heartbeat - #86
+- Refactor state collection - #85
+- Fix issue with self signed certs and config generated by wizard - #84
+
+## v4.0.0-alpha.19 - 17/01/2024
+
+- Hotfix for #85
+
+## v4.0.0-alpha.18 - 15/01/2024
+
+- Batch network message for SharedStates
+
+## v4.0.0-alpha.17 - 16/12/2023
+
+- Support bundling the server to cjs for Max externals
+
+## v4.0.0-alpha.16 - 15/12/2023
+
+- Improve StateCollection performances
+
+## v4.0.0-alpha.15 - 13/12/2023
+
+- Fix several issues with shared states
+- **Breaking Change**: by default, `StateManager::observe` and `SharedStateCollection` now retrieve locally created states

package/README.md

@@ -1,90 +1,56 @@
-# `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/)
 
-![soundworks-logo](./assets/logo-200x200.png)
+![soundworks-logo](./misc/assets/logo-200x200.png)
 
 Open-source creative coding framework for distributed applications based on Web technologies.
 
-Primarily focused on music, `soundworks` aims at supporting rapid development of real-time distributed applications using _JavaScript_. It provides abstractions to hide the complexity of the network and to foster very rapid-prototyping and trial-and-error workflows that are typical in artistic practices.
+Primarily focused on music, **soundworks** aims at supporting rapid development of real-time distributed applications using _JavaScript_. It provides abstractions to hide the complexity of the network and to foster very rapid-prototyping and trial-and-error workflows that are typical in artistic practices.
 
-*__WARNING: The version 4 of `@soundworks/core` is under heavy development.__*
-
-## Getting Started
-
-The best and most simple way to start using `soundworks` is to use the `@soundworks/create` wizard. 
-
-```sh
-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`.
-
-<!--
 ## Documentation
 
 - Guides and Tutorials: [https://soundworks.dev](https://soundworks.dev)
 - API: [https://soundworks.dev/api](https://soundworks.dev/api)
--->
 
-## API
+## Getting started
 
-The API is not publicly published for now. To access the API documentation locally, just clone this repository, go to the v4 branch and launch some http server in the docs directory. For example, using the [serve](https://www.npmjs.com/package/serve) package:
+The best and most simple way to start using **soundworks** is to use the `@soundworks/create` wizard. 
 
 ```sh
-git clone https://github.com/collective-soundworks/soundworks.git
-cd soundworks
-git checkout v4
-serve docs
+npx @soundworks/create@latest
 ```
 
-Feel welcome to open an [issue](https://github.com/collective-soundworks/soundworks/issues) or a PR if you find any inconsistency, error or missing information in the documentation.
+![soundworks-create](./misc/assets/soundworks-create-min.gif)
 
-## Share with Us
+See [https://soundworks.dev/tutorials/getting-started.html](https://soundworks.dev/tutorials/getting-started.html) for more information on the wizard and how to start using **soundworks**.
 
-If you made an application using `soundworks` please let us know here: https://github.com/collective-soundworks/soundworks/discussions/61
+## Misc
 
-## TypeScript Support
+### TypeScript support
 
 Basic TypeScript support will be proposed in a (hopefully) near future. 
 
 However, for maintenance reasons, we aim at following the TC39 and W3C specifications as close as possible. Therefore, we will wait for the https://github.com/tc39/proposal-type-annotations proposal to reach stage 3 to update the source code in a more integrated manner.
 
-## Install
+### Manual install
 
-Note that the `@soundworks/core` package is automatically installed when creating an application using the `@soundworks/create` wizard, so most of the time you should not have to install this package manually. See [https://soundworks.dev/guides/getting-started.html](https://soundworks.dev/guides/getting-started.html) for more informations on the `soundworks` wizard.
+Note that the `@soundworks/core` package is automatically installed when creating an application using the `@soundworks/create` wizard, so most of the time you should not have to install this package manually. See [https://soundworks.dev/guides/getting-started.html](https://soundworks.dev/guides/getting-started.html) for more information on the **soundworks** wizard.
 
 ```
 npm install @soundworks/core
 ```
 
-## Credits
-
-`soundworks` has been initiated by [Norbert Schnell](https://github.com/NorbertSchnell), [Sébastien Robaszkiewicz](https://github.com/i-Robi), and [Benjamin Matuszewski](https://github.com/b-ma) at the [ISMM](http://ismm.ircam.fr/) team at [Ircam - Centre Pompidou](http://www.ircam.fr/) in the context of the [CoSiMa](http://cosima.ircam.fr/) research project founded by the French National Research Agency (ANR).
-
-Development is now led by Benjamin Matuszewski, in the [Sound Music Movement Interaction Team](https://www.stms-lab.fr/team/interaction-son-musique-mouvement/) from the Ircam's STMS-LAB.
-
-### Supporting Research Projects
-
-Initial and futher developments has been supported by the following research projects:
+## Share with Us
 
-- The [DOTS](http://dots.ircam.fr/) project, funded by the French National Research Agency (ANR)
-- The Ircam projects _BeCoMe_ and _SO(a)P_
-- The _Constella(c)tions_ residency, funded by the STARTS program of the European Commission
-- The [RAPID-MIX project](http://rapidmix.goldsmithsdigital.com/), funded by the European Union’s Horizon 2020 research and innovation program
-- The [CoSiMa](http://cosima.ircam.fr/) project, funded by the French National Research Agency (ANR)
+If you made an application using **soundworks** please let us know here: https://github.com/collective-soundworks/soundworks/discussions/61
 
-### Academic Papers
+## Credits
 
-- Benjamin Matuszewski. A Web-Based Framework for Distributed Music System Research and Creation. AES - Journal of the Audio Engineering Society Audio-Accoustics-Application, Audio Engineering Society Inc, 2020. <[hal-03033143](https://hal.archives-ouvertes.fr/hal-03033143)>
-- Benjamin Matuszewski. Soundworks - A Framework for Networked Music Systems on the Web - State of Affairs and New Developments. Proceedings of the Web Audio Conference (WAC) 2019, Dec 2019, Trondheim, Norway. <[hal-02387783](https://hal.archives-ouvertes.fr/hal-02387783)>
-- Benjamin Matuszewski, Norbert Schnell, Frédéric Bevilacqua. Interaction Topologies in Mobile-Based Situated Networked Music Systems. Wireless Communications and Mobile Computing, Hindawi Publishing Corporation, 2019, 2019, pp.9142490. ⟨10.1155/2019/9142490⟩. <[hal-02086673](https://hal.archives-ouvertes.fr/hal-02086673)>
-- Norbert Schnell, Sébastien Robaszkiewicz. Soundworks – A playground for artists and developers to create collaborative mobile web performances. `Proceedings of the Web Audio Conference (WAC'15), 2015, Paris, France. <[hal-01580797](https://hal.archives-ouvertes.fr/hal-01580797)>
+[https://soundworks.dev/credits.html](https://soundworks.dev/credits.html)
 
 ## License
 
-[BSD-3-Clause](https://github.com/collective-soundworks/soundworks/blob/master/LICENSE)
+[BSD-3-Clause](./LICENSE)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soundworks/core",
-  "version": "4.0.0-alpha.2",
+  "version": "4.0.0-alpha.20",
   "description": "Open-source creative coding framework for distributed applications based on Web technologies",
   "authors": [
     "Benjamin Matuszewski",
@@ -43,52 +43,45 @@
     "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 --verbose && cp -R misc/assets docs/",
     "lint": "npx eslint src",
-    "test": "mocha",
-    "toc": "markdown-toc -i README.md",
+    "test": "npx mocha",
+    "test:all": "npx mocha tests/*/*.spec.js",
     "types": "rm -Rf types && tsc",
-    "version": "npm run toc && npm run doc && git add docs"
+    "postversion": "node ./misc/scripts/check-changelog.js"
   },
   "dependencies": {
-    "@ircam/sc-gettime": "^1.0.0",
-    "chalk": "^4.1.2",
+    "@ircam/sc-utils": "^1.3.2",
+    "chalk": "^5.3.0",
     "columnify": "^1.6.0",
     "compression": "^1.7.1",
     "express": "^4.18.1",
     "fast-deep-equal": "^3.1.3",
     "fast-text-encoding": "^1.0.0",
-    "is-plain-obj": "3.0.0",
-    "isomorphic-ws": "^4.0.1",
-    "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",
+    "isomorphic-ws": "^5.0.0",
+    "keyv": "^4.5.4",
+    "keyv-file": "^0.3.0",
+    "lodash": "^4.17.21",
+    "pem": "^1.14.8",
     "template-literal": "^1.0.4",
-    "uuid": "^8.3.2",
-    "window-or-global": "^1.0.1",
-    "ws": "^8.11.0"
+    "uuid": "^9.0.1",
+    "ws": "^8.15.0"
   },
   "devDependencies": {
-    "@ircam/eslint-config": "^1.0.0",
-    "chai": "^4.3.6",
+    "@ircam/eslint-config": "^1.3.0",
+    "chai": "^4.3.10",
     "chai-shallow-deep-equal": "^1.4.6",
     "commitizen": "^4.2.5",
     "cz-conventional-changelog": "^3.3.0",
-    "docdash": "^1.2.0",
-    "dotenv": "^16.0.3",
-    "eslint": "^8.24.0",
-    "eslint-plugin-jsdoc": "^39.6.4",
-    "generate-changelog": "^1.8.0",
-    "jsdoc": "^3.6.10",
-    "markdown-toc": "^1.2.0",
-    "mocha": "^9.2.2",
-    "puppeteer": "^18.0.5",
+    "docdash": "^2.0.2",
+    "dotenv": "^16.3.1",
+    "eslint": "^8.55.0",
+    "eslint-plugin-jsdoc": "^46.9.0",
+    "jsdoc": "^4.0.0",
+    "mocha": "^10.2.0",
+    "puppeteer": "^21.6.0",
     "tcp-ping": "^0.1.1",
-    "typescript": "^4.9.3"
+    "typescript": "^5.3.3"
   },
   "optionalDependencies": {
     "bufferutil": "^4.0.5",

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

@@ -1,4 +1,5 @@
 import Client from './Client.js';
+import PromiseStore from '../common/PromiseStore.js';
 import {
   CONTEXT_ENTER_REQUEST,
   CONTEXT_ENTER_RESPONSE,
@@ -7,11 +8,9 @@ import {
   CONTEXT_EXIT_RESPONSE,
   CONTEXT_EXIT_ERROR,
 } from '../common/constants.js';
-import {
-  storeRequestPromise,
-  resolveRequest,
-  rejectRequest,
-} from '../common/promise-store.js';
+
+// share between all context, as channels are common to all contexts
+const promiseStore = new PromiseStore('Context');
 
 /**
  * Base class to extend in order to implement a new Context.
@@ -86,7 +85,7 @@ class Context {
         return;
       }
 
-      resolveRequest(reqId);
+      promiseStore.resolve(reqId);
     });
 
     this.client.socket.addListener(CONTEXT_ENTER_ERROR, (reqId, contextName, msg) => {
@@ -94,7 +93,7 @@ class Context {
         return;
       }
 
-      rejectRequest(reqId, msg);
+      promiseStore.reject(reqId, msg);
     });
 
     this.client.socket.addListener(CONTEXT_EXIT_RESPONSE, (reqId, contextName) => {
@@ -102,7 +101,7 @@ class Context {
         return;
       }
 
-      resolveRequest(reqId);
+      promiseStore.resolve(reqId);
     });
 
     this.client.socket.addListener(CONTEXT_EXIT_ERROR, (reqId, contextName, msg) => {
@@ -110,7 +109,7 @@ class Context {
         return;
       }
 
-      rejectRequest(reqId, msg);
+      promiseStore.reject(reqId, msg);
     });
 
     this.client.contextManager.register(this);
@@ -206,10 +205,10 @@ class Context {
     // we need the try/catch block to change the promise rejection into proper error
     try {
       await new Promise((resolve, reject) => {
-        const reqId = storeRequestPromise(resolve, reject);
+        const reqId = promiseStore.add(resolve, reject, 'enter-context');
         this.client.socket.send(CONTEXT_ENTER_REQUEST, reqId, this.name);
       });
-    } catch(err) {
+    } catch (err) {
       throw new Error(err);
     }
   }
@@ -240,10 +239,10 @@ class Context {
     // we need the try/catch block to change the promise rejection into proper error
     try {
       await new Promise((resolve, reject) => {
-        const reqId = storeRequestPromise(resolve, reject);
+        const reqId = promiseStore.add(resolve, reject, 'exit-context');
         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/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,38 @@
+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.
+ *
+ * It can optionnaly exclude the states created by the current node.
+ *
+ * See {@link client.StateManager#getCollection} for factory method API
+ *
+ * ```
+ * 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,13 +1,19 @@
+import { isBrowser } from '@ircam/sc-utils';
 import WebSocket from 'isomorphic-ws';
 
+import {
+  PING_INTERVAL,
+  PING_LATENCY_TOLERANCE,
+  PING_MESSAGE,
+  PONG_MESSAGE,
+} from '../common/constants.js';
+import logger from '../common/logger.js';
 import {
   packBinaryMessage,
   unpackBinaryMessage,
   packStringMessage,
   unpackStringMessage,
 } from '../common/sockets-utils.js';
-import logger from '../common/logger.js';
-import { isBrowser } from '../common/utils.js';
 
 // WebSocket events:
 //
@@ -64,6 +70,8 @@ class Socket {
     this._stringListeners = new Map();
     /** @private */
     this._binaryListeners = new Map();
+    /** @private */
+    this._heartbeatId = null;
   }
 
   /**
@@ -110,7 +118,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
@@ -126,39 +138,73 @@ class Socket {
         ws.addEventListener('open', connectEvent => {
           // parse incoming messages for pubsub
           this.ws = ws;
+          // ping / pong to check connection
+          const heartbeat = () => {
+            clearTimeout(this._heartbeatId);
+
+            this._heartbeatId = setTimeout(() => {
+              this.terminate();
+            }, PING_INTERVAL + PING_LATENCY_TOLERANCE);
+          };
+
+          heartbeat();
+
           this.ws.addEventListener('message', e => {
+            if (e.data === PING_MESSAGE) {
+              heartbeat();
+              this.ws.send(PONG_MESSAGE);
+              // do not propagate ping / pong messages
+              return;
+            }
+
             const [channel, args] = unpackStringMessage(e.data);
             this._emit(false, channel, ...args);
           });
 
           // broadcast all `WebSocket` native events
-          ['close', 'error', 'upgrade', 'message'].forEach(eventName => {
-            this.ws.addEventListener(eventName, (e) => {
-              this._emit(false, eventName, e);
-            });
+          this.ws.addEventListener('close', (e) => {
+            clearTimeout(this._heartbeatId);
+            this._emit(false, 'close', e);
+          });
+
+          this.ws.addEventListener('error', (e) => {
+            clearTimeout(this._heartbeatId);
+            this._emit(false, 'error', e);
+          });
+
+          this.ws.addEventListener('upgrade', (e) => {
+            this._emit(false, 'upgrade', e);
+          });
+
+          this.ws.addEventListener('message', (e) => {
+            this._emit(false, 'message', e);
           });
 
           // forward open event
           this._emit(false, 'open', connectEvent);
+
           // continue with raw socket
           resolve();
         });
 
         // 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);
+            }
           }
         });
       };
@@ -166,36 +212,6 @@ class Socket {
       trySocket();
     });
 
-    // @todo - review/fix
-    // - the `ws.on` method only exists on node implementation, and the 'ping'
-    //   message is not received on addEventListener
-    // - there seems to be no way to access the ping event in browsers...
-    //
-    // let pingTimeoutId = null;
-    // const pingInterval = config.env.websockets.pingInterval;
-    // // detect broken connection
-    // // cf. https://github.com/websockets/ws#how-to-detect-and-close-broken-connections
-    // const heartbeat = () => {
-    //   try {
-    //     console.log('ping received');
-    //     clearTimeout(pingTimeoutId);
-
-    //   // pingTimeoutId = setTimeout(() => {
-    //   //   console.log('terminate');
-    //   //   this.terminate();
-    //   // }, pingInterval + 2000);
-    //   } catch (err) {
-    //     console.error(err);
-    //   }
-    // };
-    //
-    // this.ws.on('ping', heartbeat);
-    // this.ws.addEventListener('close', () => {
-    //   clearTimeout(pingTimeoutId);
-    // });
-
-    // heartbeat();
-
     // ----------------------------------------------------------
     // init binary socket
     // ----------------------------------------------------------