@soundworks/core 4.0.0-alpha.27 → 4.0.0-alpha.29

package/src/server/audit-network-latency.worker.js

@@ -4,6 +4,7 @@
 // Should move back to regular esm module once Max has fixed its loader
 export default `
 const { parentPort } = require('node:worker_threads');
+const { hrtime } =  require('node:process');
 
 let stack = [];
 let averageLatencyWindow = 5;
@@ -13,12 +14,14 @@ let intervalId = null;
 let meanLatency = 0;
 
 // workaround that sc-utils is pure emascript module
-let getTime;
-let inited = new Promise(async (resolve) => {
-  module = await import('@ircam/sc-utils');
-  getTime = module.getTime;
-  resolve(true);
-});
+// 2024/09/06 - Just copy getTime implementation so that we don't even need the node_modules
+const start = hrtime.bigint();
+
+function getTime() {
+  const now = hrtime.bigint();
+  const delta = now - start;
+  return Number(delta) * 1e-9;
+}
 
 parentPort.on('message', async msg => {
   switch (msg.type) {
@@ -26,7 +29,6 @@ parentPort.on('message', async msg => {
       averageLatencyWindow = msg.value.averageLatencyWindow;
       averageLatencyPeriod = msg.value.averageLatencyPeriod;
 
-      await inited;
       // launch compute in its own loop so that the number of computation is
       // decoupled from the number of connected clients
       clearInterval(intervalId);

package/src/server/audit-schema.js

@@ -17,7 +17,7 @@ export default {
   },
 
   /**
-   * Average latency in seconds computed from ping/pong.
+   * Average latency in seconds computed from ping/pong informations.
    */
   averageNetworkLatency: {
     type: 'float',

package/src/server/crypto.js

@@ -21,6 +21,7 @@ const encryptionIV = crypto
   .substring(0, 16);
 
 
+/** @private */
 export function encryptData(obj) {
   const data = JSON.stringify(obj);
   const cipher = crypto.createCipheriv(encryptionMethod, key, encryptionIV);
@@ -28,6 +29,7 @@ export function encryptData(obj) {
   return Buffer.from(cipher.update(data, 'utf8', 'hex') + cipher.final('hex')).toString('base64');
 }
 
+/** @private */
 export function decryptData(encryptedData) {
   const buff = Buffer.from(encryptedData, 'base64');
   const decipher = crypto.createDecipheriv(encryptionMethod, key, encryptionIV);

package/src/server/index.js

@@ -4,28 +4,25 @@
  * SPDX-License-Identifier: BSD-3-Clause
  */
 
+// this must be defined here so that we can import it into the application
 /**
- * Server-side part of the *soundworks* framework.
+ * Configuration object for the server.
  *
- * ```
- * import '@soundworks/helpers/polyfills.js';
- * import { Server } from '@soundworks/core/server.js';
- * import { loadConfig } from '../utils/load-config.js';
- *
- * // - General documentation: https://soundworks.dev/
- * // - API documentation:     https://soundworks.dev/api
- * // - Issue Tracker:         https://github.com/collective-soundworks/soundworks/issues
- * // - Wizard & Tools:        `npx soundworks`
- *
- * const config = loadConfig(process.env.ENV, import.meta.url);
- *
- * const server = new Server(config);
- * server.setDefaultTemplateConfig();
- *
- * await server.start();
- * ```
- *
- * @namespace server
+ * @typedef ServerConfig
+ * @type {object}
+ * @property {object} [app] - Application configuration object.
+ * @property {object} app.clients - Definition of the application clients.
+ * @property {string} [app.name=''] - Name of the application.
+ * @property {string} [app.author=''] - Name of the author.
+ * @property {object} [env] - Environment configuration object.
+ * @property {boolean} env.useHttps - Define is the server run in http or in https.
+ * @property {string} env.serverAddress - Domain name or IP of the server.
+ *  Mandatory when node clients are declared
+ * @property {number} env.port - Port on which the server is listening.
+ * @property {obj} [env.httpsInfos=null] - Path to cert files ( cert, key } for https.
+ *  If not given and useHttps is true self certifified certificates will be created.
+ * @property {string} [env.subpath=''] - If running behind a proxy, path to the application.
  */
+
 export { default as Server } from './Server.js';
-export { default as Context } from './Context.js';
+export { default as ServerContext } from './ServerContext.js';

package/types/client/Client.d.ts

@@ -1,147 +1,123 @@
+export const kClientVersionTest: unique symbol;
+export const kClientOnStatusChangeCallbacks: unique symbol;
 export default Client;
-/**
- * Configuration object for a client running in a browser runtime.
- */
-export type ClientConfig = any;
-/**
- * Configuration object for a client running in a browser runtime.
- *
- * @typedef ClientConfig
- * @memberof client
- * @type {object}
- * @property {string} role - Role of the client in the application (e.g. 'player', 'controller').
- * @property {object} [app] - Application configration object.
- * @property {string} [app.name=''] - Name of the application.
- * @property {string} [app.author=''] - Name of the author.
- * @property {object} [env] - Environment configration object.
- * @property {boolean} env.useHttps - Define if the websocket should use secure connection.
- * @property {boolean} [env.serverAddress=''] - Address the socket server. Mandatory for
- *  node clients. For browser clients, use `window.location.domain` as fallback if empty.
- * @property {boolean} env.port - Port of the socket server.
- * @property {string} [env.websockets={}] - Configuration options for websockets.
- * @property {string} [env.subpath=''] - If running behind a proxy, path to the application.
- */
 /**
  * The `Client` class is the main entry point for the client-side of a soundworks
  * application.
  *
- * A `Client` instance allows to access soundworks components such as {@link client.StateManager},
- * {@link client.PluginManager},{@link client.Socket} or {@link client.ContextManager}.
- * Its is also responsible for handling the initialization lifecycles of the different
- * soundworks components.
+ * A `soundworks` client can run seamlessly in a browser or in a Node.js runtime.
+ *
+ * It provides an access to the different soundworks components such as the {@link ClientStateManager},
+ * {@link ClientPluginManager}, {@link ClientSocket} and the {@link ClientContextManager}.
  *
  * ```
  * import { Client } from '@soundworks/core/client.js';
