@soundworks/core 4.0.0-alpha.9 → 5.0.0

package/src/common/BaseSharedStateCollection.js

@@ -1,179 +0,0 @@
-/**
- * @private
- */
-class BaseSharedStateCollection {
-  constructor(stateManager, schemaName) {
-    this._stateManager = stateManager;
-    this._schemaName = schemaName;
-    this._states = [];
-    this._onUpdateCallbacks = new Set();
-    this._onAttachCallbacks = new Set();
-    this._onDetachCallbacks = new Set();
-    this._unobserve = null;
-  }
-
-  async _init() {
-    this._unobserve = await this._stateManager.observe(this._schemaName, async (schemaName, stateId, nodeId) => {
-      const state = await this._stateManager.attach(schemaName, stateId);
-
-      this._states.push(state);
-
-      state.onDetach(() => {
-        const index = this._states.indexOf(state);
-        this._states.splice(index, 1);
-
-        this._onDetachCallbacks.forEach(callback => callback(state));
-      });
-
-      state.onUpdate((newValues, oldValues, context) => {
-        Array.from(this._onUpdateCallbacks).forEach(callback => {
-          callback(state, newValues, oldValues, context);
-        });
-      });
-
-      this._onAttachCallbacks.forEach(callback => callback(state));
-    });
-  }
-
-  /**
-   * Size of the collection
-   * @type {number}
-   */
-  get length() {
-    return this._states.length;
-  }
-
-  /**
-   * Detach from the collection, i.e. detach all underlying shared states.
-   * @type {number}
-   */
-  async detach() {
-    this._unobserve();
-
-    const promises = Array.from(this._states).map(state => state.detach());
-    await Promise.all(promises);
-
-    this._onUpdateCallbacks.clear();
-    this._onDetachCallbacks.clear();
-  }
-
-  /**
-   * Return the current values of all the states in the collection.
-   * @return {Object[]}
-   */
-  getValues() {
-    return this._states.map(state => state.getValues());
-  }
-
-  /**
-   * Return the current param value of all the states in the collection.
-   *
-   * @param {String} name - Name of the parameter
-   * @return {any[]}
-   */
-  get(name) {
-    return this._states.map(state => state.get(name));
-  }
-
-  /**
-   * Subscribe to any state update of the collection.
-   *
-   * @param {server.SharedStateCollection~onUpdateCallback|client.SharedStateCollection~onUpdateCallback}
-   *  callback - Callback to execute when an update is applied on a state.
-   * @param {Boolean} [executeListener=false] - Execute the callback immediately
-   *  for all underlying states with current state values. (`oldValues` will be
-   *  set to `{}`, and `context` to `null`)
-   * @returns {Function} - Function that delete the registered listener.
-   */
-  onUpdate(callback, executeListener = false) {
-    this._onUpdateCallbacks.add(callback);
-
-    if (executeListener === true) {
-      this._states.forEach(state => {
-        const currentValues = state.getValues();
-        const oldValues = {};
-        const context = null;
-
-        callback(state, currentValues, oldValues, context);
-      });
-    }
-
-    return () => this._onUpdateCallbacks.delete(callback);
-  }
-
-  /**
-   * Register a function to execute when a state is added to the collection.
-   *
-   * @param {Function} callback - callback to execute  when a state is added to
-   *   the collection.
-   */
-  onAttach(callback) {
-    this._onAttachCallbacks.add(callback);
-  }
-
-  /**
-   * Register a function to execute when a state is removed from the collection.
-   *
-   * @param {Function} callback - callback to execute  when a state is removed
-   *   from the collection.
-   */
-  onDetach(callback) {
-    this._onDetachCallbacks.add(callback);
-  }
-
-  /**
-   * Execute the given function once for each states of the collection (see `Array.forEach`).
-   *
-   * @param {Function} func - A function to execute for each element in the array.
-   *  Its return value is discarded.
-   */
-  forEach(func) {
-    this._states.forEach(func);
-  }
-
-  /**
-   * Creates a new array populated with the results of calling a provided function
-   * on every state of the collection (see `Array.map`).
-   *
-   * @param {Function} func - A function to execute for each element in the array.
-   *  Its return value is added as a single element in the new array.
-   */
-  map(func) {
-    return this._states.map(func);
-  }
-
-  /**
-   * Creates a shallow copy of a portion of the collection, filtered down to just
-   * the estates that pass the test implemented by the provided function (see `Array.filter`).
-   *
-   * @param {Function} func - A function to execute for each element in the array.
-   *  It should return a truthy to keep the element in the resulting array, and a f
-   *  alsy value otherwise.
-   */
-  filter(func) {
-    return this._states.filter(func);
-  }
-
-  /**
-   * Sort the elements of the collection in place (see `Array.sort`).
-   *
-   * @param {Function} func - Function that defines the sort order.
-   */
-  sort(func) {
-    this._states.sort(func);
-  }
-
-  /**
-   * Returns the first element of the collection that satisfies the provided testing
-   * function. If no values satisfy the testing function, undefined is returned.
-   *
-   * @param {Function} func - Function to execute for each element in the array.
-   *  It should return a truthy value to indicate a matching element has been found.
-   * @return {}
-   */
-  find(func) {
-    return this._states.find(func);
-  }
-}
-
-export default BaseSharedStateCollection;

