@soundworks/core 4.0.0-alpha.21 → 4.0.0-alpha.23

package/types/server/Server.d.ts

@@ -1,100 +1,155 @@
 export default Server;
 /**
- * Server side entry point for a `soundworks` application.
+ * Configuration object for the server.
+ */
+export type ServerConfig = any;
+/**
+ * The `Server` class is the main entry point for the server-side of a soundworks
+ * application.
  *
- * 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 server.StateManager},
+ * {@link server.PluginManager},{@link server.Socket} or {@link server.ContextManager}.
+ * Its is also responsible for handling the initialization lifecycles 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: { target: 'browser', default: true },
+ *       controller: { target: 'browser' },
+ *       thing: { target: 'node' }
+ *     },
  *   },
  *   env: {
- *     port: 8888,
+ *     port: 8000,
  *   },
  * });
- * await server.init();
+ *
  * await server.start();
+ * ```
+ *
+ * According to the clients definitions provided in `config.app.clients`, the
+ * server will automatically create a dedicated route for each browser client role.
+ * For example, given the config object of the example above that defines two
+ * different client roles for browser targets (i.e. `player` and `controller`):
+ *
+ * ```
+ * config.app.clients = {
+ *   player: { target: 'browser', default: true },
+ *   controller: { target: 'browser' },
+ * }
+ * ```
+ *
+ * The server will listen to the following URLs:
+ * - `http://127.0.0.1:8000/` for the `player` role, which is defined as the default client.
+ * - `http://127.0.0.1:8000/controller` for the `controller` role.
+ *
+ * @memberof server
  */
 declare class Server {
-    constructor(config: any);
     /**
-     * Configuration informations.
-     * Defaults to:
-     * ```
+     * @param {server.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: server.ServerConfig);
+    /**
+     * @description Given config object merged with the following defaults:
+     * @example
      * {
      *   env: {
      *     type: 'development',
      *     port: 8000,
-     *     subfolder: '',
+     *     serverAddress: null,
+     *     subpath: '',
+     *     websockets: {
+     *       path: 'socket',
+     *       pingInterval: 5000,
+     *     },
      *     useHttps: false,
      *     httpsInfos: null,
+     *     crossOriginIsolated: true,
+     *     verbose: true,
      *   },
      *   app: {
      *     name: 'soundworks',
      *     clients: {},
-     *   },
+     *   }
      * }
-     * ```
      */
     config: any;
+    version: string;
     /**
-     * Router. Internally use polka.
-     * (cf. {@link https://github.com/lukeed/polka})
+     * Instance of the express router.
+     *
+     * 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).
+     *
+     * @see {@link https://github.com/expressjs/express}
+     * @example
+     * import { Server } from '@soundworks/core/server.js';
+     * import express from 'express';
+     *
+     * // create the soundworks server instance
+     * const server = new Server(config);
+     *
+     * // expose assets located in the `soundfiles` directory on the network
+     * server.router.use('/soundfiles', express.static('soundfiles')));
      */
     router: any;
     /**
-     * Http(s) server instance. The node `http` or `https` module instance
-     * (cf. {@link https://nodejs.org/api/http.html})
+     * Raw Node.js `http` or `https` instance
+     *
+     * @see {@link https://nodejs.org/api/http.html}
+     * @see {@link https://nodejs.org/api/https.html}
      */
     httpServer: any;
     /**
-     * Key / value storage with Promise based Map API
-     * basically a wrapper around kvey (cf. {@link https://github.com/lukechilds/keyv})
-     * @private
-     */
-    private db;
-    /**
-     * The {@link server.Sockets} instance. A small wrapper around
-     * [`ws`](https://github.com/websockets/ws) server.
+     * Instance of the {@link server.Sockets} class.
+     *
      * @see {@link server.Sockets}
      * @type {server.Sockets}
      */
     sockets: server.Sockets;
     /**
-     * The {@link server.PluginManager} instance.
+     * Instance of the {@link server.PluginManager} class.
+     *
      * @see {@link server.PluginManager}
      * @type {server.PluginManager}
      */
     pluginManager: server.PluginManager;
     /**
-     * The {@link server.StateManager} instance.
+     * Instance of the {@link server.StateManager} class.
+     *
      * @see {@link server.StateManager}
      * @type {server.StateManager}
      */
     stateManager: server.StateManager;
     /**
-     * The {@link server.ContextManager} instance.
+     * Instance of the {@link server.ContextManager} class.
      *
+     * @see {@link server.ContextManager}
+     * @type {server.ContextManager}
      */
-    contextManager: ContextManager;
+    contextManager: server.ContextManager;
     /**
-     * If https is required, will contain informations about the certificates
-     * (self-signed, validity dates, etc.)
+     * If `https` is required, hold informations about the certificates, e.g. if
+     * self-signed, the dates of validity of the certificates, etc.
      */
     httpsInfos: {
         selfSigned: boolean;
-        CN: any;
-        altNames: any;
-        validFrom: any;
-        validTo: any;
+        CN: string;
+        altNames: string[];
+        validFrom: string;
+        validTo: string;
         isValid: boolean;
         daysRemaining: number;
     } | {
@@ -115,28 +170,55 @@ declare class Server {
         daysRemaining?: undefined;
     };
     /**
-     * Current status of the server ['idle', 'inited', 'started']
+     * Status of the server, 'idle', 'inited', 'started' or 'errored'.
+     *
+     * @type {string}
      */
     status: string;
+    /**
+     * Simple key / value database with Promise based Map API store on filesystem,
+     * basically a tiny wrapper around the `kvey` package.
+     *
+     * @private
+     * @see {@link https://github.com/lukechilds/keyv}
+     */
+    private db;
     /** @private */
-    private _applicationTemplateConfig;
+    private _applicationTemplateOptions;
     /** @private */
     private _onStatusChangeCallbacks;
     /** @private */
+    private _onClientConnectCallbacks;
+    /** @private */
+    private _onClientDisconnectCallbacks;
+    /** @private */
     private _auditState;
+    /** @private */
+    private _pendingConnectionTokens;
+    /** @private */
+    private _trustedClients;
     /**
-     * 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.
+     * Id of the server, a constant set to -1
+     * @type {Number}
+     * @readonly
+     */
+    readonly get id(): number;
+    /**
+     * 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.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.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
+     * - initialize all registered plugins
      *
-     * After `await server.init()`, you can safely use the StateManager, as well
-     * as any registered Plugins.
+     * After `await server.init()` is fulfilled, the {@link server.Server#stateManager}
+     * and all registered plugins can be safely used.
      *
      * @example
      * const server = new Server(config);
@@ -148,22 +230,41 @@ declare class Server {
      */
     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.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
+     * - implicitely call {@link server.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 usefull 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>;
     /**
@@ -171,6 +272,8 @@ declare class Server {
      * @private
      */
     private _openClientRoute;
+    onClientConnect(callback: any): () => boolean;
+    onClientDisconnect(callback: any): () => boolean;
     /**
      * Socket connection callback.
      * @private
@@ -189,8 +292,8 @@ declare class Server {
     /** @private */
     private _dispatchStatus;
     /**
-     * Configure the server to work out-of-the box with the soundworks-template
-     * directory tree structure.
+     * Configure the server to work _out-of-the-box_ within the soundworks application
+     * template provided by `@soundworks/create.
      *
      * - uses [template-literal](https://www.npmjs.com/package/template-literal) package
      * as html templateEngine
@@ -202,22 +305,56 @@ declare class Server {
      * 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
+     *
+     * _Note: except in very rare cases (so rare that they are quite difficult to imagine),
+     * you should rely on these defaults._
      */
-    setDefaultTemplateConfig(): void;
+    useDefaultApplicationTemplate(): 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 :)
+     * Define custom template path, template engine, and clientConfig function.
+     * This method is proposed for very advanced use-cases and should very probably
+     * be improved. If you consider using this for some reason, please get in touch
+     * first to explain your use-case :)
      */
-    setCustomTemplateConfig(options: any): void;
+    setCustomApplicationTemplateOptions(options: any): void;
     /**
-     * Get the global audit state of the application.
+     * Attach and retrieve the global audit state of the application.
+     *
+     * The audit state is a {@link server.SharedState} instance that keeps track of
+     * global informations 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<server.SharedState>}
      * @throws Will throw if called before `server.init()`
+     * @see {@link server.SharedState}
+     * @example
+     * const auditState = await server.getAuditState();
+     * auditState.onUpdate(() => console.log(auditState.getValues()), true);
+     */
+    getAuditState(): Promise<server.SharedState>;
+    /** @private */
+    private isProtected;
+    /** @private */
+    private isValidConnectionToken;
+    /**
+     * Check if the given client is trusted, i.e. config.env.type == 'production'
+     * and the client is protected behind a password.
+     *
+     * @param {server.Client} client - Client to be tested
+     * @returns {Boolean}
+     */
+    isTrustedClient(client: server.Client): 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 {Number} clientIp - Ip of the client
+     * @param {String} token - Token to be tested
+     * @returns {Boolean}
      */
-    getAuditState(): Promise<any>;
+    isTrustedToken(clientId: number, clientIp: number, token: string): boolean;
 }