- * // create a new soundworks `Client` instance
- * const client = new Client({ role: 'player' });
- * // init and start the client
+ * // create a `Client` instance
+ * const client = new Client({
+ *   role: 'player',
+ *   env: {
+ *     useHttps: false,
+ *     serverAddress: 'localhost',
+ *     port: 8000,
+ *   },
+ * });
+ * // start the client
  * await client.start();
  * ```
- *
- * @memberof client
  */
 declare class Client {
     /**
-     * @param {client.ClientConfig} config - Configuration of the soundworks client.
+     * @param {ClientConfig} config - Configuration of the soundworks client.
      * @throws Will throw if the given config object is invalid.
      */
-    constructor(config: client.ClientConfig);
+    constructor(config: ClientConfig);
     /**
-     * package version
-     * @type string
-     * @readonly
+     * Package version.
+     *
+     * @type {string}
      */
-    readonly version: string;
+    get version(): string;
     /**
      * Role of the client in the application.
      *
      * @type {string}
      */
-    role: string;
+    get role(): string;
     /**
      * Configuration object.
      *
-     * @type {client.ClientConfig}
+     * @type {ClientConfig}
      */
-    config: client.ClientConfig;
+    get config(): ClientConfig;
     /**
-     * Session id of the client (incremeted positive number), generated and
-     * retrieved by the server during `client.init`. The counter is reset when
-     * the server restarts.
+     * Session id of the client.
+     *
+     * Incremeted positive integer generated and retrieved by the server during
+     * `client.init`. The counter is reset when the server restarts.
      *
      * @type {number}
      */
-    id: number;
+    get id(): number;
     /**
-     * Unique session uuid of the client (uuidv4), generated and retrieved by
-     * the server during {@link client.Client#init}.
+     * Unique session uuid of the client (uuidv4).
      *
+     * Generated and retrieved by the server during {@link Client#init}.
      * @type {string}
      */
-    uuid: string;
+    get uuid(): string;
     /**
-     * Instance of the {@link client.Socket} class that handle websockets communications with
-     * the server.
+     * Runtime platform on which the client is executed, i.e. 'browser' or 'node'.
      *
-     * @see {@link client.Socket}
-     * @type {client.Socket}
+     * @type {string}
      */
-    socket: client.Socket;
+    get target(): string;
     /**
-     * Runtime platform on which the client is executed, i.e. 'browser' or 'node'.
+     * Instance of the {@link client.Socket} class.
      *
-     * @type {string}
+     * @see {@link ClientSocket}
+     * @type {ClientSocket}
      */
-    target: string;
+    get socket(): ClientSocket;
     /**
-     * Instance of the {@link client.ContextManager} class.
+     * Instance of the {@link ClientContextManager} class.
      *
      * The context manager can be safely used after `client.init()` has been fulfilled.
      *
-     * @see {@link client.ContextManager}
-     * @type {client.ContextManager}
+     * @see {@link ClientContextManager}
+     * @type {ClientContextManager}
      */
-    contextManager: client.ContextManager;
+    get contextManager(): ClientContextManager;
     /**
-     * Instance of the {@link client.PluginManager} class.
+     * Instance of the {@link ClientPluginManager} class.
      *
      * The context manager can be safely used after `client.init()` has been fulfilled.
      *
-     * @see {@link client.PluginManager}
-     * @type {client.PluginManager}
+     * @see {@link ClientPluginManager}
+     * @type {ClientPluginManager}
      */
-    pluginManager: client.PluginManager;
+    get pluginManager(): ClientPluginManager;
     /**
-     * Instance of the {@link client.StateManager} class.
+     * Instance of the {@link ClientStateManager} class.
      *
      * The context manager can be safely used after `client.init()` has been fulfilled.
      *
-     * @see {@link client.StateManager}
-     * @type {client.StateManager}
+     * @see {@link ClientStateManager}
+     * @type {ClientStateManager}
      */
-    stateManager: client.StateManager;
+    get stateManager(): ClientStateManager;
     /**
-     * Status of the client, 'idle', 'inited', 'started' or 'errored'.
+     * Status of the client.
      *
-     * @type {string}
-     */
-    status: string;
-    /**
-     * Token of the client if connected through HTTP authentication.
-     * @private
+     * @type {'idle'|'inited'|'started'|'errored'}
      */
-    private token;
-    /** @private */
-    private _onStatusChangeCallbacks;
-    /** @private */
-    private _auditState;
+    get status(): "idle" | "inited" | "started" | "errored";
     /**
      * The `init` method is part of the initialization lifecycle of the `soundworks`
-     * client. Most of the time, the `init` method will be implicitly called by the
-     * {@link client.Client#start} method.
+     * client. Most of the time, this method will be implicitly executed by the
+     * {@link Client#start} method.
      *
      * In some situations you might want to call this method manually, in such cases
-     * the method should be called before the {@link client.Client#start} method.
+     * the method should be called before the {@link Client#start} method.
      *
      * What it does:
      * - connect the sockets to be server
@@ -149,8 +125,8 @@ declare class Client {
      * - launch the state manager
      * - initialize all registered plugin
      *
-     * After `await client.init()` is fulfilled, the {@link client.Client#stateManager},
-     * the {@link client.Client#pluginManager} and the {@link client.Client#socket}
+     * After `await client.init()` is fulfilled, the {@link Client#stateManager},
+     * the {@link Client#pluginManager} and the {@link Client#socket}
      * can be safely used.
      *
      * @example
@@ -164,11 +140,11 @@ declare class Client {
     init(): Promise<void>;
     /**
      * The `start` method is part of the initialization lifecycle of the `soundworks`
-     * client. The `start` method will implicitly call the {@link client.Client#init}
-     * method if it has not been called manually.
+     * client. This method will implicitly execute {@link Client#init} method if it
+     * has not been called manually.
      *
      * What it does:
-     * - implicitly call {@link client.Client#init} if not done manually
+     * - implicitly call {@link Client#init} if not done manually
      * - start all created contexts. For that to happen, you will have to call `client.init`
      * manually and instantiate the contexts between `client.init()` and `client.start()`
      *
@@ -199,29 +175,32 @@ declare class Client {
     /**
      * Attach and retrieve the global audit state of the application.
      *
-     * The audit state is a {@link client.SharedState} instance that keeps track of
+     * The audit state is a {@link SharedState} instance that keeps track of
      * global informations about the application such as, the number of connected
      * clients, network latency estimation, etc. It is usefull for controller client
      * roles to give the user an overview about the state of the application.
      *
      * The audit state is lazily attached to the client only if this method is called.
      *
-     * @returns {Promise<client.SharedState>}
+     * @returns {Promise<SharedState>}
      * @throws Will throw if called before `client.init()`
-     * @see {@link client.SharedState}
+     * @see {@link SharedState}
      * @example
      * const auditState = await client.getAuditState();
      * auditState.onUpdate(() => console.log(auditState.getValues()), true);
      */
-    getAuditState(): Promise<client.SharedState>;
+    getAuditState(): Promise<SharedState>;
     /**
      * Listen for the status change ('inited', 'started', 'stopped') of the client.
      *
      * @param {Function} callback - Listener to the status change.
-     * @returns {Function} Delete the listener.
+     * @returns {Function} Function that delete the listener when executed.
      */
     onStatusChange(callback: Function): Function;
-    /** @private */
-    private _dispatchStatus;
+    [kClientOnStatusChangeCallbacks]: Set<any>;
+    #private;
 }
-//# sourceMappingURL=Client.d.ts.map
+import ClientSocket from './ClientSocket.js';
+import ClientContextManager from './ClientContextManager.js';
+import ClientPluginManager from './ClientPluginManager.js';
+import ClientStateManager from './ClientStateManager.js';

package/types/client/{Context.d.ts → ClientContext.d.ts}

@@ -1,9 +1,10 @@
-export default Context;
+export const kClientContextStatus: unique symbol;
+export default ClientContext;
 /**
  * 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
+ * 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.). This class
  * provides a simple and unified way to model these reccuring aspects of an application.
  *
@@ -16,12 +17,12 @@ export default Context;
  * 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'
+ * ```js
+ * import { Client, ClientContext } from '@soundworks/core/index.js'
  *
  * const client = new Client(config);
  *
