@soundworks/core 4.0.0-alpha.9 → 5.0.0

package/types/common/shared-state-types.d.ts

@@ -0,0 +1,95 @@
+/**
+ * User defined name for a class of {@link SharedState}
+ */
+type SharedStateClassName = string;
+/**
+ * Description of a {@link SharedState} data structure that describes the structure
+ * of a class of {@link SharedState} to be registered by {@link ServerStateManager#defineClass}
+ *
+ * A `SharedStateClassDescription` is the blueprint, or the definition from which
+ * shared states from a given class can be created.
+ *
+ * It consists of a set of key / value pairs where the key is the name of
+ * the parameter (cf. ${SharedStateParameterName}), and the value is an object
+ * describing the parameter (cf. ${SharedStateParameterDescription}).
+ */
+type SharedStateClassDescription = any;
+/**
+ * User defined name of a parameter in a class of {@link SharedState}
+ */
+type SharedStateParameterName = string;
+/**
+ * Description of a parameter in a class of {@link SharedState}
+ */
+type SharedStateParameterDescription = {
+    /**
+     * - Type of the parameter.
+     */
+    type: "boolean" | "string" | "integer" | "float" | "enum" | "any";
+    /**
+     * - Default value of the parameter. Optional only if
+     * `nullable = true` or `event = true`
+     */
+    default: any;
+    /**
+     * - Defines if the parameter is nullable.
+     * When `true` the parameter `default` is set to `null`.
+     */
+    nullable?: boolean;
+    /**
+     * - Define if the parameter is a volatile, i.e.
+     * its value only exists on an update and is set back to `null` after propagation.
+     * When `true`, `nullable` is automatically set to `true` and `default` to `null`.
+     */
+    event?: boolean;
+    /**
+     * - When set to `false`, an update will
+     * trigger the propagation of a parameter even when its value didn't change.
+     * This option provides a sort of middle ground between the default behavior
+     * (e.g. where only changed values are propagated) and the behavior of the `event`
+     * option (which has no state per se). Hence, setting this options to `false` if
+     * `event=true` makes no sens.
+     */
+    filterChange?: boolean;
+    /**
+     * - When set to `true`, an update will
+     * trigger the update listeners immediately on the node that generated the update,
+     * before propagating the change on the network.
+     * This option is useful in cases the network would introduce a noticeable
+     * latency on the client.
+     * If for some reason the value is overridden server-side (e.g. in an `updateHook`)
+     * the listeners will be called again when the "real" value is received.
+     */
+    immediate?: boolean;
+    /**
+     * - When set to true, the parameter must be
+     * provided in the initialization values when the state is created.
+     */
+    required?: boolean;
+    /**
+     * - When set to true, the parameter is never
+     * propagated on the network (hence it is no longer a shared parameter :). This
+     * is useful to declare some common parameter (e.g. some interface state) that
+     * don't need to be shared but to stay in the shared state API paradigm.
+     */
+    local?: boolean;
+    /**
+     * - Minimum value of the parameter. Only applies
+     * for `integer` and `float` types.
+     */
+    min?: number;
+    /**
+     * - Maximum value of the parameter. Only applies
+     * for `integer` and `float` types.
+     */
+    max?: number;
+    /**
+     * - Possible values of the parameter. Only applies and
+     * mandatory for `enum` type.
+     */
+    list?: Array<any>;
+    /**
+     * - Optional metadata of the parameter.
+     */
+    metas?: object;
+};

package/types/common/sockets-utils.d.ts

@@ -1,9 +1,4 @@
 /** @private */
-export function packBinaryMessage(channel: any, data: any): ArrayBufferLike;
-/** @private */
-export function unpackBinaryMessage(buffer: any): any[];
-/** @private */
 export function packStringMessage(channel: any, ...args: any[]): string;
 /** @private */
 export function unpackStringMessage(data: any): any;
-//# sourceMappingURL=sockets-utils.d.ts.map

package/types/common/version.d.ts

@@ -0,0 +1,2 @@
+declare const _default: "5.0.0";
+export default _default;

