@soundworks/core 4.0.0-alpha.1 → 4.0.0-alpha.11

package/src/server/Context.js

@@ -2,44 +2,116 @@ 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
+ * Base class to extend in order to implment the optionnal server-side counterpart
+ * of a {@link client.Context}. If not defined, a default context will be created
  * and used by the server.
  *
+ * 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.). The
+ * {@link client.Context} and optionnal {@link serverContext} abstractions provide
+ * a simple and unified way to model these reccuring aspects of an application.
+ *
+ * If a `server.Context` is recognized as the server-side counterpart of a
+ * {@link client.Context}, based on their respective `name` (see {@link client.Context#name}
+ * and {@link server.Context#name}), `soundworks` will ensure the logic defined
+ * by the server-side Context will be executed at the beginning of the
+ * {@link client.Client#enter} and {@link client.Client#exit} methods. The example
+ * show how soundwords handles (and guarantees) the order of the `enter()` steps
+ * between the client-side and the server-side parts of the context. The same goes
+ * for the `exit()` method.
+ *
+ * ```
+ * // client-side
+ * import { Context } from '@soundworks/core/client.js';
+ *
+ * class MyContext extends Context {
+ *   async enter() {
+ *     // 1. client side context enter() starts
+ *     //    server-side logic is triggered first
+ *     await super.enter();
+ *     // 4. server-side context enter() is fully done
+ *     // some async job can be done here
+ *     await new Promise(resolve => setTimeout(resolve, 1000));
+ *     // 5. client-side context enter() ends
+ *   }
+ * }
+ *
+ * // Instanciate the context (assuming the `client.role` is 'test')
+ * const myContext = new MyContext(client);
+ *
+ * // At some point in the application, the client enters the context trigerring
+ * // the steps 1 to 5 described in the client-side and server-side `enter()`
+ * // implementations. Note that the server-side `enter()` is never called manually.
+ * await myContext.enter();
+ * ```
+ *
+ * ```
+ * // server-side
+ * import { Context } from '@soundworks/core/server.js';
+ *
+ * class MyContext extends Context {
+ *   async enter(client) {
+ *     // 2. server-side context enter() starts
+ *     await super.enter(client);
+ *     // some async job can be done here
+ *     await new Promise(resolve => setTimeout(resolve, 1000));
+ *     // 3. server-side context enter() ends
+ *   }
+ * }
+ *
+ * // Instantiate the context
+ * const myContext = new Context(server);
+ * ```
+ *
  * @memberof server
  */
 class Context {
+  /**
+   * @param {client.Client} client - The soundworks client instance.
+   * @param {string|string[]} [roles=[]] - Optionnal list of client roles that can
+   *  use this context. In large applications, this may be usefull to guarantee
+   *  that a context can be consumed only by specific client roles, throwing an
+   *  error if any other client role tries to use it. If empty, no access policy
+   *  will be used.
+   * @throws Will throw if the first argument is not a soundworks server instance.
+   */
   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}
+     * @readonly
      */
     this.server = server;
 
     /**
      * List of clients that are currently in this context
-     * @type {Client[]}
+     * @type {server.Client[]}
      */
     this.clients = new Set();
 
     /**
      * Status of the context ('idle', 'inited', 'started' or 'errored')
-     * @type {String}
+     * @type {string}
+     * @readonly
      */
     this.status = 'idle';
 
     /**
-     * List of client role associated with this context.
+     * List of client roles that can use this context.
+     * @type {string[]}
+     * @readonly
      */
     roles = Array.isArray(roles) ? roles : [roles];
+
+    if (roles.length === 0) {
+      roles = Object.keys(server.config.app.clients);
+    }
+
     this.roles = new Set(roles);
 
     // register in context manager
@@ -47,32 +119,87 @@ class Context {
   }
 
   /**
-   * Name of the context, default to the class name.
-   * Override the `get name()` getter to use a user-defined context name.
+   * Optionnal user-defined name of the context (defaults to the class name).
+   *
+   * The context manager will match the client-side and server-side contexts based
+   * on this name. If the {@link server.ContextManager} don't find a corresponding
+   * user-defined context with the same name, it will use a default (noop) context.
+   *
+   * @readonly
+   * @type {string}
+   * @example
+   * // server-side and client-side contexts are matched based on their respective `name`
+   * class MyContext extends Context {
+   *   get name() {
+   *     return 'my-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()`
+   * Start the context. This method is lazilly called when a client enters the
+   * context for the first time (cf. ${server.Context#enter}). If you know some
+   * some heavy and/or potentially long job has to be done  when starting the context
+   * (e.g. connect to a database, parsing a long file) it may be a good practice
+   * to call it explicitely.
    *
-   * _WARNING: this method should never be called manually._
+   * This method should be implemented to perform operations that are valid for the
+   * whole lifetime of the context, regardless a client enters or exits the context.
+   *
+   * @example
+   * import { Context } from '@soundworks/core/server.js';
+   *
+   * class MyContext extends Context {
+   *   async start() {
+   *     await super.start();
+   *     await this.doSomeLongJob();
+   *   }
+   * }
+   *
+   * // Instantiate the context
+   * const myContext = new Context(server, ['test']);
+   * // manually start the context to perform the long operation before the first
+   * // client enters the context
+   * await myContext.start();
+   * ```
    */
   async start() {}
 
   /**
-   * Method automatically called when the server stops.
+   * Stop the context. The method that is automatically called when the server
+   * stops. It should be used to cleanup context wise operations made in `start()`
+   * (e.g. disconnect from a database, release a file handle).
    *
    * _WARNING: this method should never be called manually._
    */
   async stop() {}
 
   /**
-   * Method automatically called when the client enters the context.
+   * Enter the context. Implement this method to define the logic that should be
+   * done (e.g. creating a shared state, etc.) when a client enters the context.
+   *
+   * If the context has not been started yet, the `start` method is implicitely executed.
    *
    * _WARNING: this method should never be called manually._
+   *
+   * @param {server.Client} client - Server-side representation of the client
+   *  that enters the context.
+   * @returns {Promise} - Promise that resolves when the context is entered.
+   * @example
+   * class MyContext extends Context {
+   *   async enter(client) {
+   *     await super.enter(client);
+   *     registerTheClientSomewhere(client);
+   *   }
+   *
+   *   async exit(client) {
+   *     await super.exit(client);
+   *     unregisterTheClientSomewhere(client);
+   *   }
+   * }
    */
   async enter(client) {
     if (!(client instanceof Client)) {
@@ -83,9 +210,26 @@ class Context {
   }
 
   /**
-   * Method automatically called when the client exits the context.
+   * Exit the context. Implement this method to define the logic that should be
+   * done (e.g. delete a shared state, etc.) when a client exits the context.
    *
-   * _WARNING: this method should never be called manually._
+   * * _WARNING: this method should never be called manually._
+   *
+   * @param {server.Client} client - Server-side representation of the client
+   *  that exits the context.
+   * @returns {Promise} - Promise that resolves when the context is exited.
+   * @example
+   * class MyContext extends Context {
+   *   async enter(client) {
+   *     await super.enter(client);
+   *     this.state = await this.client.stateManager.create('my-context-state');
+   *   }
+   *
+   *   async exit(client) {
+   *     await super.exit(client);
+   *     await this.state.delete();
+   *   }
+   * }
    */
   async exit(client) {
     if (!(client instanceof Client)) {

package/src/server/ContextManager.js

@@ -57,6 +57,7 @@ class ContextCollection {
  * _WARNING: Most of the time, you should not have to manipulate the context manager directly._
  *
  * @memberof server
+ * @hideconstructor
  */
 class ContextManager {
   /**
@@ -91,10 +92,9 @@ class ContextManager {
   /**
    * Retrieve a started context from its name.
    *
-   * @see {server.Context#name}
-   * @param {String} contextName - Name of the context.
+   * _WARNING: Most of the time, you should not have to call this method manually._
    *
-   * @private
+   * @param {server.Context#name} contextName - Name of the context.
    */
   async get(contextName) {
     if (!this._contexts.has(contextName)) {
@@ -114,7 +114,7 @@ class ContextManager {
         this._contextStartPromises.set(contextName, startPromise);
         await startPromise;
         context.status = 'started';
-      } catch(err) {
+      } catch (err) {
         context.status = 'errored';
         throw new Error(err);
       }
@@ -136,16 +136,15 @@ class ContextManager {
       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);
+        new ctor(this.server);
       }
 
       // we ensure context is started, even lazilly after server.start()
       let context;
       try {
         context = await this.get(contextName);
-      } catch(err) {
+      } catch (err) {
         client.socket.send(
           CONTEXT_ENTER_ERROR,
           reqId,
@@ -186,7 +185,7 @@ class ContextManager {
         await context.enter(client);
 
         client.socket.send(CONTEXT_ENTER_RESPONSE, reqId, contextName);
-      } catch(err) {
+      } catch (err) {
         client.socket.send(CONTEXT_ENTER_ERROR, reqId, contextName, err.message);
       }
     });
@@ -208,7 +207,7 @@ class ContextManager {
         try {
           await context.exit(client);
           client.socket.send(CONTEXT_EXIT_RESPONSE, reqId, contextName);
-        } catch(err) {
+        } catch (err) {
           client.socket.send(CONTEXT_EXIT_ERROR, reqId, contextName, err.message);
         }
       } else {

package/src/server/Plugin.js

@@ -14,7 +14,8 @@ import BasePlugin from '../common/BasePlugin.js';
  */
 
 /**
- * Base class to extend in order to create new `soundworks` plugins.
+ * Base class to extend in order to create the server-side counterpart of a
+ * `soundworks` plugin.
  *
  * In the `soundworks` paradigm, a plugin is a component that allows to extend
  * the framework capabilities by encapsulating common and reusable logic in

package/src/server/PluginManager.js

@@ -23,7 +23,7 @@ import Server from './Server.js';
  *
  * 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.
+ * 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.).
@@ -33,12 +33,32 @@ import Server from './Server.js';
  * 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 platformPlugin from '@soundworks/plugin-sync/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', pluginSync);
+ * server.pluginManager.register('sync', syncPlugin);
  *
  * await server.start();
  *
@@ -58,7 +78,7 @@ import Server from './Server.js';
 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"`);
+      throw new Error(`[soundworks.PluginManager] Invalid argument, "new PluginManager(server)" should receive an instance of "soundworks.Server" as argument`);
     }
 
     super(server);
@@ -86,8 +106,8 @@ class PluginManager extends BasePluginManager {
    * 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._
+   * _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}
@@ -100,7 +120,7 @@ class PluginManager extends BasePluginManager {
       throw new Error(`[soundworks.PluginManager] Cannot get plugin before "server.init()"`);
     }
 
-    return super.getUnsafe(id);
+    return super.unsafeGet(id);
   }
 
   // server only methods