-import ContextManager from "./ContextManager.js";
 //# sourceMappingURL=Server.d.ts.map

package/types/server/Server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Server.d.ts","sourceRoot":"","sources":["../../src/server/Server.js"],"names":[],"mappings":";AA2EA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;IACE,yBA2IC;IAvIC;;;;;;;;;;;;;;;;;;OAkBG;IACH,YAA+C;IAuC/C;;;OAGG;IACH,YAAuB;IAIvB;;;OAGG;IACH,gBAAsB;IAEtB;;;;OAIG;IACH,WAAyC;IAEzC;;;;;OAKG;IACH,wBAA4B;IAE5B;;;;OAIG;IACH,oCAA4C;IAE5C;;;;OAIG;IACH,kCAAsC;IAEtC;;;OAGG;IACH,+BAA8C;IAE9C;;;OAGG;IACH;;;;;;;;;;;;;;;;;;;;;;;;MAAsB;IAEtB;;OAEG;IACH,eAAoB;IAEpB,eAAe;IACf,mCAIC;IAED,eAAe;IACf,iCAAyC;IACzC,eAAe;IACf,oBAAuB;IASzB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,sBAwMC;IAED;;;;;;;;;;;;OAYG;IACH,sBAoFC;IAGD;;;OAGG;IACH,sBAgBC;IAED;;;OAGG;IACH,yBAgEC;IAED;;;OAGG;IACH,4BAmEC;IAED;;;;;;;OAOG;IACH,2BAmBC;IAED,6CAIC;IAED,eAAe;IACf,wBAgBC;IAED;;;;;;;;;;;;;;OAcG;IACH,iCAsBC;IAED;;;;;;OAMG;IACH,4CAEC;IAED;;;;OAIG;IACH,8BAMC;CACF"}
+{"version":3,"file":"Server.d.ts","sourceRoot":"","sources":["../../src/server/Server.js"],"names":[],"mappings":";;;;;AAuGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH;IACE;;;;;;;;OAQG;IACH,yCAoLC;IA/KC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,YAA+C;IAuC/C,gBAAsB;IAEtB;;;;;;;;;;;;;;;;OAgBG;IAGH,YAAuB;IAIvB;;;;;OAKG;IACH,gBAAsB;IAEtB;;;;;OAKG;IACH,wBAA4B;IAE5B;;;;;OAKG;IACH,oCAA4C;IAE5C;;;;;OAKG;IACH,kCAAsC;IAEtC;;;;;OAKG;IACH,sCAA8C;IAE9C;;;OAGG;IACH;;;;;;;;;;;;;;;;;;;;;;;;MAAsB;IAEtB;;;;OAIG;IACH,QAFU,MAAM,CAEI;IAEpB;;;;;;OAMG;IACH,WAAyC;IAEzC,eAAe;IACf,oCAIC;IAED,eAAe;IACf,iCAAyC;IACzC,eAAe;IACf,kCAA0C;IAC1C,eAAe;IACf,qCAA6C;IAC7C,eAAe;IACf,oBAAuB;IACvB,eAAe;IACf,iCAAyC;IACzC,eAAe;IACf,wBAAgC;IASlC;;;;OAIG;IACH,0BAEC;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,sBAgPC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,sBAwFC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,sBAgBC;IAED;;;OAGG;IACH,yBA2EC;IAED,8CAIC;IAED,iDAIC;IAED;;;OAGG;IACH,4BAkHC;IAED;;;;;;;OAOG;IACH,2BAmBC;IAED,6CAIC;IAED,eAAe;IACf,wBAgBC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,sCAkDC;IAED;;;;;OAKG;IACH,wDAEC;IAED;;;;;;;;;;;;;;;OAeG;IACH,iBAPa,2BAA2B,CAavC;IAED,eAAe;IACf,oBAMC;IAED,eAAe;IACf,+BAkBC;IAED;;;;;;OAMG;IACH,gDAMC;IAED;;;;;;;;OAQG;IAEH,2EAkBC;CACF"}

