@soundworks/core 3.7.0 → 4.0.0-alpha.1

package/.eslintrc

@@ -0,0 +1,16 @@
+{
+  "extends": [
+    "@ircam",
+    "plugin:jsdoc/recommended"
+  ],
+  "settings": {
+    "jsdoc": {
+      "tagNamePreference": {
+        "augments": {
+          "message": "@extends is to be used over @augments as it is more evocative of classes than @augments",
+          "replacement": "extends"
+        }
+      }
+    }
+  }
+}

package/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2014-2020 IRCAM – Centre Pompidou (France, Paris)
+Copyright (c) 2014-present IRCAM – Centre Pompidou (France, Paris)
 
 All rights reserved.
 

package/README.md

@@ -1,58 +1,60 @@
 # `soundworks`
 
+[![npm version](https://badge.fury.io/js/@soundworks%2Fcore.svg)](https://badge.fury.io/js/@soundworks%2Fcore)
+
 ![soundworks-logo](./assets/logo-200x200.png)
 
-> Full-stack JavaScript framework for distributed WebAudio and multimedia applications.
+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.
+
+*__WARNING: The version 4 of `@soundworks/core` is under heavy development.__*
 
-## Table of Contents
+## Getting Started
 
-<!-- toc -->
+The best and most simple way to start using `soundworks` is to use the `@soundworks/create` wizard. 
 
-- [Documentation](#documentation)
-- [API](#api)
-- [Overview](#overview)
-- [Installation](#installation)
-- [Application Template](#application-template)
-- [Academic Papers](#academic-papers)
-- [Credits](#credits)
-- [License](#license)
+```sh
+npx @soundworks/create@latest
+```
 
-<!-- tocstop -->
+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
 
-[https://collective-soundworks.github.io](https://collective-soundworks.github.io)
+- Guides and Tutorials: [https://soundworks.dev](https://soundworks.dev)
+- API: [https://soundworks.dev/api](https://soundworks.dev/api)
+-->
 
 ## API
 
-[http://collective-soundworks.github.io/soundworks/](http://collective-soundworks.github.io/soundworks/)
-
-## Overview
+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:
 
-`soundworks` follows a client / server architecture where the server is written using [Node.js](https://nodejs.org/) and clients can be either regular browser clients or Node.js clients running for example on a Raspberry Pi.
+```sh
+git clone https://github.com/collective-soundworks/soundworks.git
+cd soundworks
+git checkout v4
+serve docs
+```
 
-![high-level-architecture](./assets/high-level-architecture.png)
+## TypeScript Support
 
-The core of the framework is very minimal and dedicated at handling:
-  - Http(s) server and basic routing
-  - WebSockets initialization
-  - Processes initialization
-  - Distributed state management
+Basic TypeScript support will be proposed in a (hopefully) near future. 
 
-`soundworks` can be extended with plugins to reuse common logic such as audio file loading, clock synchronisation, etc. Each plugin leaves in a separate repo for better modularity and to simplify version management.
+However, as we aim to follow the TC39 and W3C specifications as close as possible, 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.
 
-## Installation
+## Install
 
-_Note: most of the time you won't need to install `soundworks` manually, consider using the [application template](#application-template) instead._
+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.
 
 ```
 npm install @soundworks/core
 ```
 
-## Application Template
+## Share with Us
 
-The simplest way to start a new `soundworks` application is using the application template: 
-[https://github.com/collective-soundworks/soundworks-template](https://github.com/collective-soundworks/soundworks-template).
+If you made an application using `soundworks` please let us know here: https://github.com/collective-soundworks/soundworks/discussions/61
 
 ## Academic Papers
 
@@ -67,7 +69,7 @@ The simplest way to start a new `soundworks` application is using the applicatio
 
 Futher developments has been supported in the framework of:
 - The [RAPID-MIX project](http://rapidmix.goldsmithsdigital.com/), funded by the European Union’s Horizon 2020 research and innovation program
-- The Ircam project _BeCoMe_
+- The Ircam projects _BeCoMe_ and _SO(a)P_
 - The _Constella(c)tions_ residency of the STARTS program of the European Commission.
 
 Development is pursued, led by Benjamin Matuszewski, in the [Interaction Music Movement Team](https://www.stms-lab.fr/team/interaction-son-musique-mouvement/) from the Ircam's STMS-LAB.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@soundworks/core",
-  "version": "3.7.0",
-  "description": "full-stack javascript framework for distributed audio visual experiences on the web",
+  "version": "4.0.0-alpha.1",
+  "description": "Open-source creative coding framework for distributed applications based on Web technologies",
   "authors": [
     "Benjamin Matuszewski",
     "Sébastien Robaszkiewicz",
@@ -11,64 +11,84 @@
   "publishConfig": {
     "access": "public"
   },
+  "type": "module",
+  "exports": {
+    "./client.js": {
+      "module": "./src/client/index.js",
+      "node": "./src/client/index.js",
+      "types": "./types/client/index.d.ts"
+    },
+    "./server.js": {
+      "node": "./src/server/index.js",
+      "types": "./types/server/index.d.ts"
+    }
+  },
   "repository": {
     "type": "git",
-    "url": "https://github.com/collective-soundworks/soundworks"
+    "url": "git+https://github.com/collective-soundworks/soundworks.git"
+  },
+  "bugs": {
+    "url": "https://github.com/collective-soundworks/soundworks/issues"
+  },
+  "homepage": "https://soundworks.dev",
+  "keywords": [
+    "soundworks",
+    "creative-coding",
+    "music",
+    "full-stack",
+    "real-time",
+    "distributed-system"
+  ],
+  "engines": {
+    "node": ">=16.0.0"
   },
-  "main": "",
   "scripts": {
-    "clean": "rm -Rf client && rm -Rf server && rm -Rf common",
-    "doc": "rm -Rf docs && jsdoc -c .jsdoc.json --verbose && cp -R assets docs/",
-    "prepublishOnly": "npm run build",
-    "toc": "markdown-toc -i README.md",
-    "version": "npm run toc && npm run doc && git add docs",
-    "build:client": "babel src/client --out-dir client",
-    "build:server": "babel src/server --out-dir server",
-    "build:common": "babel src/common --out-dir common",
-    "build": "npm run clean && npm run build:server && npm run build:client && npm run build:common",
-    "dev:client": "chokidar src/client/ -c \"npm run build:client\"",
-    "dev:server": "chokidar src/server/ -c \"npm run build:server\"",
-    "dev:common": "chokidar src/common/ -c \"npm run build:common\"",
-    "dev": "npm run build && (npm run dev:client & npm run dev:server & npm run dev:common)",
+    "doc": "npm run jsdoc && npm run types",
+    "jsdoc": "rm -Rf docs && jsdoc -c .jsdoc.json --verbose && cp -R assets docs/",
     "lint": "npx eslint src",
-    "test": "mocha"
+    "test": "mocha",
+    "toc": "markdown-toc -i README.md",
+    "types": "rm -Rf types && tsc",
+    "version": "npm run toc && npm run doc && git add docs"
   },
   "dependencies": {
+    "@ircam/sc-gettime": "^1.0.0",
     "chalk": "^4.1.2",
     "columnify": "^1.6.0",
     "compression": "^1.7.1",
-    "debug": "^4.3.4",
+    "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",
-    "polka": "^0.5.2",
+    "serve-static": "^1.15.0",
+    "template-literal": "^1.0.4",
     "uuid": "^8.3.2",
     "window-or-global": "^1.0.1",
-    "ws": "^8.5.0"
+    "ws": "^8.11.0"
   },
   "devDependencies": {
-    "@babel/cli": "^7.17.6",
-    "@babel/core": "^7.17.9",
-    "@babel/preset-env": "^7.16.11",
-    "@soundworks/plugin-delay": "^1.0.0",
+    "@ircam/eslint-config": "^1.0.0",
     "chai": "^4.3.6",
     "chai-shallow-deep-equal": "^1.4.6",
-    "chokidar": "^3.5.3",
-    "chokidar-cli": "^3.0.0",
     "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"
+    "puppeteer": "^18.0.5",
+    "tcp-ping": "^0.1.1",
+    "typescript": "^4.9.3"
   },
   "optionalDependencies": {
     "bufferutil": "^4.0.5",

package/src/client/Client.js

@@ -0,0 +1,391 @@
+import isPlainObject from 'is-plain-obj';
+
+import ContextManager from './ContextManager.js';
+import PluginManager from './PluginManager.js';
+import Socket from './Socket.js';
+import StateManager from './StateManager.js';
+import {
+  CLIENT_HANDSHAKE_REQUEST,
+  CLIENT_HANDSHAKE_RESPONSE,
+  CLIENT_HANDSHAKE_ERROR,
+  AUDIT_STATE_NAME,
+} from '../common/constants.js';
+import { isBrowser } from '../common/utils.js';
+import logger from '../common/logger.js';
+
+/**
+ * The `Client` class is the main entry point for  the client-side of soundworks
+ * application.
+ *
+ * A `Client` instance allows to access soundworks components such as {@link client.StateManager},
+ * {@link client.PluginManager},{@link client.Socket} or {@link client.ContextManager}.
+ * Its is also responsible for handling the initialization lifecycles of the different
+ * soundworks components.
+ *
+ * ```
+ * import { Client } from '@soundworks/core/client.js';
+ * // create a new soundworks `Client` instance
+ * const client = new Client({ role: 'player' });
+ * // init and start the client
+ * await client.start();
+ * ```
+ *
+ * @memberof client
+ */
+class Client {
+  /**
+   * @param {client.BrowserClientConfig|client.NodeClientConfig} config -
+   *  Configuration of the soundworks client.
+   * @throws Will throw if the given config object is invalid.
+   */
+  constructor(config) {
+    if (!isPlainObject(config)) {
+      throw new Error(`[soundworks:Client] Invalid argument for Client constructor, config should be an object`);
+    }
+
+    if (!('role' in config)) {
+      throw new Error('[soundworks:Client] Invalid config object, "config.role" should be defined');
+    }
+
+    // for node clients env.https is requires to open the websocket
+    if (!isBrowser()) {
+      if (!('env' in config)) {
+        throw new Error('[soundworks:Client] Invalid config object, "config.env" { useHttps, serverAddress, port } should be defined');
+      }
+
+      let missing = [];
+
+      if (!('useHttps' in config.env)) {
+        missing.push('useHttps');
+      }
+
+      if (!('serverAddress' in config.env)) {
+        missing.push('serverAddress');
+      }
+
+      if (!('port' in config.env)) {
+        missing.push('port');
+      }
+
+      if (missing.length) {
+        throw new Error(`[soundworks:Client] Invalid config object, "config.env" is missing: ${missing.join(', ')}`);
+      }
+    }
+
+    /**
+     * Role of the client in the application.
+     *
+     * @type {string}
+     */
+    this.role = config.role;
+
+    /**
+     * Configuration object.
+     *
+     * @type {client.BrowserClientConfig|client.NodeClientConfig}
+     */
+    this.config = config;
+
+    if (!this.config.env) {
+      this.config.env = {};
+    }
+
+    // minimal configuration for websockets
+    this.config.env.websockets = Object.assign({
+      path: 'socket',
+      pingInterval: 5000,
+    }, config.env.websockets);
+
+    /**
+     * Session id of the client (incremeted positive number), generated and
+     * retrieved by the server during `client.init`. The counter is reset when
+     * the server restarts.
+     *
+     * @type {number}
+     */
+    this.id = null;
+
+    /**
+     * Unique session uuid of the client (uuidv4), generated and retrieved by
+     * the server during {@link client.Client#init}.
+     *
+     * @type {string}
+     */
+    this.uuid = null;
+
+    /**
+     * Instance of the {@link client.Socket} class that handle websockets communications with
+     * the server.
+     *
+     * @see {@link client.Socket}
+     * @type {client.Socket}
+     */
+    this.socket = new Socket();
+
+    /**
+     * Runtime platform on which the client is executed, i.e. 'browser' or 'node'.
+     *
+     * @type {string}
+     */
+    this.target = isBrowser() ? 'browser' : 'node';
+
+    /**
+     * Instance of the {@link client.ContextManager} class.
+     *
+     * The context manager can be safely used after `client.init()` has been fulfilled.
+     *
+     * @see {@link client.ContextManager}
+     * @type {client.ContextManager}
+     */
+    this.contextManager = new ContextManager();
+
+    /**
+     * Instance of the {@link client.PluginManager} class.
+     *
+     * The context manager can be safely used after `client.init()` has been fulfilled.
+     *
+     * @see {@link client.PluginManager}
+     * @type {client.PluginManager}
+     */
+    this.pluginManager = new PluginManager(this);
+
+    /**
+     * Instance of the {@link client.StateManager} class.
+     *
+     * The context manager can be safely used after `client.init()` has been fulfilled.
+     *
+     * @see {@link client.StateManager}
+     * @type {client.StateManager}
+     */
+    this.stateManager = null;
+
+    /**
+     * Status of the client, 'idle', 'inited', 'started' or 'errored'.
+     *
+     * @type {string}
+     */
+    this.status = 'idle';
+
+    /** @private */
+    this._onStatusChangeCallbacks = new Set();
+    /** @private */
+    this._auditState = null;
+
+    logger.configure(!!config.env.verbose);
+  }
+
+  /**
+   * The `init` method is part of the initialization lifecycle of the `soundworks`
+   * client. Most of the time, the `init` method will be implicitly called by the
+   * {@link client.Client#start} method.
+   *
+   * In some situations you might want to call this method manually, in such cases
+   * the method should be called before the {@link client.Client#start} method.
+   *
+   * What it does:
+   * - connect the sockets to be server
+   * - perform the handshake with soundworks server (retrieve id, etc.)
+   * - launch the state manager
+   * - initialize all registered plugin
+   *
+   * After `await client.init()` is fulfilled, the {@link client.Client#stateManager},
+   * the {@link client.Client#pluginManager} and the {@link client.Client#socket}
+   * can be safely used.
+   *
+   * @example
+   * import { Client } from '@soundworks/core/client.js'
+   *
+   * const client = new Client(config);
+   * // optionnal explicit call of `init` before `start`
+   * await client.init();
+   * await client.start();
+   */
+  async init() {
+    // init socket communications (string and binary)
+    await this.socket.init(this.role, this.config);
+
+    // we need the try/catch block to change the promise rejection into proper error
+    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.id = id;
+          this.uuid = uuid;
+
+          resolve();
+        });
+
+        this.socket.addListener(CLIENT_HANDSHAKE_ERROR, (err) => {
+          let msg = ``;
+
+          switch(err.type) {
+            case 'invalid-client-type':
+              msg = `[soundworks:Client] ${err.message}`;
+              break;
+            case 'invalid-plugin-list':
+              msg = `[soundworks:Client] ${err.message}`;
+              break;
+            default:
+              msg = `Undefined error`;
+              break;
+          }
+
+          this.socket.terminate();
+          reject(msg);
+        });
+
+        // send handshake request
+        const payload = {
+          role: this.role,
+          registeredPlugins: this.pluginManager.getRegisteredPlugins(),
+        };
+
+        this.socket.send(CLIENT_HANDSHAKE_REQUEST, payload);
+      });
+    } catch(err) {
+      throw new Error(err);
+    }
+
+    // ------------------------------------------------------------
+    // CREATE STATE MANAGER
+    // ------------------------------------------------------------
+    this.stateManager = new StateManager(this.id, {
+      emit: this.socket.send.bind(this.socket), // need to alias this
+      addListener: this.socket.addListener.bind(this.socket),
+      removeAllListeners: this.socket.removeAllListeners.bind(this.socket),
+    });
+
+    // ------------------------------------------------------------
+    // INIT PLUGIN MANAGER
+    // ------------------------------------------------------------
+    await this.pluginManager.start();
+
+    await this._dispatchStatus('inited');
+  }
+
+  /**
+   * The `start` method is part of the initialization lifecycle of the `soundworks`
+   * client. The `start` method will implicitly call the {@link client.Client#init}
+   * method if it has not been called manually.
+   *
+   * What it does:
+   * - optionnaly call {@link client.Client#init}
+   * - starts all the already created contexts (see {@link client.Context})
+   *
+   * @example
+   * import { Client } from '@soundworks/core/client.js'
+   *
+   * const client = new Client(config);
+   * await client.start();
+   */
+  async start() {
+    if (this.status === 'idle') {
+      await this.init();
+    }
+
+    if (this.status === 'started') {
+      throw new Error(`[soundworks:Server] Cannot call "client.start()" twice`);
+    }
+
+    if (this.status !== 'inited') {
+      throw new Error(`[soundworks:Server] Cannot "client.start()" before "client.init()"`);
+    }
+
+    // ------------------------------------------------------------
+    // START CONTEXT MANAGER
+    // ------------------------------------------------------------
+    await this.contextManager.start();
+
+    await this._dispatchStatus('started');
+  }
+
+  /**
+   * Stops all started contexts, plugins and terminates the socket connections.
+   *
+   * In most situations, you might not need to call this method. However, it can
+   * be usefull for unit testing or similar situations where you want to create
+   * and delete several clients in the same process.
+   *
+   * @example
+   * import { Client } from '@soundworks/core/client.js'
+   *
+   * const client = new Client(config);
+   * await client.start();
+   *
+   * await new Promise(resolve => setTimeout(resolve, 1000));
+   * await client.stop();
+   */
+  async stop() {
+    if (this.status !== 'started') {
+      throw new Error(`[soundworks:Client] Cannot "client.stop()" before "client.start()"`);
+    }
+
+    await this.contextManager.stop();
+    await this.pluginManager.stop();
+    await this.socket.terminate();
+
+    await this._dispatchStatus('stopped');
+  }
+
+  /**
+   * Attach and retrieve the global audit state of the application.
+   *
+   * The audit state is a {@link client.SharedState} instance that keeps track of
+   * global informations about the application such as, the number of connected
+   * clients, network latency estimation, etc. It is usefull for controller client
+   * roles to give the user an overview about the state of the application.
+   *
+   * The audit state is lazily attached to the client only if this method is called.
+   *
+   * @returns {Promise<client.SharedState>}
+   * @throws Will throw if called before `client.init()`
+   * @see {@link client.SharedState}
+   * @example
+   * const auditState = await client.getAuditState();
+   * auditState.onUpdate(() => console.log(auditState.getValues()), true);
+   */
+  async getAuditState() {
+    if (this.status === 'idle') {
+      throw new Error(`[soundworks.Client] Cannot access audit state before "client.init()"`);
+    }
+
+    if (this._auditState === null) {
+      this._auditState = await this.stateManager.attach(AUDIT_STATE_NAME);
+    }
+
+    return this._auditState;
+  }
+
+  /**
+   * Listen for the status change ('inited', 'started', 'stopped') of the client.
+   *
+   * @param {Function} callback - Listener to the status change.
+   * @returns {Function} Delete the listener.
+   */
+  onStatusChange(callback) {
+    this._onStatusChangeCallbacks.add(callback);
+
+    return () => this._onStatusChangeCallbacks.delete(callback);
+  }
+
+  /** @private */
+  async _dispatchStatus(status) {
+    this.status = status;
+
+    // if node target and launched in a child process, forward status to parent process
+    if (this.target === 'node' && process.send !== undefined) {
+      process.send(`soundworks:client:${status}`);
+    }
+
+    // execute all callbacks in parallel
+    const promises = [];
+
+    for (let callback of this._onStatusChangeCallbacks) {
+      promises.push(callback(status));
+    }
+
+    await Promise.all(promises);
+  }
+}
+
+export default Client;