- * class MyContext extends Context {
+ * class MyContext extends ClientContext {
  *   async enter() {
  *     await super.enter();
  *     console.log(`client ${this.client.id} entered my context`);
@@ -40,32 +41,28 @@ export default Context;
  * await new Promise(resolve => setTimeout(resolve, 2000));
  * await myContext.exit();
  * ```
- *
- * @memberof client
  */
-declare class Context {
+declare class ClientContext {
     /**
-     * @param {client.Client} client - The soundworks client instance.
+     * @param {Client} client - The soundworks client instance.
      * @throws Will throw if the first argument is not a soundworks client instance.
      */
-    constructor(client: client.Client);
+    constructor(client: Client);
     /**
      * The soundworks client instance.
-     * @type {client.Client}
-     * @readonly
+     * @type {Client}
      */
-    readonly client: client.Client;
+    get client(): Client;
     /**
-     * Status of the context, i.e. 'idle', 'inited', 'started', 'errored'
-     * @type {string}
-     * @readonly
+     * Status of the context.
+     * @type {'idle'|'inited'|'started'|'errored'}
      */
-    readonly status: string;
+    get status(): "idle" | "inited" | "started" | "errored";
     /**
      * 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
+     * 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
@@ -81,7 +78,7 @@ declare class Context {
     readonly get name(): string;
     /**
      * Start the context. This method is lazilly called when the client enters the
-     * context for the first time (cf. ${client.Context#enter}). If you know some
+     * context for the first time (cf. ${ClientContext#enter}). If you know some
      * some heavy and/or potentially long job has to be done  when starting the context
      * (e.g. call to a web service) it may be a good practice to call it explicitely.
      *
@@ -118,12 +115,12 @@ declare class Context {
      * 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
+     * {@link ClientContext#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.
+     * @returns {Promise<void>} - Promise that resolves when the context is entered.
      * @example
      * class MyContext extends Context {
      *   async enter() {
@@ -137,16 +134,16 @@ declare class Context {
      *   }
      * }
      */
-    enter(): Promise<any>;
+    enter(): Promise<void>;
     /**
      * 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
+     * {@link ClientContext#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.
+     * @returns {Promise<void>} - Promise that resolves when the context is exited.
      * @example
      * class MyContext extends Context {
      *   async enter() {
@@ -160,6 +157,8 @@ declare class Context {
      *   }
      * }
      */
-    exit(): Promise<any>;
+    exit(): Promise<void>;
+    [kClientContextStatus]: string;
+    #private;
 }
-//# sourceMappingURL=Context.d.ts.map
+import Client from './Client.js';

package/types/client/{ContextManager.d.ts → ClientContextManager.d.ts}

@@ -1,45 +1,42 @@
-export default ContextManager;
+export const kClientContextManagerStart: unique symbol;
+export const kClientContextManagerStop: unique symbol;
+export const kClientContextManagerRegister: unique symbol;
+export default ClientContextManager;
 /**
  * Manage the different contexts and their lifecycle.
  *
- * See {@link client.Client#contextManager}
+ * See {@link Client#contextManager}
  *
  * _WARNING: In most cases, you should not have to manipulate the context manager directly._
  *
- * @memberof client
  * @hideconstructor
  */
-declare class ContextManager {
-    /** @private */
-    private _contexts;
-    /** @private */
-    private _contextStartPromises;
-    /**
-     * Register the context into the manager. Is called in context constructor.
-     *
-     * @param {client.Context} context - The context to be registered.
-     * @private
-     */
-    private register;
+declare class ClientContextManager {
     /**
      * 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.
+     * @param {string} contextName - Name of the context.
+     * @returns {Promise<ClientContext>}
      */
-    get(contextName: any): Promise<any>;
+    get(contextName: string): Promise<ClientContext>;
     /**
-     * Start all registered contexts. Called during `client.start()`
+     * Register the context into the manager. Is called in context constructor.
      *
+     * @param {ClientContext} context - The context to be registered.
+     * @private
+     */
+    private [kClientContextManagerRegister];
+    /**
+     * Start all registered contexts. Called during `client.start()`
      * @private
      */
-    private start;
+    private [kClientContextManagerStart];
     /**
      * Stop all registered contexts. Called during `client.stop()`
-     *
      * @private
      */
-    private stop;
+    private [kClientContextManagerStop];
+    #private;
 }
-//# sourceMappingURL=ContextManager.d.ts.map

package/types/client/{Plugin.d.ts → ClientPlugin.d.ts}

@@ -1,20 +1,18 @@
-export default Plugin;
-export namespace client {
-    /**
-     * ~onStateChangeCallback
-     */
-    type Plugin = (#state: client.Plugin) => any;
-}
+export default ClientPlugin;
+/**
+ * ~onStateChangeCallback
+ */
+export type ClientPlugin = (#state: ClientPlugin) => any;
 /**
  * Callback executed when the plugin state is updated.
  *
- * @callback client.Plugin~onStateChangeCallback
- * @param {client.Plugin#state} state - Current state of the plugin.
+ * @callback ClientPlugin~onStateChangeCallback
+ * @param {ClientPlugin#state} state - Current state of the plugin.
  */
 /**
- * Delete the registered {@link client.Plugin~onStateChangeCallback}.
+ * Delete the registered {@link ClientPlugin~onStateChangeCallback}.
  *
- * @callback client.Plugin~deleteOnStateChangeCallback
+ * @callback ClientPlugin~deleteOnStateChangeCallback
  */
 /**
  * Base class to extend in order to create the client-side counterpart of a
@@ -31,24 +29,23 @@ export namespace client {
  *
  * _Creating new plugins should be considered an advanced usage._
  *
- * @memberof client
  * @extends BasePlugin
  * @inheritdoc
  */
-declare class Plugin extends BasePlugin {
+declare class ClientPlugin extends BasePlugin {
     /**
-     * @param {client.Client} client - The soundworks client instance.
+     * @param {Client} client - A soundworks client instance.
      * @param {string} id - User defined id of the plugin as defined in
-     *  {@link client.PluginManager#register}.
+     *  {@link ClientPluginManager#register}.
      */
-    constructor(client: client.Client, id: string);
+    constructor(client: Client, id: string);
     /**
      * Instance of soundworks client.
      *
-     * @type {client.Client}
-     * @see {@link client.Client}
+     * @type {Client}
+     * @see {@link Client}
      */
-    client: client.Client;
+    get client(): Client;
+    #private;
 }
 import BasePlugin from '../common/BasePlugin.js';
-//# sourceMappingURL=Plugin.d.ts.map