package/src/common/SharedStatePrivate.js

@@ -1,192 +0,0 @@
-import ParameterBag from '../common/ParameterBag.js';
-import {
-  DELETE_REQUEST,
-  DELETE_RESPONSE,
-  DELETE_NOTIFICATION,
-  DETACH_REQUEST,
-  DETACH_RESPONSE,
-  UPDATE_REQUEST,
-  UPDATE_RESPONSE,
-  UPDATE_ABORT,
-  UPDATE_NOTIFICATION,
-} from '../common/constants.js';
-
-/**
- * The "real" state, this instance is kept private by the server.StateManager.
- * It cannot be accessed without a SharedState proxy
- * @private
- */
-class SharedStatePrivate {
-  constructor(id, schemaName, schema, manager, initValues = {}) {
-    this.id = id;
-    this.schemaName = schemaName;
-
-    this._manager = manager;
-    this._parameters = new ParameterBag(schema, initValues);
-    this._attachedClients = new Map(); // other peers interested in watching / controlling the state
-
-    this._creatorRemoteId = null;
-    this._creatorId = null;
-  }
-
-  _attachClient(remoteId, client, isOwner = false) {
-    this._attachedClients.set(remoteId, client);
-
-    if (isOwner) {
-      this._creatorRemoteId = remoteId;
-      this._creatorId = client.id;
-    }
-
-    // attach client listeners
-    client.transport.addListener(`${UPDATE_REQUEST}-${this.id}-${remoteId}`, async (reqId, updates, context) => {
-      // apply registered hooks
-      const hooks = this._manager._hooksBySchemaName.get(this.schemaName);
-      const values = this._parameters.getValues();
-      let hookAborted = false;
-
-      // cf. https://github.com/collective-soundworks/soundworks/issues/45
-      for (let hook of hooks.values()) {
-        const result = await hook(updates, values, context);
-
-        if (result === null) { // explicit abort if hook returns null
-          hookAborted = true;
-          break;
-        } else if (result === undefined) { // implicit continue if hook returns undefined
-          continue;
-        } else { // the hook returned an updates object
-          updates = result;
-        }
-      }
-
-      if (hookAborted === false) {
-        const filteredUpdates = {};
-        let hasUpdates = false;
-
-        for (let name in updates) {
-          // from v3.1.0 - the `filteredUpdates` check is made using 'fast-deep-equal'
-          //    cf. https://github.com/epoberezkin/fast-deep-equal
-          //    therefore unchanged objects are not considered changed
-          //    nor propagated anymore.
-          // until v3.0.4 - we checked the `schema[name].type === 'any'`, to always consider
-          //    objects as dirty, because if the state is attached locally, we
-          //    compare the Object instances instead of their values.
-          //    @note - this should be made more robust but how?
-          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.getSchema(name);
-
-          // if event type reset internal value to null
-          if (event) {
-            this._parameters.set(name, null);
-          }
-
-          if ((filterChange && changed) || !filterChange) {
-            filteredUpdates[name] = newValue;
-            hasUpdates = true;
-          }
-        }
-
-        if (hasUpdates) {
-          // send response to requester
-          // client.transport.emit(`${UPDATE_RESPONSE}-${this.id}-${remoteId}`, reqId, filteredUpdates);
-
-          // @note: we propagate server-side last, because as the server transport
-          // is synchronous it can break ordering if a subscription function makes
-          // itself an update in reaction to an update, therefore network messages
-          // order would be broken,
-
-          // we need to handle cases where:
-          // client state (client.id: 2) sends a request
-          // server attached state (client.id: -1) spot a problem and overrides the value
-          // we want the remote client (id: 2) to receive in the right order:
-          // * 1. the value it requested,
-          // * 2. the value overriden by the server-side attached state (id: -1)
-
-          // this problem could be solved properly with a reducer system:
-          // if (dirty) {
-          //   -> call (async) reducer
-          //   -> get values from reducer
-          //.  -> dispatch to everybody
-          // }
-
-          for (let [peerRemoteId, peer] of this._attachedClients.entries()) {
-            // propagate notification to all other attached clients except server
-            if (remoteId !== peerRemoteId && peer.id !== -1) {
-              peer.transport.emit(`${UPDATE_NOTIFICATION}-${this.id}-${peerRemoteId}`, filteredUpdates, context);
-            }
-          }
-
-          if (client.id !== -1) {
-            client.transport.emit(`${UPDATE_RESPONSE}-${this.id}-${remoteId}`, reqId, filteredUpdates, context);
-          }
-
-          for (let [peerRemoteId, peer] of this._attachedClients.entries()) {
-            // propagate notification to server
-            if (remoteId !== peerRemoteId && peer.id === -1) {
-              peer.transport.emit(`${UPDATE_NOTIFICATION}-${this.id}-${peerRemoteId}`, filteredUpdates, context);
-            }
-          }
-
-          if (client.id === -1) {
-            client.transport.emit(`${UPDATE_RESPONSE}-${this.id}-${remoteId}`, reqId, filteredUpdates, context);
-          }
-        } else {
-          // propagate back to the requester that the update has been aborted
-          // ignore all other attached clients.
-          client.transport.emit(`${UPDATE_ABORT}-${this.id}-${remoteId}`, reqId, updates, context);
-        }
-      } else {
-        // retrieve values from inner state (also handle immediate approriately)
-        const oldValues = {};
-
-        for (let name in updates) {
-          oldValues[name] = this._parameters.get(name);
-        }
-        // aborted by hook (updates have been overriden to {})
-        client.transport.emit(`${UPDATE_ABORT}-${this.id}-${remoteId}`, reqId, oldValues, context);
-      }
-    });
-
-    if (isOwner) {
-      // delete only if creator
-      client.transport.addListener(`${DELETE_REQUEST}-${this.id}-${remoteId}`, (reqId) => {
-        this._manager._serverStatesById.delete(this.id);
-        // --------------------------------------------------------------------
-        // WARNING - MAKE SURE WE DON'T HAVE PROBLEM W/ THAT
-        // --------------------------------------------------------------------
-        // @todo - propagate server-side last, because if a subscription function sends a
-        // message to a client, network messages order are kept coherent
-        // this._subscriptions.forEach(func => func(updated));
-        for (let [remoteId, attached] of this._attachedClients.entries()) {
-          this._detachClient(remoteId, attached);
-
-          if (remoteId === this._creatorRemoteId) {
-            attached.transport.emit(`${DELETE_RESPONSE}-${this.id}-${remoteId}`, reqId);
-          } else {
-            attached.transport.emit(`${DELETE_NOTIFICATION}-${this.id}-${remoteId}`);
-          }
-        }
-      });
-    } else {
-      // detach only if not creator
-      client.transport.addListener(`${DETACH_REQUEST}-${this.id}-${remoteId}`, (reqId) => {
-        this._detachClient(remoteId, client);
-        client.transport.emit(`${DETACH_RESPONSE}-${this.id}-${remoteId}`, reqId);
-      });
-    }
-  }
-
-  _detachClient(remoteId, client) {
-    this._attachedClients.delete(remoteId);
-    // delete listeners
-    client.transport.removeAllListeners(`${UPDATE_REQUEST}-${this.id}-${remoteId}`);
-    client.transport.removeAllListeners(`${DELETE_REQUEST}-${this.id}-${remoteId}`);
-    client.transport.removeAllListeners(`${DETACH_REQUEST}-${this.id}-${remoteId}`);
-  }
-}
-
-export default SharedStatePrivate;
-
-

