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

package/types/server/{Plugin.d.ts → ServerPlugin.d.ts}

@@ -1,21 +1,4 @@
-export default Plugin;
-export namespace server {
-    /**
-     * ~onStateChangeCallback
-     */
-    type Plugin = (#state: server.Plugin) => any;
-}
-/**
- * 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
- */
+export default ServerPlugin;
 /**
  * Base class to extend in order to create the server-side counterpart of a
  * `soundworks` plugin.
@@ -31,41 +14,44 @@ export namespace server {
  *
  * _Creating new plugins should be considered an advanced usage._
  *
- * @memberof server
  * @extends BasePlugin
  * @inheritdoc
  */
-declare class Plugin extends BasePlugin {
+declare class ServerPlugin extends BasePlugin {
     /**
-     * @param {server.Server} server - The soundworks server instance.
+     * @param {Server} server - The soundworks server instance.
      * @param {string} id - User defined id of the plugin as defined in
-     *  {@link server.PluginManager#register}.
+     *  {@link ServerPluginManager#register}.
      */
-    constructor(server: server.Server, id: string);
+    constructor(server: Server, id: string);
     /**
      * Instance of soundworks server.
-     * @type {server.Server}
-     * @see {@link server.Server}
+     * @type {Server}
+     * @see {@link Server}
+     */
+    get server(): Server;
+    /**
+     * Set of the clients registered in the plugin.
+     * @type {Set<ServerClient>}
+     * @see {@link ServerClient}
      */
-    server: server.Server;
-    /** @private */
-    private clients;
+    get clients(): Set<ServerClient>;
     /**
      * 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
+     * @param {ServerClient} client
      */
-    addClient(client: server.Client): Promise<void>;
+    addClient(client: ServerClient): Promise<void>;
     /**
      * 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
+     * @param {ServerClient} client
      */
-    removeClient(client: server.Client): Promise<void>;
+    removeClient(client: ServerClient): Promise<void>;
+    #private;
 }
 import BasePlugin from '../common/BasePlugin.js';
-//# sourceMappingURL=Plugin.d.ts.map

package/types/server/{PluginManager.d.ts → ServerPluginManager.d.ts}

@@ -1,29 +1,12 @@
-export default PluginManager;
-export namespace server {
-    /**
-     * ~onStateChangeCallback
-     */
-    type PluginManager = (: object, initiator: server.Plugin | null) => any;
-}
-/**
- * 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
- */
+export const kServerPluginManagerCheckRegisteredPlugins: unique symbol;
+export const kServerPluginManagerAddClient: unique symbol;
+export const kServerPluginManagerRemoveClient: unique symbol;
+export default ServerPluginManager;
 /**
  * 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}
+ * and before {@link Client#start} or {@link Server#start}
  * to be properly initialized.
  *
  * In some sitautions, you might want to register the same plugin factory several times
@@ -71,15 +54,37 @@ export namespace server {
  * }, 1000);
  * ```
  *
- * @memberof server
  * @extends BasePluginManager
  * @inheritdoc
  * @hideconstructor
  */
-declare class PluginManager extends BasePluginManager {
-    register(id: any, factory?: any, options?: {}, deps?: any[]): void;
+declare class ServerPluginManager extends BasePluginManager {
+    /**
+     * Register a plugin into the manager.
+     *
+     * _A plugin must always be registered both on client-side and on server-side_
+     *
+     * Refer to the plugin documentation to check its options and proper way of
+     * registering it.
+     *
+     * @param {string} id - Unique id of the plugin. Enables the registration of the
+     *  same plugin factory under different ids.
+     * @param {Function} factory - Factory function that returns the Plugin class.
+     * @param {object} [options={}] - Options to configure the plugin.
+     * @param {array} [deps=[]] - List of plugins' names the plugin depends on, i.e.
+     *  the plugin initialization will start only after the plugins it depends on are
+     *  fully started themselves.
+     * @see {@link ClientPluginManager#register}
+     * @see {@link ServerPluginManager#register}
+     * @example
+     * // client-side
+     * client.pluginManager.register('user-defined-id', pluginFactory);
+     * // server-side
+     * server.pluginManager.register('user-defined-id', pluginFactory);
+     */
+    register(id: string, factory?: Function, options?: object, deps?: any[]): void;
     /**
-     * Retrieve an fully started instance of a registered plugin.
+     * Retrieve a 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
@@ -93,19 +98,16 @@ declare class PluginManager extends BasePluginManager {
      * _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
+     * @param {ServerPlugin#id} id - Id of the plugin as defined when registered.
+     * @returns {ServerPlugin}
      */
-    private get;
-    /** private */
-    checkRegisteredPlugins(registeredPlugins: any): void;
+    get(id: any): ServerPlugin;
+    /** @private */
+    private [kServerPluginManagerCheckRegisteredPlugins];
     /** @private */
-    private addClient;
+    private [kServerPluginManagerAddClient];
     /** @private */
-    private removeClient;
+    private [kServerPluginManagerRemoveClient];
 }
 import BasePluginManager from '../common/BasePluginManager.js';
-//# sourceMappingURL=PluginManager.d.ts.map
+import ServerPlugin from './ServerPlugin.js';

package/types/server/ServerSocket.d.ts

@@ -0,0 +1,85 @@
+export const kSocketClientId: unique symbol;
+export const kSocketTerminate: unique symbol;
+export default ServerSocket;
+/**
+ * Simple publish / subscribe wrapper built on top of the
+ * [ws](https://github.com/websockets/ws) library.
+ *
+ * An instance of {@link ServerSocket} is automatically created per client
+ * when it connects (see {@link SeverClient#socket}).
+ *
+ * _Important: In most cases, you should consider using a {@link SharedState}
+ * rather than directly using the Socket instance._
+ *
+ * @hideconstructor
+ */
+declare class ServerSocket {
+    constructor(ws: any, sockets: any);
+    /**
+     * Reference to the @link{ServerSockets} instance.
+     *
+     * Allows for broadcasting from a given socket instance.
+     *
+     * @type {ServerSockets}
+     * @example
+     * socket.sockets.broadcast('my-room', this, 'update-value', 1);
+     */
+    get sockets(): ServerSockets;
+    /**
+     * Reay state of the underlying socket instance.
+     *
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/readyState}
+     * @type {number}
+     */
+    get readyState(): number;
+    /**
+     * Send messages with JSON compatible data types on a given channel.
+     *
+     * @param {string} channel - Channel name.
+     * @param {...*} args - Payload of the message. As many arguments as needed, of
+     *  JSON compatible data types (i.e. string, number, boolean, object, array and null).
+     */
+    send(channel: string, ...args: any[]): void;
+    /**
+     * Listen messages with JSON compatible data types on a given channel.
+     *
+     * @param {string} channel - Channel name.
+     * @param {Function} callback - Callback to execute when a message is received.
+     *  Arguments of the callback function will match the arguments sent using the
+     *  {@link ServerSocket#send} method.
+     */
+    addListener(channel: string, callback: Function): void;
+    /**
+     * Remove a listener of messages with JSON compatible data types from a given channel.
+     *
+     * @param {string} channel - Channel name.
+     * @param {Function} callback - Callback to remove.
+     */
+    removeListener(channel: string, callback: Function): void;
+    /**
+     * Remove all listeners of messages with JSON compatible data types.
+     *
+     * @param {string} channel - Channel name.
+     */
+    removeAllListeners(channel?: string): void;
+    /**
+     * Add the socket to a room
+     * @param {string} roomId - Id of the room.
+     */
+    addToRoom(roomId: string): void;
+    /**
+     * Remove the socket from a room
+     * @param {string} roomId - Id of the room.
+     */
+    removeFromRoom(roomId: string): void;
+    /**
+     * Removes all listeners and immediately close the web socket.
+     *
+     * Is automatically called when socket is closed on the client side or when
+     * Server is stopped
+     *
+     * @private
+     */
+    private [kSocketTerminate];
+    #private;
+}

package/types/server/ServerSockets.d.ts

@@ -0,0 +1,50 @@
+export const kSocketsStart: unique symbol;
+export const kSocketsStop: unique symbol;
+export const kSocketsRemoveFromAllRooms: unique symbol;
+export const kSocketsLatencyStatsWorker: unique symbol;
+export const kSocketsDebugPreventHeartBeat: unique symbol;
+export default ServerSockets;
+/**
+ * Manage all {@link ServerSocket} instances.
+ *
+ * _Important: In most cases, you should consider using a {@link SharedState}
+ * rather than directly using the ServerSocket instance._
+ */
+declare class ServerSockets {
+    constructor(server: any, config: any);
+    /**
+     * Add a socket to a room.
+     *
+     * _Note that in most cases, you should use a {@link SharedState} instead_
+     *
+     * @param {ServerSocket} socket - Socket to add to the room.
+     * @param {String} roomId - Id of the room.
+     */
+    addToRoom(socket: ServerSocket, roomId: string): void;
+    /**
+     * Remove a socket from a room.
+     *
+     * _Note that in most cases, you should use a {@link SharedState} instead_
+     *
+     * @param {ServerSocket} socket - Socket to remove from the room.
+     * @param {String} roomId - Id of the room.
+     */
+    removeFromRoom(socket: ServerSocket, roomId: string): void;
+    /**
+     * Send a message to all clients os given room(s). If no room is specified,
+     * the message is sent to all clients.
+     *
+     * _Note that in most cases, you should use a {@link SharedState} instead_
+     *
+     * @param {String|Array} roomsIds - Ids of the rooms that must receive
+     *  the message. If `null` the message is sent to all clients.
+     * @param {ServerSocket} excludeSocket - Optionnal socket to ignore when
+     *  broadcasting the message, typically the client at the origin of the message.
+     * @param {String} channel - Channel name.
+     * @param {...*} args - Payload of the message. As many arguments as needed, of
+     *  JSON compatible data types (i.e. string, number, boolean, object, array and null).
+     */
+    broadcast(roomIds: any, excludeSocket: ServerSocket, channel: string, ...args: any[]): void;
+    #private;
+}
+import ServerSocket from './ServerSocket.js';

package/types/server/ServerStateManager.d.ts

@@ -0,0 +1,189 @@
+export const kServerStateManagerAddClient: unique symbol;
+export const kServerStateManagerRemoveClient: unique symbol;
+export const kServerStateManagerDeletePrivateState: unique symbol;
+export const kServerStateManagerGetHooks: unique symbol;
+export const kStateManagerClientsByNodeId: unique symbol;
+export default ServerStateManager;
+export type serverStateManagerUpdateHook = () => any;
+/**
+ * @callback serverStateManagerUpdateHook
+ * @async
+ *
+ * @param {object} updates - Update object as given on a set callback, or
+ *  result of the previous hook
+ * @param {object} currentValues - Current values of the state.
+ * @param {object} [context=null] - Optionnal context passed by the creator
+ *  of the update.
+ *
+ * @returns {object} The "real" updates to be applied on the state.
+ */
+/**
+ * The `StateManager` allows to create new {@link SharedState}s, or attach
+ * to {@link SharedState}s created by other nodes (clients or server). It
+ * can also track all the {@link SharedState}s created by other nodes.
+ *
+ * An instance of `StateManager` is automatically created by the `soundworks.Server`
+ * at initialization (cf. {@link Server#stateManager}).
+ *
+ * Compared to the {@link ClientStateManager}, the `ServerStateManager` can also
+ * register and delete schemas, as well as register update hook that are executed when
+ * a state is updated.
+ *
+ * See {@link Server#stateManager}
+ *
+ * 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);
+ * ```
+ *
+ * @extends BaseStateManager
+ * @inheritdoc
+ * @hideconstructor
+ */
+declare class ServerStateManager extends BaseStateManager {
+    /**
+     * Define a class of data structure from which {@link SharedState} can be instanciated.
+     *
+     * _In a future revision, this method and its arguments will be renamed_
+     *
+     * @param {SharedStateClassName} schemaName - Name of the schema.
+     * @param {SharedStateSchema} schema - Data structure
+     *  describing the states that will be created from this schema.
+     *
+     * @see {@link ServerStateManager#create}
+     * @see {@link ClientStateManager#create}
+     *
+     * @example
+     * server.stateManager.registerSchema('my-schema', {
+     *   myBoolean: {
+     *     type: 'boolean'
+     *     default: false,
+     *   },
+     *   myFloat: {
+     *     type: 'float'
+     *     default: 0.1,
+     *     min: -1,
+     *     max: 1
+     *   }
+     * })
+     */
+    registerSchema(schemaName: SharedStateClassName, schema: SharedStateSchema): void;
+    /**
+     * Delete a whole class of {@link ShareState}.
+     *
+     * All {@link SharedState} instance that belong to this class are deleted
+     * as well, triggering the `onDetach` and `onDelete` callbacks are called on
+     * the actual {@link SharedState} instances.
+     *
+     * _In a future revision, this method and its arguments will be renamed_
+     *
+     * @param {SharedStateClassName} schemaName - Name of the schema.
+     */
+    deleteSchema(schemaName: SharedStateClassName): void;
+    /**
+     * Register a function for a given schema (e.g. will be applied on all states
+     * created from this schema) that will be executed before the update values
+     * are propagated. For example, this could be used to implement a preset system
+     * where all the values of the state are updated from e.g. some data stored in
+     * filesystem while the consumer of the state only want to update the preset name.
+     *
+     * The hook is associated to every state of its kind (i.e. schemaName) and
+     * executed on every update (call of `set`). Note that the hooks are executed
+     * server-side regarless the node on which `set` has been called and before
+     * the "actual" update of the state (e.g. before the call of `onUpdate`).
+     *
+     * @param {string} schemaName - Kind of states on which applying the hook.
+     * @param {serverStateManagerUpdateHook} updateHook - Function
+     *   called between the `set` call and the actual update.
+     *
+     * @returns {Fuction} deleteHook - Handler that deletes the hook when executed.
+     *
+     * @example
+     * server.stateManager.registerSchema('hooked', {
+     *   value: { type: 'string', default: null, nullable: true },
+     *   numUpdates: { type: 'integer', default: 0 },
+     * });
+     * server.stateManager.registerUpdateHook('hooked', updates => {
+     *   return {
+     *     ...updates
+     *     numUpdates: currentValues.numUpdates + 1,
+     *   };
+     * });
+     *
+     * const state = await server.stateManager.create('hooked');
+     *
+     * await state.set({ value: 'test' });
+     * const values = state.getValues();
+     * assert.deepEqual(result, { value: 'test', numUpdates: 1 });
+     */
+    registerUpdateHook(schemaName: string, updateHook: serverStateManagerUpdateHook): Fuction;
+    /** @private */
+    private [kServerStateManagerDeletePrivateState];
+    /** @private */
+    private [kServerStateManagerGetHooks];
+    /** @private */
+    private [kStateManagerInit];
+    /**
+     * Add a client to the manager.
+     *
+     * This is automatically handled by the {@link Server} when a client connects.
+     *
+     * @param {number} nodeId - Id of the client node, as given in
+     *  {@link client.StateManager}
+     * @param {object} transport - Transport mecanism to communicate with the
+     *  client. Must implement a basic EventEmitter API.
+     *
+     * @private
+     */
+    private [kServerStateManagerAddClient];
+    /**
+     * Remove a client from the manager. Clean all created or attached states.
+     *
+     * This is automatically handled by the {@link Server} when a client disconnects.
+     *
+     * @param {number} nodeId - Id of the client node, as given in
+     *  {@link client.StateManager}
+     *
+     * @private
+     */
+    private [kServerStateManagerRemoveClient];
+    /** @private */
+    private [kStateManagerClientsByNodeId];
+    #private;
+}
+import BaseStateManager from '../common/BaseStateManager.js';
+import { kStateManagerInit } from '../common/BaseStateManager.js';

package/types/server/SharedStatePrivate.d.ts

@@ -0,0 +1,21 @@
+export const kSharedStatePrivateAttachClient: unique symbol;
+export const kSharedStatePrivateDetachClient: unique symbol;
+export default SharedStatePrivate;
+/**
+ * The "real" state, this instance is kept private by the server.StateManager.
+ * It can only be accessed through a SharedState proxy.
+ *
+ * @private
+ */
+declare class SharedStatePrivate {
+    constructor(id: any, schemaName: any, schema: any, manager: any, initValues?: {});
+    get id(): any;
+    get schemaName(): any;
+    get creatorId(): any;
+    get creatorRemoteId(): any;
+    get attachedClients(): Map<any, any>;
+    get parameters(): any;
+    [kSharedStatePrivateAttachClient](remoteId: any, client: any, isOwner: any, filter: any): void;
+    [kSharedStatePrivateDetachClient](remoteId: any, client: any): void;
+    #private;
+}

package/types/server/audit-network-latency.worker.d.ts

@@ -1,3 +1,2 @@
-declare const _default: "\nconst { parentPort } = require('node:worker_threads');\n\nlet stack = [];\nlet averageLatencyWindow = 5;\nlet averageLatencyPeriod = 2;\n\nlet intervalId = null;\nlet meanLatency = 0;\n\nlet getTime;\nlet inited = new Promise(async (resolve) => {\n  module = await import('@ircam/sc-utils');\n  getTime = module.getTime;\n  resolve(true);\n});\n\nparentPort.on('message', async msg => {\n  switch (msg.type) {\n    case 'config': {\n      averageLatencyWindow = msg.value.averageLatencyWindow;\n      averageLatencyPeriod = msg.value.averageLatencyPeriod;\n\n      await inited;\n\n      // launch compute in its own loop so that the number of computation is\n      // decoupled from the number of connected clients\n      clearInterval(intervalId);\n      intervalId = setInterval(computeAverageLatency, averageLatencyPeriod * 1000);\n      break;\n    }\n    case 'add-measurement': {\n      // compute latency considering ping and pong time are equal\n      const entry = msg.value;\n      entry.latency = (entry.pong - entry.ping) / 2;\n      // add new measure to the stack\n      stack.push(entry);\n    }\n  }\n});\n\nfunction computeAverageLatency() {\n  const now = getTime();\n  // remove old measurements from stack\n  stack = stack.filter(entry => entry.pong >= now - averageLatencyWindow);\n\n  // prevent dividing by zero, just return last computed value\n  if (stack.length === 0) {\n    parentPort.postMessage({\n      type: 'computed-average-latency',\n      value: meanLatency,\n    });\n  } else {\n    // compute mean\n    let sum = 0;\n    stack.forEach(entry => sum += entry.latency);\n\n    meanLatency = sum / stack.length;\n    // send result to main thread\n    parentPort.postMessage({\n      type: 'computed-average-latency',\n      value: meanLatency,\n    });\n  }\n}\n";
+declare const _default: "\nconst { parentPort } = require('node:worker_threads');\nconst { hrtime } =  require('node:process');\n\nlet stack = [];\nlet averageLatencyWindow = 5;\nlet averageLatencyPeriod = 2;\n\nlet intervalId = null;\nlet meanLatency = 0;\n\n// workaround that sc-utils is pure emascript module\n// 2024/09/06 - Just copy getTime implementation so that we don't even need the node_modules\nconst start = hrtime.bigint();\n\nfunction getTime() {\n  const now = hrtime.bigint();\n  const delta = now - start;\n  return Number(delta) * 1e-9;\n}\n\nparentPort.on('message', async msg => {\n  switch (msg.type) {\n    case 'config': {\n      averageLatencyWindow = msg.value.averageLatencyWindow;\n      averageLatencyPeriod = msg.value.averageLatencyPeriod;\n\n      // launch compute in its own loop so that the number of computation is\n      // decoupled from the number of connected clients\n      clearInterval(intervalId);\n      intervalId = setInterval(computeAverageLatency, averageLatencyPeriod * 1000);\n      break;\n    }\n    case 'add-measurement': {\n      // compute latency considering ping and pong time are equal\n      const entry = msg.value;\n      entry.latency = (entry.pong - entry.ping) / 2;\n      // add new measure to the stack\n      stack.push(entry);\n    }\n  }\n});\n\nfunction computeAverageLatency() {\n  const now = getTime();\n  // remove old measurements from stack\n  stack = stack.filter(entry => entry.pong >= now - averageLatencyWindow);\n\n  // prevent dividing by zero, just return last computed value\n  if (stack.length === 0) {\n    parentPort.postMessage({\n      type: 'computed-average-latency',\n      value: meanLatency,\n    });\n  } else {\n    // compute mean\n    let sum = 0;\n    stack.forEach(entry => sum += entry.latency);\n\n    meanLatency = sum / stack.length;\n    // send result to main thread\n    parentPort.postMessage({\n      type: 'computed-average-latency',\n      value: meanLatency,\n    });\n  }\n}\n";
 export default _default;
-//# sourceMappingURL=audit-network-latency.worker.d.ts.map

package/types/server/audit-schema.d.ts

@@ -24,4 +24,3 @@ declare namespace _default {
     }
 }
 export default _default;
-//# sourceMappingURL=audit-schema.d.ts.map

package/types/server/crypto.d.ts

@@ -1,3 +1,4 @@
+/** @private */
 export function encryptData(obj: any): string;
+/** @private */
 export function decryptData(encryptedData: any): any;
-//# sourceMappingURL=crypto.d.ts.map

package/types/server/index.d.ts

@@ -1,3 +1,25 @@
 export { default as Server } from "./Server.js";
-export { default as Context } from "./Context.js";
-//# sourceMappingURL=index.d.ts.map
+export { default as ServerContext } from "./ServerContext.js";
+/**
+ * Configuration object for the server.
+ */
+export type ServerConfig = {
+    /**
+     * - Application configuration object.
+     */
+    app?: {
+        clients: object;
+        name?: string;
+        author?: string;
+    };
+    /**
+     * - Environment configuration object.
+     */
+    env?: {
+        useHttps: boolean;
+        serverAddress: string;
+        port: number;
+        httpsInfos?: obj;
+        subpath?: string;
+    };
+};