@soundworks/core 3.6.0 → 4.0.0-alpha.0

package/src/client/Context.js

@@ -0,0 +1,225 @@
+import Client from './Client.js';
+import {
+  CONTEXT_ENTER_REQUEST,
+  CONTEXT_ENTER_RESPONSE,
+  CONTEXT_ENTER_ERROR,
+  CONTEXT_EXIT_REQUEST,
+  CONTEXT_EXIT_RESPONSE,
+  CONTEXT_EXIT_ERROR,
+} from '../common/constants.js';
+import {
+  storeRequestPromise,
+  resolveRequest,
+  rejectRequest,
+} from '../common/promise-store.js';
+
+/**
+ * Base class to extend in order to implement a new Context.
+ *
+ * In the `soundworks` paradigm, a client has a "role" (e.g. _player_, _controller_)
+ * see {@link client.Client#role}) and can be in different "contexts" (e.g. different
+ * part of the experience such as sections of a music piece, etc.). This class
+ * provides a simple and unified way to model these reccuring aspects of an application.
+ *
+ * You can also think of a `Context` as a state of a state machine from which a
+ * client can `enter()` or `exit()` (be aware that `soundworks` does not provide
+ * an implementation for the state machine).
+ *
+ * Optionally, a `Context` can also have a server-side counterpart to perform
+ * some logic (e.g. updating some global shared state) when a client enters or exits
+ * the context. In such case, `soundworks` guarantees that the server-side
+ * logic is executed before the `enter()` and `exit()` promises are fulfilled.
+ *
+ * ```
+ * import { Client, Context } from '@soundworks/core/index.js'
+ *
+ * const client = new Client(config);
+ *
+ * class MyContext extends Context {
+ *   async enter() {
+ *     await super.enter();
+ *     console.log(`client ${this.client.id} entered my context`);
+ *   }
+ *
+ *   async exit() {
+ *     await super.exit();
+ *     console.log(`client ${this.client.id} exited my context`);
+ *   }
+ * }
+ * const myContext = new MyContext(client);
+ *
+ * await client.start();
+ * await myContext.enter();
+ *
+ * await new Promise(resolve => setTimeout(resolve, 2000));
+ * await myContext.exit();
+ * ```
+ *
+ * @memberof client
+ */
+class Context {
+  /**
+   * @param {client.Client} client - The soundworks client instance.
+   * @throws Will throw if the first argument is not a soundworks client instance.
+   */
+  constructor(client) {
+    if (!(client instanceof Client)) {
+      throw new Error(`[soundworks:Context] Invalid argument, context "${this.name}" should receive a "soundworks.Client" instance as first argument`);
+    }
+
+    /**
+     * The soundworks client instance.
+     */
+    this.client = client;
+
+    /**
+     * Status of the context, i.e. 'idle', 'inited', 'started', 'errored'
+     */
+    this.status = 'idle';
+
+    this.client.socket.addListener(CONTEXT_ENTER_RESPONSE, (reqId, contextName) => {
+      if (contextName !== this.name) {
+        return;
+      }
+
+      resolveRequest(reqId);
+    });
+
+    this.client.socket.addListener(CONTEXT_ENTER_ERROR, (reqId, contextName, msg) => {
+      if (contextName !== this.name) {
+        return;
+      }
+
+      rejectRequest(reqId, msg);
+    });
+
+    this.client.socket.addListener(CONTEXT_EXIT_RESPONSE, (reqId, contextName) => {
+      if (contextName !== this.name) {
+        return;
+      }
+
+      resolveRequest(reqId);
+    });
+
+    this.client.socket.addListener(CONTEXT_EXIT_ERROR, (reqId, contextName, msg) => {
+      if (contextName !== this.name) {
+        return;
+      }
+
+      rejectRequest(reqId, msg);
+    });
+
+    this.client.contextManager.register(this);
+  }
+
+  /**
+   * Name of the context. Defaults to the class name, override to use a user-defined name.
+   *
+   * @returns {string} - Name of the context.
+   * @example
+   * class MyContext extends Context {
+   *   get name() {
+   *     return 'my-user-defined-context-name';
+   *   }
+   * }
+   */
+  get name() {
+    return this.constructor.name;
+  }
+
+  /**
+   * Start the context. This method is automatically called when `await client.start()`
+   * is called, or lazilly called when entering the context (i.e. `context.enter()`)
+   * if the context has been created after `client.start()`.
+   *
+   * In some situation, you might want to implement this method to handle application
+   * wise behavior regardeless the client enters or exists the context.
+   */
+  async start() {}
+
+  /**
+   * Stop the context. This method is automatically called when `await client.stop()`
+   * is called.
+   *
+   * In some situation, you might want to implement this method to handle application
+   * wise behavior regardeless the client enters or exists the context.
+   */
+  async stop() {}
+
+  /**
+   * Enter the context. Implement this method to define the logic that should be
+   * done (e.g. creating a shared state, etc.) when the context is entered.
+   *
+   * If a server-side part of the context is defined (i.e. a context with the same
+   * {@link client.Context#name}), the corresponding server-side `enter()` method
+   * will be executed before the returned Promise is fulfilled.
+   *
+   * If the context has not been started yet, the `start` method is implicitely executed.
+   *
+   * @returns {Promise} - Promise that resolves when the context is entered.
+   * @example
+   * class MyContext extends Context {
+   *   async enter() {
+   *     await super.enter();
+   *     this.state = await this.client.stateManager.create('my-context-state');
+   *   }
+   *
+   *   async exit() {
+   *     await super.exit();
+   *     await this.state.delete();
+   *   }
+   * }
+   */
+  async enter() {
+    // lazily start the context if registered after `client.start()`
+    if (this.status !== 'started' && this.status !== 'errored') {
+      await this.client.contextManager.get(this.name);
+    }
+
+    // we need the try/catch block to change the promise rejection into proper error
+    try {
+      await new Promise((resolve, reject) => {
+        const reqId = storeRequestPromise(resolve, reject);
+        this.client.socket.send(CONTEXT_ENTER_REQUEST, reqId, this.name);
+      });
+    } catch(err) {
+      throw new Error(err);
+    }
+  }
+
+  /**
+   * Exit the context. Implement this method to define the logic that should be
+   * done (e.g. delete a shared state, etc.) when the context is exited.
+   *
+   * If a server-side part of the context is defined (i.e. a context with the same
+   * {@link client.Context#name}), the corresponding server-side `exit()` method
+   * will be executed before the returned Promise is fulfilled.
+   *
+   * @returns {Promise} - Promise that resolves when the context is exited.
+   * @example
+   * class MyContext extends Context {
+   *   async enter() {
+   *     await super.enter();
+   *     this.state = await this.client.stateManager.create('my-context-state');
+   *   }
+   *
+   *   async exit() {
+   *     await super.exit();
+   *     await this.state.delete();
+   *   }
+   * }
+   */
+  async exit() {
+    // we need the try/catch block to change the promise rejection into proper error
+    try {
+      await new Promise((resolve, reject) => {
+        const reqId = storeRequestPromise(resolve, reject);
+        this.client.socket.send(CONTEXT_EXIT_REQUEST, reqId, this.name);
+      });
+    } catch(err) {
+      throw new Error(err);
+    }
+  }
+}
+
+export default Context;

