@soundworks/core 4.0.0-alpha.9 → 5.0.0

package/src/server/ServerClient.js

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

package/src/server/{Context.js → ServerContext.js}

@@ -1,31 +1,38 @@
-import Client from './Client.js';
+import ServerClient from './ServerClient.js';
 import Server from './Server.js';
 
+import {
+  kServerContextManagerRegister,
+} from './ServerContextManager.js';
+
+export const kServerContextStatus = Symbol('soundworks:server-context-status');
+
 /**
- * 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
+ * Base class to extend in order to implement the optional server-side counterpart
+ * of a {@link ClientContext}. 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
+ * see {@link 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.
+ * {@link ClientContext} and optional {@link ServerContext} abstractions provide
+ * a simple and unified way to model these recurring 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.
+ * If a `ServerContext` is recognized as the server-side counterpart of a
+ * {@link ClientContext}, based on their respective `name` (see {@link ClientContext#name}
+ * and {@link ServerContext#name}), `soundworks` will ensure the logic defined
+ * by the ServerContext will be executed at the beginning of the
+ * {@link ClientContext#enter} and {@link ClientContext#exit} methods.
  *
- * ```
+ * The example above shows how the order of  the `enter()` steps between the client-side
+ * and the server-side parts of a `context` is handled and guaranteed. The same goes for
+ * the `exit()` method.
+ *
+ * ```js
  * // client-side
- * import { Context } from '@soundworks/core/client.js';
+ * import { ClientContext } from '@soundworks/core/client.js';
  *
- * class MyContext extends Context {
+ * class MyContext extends ClientContext {
  *   async enter() {
  *     // 1. client side context enter() starts
  *     //    server-side logic is triggered first
@@ -37,20 +44,20 @@ import Server from './Server.js';
  *   }
  * }
  *
- * // Instanciate the context (assuming the `client.role` is 'test')
+ * // Instantiate 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
+ * // At some point in the application, the client enters the context triggering
  * // 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();
  * ```
  *
- * ```
+ * ```js
  * // server-side
- * import { Context } from '@soundworks/core/server.js';
+ * import { ServerContext } from '@soundworks/core/server.js';
  *
- * class MyContext extends Context {
+ * class MyContext extends ServerContext {
  *   async enter(client) {
  *     // 2. server-side context enter() starts
  *     await super.enter(client);
@@ -61,16 +68,18 @@ import Server from './Server.js';
  * }
  *
  * // Instantiate the context
- * const myContext = new Context(server);
+ * const myContext = new MyContext(server);
  * ```
- *
- * @memberof server
  */