package/src/common/promise-store.js

@@ -1,25 +0,0 @@
-import { idGenerator } from '@ircam/sc-utils';
-
-const generateRequestId = idGenerator();
-const requestPromises = new Map();
-
-export function storeRequestPromise(resolve, reject) {
-  const reqId = generateRequestId.next().value;
-  requestPromises.set(reqId, { resolve, reject });
-
-  return reqId;
-}
-
-export function resolveRequest(reqId, data) {
-  const { resolve } = requestPromises.get(reqId);
-  requestPromises.delete(reqId);
-
-  resolve(data);
-}
-
-export function rejectRequest(reqId, data) {
-  const { reject } = requestPromises.get(reqId);
-  requestPromises.delete(reqId);
-
-  reject(data);
-}

package/src/server/Client.js

@@ -1,55 +0,0 @@
-import { idGenerator } from '@ircam/sc-utils';
-import { v4 as uuid } from 'uuid';
-
-const generateId = idGenerator();
-
-/**
- * Server-side representation of a `soundworks` client.
- *
- * @memberof server
- * @hideconstructor
- * @see {@link client.Client}
- */
-class Client {
-  /**
-   * @param {String} role - Role of the client
-   * @param {server.Socket} socket - Socket connection with the client
-   */
-  constructor(role, socket) {
-    /**
-     * Client role, as specified in client side config {@link client.Client}.
-     *
-     * @type {String}
-     */
-    this.role = role;
-
-    /**
-     * Session Id (incremented positive number).
-     *
-     * @type {Number}
-     */
-    this.id = generateId.next().value;
-
-    /**
-     * Unique session Id (uuidv4).
-     *
-     * @type {String}
-     */
-    this.uuid = uuid();
-
-    /**
-     * Socket connection with the remote client {@link client.Client}.
-     *
-     * @type {server.Socket}
-     */
-    this.socket = socket;
-
-    /**
-     * Is set in server._onSocketConnection
-     * @private
-     */
-    this.token = null;
-  }
-}
-
-export default Client;