package/src/client/ContextManager.js

@@ -0,0 +1,111 @@
+/** @private */
+class ContextCollection {
+  constructor() {
+    this.inner = [];
+  }
+
+  add(context) {
+    this.inner.push(context);
+  }
+
+  has(name) {
+    return this.inner.find(c => c.name === name) !== undefined;
+  }
+
+  get(name) {
+    return this.inner.find(c => c.name === name);
+  }
+
+  map(func) {
+    return this.inner.map(func);
+  }
+}
+
+/**
+ * Manage the different contexts and their lifecycle.
+ *
+ * See {@link client.Client#contextManager}
+ *
+ * _WARNING: In most cases, you should not have to manipulate the context manager directly._
+ *
+ * @memberof client
+ * @hideconstructor
+ */
+class ContextManager {
+  constructor() {
+    /** @private */
+    this._contexts = new ContextCollection();
+    /** @private */
+    this._contextStartPromises = new Map();
+  }
+
+  /**
+   * Register the context into the manager. Is called in context constructor.
+   *
+   * @param {client.Context} context - The context to be registered.
+   * @private
+   */
+  register(context) {
+    if (this._contexts.has(context.name)) {
+      throw new Error(`[soundworks:context-manager] Context "${context.name}" already registered`);
+    }
+
+    this._contexts.add(context);
+  }
+
+  /**
+   * Retrieve a started context from its name.
+   *
+   * _WARNING: Most of the time, you should not have to call this method manually._
+   *
+   * @param {client.Context#name} contextName - Name of the context.
+   */
+  async get(contextName) {
+    if (!this._contexts.has(contextName)) {
+      throw new Error(`[soundworks:ContextManager] Can't get context "${contextName}", not registered`);
+    }
+
+    const context = this._contexts.get(contextName);
+
+    if (this._contextStartPromises.has(contextName)) {
+      const startPromise = this._contextStartPromises.get(contextName);
+      await startPromise;
+    } else {
+      context.status = 'inited';
+
+      try {
+        const startPromise = context.start();
+        this._contextStartPromises.set(contextName, startPromise);
+        await startPromise;
+        context.status = 'started';
+      } catch(err) {
+        context.status = 'errored';
+        throw new Error(err);
+      }
+    }
+
+    return context;
+  }
+
+  /**
+   * Start all registered contexts. Called during `client.start()`
+   *
+   * @private
+   */
+  async start() {
+    const promises = this._contexts.map(context => this.get(context.name));
+    await Promise.all(promises);
+  }
+
+  /**
+   * Stop all registered contexts. Called during `client.stop()`
+   *
+   * @private
+   */
+  async stop() {
+    const promises = this._contexts.map(context => context.stop());
+    await Promise.all(promises);
+  }
+}
+
+export default ContextManager;

