@soundworks/core 3.6.0 → 4.0.0-alpha.0

package/src/server/Context.js

@@ -0,0 +1,99 @@
+import Client from './Client.js';
+import Server from './Server.js';
+
+/**
+ * Base class to extend in order to create the server-side counterpart of
+ * a {@link client.Context}. If not defined, a default context will be created
+ * and used by the server.
+ *
+ * @memberof server
+ */
+class Context {
+  constructor(server, roles = []) {
+    if (!(server instanceof Server)) {
+      throw new Error(`[soundworks:Context] Invalid argument, context "${this.constructor.name}" should receive a "soundworks.Server" instance as first argument`);
+    }
+
+    if (roles === null) {
+      throw new Error('Invalid client types');
+    }
+
+    /**
+     * soundworks server
+     * @type {server.Server}
+     */
+    this.server = server;
+
+    /**
+     * List of clients that are currently in this context
+     * @type {Client[]}
+     */
+    this.clients = new Set();
+
+    /**
+     * Status of the context ('idle', 'inited', 'started' or 'errored')
+     * @type {String}
+     */
+    this.status = 'idle';
+
+    /**
+     * List of client role associated with this context.
+     */
+    roles = Array.isArray(roles) ? roles : [roles];
+    this.roles = new Set(roles);
+
+    // register in context manager
+    this.server.contextManager.register(this);
+  }
+
+  /**
+   * Name of the context, default to the class name.
+   * Override the `get name()` getter to use a user-defined context name.
+   */
+  get name() {
+    return this.constructor.name;
+  }
+
+  /**
+   * Method automatically called when the server starts, or lazilly called if
+   * the context is created after `server.start()`
+   *
+   * _WARNING: this method should never be called manually._
+   */
+  async start() {}
+
+  /**
+   * Method automatically called when the server stops.
+   *
+   * _WARNING: this method should never be called manually._
+   */
+  async stop() {}
+
+  /**
+   * Method automatically called when the client enters the context.
+   *
+   * _WARNING: this method should never be called manually._
+   */
+  async enter(client) {
+    if (!(client instanceof Client)) {
+      throw new Error(`[soundworks.Context] Invalid argument, ${this.name} context ".enter()" method should receive a server-side "soundworks.Client" instance argument`);
+    }
+
+    this.clients.add(client);
+  }
+
+  /**
+   * Method automatically called when the client exits the context.
+   *
+   * _WARNING: this method should never be called manually._
+   */
+  async exit(client) {
+    if (!(client instanceof Client)) {
+      throw new Error(`[soundworks.Context] Invalid argument, ${this.name}.exit() should receive a server-side "soundworks.Client" instance argument`);
+    }
+
+    this.clients.delete(client);
+  }
+}
+
+export default Context;

package/src/server/ContextManager.js