package/src/server/PluginManager.js

@@ -1,170 +0,0 @@
-import BasePluginManager from '../common/BasePluginManager.js';
-import Plugin from './Plugin.js';
-import Server from './Server.js';
-
-/**
- * Callback executed when a plugin internal state is updated.
- *
- * @callback server.PluginManager~onStateChangeCallback
- * @param {object<server.Plugin#id, server.Plugin>} fullState - List of all plugins.
- * @param {server.Plugin|null} initiator - Plugin that initiated the update or `null`
- *  if the change was initiated by the state manager (i.e. when the initialization
- *  of the plugins starts).
- */
-
-/**
- * Delete the registered {@link server.PluginManager~onStateChangeCallback}.
- *
- * @callback server.PluginManager~deleteOnStateChangeCallback
- */
-
-/**
- * The `PluginManager` allows to register and retrieve `soundworks` plugins.
- *
- * Plugins should always be registered both client-side and server-side,
- * and before {@link client.Client#start} or {@link server.Server#start}
- * to be properly initialized.
- *
- * In some sitautions, you might want to register the same plugin factory several times
- * using different ids (e.g. for watching several parts of the file system, etc.).
- *
- * Refer to the plugins' documentation for more precise examples, and the specific API
- * they expose. See [https://soundworks.dev/guide/ecosystem](https://soundworks.dev/guide/ecosystem)
- * for more informations on the available plugins.
- *
- * ```
- * // client-side
- * import { Client } from '@soundworks/core/client.js';
- * import syncPlugin from '@soundworks/plugin-sync/client.js';
- *
- * const client = new Client(config);
- * // register the plugin before `client.start()`
- * client.pluginManager.register('sync', syncPlugin);
- *
- * await client.start();
- *
- * const sync = await client.pluginManager.get('sync');
- *
- * setInterval(() => {
- *   // log the estimated global synced clock alongside the local clock.
- *   console.log(sync.getSyncTime(), sync.getLocalTime());
- * }, 1000);
- * ```
- *
- * ```
- * // server-side
- * import { Server } from '@soundworks/core/server.js';
- * import syncPlugin from '@soundworks/plugin-sync/server.js';
- *
- * const server = new Server(config);
- * // register the plugin before `server.start()`
- * server.pluginManager.register('sync', syncPlugin);
- *
- * await server.start();
- *
- * const sync = await server.pluginManager.get('sync');
- *
- * setInterval(() => {
- *   // log the estimated global synced clock alongside the local clock.
- *   console.log(sync.getSyncTime(), sync.getLocalTime());
- * }, 1000);
- * ```
- *
- * @memberof server
- * @extends BasePluginManager
- * @inheritdoc
- * @hideconstructor
- */
-class PluginManager extends BasePluginManager {
-  constructor(server) {
-    if (!(server instanceof Server)) {
-      throw new Error(`[soundworks.PluginManager] Invalid argument, "new PluginManager(server)" should receive an instance of "soundworks.Server" as argument`);
-    }
-
-    super(server);
-  }
-
-  register(id, factory = null, options = {}, deps = []) {
-    const ctor = factory(Plugin);
-
-    if (!(ctor.prototype instanceof Plugin)) {
-      throw new Error(`[soundworks.PluginManager] Invalid argument, "pluginManager.register" second argument should be a factory function returning a class extending the "Plugin" base class`);
-    }
-
-    super.register(id, ctor, options, deps);
-  }
-
-  /**
-   * Retrieve an fully started instance of a registered plugin.
-   *
-   * Be aware that the `get` method resolves only when the plugin is fully 'started',
-   * which is what we want 99.99% of the time. As such, and to prevent the application
-   * to be stuck in some kind of Promise dead lock, this method will throw if
-   * used before `server.init()` (or `server.start()`).
-   *
-   * To handle the remaining 0.01% cases and access plugin instances during their
-   * initialization (e.g. to display initialization screen, etc.), you should rely
-   * on the `onStateChange` method.
-   *
-   * _Note: the async API is designed to enable the dynamic creation of plugins
-   * (hopefully without brealing changes) in a future release._
-   *
-   * @param {server.Plugin#id} id - Id of the plugin as defined when registered.
-   * @returns {server.Plugin}
-   * @see {@link server.PluginManager#onStateChange}
-   *
-   * @private
-   */
-  async get(id) {
-    if (this.status !== 'started') {
-      throw new Error(`[soundworks.PluginManager] Cannot get plugin before "server.init()"`);
-    }
-
-    return super.unsafeGet(id);
-  }
-
-  // server only methods
-
-  /** private */
-  checkRegisteredPlugins(registeredPlugins) {
-    let missingPlugins = [];
-
-    for (let id of registeredPlugins) {
-      if (!this._instances.has(id)) {
-        missingPlugins.push(id);
-      }
-    }
-
-    if (missingPlugins.length > 0) {
-      throw new Error(`Invalid plugin list, the following plugins registered client-side: [${missingPlugins.join(', ')}] have not been registered server-side. Registered server-side plugins are: [${Array.from(this._instances.keys()).join(', ')}].`);
-    }
-  }
-
-  /** @private */
-  async addClient(client, registeredPlugins = []) {
-    let promises = [];
-
-    for (let pluginName of registeredPlugins) {
-      const plugin = await this.get(pluginName);
-      const promise = plugin.addClient(client);
-      promises.push(promise);
-    }
-
-    await Promise.all(promises);
-  }
-
-  /** @private */
-  async removeClient(client) {
-    let promises = [];
-
-    for (let plugin of this._instances.values()) {
-      if (plugin.clients.has(client)) {
-        promises.push(plugin.removeClient(client));
-      }
-    }
-
-    await Promise.all(promises);
-  }
-}
-
-export default PluginManager;