package/types/server/SharedState.d.ts

@@ -82,5 +82,5 @@ export namespace server {
  */
 declare class SharedState extends BaseSharedState {
 }
-import BaseSharedState from "../common/BaseSharedState.js";
+import BaseSharedState from '../common/BaseSharedState.js';
 //# sourceMappingURL=SharedState.d.ts.map

package/types/server/SharedState.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SharedState.d.ts","sourceRoot":"","sources":["../../src/server/SharedState.js"],"names":[],"mappings":";;;;;;;AAIA;;;;;;;;GAQG;AAEH;;;;GAIG;AAGH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH;CAA4C"}
+{"version":3,"file":"SharedState.d.ts","sourceRoot":"","sources":["../../src/server/SharedState.js"],"names":[],"mappings":";;;;;;;AAIA;;;;;;;;GAQG;AAEH;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH;CAA4C;4BAjFhB,8BAA8B"}

package/types/server/SharedStateCollection.d.ts

@@ -0,0 +1,41 @@
+export default SharedStateCollection;
+export namespace server {
+    /**
+     * ~onUpdateCallback
+     */
+    type SharedStateCollection = (state: server.SharedState, newValues: any, oldValues: any, context?: Mixed) => any;
+}
+/**
+ * @callback server.SharedStateCollection~onUpdateCallback
+ * @param {server.SharedState} state - State that triggered the update.
+ * @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.
+ */
+/**
+ * The `SharedStateCollection` interface represent a collection of all states
+ * created from a given schema name on the network.
+ *
+ * It can optionnaly exclude the states created by the current node.
+ *
+ * See {@link server.StateManager#getCollection} for factory method API
+ *
+ * ```
+ * const collection = await server.stateManager.getCollection('my-schema');
+ * const allValues = collection.getValues();
+ * collection.onUpdate((state, newValues, oldValues, context) => {
+ *   // do something
+ * });
+ * ```
+ * @memberof server
+ * @extends BaseSharedStateCollection
+ * @inheritdoc
+ * @hideconstructor
+ */
+declare class SharedStateCollection extends BaseSharedStateCollection {
+}
+import BaseSharedStateCollection from '../common/BaseSharedStateCollection.js';
+//# sourceMappingURL=SharedStateCollection.d.ts.map

package/types/server/SharedStateCollection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SharedStateCollection.d.ts","sourceRoot":"","sources":["../../src/server/SharedStateCollection.js"],"names":[],"mappings":";;;;;;;AAIA;;;;;;;;;GASG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH;CAAgE;sCAnC1B,wCAAwC"}