@soundworks/core 4.0.0-alpha.7 → 5.0.0

package/types/server/ServerStateManager.d.ts

@@ -0,0 +1,284 @@
+export const kServerStateManagerAddClient: unique symbol;
+export const kServerStateManagerRemoveClient: unique symbol;
+export const kServerStateManagerHasClient: unique symbol;
+export const kServerStateManagerDeletePrivateState: unique symbol;
+export const kServerStateManagerGetUpdateHooks: unique symbol;
+export const kStateManagerClientsByNodeId: unique symbol;
+export default ServerStateManager;
+export type serverStateManagerCreateHook = () => any;
+export type serverStateManagerUpdateHook = () => any;
+export type serverStateManagerDeleteHook = () => any;
+/**
+ * @callback serverStateManagerCreateHook
+ * @async
+ *
+ * @param {object} initValues - Initialization values object as given when the
+ *  shared state is created
+ */
+/**
+ * @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.
+ * @returns {object} The "real" updates to be applied on the state.
+ */
+/**
+ * @callback serverStateManagerDeleteHook
+ * @async
+ *
+ * @param {object} currentValues - Update object as given on a `set` callback, or
+ *  result of the previous hook.
+ */
+/**
+ * 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
+ * define and delete shared state classes, as well as register hooks executed at
+ * lifecycle phases of a shared state
+ *
+ * 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 class of a shared state.
+ * server.stateManager.defineClass('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 generic class from which {@link SharedState}s can be created.
+     *
+     * @param {SharedStateClassName} className - Name of the class.
+     * @param {SharedStateClassDescription} classDescription - Description of the class.
+     *
+     * @see {@link ServerStateManager#create}
+     * @see {@link ClientStateManager#create}
+     *
+     * @example
+     * server.stateManager.defineClass('my-class', {
+     *   myBoolean: {
+     *     type: 'boolean'
+     *     default: false,
+     *   },
+     *   myFloat: {
+     *     type: 'float'
+     *     default: 0.1,
+     *     min: -1,
+     *     max: 1
+     *   }
+     * });
+     */
+    defineClass(className: SharedStateClassName, classDescription: SharedStateClassDescription): void;
+    /**
+     * @deprecated Use {@link ServerStateManager#defineClass} instead.
+     */
+    registerSchema(className: any, classDescription: any): void;
+    /**
+     * Delete a whole class of {@link SharedState}.
+     *
+     * All {@link SharedState} instances created from this class will be deleted
+     * as well, triggering their eventual `onDetach` and `onDelete` callbacks.
+     *
+     * @param {SharedStateClassName} className - Name of the shared state class to delete.
+     */
+    deleteClass(className: SharedStateClassName): void;
+    /**
+     * @deprecated Use {@link ServerStateManager#defineClass} instead.
+     */
+    deleteSchema(className: any): void;
+    /**
+     * Register a function for a given class of shared state class to be executed
+     * when a state is created.
+     *
+     * For example, this can be useful to retrieve some initialization values stored
+     * in the filesystem, given the value (e.g. a hostname) of one the parameters.
+     *
+     * The hook is associated to each states created from the given class name.
+     * Note that the hooks are executed server-side regardless the node on which
+     * `create` has been called.
+     *
+     * Multiple hook can be added to the same `className`, they will be executed in
+     * order of registration.
+     *
+     * @param {string} className - Kind of states on which applying the hook.
+     * @param {serverStateManagerUpdateHook} createHook - Function called on when
+     *  a state of `className` is created on the network.
+     *
+     * @returns {function} deleteHook - Handler that deletes the hook when executed.
+     *
+     * @example
+     * server.stateManager.defineClass('hooked', {
+     *   name: { type: 'string', required: true },
+     *   hookTriggered: { type: 'boolean', default: false },
+     * });
+     * server.stateManager.registerCreateHook('hooked', initValues => {
+     *   return {
+     *     ...initValues
+     *     hookTriggered: true,
+     *   };
+     * });
+     *
+     * const state = await server.stateManager.create('hooked', {
+     *   name: 'coucou',
+     * });
+     *
+     * const values = state.getValues();
+     * assert.deepEqual(result, { value: 'coucou', hookTriggered: true });
+     */
+    registerCreateHook(className: string, createHook: serverStateManagerUpdateHook): Function;
+    /**
+     * Register a function for a given class of shared state class to be executed
+     * when a state is deleted.
+     *
+     * For example, this can be useful to store the values of a given shared state
+     * in the filesystem.
+     *
+     * The hook is associated to each states created from the given class name.
+     * Note that the hooks are executed server-side regardless the node on which
+     * `delete` has been called.
+     *
+     * Multiple hook can be added to the same `className`, they will be executed in
+     * order of registration.
+     *
+     * @param {string} className - Kind of states on which applying the hook.
+     * @param {serverStateManagerUpdateHook} createHook - Function called on when
+     *  a state of `className` is created on the network.
+     *
+     * @returns {function} deleteHook - Handler that deletes the hook when executed.
+     *
+     * @example
+     * server.stateManager.defineClass('hooked', {
+     *   name: { type: 'string', required: true },
+     *   hookTriggered: { type: 'boolean', default: false },
+     * });
+     * server.stateManager.registerDeleteHook('hooked', async currentValues => {
+     *   await doSomethingWithValues(currentValues)
+     * });
+     *
+     * const state = await server.stateManager.create('hooked');
+     * // later
+     * await state.delete();
+     */
+    registerDeleteHook(className: string, deleteHook: any): Function;
+    /**
+     * Register a function for a given class of shared state to be executed between
+     * `set` instructions and `onUpdate` callback(s).
+     *
+     * For example, this can 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 each states created from the given class name and
+     * executed on each update (i.e. `state.set(updates)`). Note that the hooks are
+     * executed server-side regardless the node on which `set` has been called and
+     * before the call of the `onUpdate` callback of the shared state.
+     *
+     * Multiple hook can be added to the same `className`, they will be executed in
+     * order of registration.
+     *
+     * @param {string} className - Kind of states on which applying the hook.
+     * @param {serverStateManagerUpdateHook} updateHook - Function called on each update,
+     *  to eventually modify the updates before they are actually applied.
+     *
+     * @returns {function} deleteHook - Handler that deletes the hook when executed.
+     *
+     * @example
+     * server.stateManager.defineClass('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(className: string, updateHook: serverStateManagerUpdateHook): Function;
+    /** @private */
+    private [kStateManagerInit];
+    /** @private */
+    private [kServerStateManagerDeletePrivateState];
+    /** @private */
+    private [kServerStateManagerGetUpdateHooks];
+    /** @private */
+    private [kServerStateManagerHasClient];
+    /**
+     * Add a client to the manager.
+     *
+     * This is automatically handled by the {@link Server} when a client connects.
+     *
+     * @param {number} nodeId - Unique id of the client node
+     * @param {object} transport - Transport mechanism 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,23 @@
+export const kSharedStatePrivateAttachClient: unique symbol;
+export const kSharedStatePrivateDetachClient: unique symbol;
+export const kSharedStatePrivateGetValues: 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(manager: any, className: any, classDefinition: any, id: any, initValues?: {});
+    get id(): any;
+    get className(): any;
+    get creatorId(): any;
+    get creatorInstanceId(): any;
+    get attachedClients(): Map<any, any>;
+    get parameters(): any;
+    [kSharedStatePrivateGetValues](): any;
+    [kSharedStatePrivateAttachClient](instanceId: any, client: any, isOwner: any, filter: any): void;
+    [kSharedStatePrivateDetachClient](instanceId: any, client: any): void;
+    #private;
+}

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

@@ -1,2 +1,2 @@
-export {};
-//# sourceMappingURL=audit-network-latency.worker.d.ts.map
+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 ecmascript 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;

package/types/server/{audit-schema.d.ts → audit-state-class-description.d.ts}

@@ -1,27 +1,26 @@
 declare namespace _default {
     namespace numClients {
-        export const type: string;
-        const _default: {};
+        export let type: string;
+        let _default: {};
         export { _default as default };
     }
     namespace averageNetworkLatency {
-        const type_1: string;
+        let type_1: string;
         export { type_1 as type };
-        const _default_1: number;
+        let _default_1: number;
         export { _default_1 as default };
     }
     namespace averageNetworkLatencyWindow {
-        const type_2: string;
+        let type_2: string;
         export { type_2 as type };
-        const _default_2: number;
+        let _default_2: number;
         export { _default_2 as default };
     }
     namespace averageNetworkLatencyPeriod {
-        const type_3: string;
+        let type_3: string;
         export { type_3 as type };
-        const _default_3: number;
+        let _default_3: number;
         export { _default_3 as default };
     }
 }
 export default _default;
-//# sourceMappingURL=audit-schema.d.ts.map

package/types/server/create-http-server.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @private
+ * @return {HttpServer|HttpsServer}
+ */
+export function createHttpServer(server: any): HttpServer | HttpsServer;