package/types/server/Server.d.ts

@@ -1,142 +1,198 @@
+export const kServerOnSocketConnection: unique symbol;
+export const kServerIsValidConnectionToken: unique symbol;
+export const kServerOnStatusChangeCallbacks: unique symbol;
 export default Server;
 /**
- * Server side entry point for a `soundworks` application.
+ * The `Server` class is the main entry point for soundworks server-side project.
  *
- * This object hosts configuration informations, as well as methods to
- * initialize and start the application. It is also responsible for creating
- * the static file (http) server as well as the socket server.
+ * The `Server` instance allows to access soundworks components such as {@link ServerStateManager},
+ * {@link ServerPluginManager}, {@link ServerSocket} or {@link ServerContextManager}.
+ * Its is also responsible for handling the initialization lifecycle of the different
+ * soundworks components.
  *
- * @memberof server
- *
- * @param {server.ServerConfig} config
- * @example
+ * ```
  * import { Server } from '@soundworks/core/server';
+ *
  * const server = new Server({
  *   app: {
  *     name: 'my-example-app',
- *     clients: { myClient: { target: 'node' } },
+ *     clients: {
+ *       player: { runtime: 'browser', default: true },
+ *       controller: { runtime: 'browser' },
+ *       thing: { runtime: 'node' }
+ *     },
  *   },
  *   env: {
- *     port: 8888,
+ *     port: 8000,
  *   },
  * });
- * await server.init();
+ *
  * await server.start();
+ * ```
  */
 declare class Server {
-    constructor(config: any);
     /**
-     * Configuration informations.
-     * Defaults to:
-     * ```
+     * @param {ServerConfig} config - Configuration object for the server.
+     * @throws
+     * - If `config.app.clients` is empty.
+     * - If a `node` client is defined but `config.env.serverAddress` is not defined.
+     * - if `config.env.useHttps` is `true` and `config.env.httpsInfos` is not `null`
+     *   (which generates self signed certificated), `config.env.httpsInfos.cert` and
+     *   `config.env.httpsInfos.key` should point to valid cert files.
+     */
+    constructor(config: ServerConfig);
+    /**
+     * Given config object merged with the following defaults:
+     * @example
      * {
      *   env: {
      *     type: 'development',
      *     port: 8000,
-     *     subfolder: '',
+     *     serverAddress: null,
+     *     baseUrl: '',
      *     useHttps: false,
      *     httpsInfos: null,
+     *     crossOriginIsolated: true,
+     *     verbose: true,
      *   },
      *   app: {
      *     name: 'soundworks',
      *     clients: {},
-     *   },
+     *   }
      * }
-     * ```
+     * @type {ServerConfig}
      */
-    config: any;
+    get config(): ServerConfig;
     /**
-     * Router. Internally use polka.
-     * (cf. {@link https://github.com/lukeed/polka})
+     * Package version.
+     *
+     * @type {string}
      */
-    router: any;
+    get version(): string;
     /**
-     * Http(s) server instance. The node `http` or `https` module instance
-     * (cf. {@link https://nodejs.org/api/http.html})
+     * Id of the server, a constant set to `-1`
+     * @type {number}
+     * @readonly
      */
-    httpServer: any;
+    readonly get id(): number;
     /**
-     * Key / value storage with Promise based Map API
-     * basically a wrapper around kvey (cf. {@link https://github.com/lukechilds/keyv})
-     * @private
+     * Status of the server.
+     *
+     * @type {'idle'|'inited'|'started'|'errored'}
+     */
+    get status(): "idle" | "inited" | "started" | "errored";
+    set router(router: any);
+    /**
+     * Instance of the router if any.
+     *
+     * The router can be used to open new route, for example to expose a directory
+     * of static assets (in default soundworks applications only the `public` is exposed).
+     *
+     * @example
+     * import { Server } from '@soundworks/core/server.js';
+     * import { loadConfig, configureHttpRouter } from '@soundworks/helpers/server.js';
+     *
+     * // create the server instance
+     * const server = new Server(loadConfig());
+     * // configure the express router provided by the helpers
+     * configureHttpRouter(server);
+     *
+     * // expose assets located in the `soundfiles` directory on the network
+     * server.router.use('/soundfiles', express.static('soundfiles')));
      */
-    private db;
+    get router(): any;
     /**
-     * The {@link server.Sockets} instance. A small wrapper around
-     * [`ws`](https://github.com/websockets/ws) server.
-     * @see {@link server.Sockets}
-     * @type {server.Sockets}
+     * Instance of the Node.js `http.Server` or `https.Server`
+     *
+     * @see {@link https://nodejs.org/api/http.html#class-httpserver}
+     * @see {@link https://nodejs.org/api/https.html#class-httpsserver}
      */
-    sockets: server.Sockets;
+    get httpServer(): any;
     /**
-     * The {@link server.PluginManager} instance.
-     * @see {@link server.PluginManager}
-     * @type {server.PluginManager}
+     * Simple key / value filesystem database with Promise based Map API.
+     *
+     * Basically a tiny wrapper around the {@link https://github.com/lukechilds/keyv} package.
      */
-    pluginManager: server.PluginManager;
+    get db(): any;
     /**
-     * The {@link server.StateManager} instance.
-     * @see {@link server.StateManager}
-     * @type {server.StateManager}
+     * Instance of the {@link ServerSockets} class.
+     *
+     * @type {ServerSockets}
      */
-    stateManager: server.StateManager;
+    get sockets(): ServerSockets;
     /**
-     * The {@link server.ContextManager} instance.
+     * Instance of the {@link ServerPluginManager} class.
      *
+     * @type {ServerPluginManager}
      */
-    contextManager: ContextManager;
+    get pluginManager(): ServerPluginManager<any>;
     /**
-     * If https is required, will contain informations about the certificates
-     * (self-signed, validity dates, etc.)
+     * Instance of the {@link ServerStateManager} class.
+     *
+     * @type {ServerStateManager}
      */
-    httpsInfos: {
-        selfSigned: boolean;
-        CN: any;
-        altNames: any;
-        validFrom: any;
-        validTo: any;
-        isValid: boolean;
-        daysRemaining: number;
-    } | {
-        selfSigned: boolean;
-        CN?: undefined;
-        altNames?: undefined;
-        validFrom?: undefined;
-        validTo?: undefined;
-        isValid?: undefined;
-        daysRemaining?: undefined;
-    } | {
-        selfSigned: boolean;
-        CN?: undefined;
-        altNames?: undefined;
-        validFrom?: undefined;
-        validTo?: undefined;
-        isValid?: undefined;
-        daysRemaining?: undefined;
-    };
+    get stateManager(): ServerStateManager;
     /**
-     * Current status of the server ['idle', 'inited', 'started']
+     * Instance of the {@link ServerContextManager} class.
+     *
+     * @type {ServerContextManager}
      */
-    status: string;
-    /** @private */
-    private _applicationTemplateConfig;
-    /** @private */
-    private _onStatusChangeCallbacks;
-    /** @private */
-    private _auditState;
+    get contextManager(): ServerContextManager<any>;
     /**
-     * Method to be called before `start` in the initialization lifecycle of the
-     * soundworks server. Note that if `init()`` is not explicitely called, `start()`
-     *  will call it implicitely.
+     * Register a callback to execute when status change.
+     *
+     * Status are dispatched in the following order:
+     * - 'http-server-ready'
+     * - 'inited'
+     * - 'started'
+     * - 'stopped'
+     * during the lifecycle of the server. If an error occurs the 'errored' status is propagated.
+     *
+     * @param {function} callback
+     */
+    onStatusChange(callback: Function): () => boolean;
+    /**
+     * Attach and retrieve the global audit state of the application.
+     *
+     * The audit state is a {@link SharedState} instance that keeps track of
+     * global information about the application such as, the number of connected
+     * clients, network latency estimation, etc.
+     *
+     * The audit state is created by the server on start up.
+     *
+     * @returns {Promise<SharedState>}
+     * @throws Will throw if called before `server.init()`
+     *
+     * @example
+     * const auditState = await server.getAuditState();
+     * auditState.onUpdate(() => console.log(auditState.getValues()), true);
+     */
+    getAuditState(): Promise<SharedState>;
+    /**
+     * The `init` method is part of the initialization lifecycle of the `soundworks`
+     * server. Most of the time, the `init` method will be implicitly called by the
+     * {@link Server#start} method.
+     *
+     * In some situations you might want to call this method manually, in such cases
+     * the method should be called before the {@link Server#start} method.
      *
      * What it does:
-     * - create the audit state
-     * - prepapre http(s) server and routing according to the informations
-     * declared in `config.app.clients`
-     * - starts all registered plugins
+     * 1) Create the audit state
+     * 2) Create the HTTP(s) server
+     * 3) Initialize registered plugins
      *
-     * After `await server.init()`, you can safely use the StateManager, as well
-     * as any registered Plugins.
+     * Between steps 2 and 3, the 'http-server-ready' event status is dispatched so
+     * that consumer code can register its router before plugin initialization:
+     * ```js
+     * server.onStatusChange(status => {
+     *   if (status === 'http-server-ready') {
+     *     server.httpServer.on('request', router);
+     *   }
+     * });
+     * ```
+     *
+     * After `await server.init()` is fulfilled, the {@link Server#stateManager}
+     * and all registered plugins can be safely used.
      *
      * @example
      * const server = new Server(config);
@@ -144,38 +200,77 @@ declare class Server {
      * await server.start();
      * // or implicitly called by start
      * const server = new Server(config);
-     * await server.start(); // init is called implicitely
+     * await server.start(); // init is called implicitly
      */
     init(): Promise<void>;
     /**
-     * Method to be called when `init` step is done in the initialization
-     * lifecycle of the soundworks server. If `server.init()` has not been called
-     * explicitely, `server.start()` will call it automatically.
+     * The `start` method is part of the initialization lifecycle of the `soundworks`
+     * server. The `start` method will implicitly call the {@link Server#init}
+     * method if it has not been called manually.
      *
      * What it does:
-     * - starts all registered contexts (context are automatically registered
-     * when instantiated)
-     * - start the web socket server
-     * - launch the HTTP server on given port
+     * - implicitly call {@link Server#init} if not done manually
+     * - launch the HTTP and WebSocket servers
+     * - start all created contexts. To this end, you will have to call `server.init`
+     * manually and instantiate the contexts between `server.init()` and `server.start()`
+     *
+     * After `await server.start()` the server is ready to accept incoming connections
      *
-     * After `await server.start()` the server is ready to accept incoming connexions
+     * @example
+     * import { Server } from '@soundworks/core/server.js'
+     *
+     * const server = new Server(config);
+     * await server.start();
      */
     start(): Promise<any>;
     /**
-     * Stop the server, close all existing WebSocket connections.
-     * Mainly usefull for test.
+     * Stops all started contexts, plugins, close all the socket connections and
+     * the http(s) server.
+     *
+     * In most situations, you might not need to call this method. However, it can
+     * be useful for unit testing or similar situations where you want to create
+     * and delete several servers in the same process.
+     *
+     * @example
+     * import { Server } from '@soundworks/core/server.js'
+     *
+     * const server = new Server(config);
+     * await server.start();
+     *
+     * await new Promise(resolve => setTimeout(resolve, 1000));
+     * await server.stop();
      */
     stop(): Promise<void>;
+    onClientConnect(callback: any): () => boolean;
+    onClientDisconnect(callback: any): () => boolean;
+    /** @private */
+    private isProtectedClientRole;
     /**
-     * Open the route for a given client.
-     * @private
+     * Generate a token to secure client connection.
+     *
+     * The token should be passed to the client-side `Client` config object, it will
+     * be internally used to check the WebSocket connection and reject it if the
+     * token is invalid.
      */
-    private _openClientRoute;
+    generateAuthToken(req: any): string;
     /**
-     * Socket connection callback.
-     * @private
+     * Check if the given client is trusted, i.e. config.env.type == 'production'
+     * and the client is protected behind a password.
+     *
+     * @param {ServerClient} client - Client to be tested
+     * @returns {boolean}
      */
-    private _onSocketConnection;
+    isTrustedClient(client: ServerClient): boolean;
+    /**
+     * Check if the token from a client is trusted, i.e. config.env.type == 'production'
+     * and the client is protected behind a password.
+     *
+     * @param {number} clientId - Id of the client
+     * @param {string} clientIp - Ip of the client
+     * @param {string} token - Token to be tested
+     * @returns {boolean}
+     */
+    isTrustedToken(clientId: number, clientIp: string, token: string): boolean;
     /**
      * Create namespaced databases for core and plugins
      * (kind of experimental API do not expose in doc for now)
@@ -185,39 +280,23 @@ declare class Server {
      * @private
      */
     private createNamespacedDb;
-    onStatusChange(callback: any): () => boolean;
-    /** @private */
-    private _dispatchStatus;
-    /**
-     * Configure the server to work out-of-the box with the soundworks-template
-     * directory tree structure.
-     *
-     * - uses [template-literal](https://www.npmjs.com/package/template-literal) package
-     * as html templateEngine
-     * - define `.build/server/tmpl` as the directory in which html template can be
-     * found
-     * - define the `clientConfigFunction` function that return client compliant
-     * config object to be injected in the html template.
-     *
-     * Also expose two public directory:
-     * - the `public` directory which is exposed behind the root path
-     * - the `./.build/public` directory which is exposed behind the `build` path
-     */
-    setDefaultTemplateConfig(): void;
     /**
-     * Define your own template path, template engine, and clientConfig function.
-     * This method is for very advanced use-cases and only be used if you know what
-     * you are doing. As such its behavior could probably be improved a lot...
-     *
-     * If you end up using this, please contact me to explain your use-case :)
+     * @deprecated
      */
-    setCustomTemplateConfig(options: any): void;
+    useDefaultApplicationTemplate(): void;
     /**
-     * Get the global audit state of the application.
-     *
-     * @throws Will throw if called before `server.init()`
+     * Socket connection callback.
+     * @private
      */
-    getAuditState(): Promise<any>;
+    private [kServerOnSocketConnection];
+    /** @private */
+    private [kServerIsValidConnectionToken];
+    /** @private */
+    private [kServerOnStatusChangeCallbacks];
+    #private;
 }