@@ -0,0 +1,266 @@
+import Context from './Context.js';
+import {
+  CONTEXT_ENTER_REQUEST,
+  CONTEXT_ENTER_RESPONSE,
+  CONTEXT_ENTER_ERROR,
+  CONTEXT_EXIT_REQUEST,
+  CONTEXT_EXIT_RESPONSE,
+  CONTEXT_EXIT_ERROR,
+} from '../common/constants.js';
+
+/**
+ * Create a dummy server side context if a proper server-side context has not
+ * been declared and registered, one DefaultContext is created per unknown
+ * contextName and associated to all known client types.
+ *
+ * @private
+ */
+function createNamedContextClass(contextName) {
+  return class DefaultContext extends Context {
+    get name() {
+      return contextName;
+    }
+  };
+}
+
+/** @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);
+  }
+
+  filter(func) {
+    return this.inner.filter(func);
+  }
+}
+
+/**
+ * Manage the different server-side contexts and their lifecycle. The `ContextManager`
+ * is automatically instantiated by the {@link server.Server}.
+ *
+ * _WARNING: Most of the time, you should not have to manipulate the context manager directly._
+ *
+ * @memberof server
+ */
+class ContextManager {
+  /**
+   * @param {server.Server} server - Instance of the soundworks server.
+   */
+  constructor(server) {
+    /** @private */
+    this.server = server;
+    /** @private */
+    this._contexts = new ContextCollection();
+    /** @private */
+    this._contextStartPromises = new Map();
+  }
+
+  /**
+   * Register a context in the manager.
+   * This method is called in the {@link server.Context} constructor
+   *
+   * @param {server.Context} context - Context instance to register.
+   *
+   * @private
+   */
+  register(context) {
+    // we must await the contructor initialization end to check the name and throw
+    if (this._contexts.has(context.name)) {
+      throw new Error(`[soundworks:ContextManager] Context "${context.name}" already registered`);
+    }
+
+    this._contexts.add(context);
+  }
+
+  /**
+   * Retrieve a started context from its name.
+   *
+   * @see {server.Context#name}
+   * @param {String} contextName - Name of the context.
+   *
+   * @private
+   */
+  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;
+  }
+
+  /**
+   * Called when a client connects to the server (websocket handshake)
+   *
+   * @param {server.Client} client
+   *
+   * @private
+   */
+  addClient(client) {
+    client.socket.addListener(CONTEXT_ENTER_REQUEST, async (reqId, contextName) => {
+      // if no context found, create a DefaultContext on the fly
+      if (!this._contexts.has(contextName)) {
+        // create default context for all client types
+        const ctor = createNamedContextClass(contextName);
+        const roles = Object.keys(this.server.config.app.clients);
+        // this will automatically register the context in the context manager
+        new ctor(this.server, roles);
+      }
+
+      // we ensure context is started, even lazilly after server.start()
+      let context;
+      try {
+        context = await this.get(contextName);
+      } catch(err) {
+        client.socket.send(
+          CONTEXT_ENTER_ERROR,
+          reqId,
+          contextName,
+          err.message,
+        );
+        return;
+      }
+
+      // don't do this check with default context to allow several parallel
+      // contexts client side with no server-side part.
+      if (context && context.clients.has(client)) {
+        client.socket.send(
+          CONTEXT_ENTER_ERROR,
+          reqId,
+          contextName,
+          `[soundworks:ContextManager] Client already in context (if only one context is created .enter() has been called automatically)`,
+        );
+        return;
+      }
+
+      // use default context if no server-side context part defined
+      if (context === undefined) {
+        context = this.defaultContext;
+      }
+
+      if (!context.roles.has(client.role)) {
+        client.socket.send(
+          CONTEXT_ENTER_ERROR,
+          reqId,
+          contextName,
+          `[soundworks:ContextManager] Clients with role "${client.role}" are not declared as possible consumers of context "${contextName}"`,
+        );
+        return;
+      }
+
+      try {
+        await context.enter(client);
+
+        client.socket.send(CONTEXT_ENTER_RESPONSE, reqId, contextName);
+      } catch(err) {
+        client.socket.send(CONTEXT_ENTER_ERROR, reqId, contextName, err.message);
+      }
+    });
+
+    client.socket.addListener(CONTEXT_EXIT_REQUEST, async (reqId, contextName) => {
+      if (!this._contexts.has(contextName)) {
+        client.socket.send(
+          CONTEXT_EXIT_ERROR,
+          reqId,
+          contextName,
+          `[soundworks:ContextManager] Cannot exit(), context ${contextName} does not exists`,
+        );
+        return;
+      }
+
+      let context = await this.get(contextName);
+
+      if (context.clients.has(client)) {
+        try {
+          await context.exit(client);
+          client.socket.send(CONTEXT_EXIT_RESPONSE, reqId, contextName);
+        } catch(err) {
+          client.socket.send(CONTEXT_EXIT_ERROR, reqId, contextName, err.message);
+        }
+      } else {
+        client.socket.send(
+          CONTEXT_EXIT_ERROR,
+          reqId,
+          contextName,
+          `[soundworks:ContextManager] Client with role "${client.role}" is not in context "${contextName}"`,
+        );
+      }
+    });
+  }
+
+  /**
+   * Called when a client connects to the server (websocket 'close' event)
+   *
+   * @param {server.Client} client
+   *
+   * @private
+   */
+  async removeClient(client) {
+    client.socket.removeAllListeners(CONTEXT_ENTER_REQUEST);
+    client.socket.removeAllListeners(CONTEXT_EXIT_REQUEST);
+
+    // exit from all contexts
+    const promises = this._contexts
+      .filter(context => context.clients.has(client))
+      .map(context => context.exit(client));
+
+    await Promise.all(promises);
+  }
+
+  /**
+   * Start all contexts registered before `await server.start()`.
+   * Called on {@link server.Server#start}
+   *
+   * @private
+   */
+  async start() {
+    const promises = this._contexts.map(context => this.get(context.name));
+    await Promise.all(promises);
+  }
+
+  /**
+   * Stop all contexts. Called on {@link server.Server#stop}
+   *
+   * @private
+   */
+  async stop() {
+    const promises = this._contexts.map(context => context.stop());
+    await Promise.all(promises);
+  }
+}
+
+export default ContextManager;

package/src/server/Plugin.js

@@ -0,0 +1,77 @@
+import BasePlugin from '../common/BasePlugin.js';
+
+/**
+ * Callback executed when the plugin state is updated.
+ *
+ * @callback server.Plugin~onStateChangeCallback
+ * @param {server.Plugin#state} state - Current state of the plugin.
+ */
+
+/**
+ * Delete the registered {@link server.Plugin~onStateChangeCallback}.
+ *
+ * @callback server.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 server
+ * @extends BasePlugin
+ * @inheritdoc
+ */
+class Plugin extends BasePlugin {
+  /**
+   * @param {server.Server} server - The soundworks server instance.
+   * @param {string} id - User defined id of the plugin as defined in
+   *  {@link server.PluginManager#register}.
+   */
+  constructor(server, id) {
+    super(id);
+
+    /**
+     * Instance of soundworks server.
+     * @type {server.Server}
+     * @see {@link server.Server}
+     */
+    this.server = server;
+
+    /** @private */
+    this.clients = new Set();
+  }
+
+  /**
+   * Method called when a client (which registered the client-side plugin),
+   * connects to the application. Override this method if you need to perform
+   * some particular logic (e.g. creating a shared state) for each clients.
+   *
+   * @param {server.Client} client
+   */
+  async addClient(client) {
+    this.clients.add(client);
+  }
+
+  /**
+   * Method called when a client (which registered the client-side plugin),
+   * disconnects from the application. Override this method if you need to perform
+   * some particular logic (e.g. creating a shared state) for each clients.
+   *
+   * @param {server.Client} client
+   */
+  async removeClient(client) {
+    this.clients.delete(client);
+  }
+}
+
+export default Plugin;

package/src/server/PluginManager.js

@@ -0,0 +1,150 @@
+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}
+ * 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.
+ *
+ * ```
+ * import { Server } from '@soundworks/core/server.js';
+ * import platformPlugin from '@soundworks/plugin-sync/server.js';
+ *
+ * const server = new Server(config);
+ * // register the plugin before `server.start()`
+ * server.pluginManager.register('sync', pluginSync);
+ *
+ * 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.getUnsafe(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;