-class Context {
+class ServerContext {
+  #server = null;
+  #clients = new Set();
+  #roles = null;
+
   /**
-   * @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
+   * @param {Server} server - The soundworks server instance.
+   * @param {string|string[]} [roles=[]] - Optional list of client roles that can
+   *  use this context. In large applications, this may be useful 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.
@@ -78,55 +87,65 @@ 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`);
+      throw new TypeError(`Cannot construct '${this.constructor.name}': argument 1 must be an instance of Server`);
     }
 
-    /**
-     * soundworks server
-     * @type {server.Server}
-     * @readonly
-     */
-    this.server = server;
-
-    /**
-     * List of clients that are currently in this context
-     * @type {server.Client[]}
-     */
-    this.clients = new Set();
-
-    /**
-     * Status of the context ('idle', 'inited', 'started' or 'errored')
-     * @type {string}
-     * @readonly
-     */
-    this.status = 'idle';
-
-    /**
-     * 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);
+    this.#server = server;
+    this.#roles = new Set(roles);
 
+    /** @private */
+    this[kServerContextStatus] = 'idle';
     // register in context manager
-    this.server.contextManager.register(this);
+    this.#server.contextManager[kServerContextManagerRegister](this);
+  }
+
+  /**
+   * The soundworks server instance.
+   *
+   * @type {Server}
+   */
+  get server() {
+    return this.#server;
   }
 
   /**
-   * Optionnal user-defined name of the context (defaults to the class name).
+   * List of clients that are currently in this context.
+   *
+   * @type {Set<ServerClient>}
+   */
+  get clients() {
+    return this.#clients;
+  }
+
+  /**
+   * List of client roles that can use this context. No access policy if empty.
+   *
+   * @type {Set<string>}
+   */
+  get roles() {
+    return this.#roles;
+  }
+
+  /**
+   * Status of the context ('idle', 'inited', 'started' or 'errored')
+   *
+   * @type {string}
+   */
+  get status() {
+    return this[kServerContextStatus];
+  }
+
+  /**
+   * Optional 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
+   * on this name. If the {@link ServerContextManager} 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 {
@@ -140,11 +159,11 @@ class Context {
   }
 
   /**
-   * 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
+   * Start the context. This method is lazily called when a client enters the
+   * context for the first time (cf. ${ServerContext#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.
+   * to call it explicitly.
    *
    * 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.
@@ -181,11 +200,11 @@ class 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.
+   * If the context has not been started yet, the `start` method is implicitly executed.
    *
    * _WARNING: this method should never be called manually._
    *
-   * @param {server.Client} client - Server-side representation of the client
+   * @param {ServerClient} client - Server-side representation of the client
    *  that enters the context.
    * @returns {Promise} - Promise that resolves when the context is entered.
    * @example
@@ -202,11 +221,11 @@ class Context {
    * }
    */
   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`);
+    if (!(client instanceof ServerClient)) {
+      throw new TypeError(`Cannot execute 'enter' on ${this.constructor.name}: argument 1 must be an instance of ServerClient`);
     }
 
-    this.clients.add(client);
+    this.#clients.add(client);
   }
 
   /**
@@ -215,7 +234,7 @@ class Context {
    *
    * * _WARNING: this method should never be called manually._
    *
-   * @param {server.Client} client - Server-side representation of the client
+   * @param {ServerClient} client - Server-side representation of the client
    *  that exits the context.
    * @returns {Promise} - Promise that resolves when the context is exited.
    * @example
@@ -232,12 +251,12 @@ class Context {
    * }
    */
   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`);
+    if (!(client instanceof ServerClient)) {
+      throw new TypeError(`Cannot execute 'exit' on ${this.constructor.name}: argument 1 must be an instance of ServerClient`);
     }
 
-    this.clients.delete(client);
+    this.#clients.delete(client);
   }
 }
 
-export default Context;
+export default ServerContext;

package/src/server/{ContextManager.js → ServerContextManager.js}

