@soundworks/core 4.0.0-alpha.7 → 5.0.0

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;

package/src/server/SharedState.js

@@ -1,85 +0,0 @@
-import BaseSharedState from '../common/BaseSharedState.js';
-
-// this file exists only for documentation purposes
-
-/**
- * @callback server.SharedState~onUpdateCallback
- * @param {Object} newValues - Key / value pairs of the updates that have been
- *  applied to the state.
- * @param {Object} oldValues - Key / value pairs of the updated params before
- *  the updates has been applied to the state.
- * @param {Mixed} [context=null] - Optionnal context object that has been passed
- *  with the values updates in the `set` call.
- */
-
-/**
- * Delete the registered {@link server.SharedState~onUpdateCallback}.
- *
- * @callback server.SharedState~deleteOnUpdateCallback
- */
-
-/**
- * The `SharedState` is one of the most important and versatile abstraction provided
- * by `soundworks`. It represents a set of parameters that are synchronized accross
- * every nodes of the application (clients and server) that declared some interest
- * to the shared state.
- *
- * A `SharedState` is created according to a "schema" (in the sense of a database
- * schema) that must be declared and registered server-side. Any number of `SharedState`s
- * can be created from a single schema.
- *
- * A shared state can be created both by the clients or by the server (in which case
- * it is generally considered as a global state of the application). Similarly any
- * node of the application (clients or server) can declare interest and "attach" to
- * a state created by another node. All node attached to a state can modify its values
- * and/or react to the modifications applied by other nodes.
- *
- * Tutorial: {@link https://soundworks.dev/guide/state-manager.html}
- *
- * ```
- * // server-side
- * import { Server } from '@soundworks/server/index.js';
- *
- * const server = new Server(config);
- * // declare and register the schema of a shared state.
- * server.stateManager.registerSchema('some-global-state', {
- *   myRandom: {
- *     type: 'float',
- *     default: 0,
- *   }
- * });
- *
- * await server.start();
- *
- * // create a global state server-side
- * const globalState = await server.stateManager.create('some-global-state');
- * // listen and react to the changes made by the clients
- * globalState.onUpdate(updates => console.log(updates));
- * ```
- *
- * ```
- * // client-side
- * import { Client } from '@soundworks/client.index.js';
- *
- * const client = new Client(config);
- * await client.start();
- *
- * // attach to the global state created by the server
- * const globalState = await client.stateManager.attach('some-global-state');
- *
- * // update the value of a `myRandom` parameter every seconds
- * setInterval(() => {
- *   globalState.set({ myRandom: Math.random() });
- * }, 1000);
- * ``
- *
- * @memberof server
- * @extends BaseSharedState
- * @inheritdoc
- * @hideconstructor
- * @see {server.StateManager}
- */
-class SharedState extends BaseSharedState {}
-
-export default SharedState;
-

package/src/server/SharedStateCollection.js

@@ -1,36 +0,0 @@
-import BaseSharedStateCollection from '../common/BaseSharedStateCollection.js';
-
-// this file exists only for documentation purposesSharedStateCollection.js
-
-/**
- * @callback server.SharedStateCollection~onUpdateCallback
- * @param {server.SharedState} state - State that triggered the update.
- * @param {Object} newValues - Key / value pairs of the updates that have been
- *  applied to the state.
- * @param {Object} oldValues - Key / value pairs of the updated params before
- *  the updates has been applied to the state.
- * @param {Mixed} [context=null] - Optionnal context object that has been passed
- *  with the values updates in the `set` call.
- */
-
-/**
- * The `SharedStateCollection` interface represent a collection of all states
- * created from a given schema name on the network, at the execption of the ones
- * created by the current node.
- *
- * ```
- * const collection = await server.stateManager.getCollection('my-schema');
- * const allValues = collection.getValues();
- * collection.onUpdate((state, newValues, oldValues, context) => {
- *   // do something
- * });
- * ```
- * @memberof server
- * @extends BaseSharedStateCollection
- * @inheritdoc
- * @hideconstructor
- */
-class SharedStateCollection extends BaseSharedStateCollection {}
-
-export default SharedStateCollection;
-