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

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## v4.0.0-alpha.22 - 16/05/2025
+
+- Feat: allow configuring socket endpoint on browser clients
+- Check and warn if version inconsistency between server and client
+
+## v4.0.0-alpha.21 - 6/05/2025
+
+- Fix: prevent multiple 'close' events
+- Fix: disable heartbeat check on client-side, was unstable
+- Feat(SharedState): introduce 'local' option for parameters
+- Feat(SharedState): ability to filter parameters of interest
+
 ## v4.0.0-alpha.20 - 19/02/2024
 
 - Refactor heartbeat - #86

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soundworks/core",
-  "version": "4.0.0-alpha.20",
+  "version": "4.0.0-alpha.22",
   "description": "Open-source creative coding framework for distributed applications based on Web technologies",
   "authors": [
     "Benjamin Matuszewski",
@@ -48,7 +48,8 @@
     "test": "npx mocha",
     "test:all": "npx mocha tests/*/*.spec.js",
     "types": "rm -Rf types && tsc",
-    "postversion": "node ./misc/scripts/check-changelog.js"
+    "preversion": "node ./misc/scripts/generate-version-file.js $npm_new_version",
+    "postversion": "node ./misc/scripts/check-changelog.js && git commit -am \"$npm_new_version\" --allow-empty"
   },
   "dependencies": {
     "@ircam/sc-utils": "^1.3.2",

package/src/client/Client.js

@@ -11,11 +11,12 @@ import {
   AUDIT_STATE_NAME,
 } from '../common/constants.js';
 import logger from '../common/logger.js';
+import version from '../common/version.js';
 
 /**
  * Configuration object for a client running in a browser runtime.
  *
- * @typedef BrowserClientConfig
+ * @typedef ClientConfig
  * @memberof client
  * @type {object}
  * @property {string} role - Role of the client in the application (e.g. 'player', 'controller').
@@ -23,24 +24,10 @@ import logger from '../common/logger.js';
  * @property {string} [app.name=''] - Name of the application.
  * @property {string} [app.author=''] - Name of the author.
  * @property {object} [env] - Environment configration object.
- * @property {string} [env.websockets={}] - Configuration options for websockets.
- * @property {string} [env.subpath=''] - If running behind a proxy, path to the application.
- */
-
-/**
- * Configuration object for a client running in a node runtime.
- *
- * @typedef NodeClientConfig
- * @memberof client
- * @type {object}
- * @property {string} role - Role of the client in the application (e.g. 'player', 'controller').
- * @property {object} [app] - Application configration object.
- * @property {string} [app.name=''] - Name of the application.
- * @property {string} [app.author=''] - Name of the author.
- * @property {object} env - Environment configration object.
- * @property {boolean} env.serverAddress - Domain name or IP of the server.
- * @property {boolean} env.useHttps - Define is the server run in http or in https.
- * @property {boolean} env.port - Port on which the server is listening.
+ * @property {boolean} env.useHttps - Define if the websocket should use secure connection.
+ * @property {boolean} [env.serverAddress=''] - Address the socket server. Mandatory for
+ *  node clients. For browser clients, use `window.location.domain` as fallback if empty.
+ * @property {boolean} env.port - Port of the socket server.
  * @property {string} [env.websockets={}] - Configuration options for websockets.
  * @property {string} [env.subpath=''] - If running behind a proxy, path to the application.
  */
@@ -66,8 +53,7 @@ import logger from '../common/logger.js';
  */
 class Client {
   /**
-   * @param {client.BrowserClientConfig|client.NodeClientConfig} config -
-   *  Configuration of the soundworks client.
+   * @param {client.ClientConfig} config - Configuration of the soundworks client.
    * @throws Will throw if the given config object is invalid.
    */
   constructor(config) {
@@ -104,6 +90,13 @@ class Client {
       }
     }
 
+    /**
+     * package version
+     * @type string
+     * @readonly
+     */
+    this.version = version;
+
     /**
      * Role of the client in the application.
      *
@@ -114,7 +107,7 @@ class Client {
     /**
      * Configuration object.
      *
-     * @type {client.BrowserClientConfig|client.NodeClientConfig}
+     * @type {client.ClientConfig}
      */
     this.config = config;
 
@@ -189,7 +182,7 @@ class Client {
      * @see {@link client.StateManager}
      * @type {client.StateManager}
      */
-    this.stateManager = null;
+    this.stateManager = new StateManager();
 
     /**
      * Status of the client, 'idle', 'inited', 'started' or 'errored'.
@@ -246,11 +239,26 @@ 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, token }) => {
+        this.socket.addListener(CLIENT_HANDSHAKE_RESPONSE, async ({ id, uuid, token, version }) => {
           this.id = id;
           this.uuid = uuid;
           this.token = token;
 
+          if (version !== this.version) {
+            console.warn(`
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+WARNING
+
+Version discrepancies between server and "${this.role}" client:
++ server: ${version} | client: ${this.version}
+
+This might lead to unexpected behavior, you should consider to update your
+dependancies on both your server and clients.
+
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!`);
+          }
+
           resolve();
         });
 
@@ -276,6 +284,7 @@ class Client {
         // send handshake request
         const payload = {
           role: this.role,
+          version: this.version,
           registeredPlugins: this.pluginManager.getRegisteredPlugins(),
         };
 
@@ -288,7 +297,7 @@ class Client {
     // ------------------------------------------------------------
     // CREATE STATE MANAGER
     // ------------------------------------------------------------
-    this.stateManager = new StateManager(this.id, {
+    this.stateManager.init(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),

package/src/client/Socket.js

@@ -99,25 +99,29 @@ class Socket {
       path = `${config.env.subpath}/${path}`;
     }
 
-    let url;
+    const protocol = config.env.useHttps ? 'wss:' : 'ws:';
+    const port = config.env.port;
+    let serverAddress;
     let webSocketOptions;
 
     if (isBrowser()) {
-      const protocol = window.location.protocol.replace(/^http?/, 'ws');
-      const { hostname, port } = window.location;
+      // if a server address is given in config, use it, else fallback to URL hostname
+      if (config.env.serverAddress !== '') {
+        serverAddress = config.env.serverAddress;
+      } else {
+        serverAddress = window.location.hostname;
+      }
 
-      url = `${protocol}//${hostname}:${port}/${path}`;
       webSocketOptions = [];
     } else {
-      const protocol = config.env.useHttps ? 'wss:' : 'ws:';
-      const { serverAddress, port } = config.env;
+      serverAddress = config.env.serverAddress;
 
-      url = `${protocol}//${serverAddress}:${port}/${path}`;
       webSocketOptions = {
         rejectUnauthorized: false,
       };
     }
 
+    const url = `${protocol}//${serverAddress}:${port}/${path}`;
     let queryParams = `role=${role}&key=${key}`;
 
     if (config.token) {
@@ -138,20 +142,25 @@ 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 ping / pong check, to detect if connection has been
+          // broken but not detected by the client
+          // @note (2024-04): unstable and creates more issues than it solves, disable
+          // for now and review later
+          // const heartbeat = () => {
+          //   clearTimeout(this._heartbeatId);
+
+          //   this._heartbeatId = setTimeout(() => {
+          //     console.log('> HEARTBEAT missed, closing...');
+          //     this.terminate();
+          //   }, PING_INTERVAL + PING_LATENCY_TOLERANCE);
+          // };
 
-          heartbeat();
+          // heartbeat();
 
           this.ws.addEventListener('message', e => {
             if (e.data === PING_MESSAGE) {
-              heartbeat();
+              // heartbeat();
               this.ws.send(PONG_MESSAGE);
               // do not propagate ping / pong messages
               return;
@@ -250,15 +259,30 @@ class Socket {
    * Removes all listeners and immediately close the two sockets. Is automatically
    * called on `client.stop()`
    *
+   * Is also called when a disconnection is detected by the heartbeat (note that
+   * in this case, the launcher will call `client.stop()` but the listeners are
+   * already cleared so the event will be trigerred only once)
+   *
    * @private
    */
   async terminate() {
+    const closeListeners = this._stringListeners.get('close');
+    const closeBinaryListeners = this._binaryListeners.get('close');
+
     this.removeAllListeners();
     this.removeAllBinaryListeners();
 
     this.ws.close();
     this.binaryWs.close();
 
+    if (closeListeners) {
+      closeListeners.forEach(listener => listener());
+    }
+
+    if (closeBinaryListeners) {
+      closeBinaryListeners.forEach(listener => listener());
+    }
+
     return Promise.resolve();
   }
 

package/src/client/index.js

@@ -1,3 +1,9 @@
+/**
+ * @license
+ * Copyright (c) 2014-present IRCAM – Centre Pompidou (France, Paris)
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
 /**
  * Client-side part of the `soundworks` framework.
  *

package/src/common/BaseSharedState.js

@@ -24,7 +24,7 @@ import {
 // }
 
 class BaseSharedState {
-  constructor(id, remoteId, schemaName, schema, client, isOwner, manager, initValues = {}) {
+  constructor(id, remoteId, schemaName, schema, client, isOwner, manager, initValues, filter) {
     /** @private */
     this._id = id;
     /** @private */
@@ -37,6 +37,9 @@ class BaseSharedState {
     this._client = client;
     /** @private */
     this._manager = manager;
+    /** @private */
+    this._filter = filter;
+
     /**
      * true is the state has been detached or deleted
      * @private
@@ -332,55 +335,103 @@ ${JSON.stringify(initValues, null, 2)}`);
     }
 
     if (!isPlainObject(updates)) {
-      throw new ReferenceError(`[SharedState] State "${this.schemaName}": state.set(updates[, context]) should receive an object as first parameter`);
+      throw new TypeError(`[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`);
+      throw new TypeError(`[SharedState] State "${this.schemaName}": state.set(updates[, context]) should receive an object as second parameter`);
     }
 
-    // handle immediate option
-    const immediateNewValues = {};
-    const immediateOldValues = {};
+    const newValues = {};
+    const oldValues = {};
+    const localParams = {};
+    const sharedParams = {};
+    let hasLocalParam = false;
+    let hasSharedParam = false;
+    let forwardParams = undefined;
     let propagateNow = false;
 
     for (let name in updates) {
-      // try to coerce value early, so that eventual errors are triggered early
-      // on the node requesting the update
+      // Try to coerce value early, so that eventual errors are triggered early
+      // on the node requesting the update, and not only on the server side
+      // This throws if name does not exists
       this._parameters.coerceValue(name, updates[name]);
 
-      // @note: general idea...
-      // if immediate=true
+      // Check that name is in filter list, if any
+      if (this._filter !== null) {
+        if (!this._filter.includes(name)) {
+          throw new DOMException(`[SharedState] State "${this.schemaName}": cannot set parameter '${name}', parameter is not in filter list`, 'NotSupportedError');
+        }
+      }
+
+      // `immediate` option behavior
+      //
+      // If immediate=true
       //  - call listeners if value changed
       //  - go through normal server path
       //  - retrigger only if response from server is different from current value
-      // if immediate=true && (filterChange=false || event=true)
+      // If immediate=true && (filterChange=false || event=true)
       //  - call listeners with value regarless it changed
       //  - go through normal server path
       //  - if the node is initiator of the update (UPDATE_RESPONSE), (re-)check
       //    to prevent execute the listeners twice
 
-      const { immediate, filterChange, event } = this._parameters.getSchema(name);
+      // `local` option behavior
+      //
+      // - If the `updates` object only contains local variables, we can call the
+      // update listeners and return a fulfilled promise immediately
+      // - If parameters that require network communication are present, we call the
+      // update callback onces with the local payload, then we need to wait for the server
+      // response, call update listeners with server response and resolve promise with
+      // the full payload, i.e. reintegrating the local params in the resolve payload
+
+      const { local, immediate, filterChange, event } = this._parameters.getSchema(name);
 
-      if (immediate) {
+      if (immediate || local) {
         const oldValue = this._parameters.get(name);
         const [newValue, changed] = this._parameters.set(name, updates[name]);
 
+        // prepare data for immediate propagation of listeners
         if (changed || filterChange === false || event) {
-          immediateOldValues[name] = oldValue;
-          immediateNewValues[name] = newValue;
+          oldValues[name] = oldValue;
+          newValues[name] = newValue;
           propagateNow = true;
         }
       }
+
+      // define params that must go through network or not
+      if (local) {
+        hasLocalParam = true;
+        // get sanitize value for fulfilling promise
+        localParams[name] = this._parameters.get(name);
+      } else {
+        // note that immediate are shared params too
+        hasSharedParam = true;
+        sharedParams[name] = updates[name];
+      }
     }
 
+    // propagate immediate params if changed
     if (propagateNow) {
-      this._onUpdateCallbacks.forEach(listener => listener(immediateNewValues, immediateOldValues, context));
+      this._onUpdateCallbacks.forEach(listener => listener(newValues, oldValues, context));
+    }
+
+    // check if we can resolve immediately or if we need to go through network
+    if (hasLocalParam) {
+      if (!hasSharedParam) {
+        return Promise.resolve(localParams);
+      } else {
+        // store local params to fulfill promise with all values, see PromiseStore
+        forwardParams = localParams;
+      }
     }
 
+    // override updates to be shared on network without local params
+    updates = sharedParams;
+
     // go through server-side normal behavior
     return new Promise((resolve, reject) => {
-      const reqId = this._promiseStore.add(resolve, reject, 'update-request');
+      const reqId = this._promiseStore.add(resolve, reject, 'update-request', forwardParams);
       this._client.transport.emit(`${UPDATE_REQUEST}-${this.id}-${this.remoteId}`, reqId, updates, context);
     });
   }
@@ -397,6 +448,16 @@ ${JSON.stringify(initValues, null, 2)}`);
    * const value = state.get('paramName');
    */
   get(name) {
+    if (!this._parameters.has(name)) {
+      throw new ReferenceError(`[SharedState] State "${this.schemaName}": Cannot get value of undefined parameter "${name}"`);
+    }
+
+    if (this._filter !== null) {
+      if (!this._filter.includes(name)) {
+        throw new DOMException(`[SharedState] State "${this.schemaName}": cannot get parameter '${name}', parameter is not in filter list`, 'NotSupportedError');
+      }
+    }
+
     return this._parameters.get(name);
   }
 
@@ -415,24 +476,45 @@ ${JSON.stringify(initValues, null, 2)}`);
    * const value = state.getUnsafe('paramName');
    */
   getUnsafe(name) {
+    if (!this._parameters.has(name)) {
+      throw new ReferenceError(`[SharedState] State "${this.schemaName}": Cannot get value of undefined parameter "${name}"`);
+    }
+
+    if (this._filter !== null) {
+      if (!this._filter.includes(name)) {
+        throw new DOMException(`[SharedState] State "${this.schemaName}": cannot get parameter '${name}', parameter is not in filter list`, 'NotSupportedError');
+      }
+    }
+
     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.
+   * Get all the key / value pairs of the state.
+   *
+   * If a parameter is of `any` type, a deep copy is made.
    *
    * @return {object}
    * @example
    * const values = state.getValues();
    */
   getValues() {
-    return this._parameters.getValues();
+    const values = this._parameters.getValues();
+
+    if (this._filter !== null) {
+      for (let name in values) {
+        if (!this._filter.includes(name)) {
+          delete values[name];
+        }
+      }
+    }
+
+    return values;
   }
 
   /**
-   * Get all the key / value pairs of the state. If a parameter is of `any`
-   * type, a deep copy is made.
+   * Get all the key / value pairs of the state.
+   *
    * 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
@@ -444,7 +526,17 @@ ${JSON.stringify(initValues, null, 2)}`);
    * const values = state.getValues();
    */
   getValuesUnsafe() {
-    return this._parameters.getValuesUnsafe();
+    const values = this._parameters.getValuesUnsafe();
+
+    if (this._filter !== null) {
+      for (let name in values) {
+        if (!this._filter.includes(name)) {
+          delete values[name];
+        }
+      }
+    }
+
+    return values;
   }
 
   /**

package/src/common/BaseSharedStateCollection.js

@@ -1,8 +1,9 @@
 /** @private */
 class BaseSharedStateCollection {
-  constructor(stateManager, schemaName, options = {}) {
+  constructor(stateManager, schemaName, filter = null, options = {}) {
     this._stateManager = stateManager;
     this._schemaName = schemaName;
+    this._filter = filter;
     this._options = Object.assign({ excludeLocal: false }, options);
 
     this._schema = null;
@@ -18,8 +19,19 @@ class BaseSharedStateCollection {
   async _init() {
     this._schema = await this._stateManager.getSchema(this._schemaName);
 
+    // if filter is set, check that it contains only valid param names
+    if (this._filter !== null) {
+      const keys = Object.keys(this._schema);
+
+      for (let filter of this._filter) {
+        if (!keys.includes(filter)) {
+          throw new ReferenceError(`[SharedStateCollection] Invalid filter key (${filter}) for schema "${this._schemaName}"`)
+        }
+      }
+    }
+
     this._unobserve = await this._stateManager.observe(this._schemaName, async (schemaName, stateId) => {
-      const state = await this._stateManager.attach(schemaName, stateId);
+      const state = await this._stateManager.attach(schemaName, stateId, this._filter);
       this._states.push(state);
 
       state.onDetach(() => {
@@ -108,6 +120,21 @@ class BaseSharedStateCollection {
     return this._states.map(state => state.getValues());
   }
 
+  /**
+   * Return the current values of all the states in the collection.
+   *
+   * 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() {
+    return this._states.map(state => state.getValues());
+  }
+
   /**
    * Return the current param value of all the states in the collection.
    *
@@ -115,6 +142,24 @@ class BaseSharedStateCollection {
    * @return {any[]}
    */
   get(name) {
+    // we can delegate to the state.get(name) method for throwing in case of filtered
+    // keys, as the Promise.all will reject on first reject Promise
+    return this._states.map(state => state.get(name));
+  }
+
+  /**
+   * 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 {any[]}
+   */
+  getUnsafe(name) {
+    // we can delegate to the state.get(name) method for throwing in case of filtered
+    // keys, as the Promise.all will reject on first reject Promise
     return this._states.map(state => state.get(name));
   }
 
@@ -126,8 +171,8 @@ class BaseSharedStateCollection {
    *   current call and will be passed as third argument to all update listeners.
    */
   async set(updates, context = null) {
-    // hot fix for https://github.com/collective-soundworks/soundworks/issues/85
-    // to be cleaned soon
+    // we can delegate to the state.set(update) method for throwing in case of
+    // filtered keys, as the Promise.all will reject on first reject Promise
     const promises = this._states.map(state => state.set(updates, context));
     return Promise.all(promises);
   }

package/src/common/BaseStateManager.js

@@ -22,19 +22,9 @@ import {
   GET_SCHEMA_ERROR,
 } from './constants.js';
 
-/**
- * @private
- */
+/** @private */
 class BaseStateManager {
-  /**
-   * @param {Number} id - Id of the node.
-   * @param {Object} transport - Transport to use for synchronizing the state.
-   *  Must implement a basic EventEmitter API.
-   */
-  constructor(id, transport) {
-    // proxy transport with BatchedTransport;
-    this.client = { id, transport: new BatchedTransport(transport) };
-
+  constructor() {
     this._statesById = new Map(); // <id, state>
     this._cachedSchemas = new Map(); // <shemaName, definition>
 
@@ -42,12 +32,24 @@ class BaseStateManager {
     this._observeRequestCallbacks = new Map(); // Map <reqId, [observedSchemaName, callback, options]>
 
     this._promiseStore = new PromiseStore();
+  }
+
+  /**
+   * Executed on `client.init`
+   * @param {Number} id - Id of the node.
+   * @param {Object} transport - Transport to use for synchronizing the states.
+   *  Must implement a basic EventEmitter API.
+   */
+  /** @private */
+  init(id, transport) {
+    const batchedTransport = new BatchedTransport(transport);
+    this.client = { id, transport: batchedTransport };
 
     // ---------------------------------------------
     // CREATE
     // ---------------------------------------------
 
-    this.client.transport.addListener(CREATE_RESPONSE, (reqId, stateId, remoteId, schemaName, schema, initValues) => {
+    this.client.transport.addListener(CREATE_RESPONSE, (reqId, stateId, remoteId, schemaName, schema, initValues, filter) => {
 
       // cache schema when first dealing it to save some bandwidth
       if (!this._cachedSchemas.has(schemaName)) {
@@ -56,7 +58,7 @@ class BaseStateManager {
 
       schema = this._cachedSchemas.get(schemaName);
 
-      const state = new SharedState(stateId, remoteId, schemaName, schema, this.client, true, this, initValues);
+      const state = new SharedState(stateId, remoteId, schemaName, schema, this.client, true, this, initValues, null);
       this._statesById.set(state.id, state);
 
       this._promiseStore.resolve(reqId, state);
@@ -69,7 +71,7 @@ class BaseStateManager {
     // ---------------------------------------------
     // ATTACH (when creator, is attached by default)
     // ---------------------------------------------
-    this.client.transport.addListener(ATTACH_RESPONSE, (reqId, stateId, remoteId, schemaName, schema, currentValues) => {
+    this.client.transport.addListener(ATTACH_RESPONSE, (reqId, stateId, remoteId, schemaName, schema, currentValues, filter) => {
       // cache schema when first dealing with it to save some bandwidth
       // note: when we make the schemas dynamic at some point
       // the server should be able to invalidate the schema and send
@@ -80,7 +82,7 @@ class BaseStateManager {
 
       schema = this._cachedSchemas.get(schemaName);
 
-      const state = new SharedState(stateId, remoteId, schemaName, schema, this.client, false, this, currentValues);
+      const state = new SharedState(stateId, remoteId, schemaName, schema, this.client, false, this, currentValues, filter);
       this._statesById.set(state.id, state);
 
       this._promiseStore.resolve(reqId, state);
@@ -229,22 +231,64 @@ class BaseStateManager {
   /**
    * Attach to an existing `SharedState` instance.
    *
+   * Alternative signatures:
+   * - `stateManager.attach(schemaName)`
+   * - `stateManager.attach(schemaName, stateId)`
+   * - `stateManager.attach(schemaName, filter)`
+   * - `stateManager.attach(schemaName, stateId, filter)`
+   *
    * @param {String} schemaName - Name of the schema as given on registration
    *  (cf. ServerStateManager)
    * @param {Object} [stateId=null] - Id of the state to attach to. If `null`,
    *  attach to the first state found with the given schema name (usefull for
    *  globally shared states owned by the server).
+   * @param {array|null} [filter=null] - Filter parameters of interest in the
+   *  returned state. If set to `null`, no filter applied.
    * @returns {client.SharedState|server.SharedState}
    * @see {@link client.SharedState}
    * @see {@link server.SharedState}
+   *
    * @example
    * const state = await client.stateManager.attach('my-schema');
    */
-  async attach(schemaName, stateId = null) {
+  async attach(schemaName, stateIdOrFilter = null, filter = null) {
+    let stateId = null;
+
+    if (!isString(schemaName)) {
+      throw new TypeError(`Cannot execute 'attach' on 'StateManager': argument 1 should be either a number or an array`);
+    }
+
+    if (arguments.length === 2) {
+      if (stateIdOrFilter === null) {
+        stateId = null;
+        filter = null;
+      } else if (Number.isFinite(stateIdOrFilter)) {
+        stateId = stateIdOrFilter;
+        filter = null;
+      } else if (Array.isArray(stateIdOrFilter)) {
+        stateId = null;
+        filter = stateIdOrFilter;
+      } else {
+        throw new TypeError(`Cannot execute 'attach' on 'StateManager': argument 2 should be either null, a number or an array`);
+      }
+    }
+
+    if (arguments.length === 3) {
+      stateId = stateIdOrFilter;
+
+      if (stateId !== null && !Number.isFinite(stateId)) {
+        throw new TypeError(`Cannot execute 'attach' on 'StateManager': argument 2 should be either null or a number`);
+      }
+
+      if (filter !== null && !Array.isArray(filter)) {
+        throw new TypeError(`Cannot execute 'attach' on 'StateManager': argument 3 should be either null or an array`);
+      }
+    }
+
     return new Promise((resolve, reject) => {
       const reqId = this._promiseStore.add(resolve, reject, 'attach-request');
       const requireSchema = this._cachedSchemas.has(schemaName) ? false : true;
-      this.client.transport.emit(ATTACH_REQUEST, reqId, schemaName, stateId, requireSchema);
+      this.client.transport.emit(ATTACH_REQUEST, reqId, schemaName, stateId, requireSchema, filter);
     });
   }
 
@@ -263,10 +307,10 @@ class BaseStateManager {
    * Such strategy allows to share the observe notifications between all observers.
    *
    * Alternative signatures:
-   * - .observe(callback)
-   * - .observe(schemaName, callback)
-   * - .observe(callback, options)
-   * - .observe(schemaName, callback, options)
+   * - `stateManager.observe(callback)`
+   * - `stateManager.observe(schemaName, callback)`
+   * - `stateManager.observe(callback, options)`
+   * - `stateManager.observe(schemaName, callback, options)`
    *
    * @param {string} [schemaName] - optionnal schema name to filter the observed
    *  states.
@@ -278,6 +322,7 @@ class BaseStateManager {
    * @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) => {
    *   if (schemaName === 'something') {
@@ -333,7 +378,7 @@ class BaseStateManager {
           options = Object.assign(defaultOptions, args[1]);
 
         } else {
-          throw new Error(`[stateManager] Invalid signature, refer to the StateManager.observe documentation"`);
+          throw new TypeError(`[stateManager] Invalid signature, refer to the StateManager.observe documentation"`);
         }
 
         break;
@@ -397,22 +442,60 @@ class BaseStateManager {
   /**
    * Returns a collection of all the states created from the schema name.
    *
+   * Alternitive signatures:
+   * - `stateManager.getCollection(schemaName)`
+   * - `stateManager.getCollection(schemaName, filter)`
+   * - `stateManager.getCollection(schemaName, options)`
+   * - `stateManager.getCollection(schemaName, filter, options)`
+   *
    * @param {string} schemaName - Name of the schema.
-   * @param {object} options - Options.
-   * @param {boolean} [options.excludeLocal = false] - If set to true, exclude states
-   *  created locallly, i.e. by the same node, from the collection.
+   * @param {array|null} [filter=null] - Filter parameter of interest for each
+   *  state of the collection. If set to `null`, no filter applied.
+   * @param {object} [options={}] - Options.
+   * @param {boolean} [options.excludeLocal=false] - If set to true, exclude states
+   *  created by the same node from the collection.
    * @returns {server.SharedStateCollection|client.SharedStateCollection}
+   *
+   * @example
+   * const collection = await client.stateManager.getCollection(schemaName);
    */
-  async getCollection(schemaName, options) {
-    const collection = new SharedStateCollection(this, schemaName, options);
-
-    try {
-      await collection._init();
-    } catch (err) {
-      console.log(err.message);
-      throw new Error(`[stateManager] Cannot create collection, schema "${schemaName}" does not exists`);
+  async getCollection(schemaName, filterOrOptions = null, options = {}) {
+    if (!isString(schemaName)) {
+      throw new TypeError(`[stateManager] Cannot execute 'getCollection' on 'StateManager': 'schemaName' should be a string"`);
+    }
+
+    let filter;
+
+    if (arguments.length === 2) {
+      if (filterOrOptions === null) {
+        filter = null;
+        options = null;
+      } else if (Array.isArray(filterOrOptions)) {
+        filter = filterOrOptions;
+        options = {};
+      } else if (typeof filterOrOptions === 'object') {
+        filter = null;
+        options = filterOrOptions;
+      } else {
+        throw new TypeError(`[stateManager] Cannot execute 'getCollection' on 'StateManager': argument 2 should be either null, an array or an object"`);
+      }
     }
 
+    if (arguments.length === 3) {
+      filter = filterOrOptions;
+
+      if (filter !== null && !Array.isArray(filter)) {
+        throw new TypeError(`[stateManager] Cannot execute 'getCollection' on 'StateManager': 'filter' should be either an array or null"`);
+      }
+
+      if (options === null || typeof options !== 'object') {
+        throw new TypeError(`[stateManager] Cannot execute 'getCollection' on 'StateManager': 'options' should be an object"`);
+      }
+    }
+
+    const collection = new SharedStateCollection(this, schemaName, filter, options);
+    await collection._init();
+
     return collection;
   }
 }

package/src/common/BatchedTransport.js

@@ -1,14 +1,20 @@
+import { delay } from '@ircam/sc-utils';
+
 import { BATCHED_TRANSPORT_CHANNEL } from './constants.js';
 
 /**
  * This class proxies transports given the SharedStateManager to batch messages
+ *
+ * @param {number} [options.wait=0] - Wait for given number of milliseconds
+ *  for stacking messages before emitting on the network. If 0 is given, network
+ *  message is emitted on next microtask
  * @private
  */
 class BatchedTransport {
   constructor(transport) {
     this._transport = transport;
-    this._stack = [];
     this._listeners = new Map();
+    this._stack = [];
     this._sending = false;
 
     this._transport.addListener(BATCHED_TRANSPORT_CHANNEL, stack => {
@@ -39,7 +45,8 @@ class BatchedTransport {
 
     if (!this._sending) {
       this._sending = true;
-      this._sending = await false;
+      await false;
+      this._sending = false;
       const stack = this._stack;
       this._stack = [];
       this._transport.emit(BATCHED_TRANSPORT_CHANNEL, stack);

package/src/common/PromiseStore.js

@@ -7,18 +7,23 @@ export default class PromiseStore {
     this.generateRequestId = idGenerator();
   }
 
-  add(resolve, reject, type) {
+  add(resolve, reject, type, localParams) {
     const reqId = this.generateRequestId.next().value;
-    this.store.set(reqId, { resolve, reject, type });
+    this.store.set(reqId, { resolve, reject, type, localParams });
 
     return reqId;
   }
 
   resolve(reqId, data) {
     if (this.store.has(reqId)) {
-      const { resolve } = this.store.get(reqId);
+      const { resolve, localParams } = this.store.get(reqId);
       this.store.delete(reqId);
 
+      // re-merge local params into network response
+      if (localParams !== undefined) {
+        Object.assign(data, localParams);
+      }
+
       resolve(data);
     } else {
       throw new Error(`[${this.name}] cannot resolve request id (${reqId}), id does not exist`);
@@ -36,7 +41,7 @@ export default class PromiseStore {
     }
   }
 
-  // reject all pendeing request
+  // reject all pending request
   flush() {
     for (let [_reqId, entry] of this.store) {
       const { reject, type } = entry;

package/src/common/SharedStatePrivate.js

@@ -11,6 +11,25 @@ import {
   UPDATE_NOTIFICATION,
 } from '../common/constants.js';
 
+/**
+ * Filter update object according to filter list.
+ * Return identity is filter is null
+ * @param {object} updates
+ * @param {array|null} filter
+ */
+function filterUpdates(updates, filter) {
+  if (filter === null) {
+    return updates;
+  }
+
+  return filter.reduce((acc, key) => {
+    if (key in updates) {
+      acc[key] = updates[key];
+    }
+    return acc;
+  }, {});
+}
+
 /**
  * The "real" state, this instance is kept private by the server.StateManager.
  * It can only be accessed through a SharedState proxy.
@@ -30,8 +49,8 @@ class SharedStatePrivate {
     this._creatorId = null;
   }
 
-  _attachClient(remoteId, client, isOwner = false) {
-    const clientInfos = { client, isOwner };
+  _attachClient(remoteId, client, isOwner, filter) {
+    const clientInfos = { client, isOwner, filter };
     this._attachedClients.set(remoteId, clientInfos);
 
     if (isOwner) {
@@ -61,7 +80,7 @@ class SharedStatePrivate {
       }
 
       if (hookAborted === false) {
-        const filteredUpdates = {};
+        let acknowledgedUpdates = {};
         let hasUpdates = false;
 
         for (let name in updates) {
@@ -76,7 +95,7 @@ class SharedStatePrivate {
           }
 
           if ((filterChange && changed) || !filterChange) {
-            filteredUpdates[name] = newValue;
+            acknowledgedUpdates[name] = newValue;
             hasUpdates = true;
           }
         }
@@ -103,41 +122,54 @@ class SharedStatePrivate {
 
           // propagate RESPONSE to the client that originates the request if not the server
           if (client.id !== -1) {
+            // no need to filter updates on requested, is blocked on client-side
             client.transport.emit(
               `${UPDATE_RESPONSE}-${this.id}-${remoteId}`,
-              reqId, filteredUpdates, context,
+              reqId, acknowledgedUpdates, context,
             );
           }
 
-          // propagate NOTIFICATION to all other attached clients except server
+          // propagate NOTIFICATION to all attached clients except server
           for (let [peerRemoteId, clientInfos] of this._attachedClients) {
             const peer = clientInfos.client;
 
             if (remoteId !== peerRemoteId && peer.id !== -1) {
-              peer.transport.emit(
-                `${UPDATE_NOTIFICATION}-${this.id}-${peerRemoteId}`,
-                filteredUpdates, context,
-              );
+              const filter = clientInfos.filter;
+              const filteredUpdates = filterUpdates(acknowledgedUpdates, filter);
+
+              // propagate only if there something left after applying the filter
+              if (Object.keys(filteredUpdates).length > 0) {
+                peer.transport.emit(
+                  `${UPDATE_NOTIFICATION}-${this.id}-${peerRemoteId}`,
+                  filteredUpdates, context,
+                );
+              }
             }
           }
 
           // propagate RESPONSE to server if it is the requester
           if (client.id === -1) {
+            // no need to filter updates on requested, is blocked on client-side
             client.transport.emit(
               `${UPDATE_RESPONSE}-${this.id}-${remoteId}`,
-              reqId, filteredUpdates, context,
+              reqId, acknowledgedUpdates, context,
             );
           }
 
-          // propagate NOTIFICATION other attached state that belongs to server
+          // propagate NOTIFICATION to other state attached on the server
           for (let [peerRemoteId, clientInfos] of this._attachedClients) {
             const peer = clientInfos.client;
 
             if (remoteId !== peerRemoteId && peer.id === -1) {
-              peer.transport.emit(
-                `${UPDATE_NOTIFICATION}-${this.id}-${peerRemoteId}`,
-                filteredUpdates, context,
-              );
+              const filter = clientInfos.filter;
+              const filteredUpdates = filterUpdates(acknowledgedUpdates, filter);
+
+              if (Object.keys(filteredUpdates).length > 0) {
+                peer.transport.emit(
+                  `${UPDATE_NOTIFICATION}-${this.id}-${peerRemoteId}`,
+                  filteredUpdates, context,
+                );
+              }
             }
           }
         } else {

package/src/common/version.js

@@ -0,0 +1,2 @@
+// [WARNING] This file is generated, do not edit
+export default '4.0.0-alpha.22';

package/src/server/Server.js

@@ -1,3 +1,4 @@
+import EventEmitter from 'node:events';
 import fs from 'node:fs';
 import http from 'node:http';
 import https from 'node:https';
@@ -31,7 +32,7 @@ import {
   CLIENT_HANDSHAKE_ERROR,
   AUDIT_STATE_NAME,
 } from '../common/constants.js';
-
+import version from '../common/version.js';
 
 let _dbNamespaces = new Set();
 
@@ -161,6 +162,7 @@ class Server {
     if (!isPlainObject(config)) {
       throw new Error(`[soundworks:Server] Invalid argument for Server constructor, config should be an object`);
     }
+
     /**
      * @description Given config object merged with the following defaults:
      * @example
@@ -224,6 +226,8 @@ class Server {
       }
     }
 
+    this.version = version;
+
     /**
      * Instance of the express router.
      *
@@ -371,6 +375,11 @@ class Server {
    * await server.start(); // init is called implicitely
    */
   async init() {
+    // ------------------------------------------------------------
+    // INIT STATE MANAGER
+    // ------------------------------------------------------------
+    this.stateManager.init(SERVER_ID, new EventEmitter());
+
     const numClients = {};
     for (let name in this.config.app.clients) {
       numClients[name] = 0;
@@ -902,18 +911,34 @@ Invalid certificate files, please check your:
     });
 
     socket.addListener(CLIENT_HANDSHAKE_REQUEST, async payload => {
-      const { role, registeredPlugins } = payload;
+      const { role, version, registeredPlugins } = payload;
+
 
       if (!roles.includes(role)) {
-        console.error(`[soundworks.Server] A client with invalid type ("${role}") attempted to connect`);
+        console.error(`[soundworks.Server] A client with invalid role ("${role}") attempted to connect`);
 
         socket.send(CLIENT_HANDSHAKE_ERROR, {
           type: 'invalid-client-type',
-          message: `Invalid client type, please check server configuration (valid client types are: ${roles.join(', ')})`,
+          message: `Invalid client role, please check server configuration (valid client roles are: ${roles.join(', ')})`,
         });
         return;
       }
 
+      if (version !== this.version) {
+        console.warn(`
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+WARNING
+
+Version discrepancies between server and "${role}" client:
++ server: ${this.version} | client: ${version}
+
+This might lead to unexpected behavior, you should consider to update your
+dependancies on both your server and clients.
+
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!`);
+      }
+
       try {
         this.pluginManager.checkRegisteredPlugins(registeredPlugins);
       } catch (err) {
@@ -944,7 +969,7 @@ Invalid certificate files, please check your:
       this._onClientConnectCallbacks.forEach(callback => callback(client));
 
       const { id, uuid, token } = client;
-      socket.send(CLIENT_HANDSHAKE_RESPONSE, { id, uuid, token });
+      socket.send(CLIENT_HANDSHAKE_RESPONSE, { id, uuid, token, version: this.version });
     });
   }
 
@@ -1054,6 +1079,12 @@ Invalid certificate files, please check your:
           },
           env: {
             type: config.env.type,
+            // use to configure the socket if the server is running on a different
+            // location than the one the client was served from (cf. #90)
+            useHttps: config.env.useHttps,
+            serverAddress: config.env.serverAddress,
+            port: config.env.port,
+            // other config, to review
             websockets: config.env.websockets,
             subpath: config.env.subpath,
             useMinifiedFile: useMinifiedFile[role],

package/src/server/Socket.js

@@ -122,6 +122,11 @@ class Socket {
       this.ws.send(PING_MESSAGE);
     }, PING_INTERVAL);
 
+    // for testing purpose
+    if (this.sockets._DEBUG_PREVENT_HEARTBEAT === true) {
+      clearInterval(this._heartbeatId);
+    }
+
     // broadcast all "native" events
     [
       'close',

package/src/server/Sockets.js

@@ -32,6 +32,8 @@ class Sockets {
     /** @private */
     this._auditState = null;
 
+    /** @private */
+    this._DEBUG_PREVENT_HEARTBEAT = false;
   }
 
   /**

package/src/server/StateManager.js

@@ -1,5 +1,3 @@
-import EventEmitter from 'node:events';
-
 import { idGenerator, isString, isPlainObject } from '@ircam/sc-utils';
 import clonedeep from 'lodash/cloneDeep.js';
 
@@ -8,7 +6,6 @@ import BatchedTransport from '../common/BatchedTransport.js';
 import ParameterBag from '../common/ParameterBag.js';
 import SharedStatePrivate from '../common/SharedStatePrivate.js';
 import {
-  SERVER_ID,
   CREATE_REQUEST,
   CREATE_RESPONSE,
   CREATE_ERROR,
@@ -314,19 +311,19 @@ const kIsObservableState = Symbol('StateManager::isObservableState');
  */
 class StateManager extends BaseStateManager {
   constructor() {
-    // acts as a client of itself locally
-    const localClientId = SERVER_ID;
-    const localTransport = new EventEmitter();
-
-    super(localClientId, localTransport);
+    super();
 
     this._clientByNodeId = new Map();
     this._sharedStatePrivateById = new Map();
     this._schemas = new Map();
     this._observers = new Set();
     this._hooksBySchemaName = new Map(); // protected
+  }
 
-    this.addClient(localClientId, localTransport);
+  init(id, transport) {
+    super.init(id, transport);
+    // add itself as client of the state manager server
+    this.addClient(id, transport);
   }
 
   [kIsObservableState](state) {
@@ -348,9 +345,12 @@ class StateManager extends BaseStateManager {
    * @private
    */
   addClient(nodeId, transport) {
-    transport = new BatchedTransport(transport);
+    const batchedTransport = new BatchedTransport(transport);
+    const client = {
+      id: nodeId,
+      transport: batchedTransport,
+    };
 
-    const client = { id: nodeId, transport };
     this._clientByNodeId.set(nodeId, client);
 
     // ---------------------------------------------
@@ -368,7 +368,8 @@ class StateManager extends BaseStateManager {
 
             // attach client to the state as owner
             const isOwner = true;
-            state._attachClient(remoteId, client, isOwner);
+            const filter = null;
+            state._attachClient(remoteId, client, isOwner, filter);
 
             this._sharedStatePrivateById.set(stateId, state);
 
@@ -407,7 +408,7 @@ class StateManager extends BaseStateManager {
     // ---------------------------------------------
     client.transport.addListener(
       ATTACH_REQUEST,
-      (reqId, schemaName, stateId = null, requireSchema = true) => {
+      (reqId, schemaName, stateId = null, requireSchema = true, filter = null) => {
         if (this._schemas.has(schemaName)) {
           let state = null;
 
@@ -432,15 +433,29 @@ class StateManager extends BaseStateManager {
             // i.e. same state -> several remote attach on the same node
             const remoteId = generateRemoteId.next().value;
             const isOwner = false;
-            state._attachClient(remoteId, client, isOwner);
-
             const currentValues = state._parameters.getValues();
             const schema = this._schemas.get(schemaName);
             const schemaOption = requireSchema ? schema : null;
 
+            // if filter given, check that all filter entries are valid schema keys
+            // @todo - improve error reportin: report invalid filters
+            if (filter !== null) {
+              const keys = Object.keys(schema);
+              const isValid = filter.reduce((acc, key) => acc && keys.includes(key), true);
+
+              if (!isValid) {
+                const msg = `[stateManager] Cannot attach, invalid filter (${filter.join(', ')}) for schema "${schemaName}"`;
+                console.error(msg);
+
+                return client.transport.emit(ATTACH_ERROR, reqId, msg);
+              }
+            }
+
+            state._attachClient(remoteId, client, isOwner, filter);
+
             client.transport.emit(
               ATTACH_RESPONSE,
-              reqId, state.id, remoteId, schemaName, schemaOption, currentValues,
+              reqId, state.id, remoteId, schemaName, schemaOption, currentValues, filter,
             );
 
           } else {

package/src/server/index.js

@@ -1,3 +1,9 @@
+/**
+ * @license
+ * Copyright (c) 2014-present IRCAM – Centre Pompidou (France, Paris)
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
 /**
  * Server-side part of the *soundworks* framework.
  *