@@ -1,4 +1,7 @@
-import Context from './Context.js';
+import Server from './Server.js';
+import ServerContext, {
+  kServerContextStatus,
+} from './ServerContext.js';
 import {
   CONTEXT_ENTER_REQUEST,
   CONTEXT_ENTER_RESPONSE,
@@ -8,15 +11,22 @@ import {
   CONTEXT_EXIT_ERROR,
 } from '../common/constants.js';
 
+export const kServerContextManagerStart = Symbol('soundworks:server-context-manager-start');
+export const kServerContextManagerStop = Symbol('soundworks:server-context-manager-stop');
+export const kServerContextManagerAddClient = Symbol('soundworks:server-context-manager-add-client');
+export const kServerContextManagerRemoveClient = Symbol('soundworks:server-context-manager-remove-client');
+export const kServerContextManagerRegister = Symbol('soundworks:server-context-manager-register');
+// for testing purposes
+export const kServerContextManagerContexts = Symbol('soundworks:server-context-manager-contexts');
+
 /**
  * Create a dummy server side context if a proper server-side context has not
- * been declared and registered, one DefaultContext is created per unknown
+ * been declared and registered. Ane DefaultContext is created per unknown
  * contextName and associated to all known client types.
- *
  * @private
  */
 function createNamedContextClass(contextName) {
-  return class DefaultContext extends Context {
+  return class DefaultContext extends ServerContext {
     get name() {
       return contextName;
     }
@@ -25,122 +35,118 @@ function createNamedContextClass(contextName) {
 
 /** @private */
 class ContextCollection {
-  constructor() {
-    this.inner = [];
+  #inner = [];
+
+  // for testing purposes
+  get length() {
+    return this.#inner.length;
   }
 
   add(context) {
-    this.inner.push(context);
+    this.#inner.push(context);
   }
 
   has(name) {
-    return this.inner.find(c => c.name === name) !== undefined;
+    return this.#inner.find(c => c.name === name) !== undefined;
   }
 
   get(name) {
-    return this.inner.find(c => c.name === name);
+    return this.#inner.find(c => c.name === name);
   }
 
   map(func) {
-    return this.inner.map(func);
+    return this.#inner.map(func);
   }
 
   filter(func) {
-    return this.inner.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}.
+ * Manage the different server-side contexts and their lifecycle.
+ *
+ * The `ServerContextManager` is automatically instantiated by the {@link Server}.
  *
  * _WARNING: Most of the time, you should not have to manipulate the context manager directly._
  *
- * @memberof server
- * @hideconstructor
+ * @template T
  */
-class ContextManager {
+class ServerContextManager {
+  #server = null;
+
+  #contextStartPromises = new Map();
+
   /**
-   * @param {server.Server} server - Instance of the soundworks server.
+   * @param {Server} server - Instance of the soundworks server.
+   * @hideconstructor
    */
   constructor(server) {
+    if (!(server instanceof Server)) {
+      throw new TypeError(`Cannot construct 'ServerContextManager': argument 1 must be an instance of Server`);
+    }
+
+    this.#server = server;
     /** @private */
-    this.server = server;
-    /** @private */
-    this._contexts = new ContextCollection();
-    /** @private */
-    this._contextStartPromises = new Map();
+    this[kServerContextManagerContexts] = new ContextCollection();
   }
 
   /**
    * Register a context in the manager.
-   * This method is called in the {@link server.Context} constructor
+   * This method is called in the {@link ServerContext} constructor
    *
-   * @param {server.Context} context - Context instance to register.
+   * @param {ServerContext} 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`);
+  [kServerContextManagerRegister](context) {
+    // we must await the constructor initialization end to check the name and throw
+    if (this[kServerContextManagerContexts].has(context.name)) {
+      throw new DOMException(`Cannot register '${context.name}': a Context with same name has already been registered`, 'NotSupportedError');
     }
 
-    this._contexts.add(context);
+    this[kServerContextManagerContexts].add(context);
   }
 
   /**
-   * Retrieve a started context from its name.
-   *
-   * _WARNING: Most of the time, you should not have to call this method manually._
+   * Start all contexts registered before `await server.start()`.
+   * Called on {@link Server#start}
    *
-   * @param {server.Context#name} 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);
-      }
-    }
+  async [kServerContextManagerStart]() {
+    const promises = this[kServerContextManagerContexts].map(context => this.get(context.name));
+    await Promise.all(promises);
+  }
 
-    return context;
+  /**
+   * Stop all contexts. Called on {@link Server#stop}
+   *
+   * @private
+   */
+  async [kServerContextManagerStop]() {
+    const promises = this[kServerContextManagerContexts].map(context => context.stop());
+    await Promise.all(promises);
   }
 
   /**
    * Called when a client connects to the server (websocket handshake)
    *
-   * @param {server.Client} client
+   * @param {ServerClient} client
    *
    * @private
    */
-  addClient(client) {
+  [kServerContextManagerAddClient](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)) {
+      if (!this[kServerContextManagerContexts].has(contextName)) {
         // create default context for all client types
         const ctor = createNamedContextClass(contextName);
         // this will automatically register the context in the context manager
-        new ctor(this.server);
+        new ctor(this.#server);
       }
 
-      // we ensure context is started, even lazilly after server.start()
+      // we ensure context is started, even lazily after server.start()
       let context;
       try {
         context = await this.get(contextName);
@@ -161,7 +167,7 @@ class ContextManager {
           CONTEXT_ENTER_ERROR,
           reqId,
           contextName,
-          `[soundworks:ContextManager] Client already in context (if only one context is created .enter() has been called automatically)`,
+          `Client already in context: if only one context is created 'enter' is called automatically)`,
         );
         return;
       }
@@ -171,12 +177,12 @@ class ContextManager {
         context = this.defaultContext;
       }
 
-      if (!context.roles.has(client.role)) {
+      if (context.roles.size > 0 && !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}"`,
+          `Clients with role "${client.role}" are not declared as possible consumers of "${contextName}"`,
         );
         return;
       }
@@ -191,12 +197,12 @@ class ContextManager {
     });
 
     client.socket.addListener(CONTEXT_EXIT_REQUEST, async (reqId, contextName) => {
-      if (!this._contexts.has(contextName)) {
+      if (!this[kServerContextManagerContexts].has(contextName)) {
         client.socket.send(
           CONTEXT_EXIT_ERROR,
           reqId,
           contextName,
-          `[soundworks:ContextManager] Cannot exit(), context ${contextName} does not exists`,
+          `Context ${contextName} does not exists`,
         );
         return;
       }
@@ -215,7 +221,7 @@ class ContextManager {
           CONTEXT_EXIT_ERROR,
           reqId,
           contextName,
-          `[soundworks:ContextManager] Client with role "${client.role}" is not in context "${contextName}"`,
+          `Client with role "${client.role}" is not entered in context "${contextName}"`,
         );
       }
     });
@@ -224,16 +230,16 @@ class ContextManager {
   /**
    * Called when a client connects to the server (websocket 'close' event)
    *
-   * @param {server.Client} client
+   * @param {ServerClient} client
    *
    * @private
    */
-  async removeClient(client) {
+  async [kServerContextManagerRemoveClient](client) {
     client.socket.removeAllListeners(CONTEXT_ENTER_REQUEST);
     client.socket.removeAllListeners(CONTEXT_EXIT_REQUEST);
 
     // exit from all contexts
-    const promises = this._contexts
+    const promises = this[kServerContextManagerContexts]
       .filter(context => context.clients.has(client))
       .map(context => context.exit(client));
 
@@ -241,25 +247,39 @@ class ContextManager {
   }
 
   /**
-   * Start all contexts registered before `await server.start()`.
-   * Called on {@link server.Server#start}
+   * Retrieve a started context from its name.
    *
-   * @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}
+   * _WARNING: Most of the time, you should not have to call this method manually._
    *
-   * @private
+   * @param {string} contextName - Name of the context.
+   * @return {Promise<T<ServerContext>>}
    */
-  async stop() {
-    const promises = this._contexts.map(context => context.stop());
-    await Promise.all(promises);
+  async get(contextName) {
+    if (!this[kServerContextManagerContexts].has(contextName)) {
+      throw new ReferenceError(`Cannot execute 'get' on ServerContextManager: Context '${contextName}' is not defined`);
+    }
+
+    const context = this[kServerContextManagerContexts].get(contextName);
+
+    if (this.#contextStartPromises.has(contextName)) {
+      const startPromise = this.#contextStartPromises.get(contextName);
+      await startPromise;
+    } else {
+      context[kServerContextStatus] = 'inited';
+
+      try {
+        const startPromise = context.start();
+        this.#contextStartPromises.set(contextName, startPromise);
+        await startPromise;
+        context[kServerContextStatus] = 'started';
+      } catch (err) {
+        context[kServerContextStatus] = 'errored';
+        throw new Error(err);
+      }
+    }
+
+    return context;
   }
 }
 
-export default ContextManager;
+export default ServerContextManager;