package/src/client/Plugin.js

@@ -0,0 +1,66 @@
+import BasePlugin from '../common/BasePlugin.js';
+
+/**
+ * Callback executed when the plugin state is updated.
+ *
+ * @callback client.Plugin~onStateChangeCallback
+ * @param {client.Plugin#state} state - Current state of the plugin.
+ */
+
+/**
+ * Delete the registered {@link client.Plugin~onStateChangeCallback}.
+ *
+ * @callback client.Plugin~deleteOnStateChangeCallback
+ */
+
+/**
+ * Base class to extend in order to create new `soundworks` plugins.
+ *
+ * In the `soundworks` paradigm, a plugin is a component that allows to extend
+ * the framework capabilities by encapsulating common and reusable logic in
+ * an application wise perspective. For example, plugins are available to handle
+ * clock synchronization, to deal with the file system, etc. Plugin should always
+ * have both a client-side and a server-side part.
+ *
+ * See [https://soundworks.dev/guide/ecosystem](https://soundworks.dev/guide/ecosystem)
+ * for more informations on the available plugins.
+ *
+ * _Creating new plugins should be considered an advanced usage._
+ *
+ * @memberof client
+ * @extends BasePlugin
+ * @inheritdoc
+ */
+class Plugin extends BasePlugin {
+  /**
+   * @param {client.Client} client - The soundworks client instance.
+   * @param {string} id - User defined id of the plugin as defined in
+   *  {@link client.PluginManager#register}.
+   */
+  constructor(client, id) {
+    super(id);
+
+    /**
+     * Instance of soundworks client.
+     *
+     * @type {client.Client}
+     * @see {@link client.Client}
+     */
+    this.client = client;
+  }
+
+  // @todo
+  // /**
+  //  * Interface method to implement if specific logic should be done when a
+  //  * {@link client.Client} enters the plugin.
+  //  */
+  // async activate() {}
+  //
+  // /**
+  //  * Interface method to implement if specific logic should be done when a
+  //  * {@link client.Client} exists the plugin.
+  //  */
+  // async deactivate() {}
+}
+
+export default Plugin;

package/src/client/PluginManager.js

@@ -0,0 +1,123 @@
+import BasePluginManager from '../common/BasePluginManager.js';
+import Plugin from './Plugin.js';
+import Client from './Client.js';
+
+/**
+ * Callback executed when a plugin internal state is updated.
+ *
+ * @callback client.PluginManager~onStateChangeCallback
+ * @param {object<client.Plugin#id, client.Plugin>} fullState - List of all plugins.
+ * @param {client.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 client.PluginManager~onStateChangeCallback}.
+ *
+ * @callback client.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}
+ * are called for proper initialization.
+ *
+ * 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.
+ *
+ * See {@link client.Client#pluginManager}
+ *
+ * ```
+ * import { Client } from '@soundworks/core/client.js';
+ * import platformPlugin from '@soundworks/plugin-sync/client.js';
+ *
+ * const client = new Client(config);
+ * // register the plugin before `client.start()`
+ * client.pluginManager.register('sync', pluginSync);
+ *
+ * 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);
+ * ```
+ *
+ * @memberof client
+ * @extends BasePluginManager
+ * @inheritdoc
+ * @hideconstructor
+ */
+class PluginManager extends BasePluginManager {
+  /**
+   * @param {client.Client} client - The soundworks client instance.
+   */
+  constructor(client) {
+    if (!(client instanceof Client)) {
+      throw new Error(`[soundworks.PluginManager] Invalid argument, "new PluginManager(client)" should receive an instance of "soundworks.Client as argument"`);
+    }
+
+    super(client);
+  }
+
+  register(id, factory, 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 `client.init()` (or `client.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 {client.Plugin#id} id - Id of the plugin as defined when registered.
+   * @returns {client.Plugin}
+   * @see {@link client.PluginManager#onStateChange}
+   *
+   * @private
+   */
+  async get(id) {
+    if (this.status !== 'started') {
+      throw new Error(`[soundworks.PluginManager] Cannot get plugin before "client.init()"`);
+    }
+
+    return super.getUnsafe(id);
+  }
+
+  // client only methods
+  // ------------------------------------------------------------
+
+  /**
+   * @protected
+   * @ignore
+   */
+  getRegisteredPlugins() {
+    return Array.from(this._registeredPlugins.keys());
+  }
+}
+
+export default PluginManager;

package/src/client/SharedState.js

@@ -0,0 +1,84 @@
+import BaseSharedState from '../common/BaseSharedState.js';
+
+// this file exists only for documentation purposes
+
+/**
+ * @callback client.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 client.SharedState~onUpdateCallback}.
+ *
+ * @callback client.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 client
+ * @extends BaseSharedState
+ * @inheritdoc
+ * @hideconstructor
+ */
+class SharedState extends BaseSharedState {}
+
+export default SharedState;