-import ContextManager from "./ContextManager.js";
-//# sourceMappingURL=Server.d.ts.map
+import ServerSockets from './ServerSockets.js';
+import ServerPluginManager from './ServerPluginManager.js';
+import ServerStateManager from './ServerStateManager.js';
+import ServerContextManager from './ServerContextManager.js';
+import ServerClient from './ServerClient.js';

package/types/server/ServerClient.d.ts

@@ -0,0 +1,45 @@
+export const kServerClientToken: unique symbol;
+export default ServerClient;
+/**
+ * Server-side representation of a client.
+ *
+ * @hideconstructor
+ * @see {@link Client}
+ */
+declare class ServerClient {
+    /**
+     * @param {String} role - Role of the client
+     * @param {ServerSocket} socket - Socket connection with the client
+     */
+    constructor(role: string, socket: ServerSocket);
+    /**
+     * Client role, as specified in client side config {@link Client}.
+     *
+     * @type {String}
+     */
+    get role(): string;
+    /**
+     * Session Id (incremented positive number).
+     *
+     * @type {Number}
+     */
+    get id(): number;
+    /**
+     * Unique session Id (uuidv4).
+     *
+     * @type {String}
+     */
+    get uuid(): string;
+    /**
+     * Socket connection with the remote {@link Client}.
+     *
+     * @type {ServerSocket}
+     */
+    get socket(): ServerSocket;
+    /**
+     * Set in `server[kServerOnSocketConnection]`
+     * @private
+     */
+    private [kServerClientToken];
+    #private;
+}