@soundworks/core 5.2.1 → 5.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soundworks/core",
-  "version": "5.2.1",
+  "version": "5.4.0",
   "description": "Open-source creative coding framework for distributed applications based on Web technologies",
   "collaborators": [
     "Benjamin Matuszewski",

package/src/client/Client.js

@@ -314,6 +314,10 @@ class Client {
    * await client.start();
    */
   async init() {
+    if (this.#status === 'inited') {
+      throw new DOMException(`Cannot execute 'init' twice on Client: Lifecycle methods must be called in following order: init, start, stop`, 'InvalidAccessError');
+    }
+
     if (this.#status !== 'idle') {
       throw new DOMException(`Cannot execute 'init' on Client: Lifecycle methods must be called in following order: init, start, stop`, 'InvalidAccessError');
     }
@@ -391,6 +395,10 @@ class Client {
       await this.init();
     }
 
+    if (this.#status === 'started') {
+      throw new DOMException(`Cannot execute 'start' twice on Client: Lifecycle methods must be called in following order: init, start, stop`, 'InvalidAccessError');
+    }
+
     if (this.#status !== 'inited') {
       throw new DOMException(`Cannot execute 'start' on Client: Lifecycle methods must be called in following order: init, start, stop`, 'InvalidAccessError');
     }
@@ -416,6 +424,10 @@ class Client {
    * await client.stop();
    */
   async stop() {
+    if (this.#status === 'stopped') {
+      throw new DOMException(`Cannot execute 'stop' twice on Client: Lifecycle methods must be called in following order: init, start, stop`, 'InvalidAccessError');
+    }
+
     if (this.#status !== 'started') {
       throw new DOMException(`Cannot execute 'stop' on Client: Lifecycle methods must be called in following order: init, start, stop`, 'InvalidAccessError');
     }

package/src/common/BaseStateManager.js

@@ -230,6 +230,17 @@ class BaseStateManager {
     this.#status = 'inited';
   }
 
+  /**
+   * Validates the given class description.
+   *
+   * @throws Throws if the class description is invalid
+   * @param {*} classDescription
+   * @returns undefined
+   */
+  validateClassDescription(classDescription) {
+    return ParameterBag.validateDescription(classDescription);
+  }
+
   /**
    * Return a class description from a given class name
    *

package/src/common/ParameterBag.js

@@ -12,6 +12,7 @@ export const sharedOptions = {
   metas: {},
   filterChange: true,
   immediate: false,
+  acknowledge: true,
 };
 
 export const types = {

package/src/common/SharedState.js

@@ -214,11 +214,19 @@ class SharedState {
         this.#clearTransport();
 
         for (let callback of this.#onDetachCallbacks) {
-          await callback();
+          try {
+            await callback();
+          } catch (err) {
+            console.log(err.message);
+          }
         }
 
         for (let callback of this.#onDeleteCallbacks) {
-          await callback();
+          try {
+            await callback();
+          } catch (err) {
+            console.log(err.message);
+          }
         }
 
         this.#onDetachCallbacks.clear();
@@ -240,7 +248,11 @@ class SharedState {
         this.#clearTransport();
 
         for (let callback of this.#onDetachCallbacks) {
-          await callback();
+          try {
+            await callback();
+          } catch (err) {
+            console.log(err.message);
+          }
         }
 
         this.#onDetachCallbacks.clear();
@@ -465,31 +477,31 @@ class SharedState {
 
     const newValues = {};
     const oldValues = {};
-    const localParams = {};
-    const sharedParams = {};
+    const locallyResolvedParam = {};
+    const networkPropagatedParams = {};
     let hasLocalParam = false;
-    let hasSharedParam = false;
-    let forwardParams = undefined;
-    let propagateNow = false;
+    let hasRegularSharedParam = false;
+    let hasNonAcknowledgedParams = false;
+    let syncedOnUpdate = false;
 
     for (let name in updates) {
-      // 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
+      // Try to coerce value now, so that eventual errors are triggered early
+      // on the node requesting the update and not only on the server side.
       try {
+        // This also throws if name does not exists
         this.#parameters.coerceValue(name, updates[name]);
       } catch (err) {
         throw new TypeError(`Cannot execute 'set' on SharedState (${this.#className}): ${err.message}`);
       }
 
-      // Check that name is in filter list, if any
+      // Make sure that given name is in filter white list (if any)
       if (this.#filter !== null) {
         if (!this.#filter.includes(name)) {
           throw new DOMException(`Cannot execute 'set' on SharedState (${this.#className}): Parameter '${name}' is not in white list`, 'NotSupportedError');
         }
       }
 
-      // `immediate` option behavior
+      // ### `immediate` modifier behavior
       //
       // If immediate=true
       //  - call listeners if value changed
@@ -501,7 +513,7 @@ class SharedState {
       //  - if the node is initiator of the update (UPDATE_RESPONSE), (re-)check
       //    to prevent execute the listeners twice
 
-      // `local` option behavior
+      // ### `local` modifier behavior
       //
       // - If the `updates` object only contains local variables, we can call the
       // update listeners and return a fulfilled promise immediately
@@ -510,9 +522,19 @@ class SharedState {
       // 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.getDescription(name);
+      // ### `acknowledge` modifier behavior
+      //
+      // Same as immediate, but no feedback from server
 
-      if (immediate || local) {
+      const {
+        local,
+        immediate,
+        filterChange,
+        event,
+        acknowledge,
+      } = this.#parameters.getDescription(name);
+
+      if (immediate || local || acknowledge === false) {
         const oldValue = this.#parameters.get(name);
         const [newValue, changed] = this.#parameters.set(name, updates[name]);
 
@@ -520,46 +542,50 @@ class SharedState {
         if (changed || filterChange === false || event) {
           oldValues[name] = oldValue;
           newValues[name] = newValue;
-          propagateNow = true;
+          syncedOnUpdate = true;
         }
       }
 
-      // define params that must go through network or not
       if (local) {
+        // these don't go to the network
         hasLocalParam = true;
-        // get sanitize value for fulfilling promise
-        localParams[name] = this.#parameters.get(name);
+        locallyResolvedParam[name] = this.#parameters.get(name);
+      } else if (acknowledge === false) {
+        // these go to the network but don't receive an ack
+        // they are both locally forwarded and network propagated then
+        hasNonAcknowledgedParams = true;
+        locallyResolvedParam[name] = this.#parameters.get(name);
+        networkPropagatedParams[name] = updates[name];
       } else {
-        // note that immediate are shared params too
-        hasSharedParam = true;
-        sharedParams[name] = updates[name];
+        // note that immediate params are shared and acknowledged
+        hasRegularSharedParam = true;
+        networkPropagatedParams[name] = updates[name];
       }
     }
 
-    // propagate immediate params if changed
-    if (propagateNow) {
+    // params that trigger a synced onUpdate call: immediate, local, non-acknowledged
+    if (syncedOnUpdate) {
       this.#onUpdateCallbacks.forEach(listener => listener(newValues, oldValues));
     }
 
-    // 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;
-      }
+    // if we only have local params, we can resolve immediately
+    if (hasLocalParam && !hasNonAcknowledgedParams && !hasRegularSharedParam) {
+      return Promise.resolve(locallyResolvedParam);
     }
 
-    // override updates to be shared on network without local params
-    updates = sharedParams;
-
     // go through server-side normal behavior
     const { id: reqId, promise } = this[kSharedStatePromiseStore].createPromise();
-    if (forwardParams) {
-      this[kSharedStatePromiseStore].associateResolveData(reqId, forwardParams);
+    // store local params that should be re-merged w/ regular ones
+    if (Object.keys(locallyResolvedParam).length > 0) {
+      this[kSharedStatePromiseStore].associateResolveData(reqId, locallyResolvedParam);
+    }
+
+    this.#client.transport.emit(`${UPDATE_REQUEST}-${this.#id}-${this.#instanceId}`, reqId, networkPropagatedParams);
+
+    // if we don't have regular shared params, we can resolve now
+    if (!hasRegularSharedParam) {
+      this[kSharedStatePromiseStore].resolve(reqId, {});
     }
-    this.#client.transport.emit(`${UPDATE_REQUEST}-${this.#id}-${this.#instanceId}`, reqId, updates);
 
     return promise;
   }
@@ -746,7 +772,7 @@ class SharedState {
 
       return this.detach();
     } else {
-      throw new DOMException(`Cannot execute 'delete' on SharedState (${this.#className}): SharedState (${this.#id}) is not owned by this node. Use 'SharedState#detach' instead`, 'NotSupportedError');
+      throw new DOMException(`Cannot execute 'delete' on SharedState (${this.#className}): This instance is attached and not owned. Use 'SharedState#detach' instead`, 'NotSupportedError');
     }
   }
 
@@ -814,6 +840,10 @@ class SharedState {
    * @param {Function} callback - Callback to execute when the state is deleted.
    */
   onDelete(callback) {
+    if (!this.#isOwner) {
+      throw new DOMException(`Cannot execute 'onDelete' on SharedState (${this.#className}): This instance is attached and not owned. Use 'SharedState#onDetach' instead`, 'NotSupportedError');
+    }
+
     this.#onDeleteCallbacks.add(callback);
     return () => this.#onDeleteCallbacks.delete(callback);
   }

package/src/common/shared-state-types.js

@@ -52,25 +52,33 @@
  * @property {boolean} [event=false] - Define if the parameter is a volatile, i.e.
  *   its value only exists on an update and is set back to `null` after propagation.
  *   When `true`, `nullable` is automatically set to `true` and `default` to `null`.
+ * @property {boolean} [required=false] - When set to true, the parameter must be
+ *   provided at the creation of the shared state.
  * @property {boolean} [filterChange=true] - When set to `false`, an update will
  *   trigger the propagation of a parameter even when its value didn't change.
- *   This option provides a sort of middle ground between the default behavior
+ *   This modifier provides a sort of middle ground between the default behavior
  *   (e.g. where only changed values are propagated) and the behavior of the `event`
  *   option (which has no state per se). Hence, setting this options to `false` if
  *   `event=true` makes no sens.
  * @property {boolean} [immediate=false] - When set to `true`, an update will
  *   trigger the update listeners immediately on the node that generated the update,
- *   before propagating the change on the network.
- *   This option is useful in cases the network would introduce a noticeable
- *   latency on the client.
+ *   before propagating the change on the network. This modifier is useful in cases
+ *   the network would introduce a noticeable latency on the client.
  *   If for some reason the value is overridden server-side (e.g. in an `updateHook`)
  *   the listeners will be called again when the "real" value is received.
- * @property {boolean} [required=false] - When set to true, the parameter must be
- *   provided in the initialization values when the state is created.
+ *   Setting this modifier to `true` will trigger the `onUpdate` callback synchronously
+ *   according to the `set` call.
  * @property {boolean} [local=false] - When set to true, the parameter is never
  *   propagated on the network (hence it is no longer a shared parameter :). This
  *   is useful to declare some common parameter (e.g. some interface state) that
  *   don't need to be shared but to stay in the shared state API paradigm.
+ *   Setting this modifier to `true` will trigger the `onUpdate` callback synchronously
+ *   according to the `set` call.
+ * @property {boolean} [acknowledge=true] - When set to false, the acknowledgement
+ *   is never sent back to the shared state that initiated an update. This can be
+ *   useful to e.g. stream values to the network, but can lead to invalid state.
+ *   Setting this modifier to `true` will trigger the `onUpdate` callback synchronously
+ *   according to the `set` call.
  * @property {number} [min=-Number.MIN_VALUE] - Minimum value of the parameter. Only applies
  *   for `integer` and `float` types.
  * @property {number} [max=Number.MAX_VALUE] - Maximum value of the parameter. Only applies

package/src/common/version.js

@@ -1,2 +1,2 @@
 // [WARNING] This file is generated, do not edit
-export default '5.2.1';
+export default '5.4.0';

package/src/server/Server.js

@@ -482,6 +482,10 @@ class Server {
    * await server.start(); // init is called implicitly
    */
   async init() {
+    if (this.#status === 'inited') {
+      throw new DOMException(`Cannot execute 'init' twice on Server: Lifecycle methods must be called in following order: init, start, stop`, 'InvalidAccessError');
+    }
+
     if (this.#status !== 'idle') {
       throw new DOMException(`Cannot execute 'init' on Server: Lifecycle methods must be called in following order: init, start, stop`, 'InvalidAccessError');
     }
@@ -547,6 +551,10 @@ class Server {
       await this.init();
     }
 
+    if (this.#status === 'started') {
+      throw new DOMException(`Cannot execute 'start' twice on Server: Lifecycle methods must be called in following order: init, start, stop`, 'InvalidAccessError');
+    }
+
     if (this.#status !== 'inited') {
       throw new DOMException(`Cannot execute 'start' on Server: Lifecycle methods must be called in following order: init, start, stop`, 'InvalidAccessError');
     }
@@ -601,6 +609,10 @@ class Server {
    * await server.stop();
    */
   async stop() {
+    if (this.#status === 'stopped') {
+      throw new DOMException(`Cannot execute 'stop' twice on Server: Lifecycle methods must be called in following order: init, start, stop`, 'InvalidAccessError');
+    }
+
     if (this.#status !== 'started') {
       throw new DOMException(`Cannot execute 'stop' on Server: Lifecycle methods must be called in following order: init, start, stop`, 'InvalidAccessError');
     }

package/src/server/SharedStatePrivate.js

@@ -16,18 +16,18 @@ import {
 } from '../server/ServerStateManager.js';
 
 /**
- * Filter update object according to filter list.
+ * Filter update object according to a given white list.
  * Return identity is filter is null
  * @param {object} updates
- * @param {array|null} filter
+ * @param {array|null} whiteList
  * @private
  */
-function filterUpdates(updates, filter) {
-  if (filter === null) {
+function whiteListFilterUpdates(updates, whiteList) {
+  if (whiteList === null) {
     return updates;
   }
 
-  return filter.reduce((acc, key) => {
+  return whiteList.reduce((acc, key) => {
     if (key in updates) {
       acc[key] = updates[key];
     }
@@ -35,6 +35,29 @@ function filterUpdates(updates, filter) {
   }, {});
 }
 
+/**
+ * Filter update object according to a given black list.
+ * Return identity is filter is null
+ * @param {object} updates
+ * @param {array|null} filter
+ * @private
+ */
+function blackListFilterUpdates(updates, blackList) {
+  if (blackList === null) {
+    return updates;
+  }
+  // create a shallow copy so we can have multiple filters applied on same source
+  const filtered = Object.assign({}, updates);
+
+  blackList.forEach(key => {
+    if (key in updates) {
+      delete filtered[key];
+    }
+  });
+
+  return filtered;
+}
+
 export const kSharedStatePrivateAttachClient = Symbol('soundworks:shared-state-private-attach-client');
 export const kSharedStatePrivateDetachClient = Symbol('soundworks:shared-state-private-detach-client');
 export const kSharedStatePrivateGetValues = Symbol('soundworks:shared-state-private-get-values');
@@ -122,13 +145,13 @@ class SharedStatePrivate {
 
       if (hookAborted === false) {
         let acknowledgedUpdates = {};
-        let hasUpdates = false;
+        let acknowledgeFilter = [];
 
         for (let name in updates) {
           const [newValue, changed] = this.#parameters.set(name, updates[name]);
           // if `filterChange` is set to `false` we don't check if the value
           // has been changed or not, it is always propagated to client states
-          const { event, filterChange } = this.#parameters.getDescription(name);
+          const { event, filterChange, acknowledge } = this.#parameters.getDescription(name);
 
           // if event type reset internal value to null
           if (event) {
@@ -137,11 +160,14 @@ class SharedStatePrivate {
 
           if ((filterChange && changed) || !filterChange) {
             acknowledgedUpdates[name] = newValue;
-            hasUpdates = true;
+
+            if (acknowledge === false) {
+              acknowledgeFilter.push(name);
+            }
           }
         }
 
-        if (hasUpdates) {
+        if (Object.keys(acknowledgedUpdates).length > 0) {
           // Normal case
           //
           // We need to handle cases where:
@@ -161,25 +187,29 @@ class SharedStatePrivate {
           //
           // @note - instanceId correspond to unique remote state id
 
+          // - Apply acknowledge filter on `acknowledgedUpdates`
+          // - We don't need to apply the regular filter on update request, they are blocked client-side
+          const requesterFilteredUpdates = blackListFilterUpdates(acknowledgedUpdates, acknowledgeFilter);
+
           // 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}-${instanceId}`,
-              reqId,
-              acknowledgedUpdates,
-            );
+            // propagate only if there something left after applying the acknowledge filter
+            if (Object.keys(requesterFilteredUpdates).length > 0) {
+              client.transport.emit(
+                `${UPDATE_RESPONSE}-${this.id}-${instanceId}`,
+                reqId,
+                requesterFilteredUpdates,
+              );
+            };
           }
 
-          // propagate NOTIFICATION to all attached clients except server
+          // propagate NOTIFICATION to all peer states except on server-side
           for (let [peerInstanceId, clientInfos] of this.#attachedClients) {
-            const peer = clientInfos.client;
+            const { client: peer, filter } = clientInfos;
 
             if (instanceId !== peerInstanceId && peer.id !== -1) {
-              const filter = clientInfos.filter;
-              const filteredUpdates = filterUpdates(acknowledgedUpdates, filter);
-
-              // propagate only if there something left after applying the filter
+              const filteredUpdates = whiteListFilterUpdates(acknowledgedUpdates, filter);
+              // propagate only if there something left after applying the white list filter
               if (Object.keys(filteredUpdates).length > 0) {
                 peer.transport.emit(
                   `${UPDATE_NOTIFICATION}-${this.id}-${peerInstanceId}`,
@@ -191,22 +221,23 @@ class SharedStatePrivate {
 
           // 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}-${instanceId}`,
-              reqId,
-              acknowledgedUpdates,
-            );
+            // propagate only if there something left after applying the acknowledge filter
+            if (Object.keys(requesterFilteredUpdates).length > 0) {
+              client.transport.emit(
+                `${UPDATE_RESPONSE}-${this.id}-${instanceId}`,
+                reqId,
+                requesterFilteredUpdates,
+              );
+            }
           }
 
-          // propagate NOTIFICATION to other state attached on the server
+          // propagate NOTIFICATION to all peer states on the server-side
           for (let [peerInstanceId, clientInfos] of this.#attachedClients) {
-            const peer = clientInfos.client;
+            const { client: peer, filter } = clientInfos;
 
             if (instanceId !== peerInstanceId && peer.id === -1) {
-              const filter = clientInfos.filter;
-              const filteredUpdates = filterUpdates(acknowledgedUpdates, filter);
-
+              const filteredUpdates = whiteListFilterUpdates(acknowledgedUpdates, filter);
+              // propagate only if there something left after applying the white list filter
               if (Object.keys(filteredUpdates).length > 0) {
                 peer.transport.emit(
                   `${UPDATE_NOTIFICATION}-${this.id}-${peerInstanceId}`,
@@ -216,8 +247,7 @@ class SharedStatePrivate {
             }
           }
         } else {
-          // propagate back to the requester that the update has been aborted
-          // ignore all other attached clients.
+          // propagate back to the requester that the update has been aborted, ignore all peers
           client.transport.emit(`${UPDATE_ABORT}-${this.id}-${instanceId}`, reqId, updates);
         }
       } else {

package/types/common/BaseStateManager.d.ts

@@ -28,6 +28,14 @@ export type stateManagerDeleteObserveCallback = () => any;
  */
 /** @private */
 declare class BaseStateManager {
+    /**
+     * Validates the given class description.
+     *
+     * @throws Throws if the class description is invalid
+     * @param {*} classDescription
+     * @returns undefined
+     */
+    validateClassDescription(classDescription: any): void;
     /**
      * Return a class description from a given class name
      *

package/types/common/ParameterBag.d.ts

@@ -5,6 +5,7 @@ export namespace sharedOptions {
     let metas: {};
     let filterChange: boolean;
     let immediate: boolean;
+    let acknowledge: boolean;
 }
 export namespace types {
     export namespace boolean {

package/types/common/shared-state-types.d.ts

@@ -42,10 +42,15 @@ type SharedStateParameterDescription = {
      * When `true`, `nullable` is automatically set to `true` and `default` to `null`.
      */
     event?: boolean;
+    /**
+     * - When set to true, the parameter must be
+     * provided at the creation of the shared state.
+     */
+    required?: boolean;
     /**
      * - When set to `false`, an update will
      * trigger the propagation of a parameter even when its value didn't change.
-     * This option provides a sort of middle ground between the default behavior
+     * This modifier provides a sort of middle ground between the default behavior
      * (e.g. where only changed values are propagated) and the behavior of the `event`
      * option (which has no state per se). Hence, setting this options to `false` if
      * `event=true` makes no sens.
@@ -54,25 +59,31 @@ type SharedStateParameterDescription = {
     /**
      * - When set to `true`, an update will
      * trigger the update listeners immediately on the node that generated the update,
-     * before propagating the change on the network.
-     * This option is useful in cases the network would introduce a noticeable
-     * latency on the client.
+     * before propagating the change on the network. This modifier is useful in cases
+     * the network would introduce a noticeable latency on the client.
      * If for some reason the value is overridden server-side (e.g. in an `updateHook`)
      * the listeners will be called again when the "real" value is received.
+     * Setting this modifier to `true` will trigger the `onUpdate` callback synchronously
+     * according to the `set` call.
      */
     immediate?: boolean;
-    /**
-     * - When set to true, the parameter must be
-     * provided in the initialization values when the state is created.
-     */
-    required?: boolean;
     /**
      * - When set to true, the parameter is never
      * propagated on the network (hence it is no longer a shared parameter :). This
      * is useful to declare some common parameter (e.g. some interface state) that
      * don't need to be shared but to stay in the shared state API paradigm.
+     * Setting this modifier to `true` will trigger the `onUpdate` callback synchronously
+     * according to the `set` call.
      */
     local?: boolean;
+    /**
+     * - When set to false, the acknowledgement
+     * is never sent back to the shared state that initiated an update. This can be
+     * useful to e.g. stream values to the network, but can lead to invalid state.
+     * Setting this modifier to `true` will trigger the `onUpdate` callback synchronously
+     * according to the `set` call.
+     */
+    acknowledge?: boolean;
     /**
      * - Minimum value of the parameter. Only applies
      * for `integer` and `float` types.

package/types/common/version.d.ts

@@ -1,2 +1,2 @@
-declare const _default: "5.2.1";
+declare const _default: "5.4.0";
 export default _default;