package/types/server/crypto.d.ts

@@ -0,0 +1,4 @@
+/** @private */
+export function encryptData(obj: any): string;
+/** @private */
+export function decryptData(encryptedData: any): any;

package/types/server/index.d.ts

@@ -1,7 +1,55 @@
 export { default as Server } from "./Server.js";
-export { default as Context } from "./Context.js";
+export { default as ServerPlugin } from "./ServerPlugin.js";
+export { default as ServerContext } from "./ServerContext.js";
+export { default as version } from "../common/version.js";
+/**
+ * The role of the client in the application.
+ *
+ * For browser client, this information is used to create the URL endpoint.
+ */
+export type ClientRole = string;
+export type ClientDescription = {
+    /**
+     * - Runtime on which the client is aimed at running
+     */
+    runtime: "browser" | "node";
+    /**
+     * - For browser client, define is the client should be
+     * accessible at the default / root HTTP endpoint
+     */
+    default?: boolean;
+};
+/**
+ * Application configuration object.
+ */
+export type ServerAppConfig = {
+    /**
+     * <ClientRole, ClientDescription>} clients - Definition of the application clients.
+     */
+    "": object;
+    /**
+     * - Name of the application.
+     */
+    name?: string;
+    /**
+     * - Name of the author.
+     */
+    author?: string;
+};
+/**
+ * Environment configuration object.
+ */
+export type ServerEnvConfig = objecy;
 /**
  * Configuration object for the server.
  */
-export type ServerConfig = any;
-//# sourceMappingURL=index.d.ts.map
+export type ServerConfig = {
+    /**
+     * - Application configuration object.
+     */
+    app: AppConfig;
+    /**
+     * - Environment configuration object.
+     */
+    env: ServerEnvConfig;
+};

package/.eslintrc

@@ -1,15 +0,0 @@
-{
-  "extends": [
-    "@ircam",
-  ],
-  "settings": {
-    "jsdoc": {
-      "tagNamePreference": {
-        "augments": {
-          "message": "@extends is to be used over @augments as it is more evocative of classes than @augments",
-          "replacement": "extends"
-        }
-      }
-    }
-  }
-}

package/.github/workflows/gh-pages.yml

@@ -1,31 +0,0 @@
-name: GH Pages
-
-on:
-  push:
-    tags:
-      - '*'
-
-permissions:
-  contents: write
-
-jobs:
-  deploy:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v3
-
-      - name: 'Install Node'
-        uses: actions/setup-node@v3.6.0
-
-      - name: Install dependencies
-        run: npm install
-
-      - name: Build Docs
-        run: npm run doc
-
-      - name: Deploy
-        uses: JamesIves/github-pages-deploy-action@v4
-        with:
-          folder: docs
-

package/.github/workflows/unit-tests.yml

@@ -1,18 +0,0 @@
-name: Unit Tests
-on: push
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v3
-
-      - name: 'Install Node'
-        uses: actions/setup-node@v3.6.0
-
-      - name: Install dependencies
-        run: npm install
-
-      - name: "Run Test"
-        run: npm test -- tests/**.spec.js

package/src/client/ContextManager.js

@@ -1,111 +0,0 @@
-/** @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);
-  }
-}
-
-/**
- * Manage the different contexts and their lifecycle.
- *
- * See {@link client.Client#contextManager}
- *
- * _WARNING: In most cases, you should not have to manipulate the context manager directly._
- *
- * @memberof client
- * @hideconstructor
- */
-class ContextManager {
-  constructor() {
-    /** @private */
-    this._contexts = new ContextCollection();
-    /** @private */
-    this._contextStartPromises = new Map();
-  }
-
-  /**
-   * Register the context into the manager. Is called in context constructor.
-   *
-   * @param {client.Context} context - The context to be registered.
-   * @private
-   */
-  register(context) {
-    if (this._contexts.has(context.name)) {
-      throw new Error(`[soundworks:context-manager] Context "${context.name}" already registered`);
-    }
-
-    this._contexts.add(context);
-  }
-
-  /**
-   * 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.
-   */
-  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;
-  }
-
-  /**
-   * Start all registered contexts. Called during `client.start()`
-   *
-   * @private
-   */
-  async start() {
-    const promises = this._contexts.map(context => this.get(context.name));
-    await Promise.all(promises);
-  }
-
-  /**
-   * Stop all registered contexts. Called during `client.stop()`
-   *
-   * @private
-   */
-  async stop() {
-    const promises = this._contexts.map(context => context.stop());
-    await Promise.all(promises);
-  }
-}
-
-export default ContextManager;

package/src/client/SharedState.js

@@ -1,84 +0,0 @@
-import BaseSharedState from '../common/BaseSharedState.js';
-
-// this file exists only for documentation purposes
-
-/**
- * @callback client.SharedState~onUpdateCallback
- * @param {Object} newValues - Key / value pairs of the updates that have been
- *  applied to the state.
- * @param {Object} oldValues - Key / value pairs of the updated params before
- *  the updates has been applied to the state.
- * @param {Mixed} [context=null] - Optionnal context object that has been passed
- *  with the values updates in the `set` call.
- */
-
-/**
- * Delete the registered {@link client.SharedState~onUpdateCallback}.
- *
- * @callback client.SharedState~deleteOnUpdateCallback
- */
-
-
-/**
- * The `SharedState` is one of the most important and versatile abstraction provided
- * by `soundworks`. It represents a set of parameters that are synchronized accross
- * every nodes of the application (clients and server) that declared some interest
- * to the shared state.
- *
- * A `SharedState` is created according to a "schema" (in the sense of a database
- * schema) that must be declared and registered server-side. Any number of `SharedState`s
- * can be created from a single schema.
- *
- * A shared state can be created both by the clients or by the server (in which case
- * it is generally considered as a global state of the application). Similarly any
- * node of the application (clients or server) can declare interest and "attach" to
- * a state created by another node. All node attached to a state can modify its values
- * and/or react to the modifications applied by other nodes.
- *
- * 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);
- * ```
- *
- * @memberof client
- * @extends BaseSharedState
- * @inheritdoc
- * @hideconstructor
- */
-class SharedState extends BaseSharedState {}
-
-export default SharedState;