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

package/types/server/Server.d.ts

@@ -1,14 +1,15 @@
+export const kServerOnSocketConnection: unique symbol;
+export const kServerIsProtectedRole: unique symbol;
+export const kServerIsValidConnectionToken: unique symbol;
+export const kServerOnStatusChangeCallbacks: unique symbol;
+export const kServerApplicationTemplateOptions: unique symbol;
 export default Server;
-/**
- * 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.
  *
- * The `Server` instance allows to access soundworks components such as {@link server.StateManager},
- * {@link server.PluginManager},{@link server.Socket} or {@link server.ContextManager}.
+ * 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 lifecycles of the different
  * soundworks components.
  *
@@ -47,12 +48,10 @@ export type ServerConfig = any;
  * 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 {
     /**
-     * @param {server.ServerConfig} config - Configuration object for the server.
+     * @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.
@@ -60,9 +59,9 @@ declare class Server {
      *   (which generates self signed certificated), `config.env.httpsInfos.cert` and
      *   `config.env.httpsInfos.key` should point to valid cert files.
      */
-    constructor(config: server.ServerConfig);
+    constructor(config: ServerConfig);
     /**
-     * @description Given config object merged with the following defaults:
+     * Given config object merged with the following defaults:
      * @example
      * {
      *   env: {
@@ -70,10 +69,6 @@ declare class Server {
      *     port: 8000,
      *     serverAddress: null,
      *     subpath: '',
-     *     websockets: {
-     *       path: 'socket',
-     *       pingInterval: 5000,
-     *     },
      *     useHttps: false,
      *     httpsInfos: null,
      *     crossOriginIsolated: true,
@@ -84,9 +79,27 @@ declare class Server {
      *     clients: {},
      *   }
      * }
+     * @type {ServerConfig}
+     */
+    get config(): ServerConfig;
+    /**
+     * Package version.
+     *
+     * @type {string}
      */
-    config: any;
-    version: string;
+    get version(): string;
+    /**
+     * Id of the server, a constant set to -1
+     * @type {number}
+     * @readonly
+     */
+    readonly get id(): number;
+    /**
+     * Status of the server.
+     *
+     * @type {'idle'|'inited'|'started'|'errored'}
+     */
+    get status(): "idle" | "inited" | "started" | "errored";
     /**
      * Instance of the express router.
      *
@@ -104,112 +117,74 @@ declare class Server {
      * // expose assets located in the `soundfiles` directory on the network
      * server.router.use('/soundfiles', express.static('soundfiles')));
      */
-    router: any;
+    get router(): any;
     /**
      * 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;
+    get httpServer(): any;
     /**
-     * Instance of the {@link server.Sockets} class.
+     * Simple key / value filesystem database with Promise based Map API.
      *
-     * @see {@link server.Sockets}
-     * @type {server.Sockets}
+     * Basically a tiny wrapper around the {@link https://github.com/lukechilds/keyv} package.
      */
-    sockets: server.Sockets;
+    get db(): any;
     /**
-     * Instance of the {@link server.PluginManager} class.
+     * Instance of the {@link ServerSockets} class.
      *
-     * @see {@link server.PluginManager}
-     * @type {server.PluginManager}
+     * @type {ServerSockets}
      */
-    pluginManager: server.PluginManager;
+    get sockets(): ServerSockets;
     /**
-     * Instance of the {@link server.StateManager} class.
+     * Instance of the {@link ServerPluginManager} class.
      *
-     * @see {@link server.StateManager}
-     * @type {server.StateManager}
+     * @type {ServerPluginManager}
      */
-    stateManager: server.StateManager;
+    get pluginManager(): ServerPluginManager;
     /**
-     * Instance of the {@link server.ContextManager} class.
+     * Instance of the {@link ServerStateManager} class.
      *
-     * @see {@link server.ContextManager}
-     * @type {server.ContextManager}
-     */
-    contextManager: server.ContextManager;
-    /**
-     * If `https` is required, hold informations about the certificates, e.g. if
-     * self-signed, the dates of validity of the certificates, etc.
+     * @type {ServerStateManager}
      */
-    httpsInfos: {
-        selfSigned: boolean;
-        CN: string;
-        altNames: string[];
-        validFrom: string;
-        validTo: string;
-        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;
     /**
-     * Status of the server, 'idle', 'inited', 'started' or 'errored'.
+     * Instance of the {@link ServerContextManager} class.
      *
-     * @type {string}
+     * @type {ServerContextManager}
      */
-    status: string;
+    get contextManager(): ServerContextManager;
     /**
-     * Simple key / value database with Promise based Map API store on filesystem,
-     * basically a tiny wrapper around the `kvey` package.
+     * Register a callback to execute when status change
      *
-     * @private
-     * @see {@link https://github.com/lukechilds/keyv}
+     * @param {function} callback
      */
-    private db;
-    /** @private */
-    private _applicationTemplateOptions;
-    /** @private */
-    private _onStatusChangeCallbacks;
-    /** @private */
-    private _onClientConnectCallbacks;
-    /** @private */
-    private _onClientDisconnectCallbacks;
-    /** @private */
-    private _auditState;
-    /** @private */
-    private _pendingConnectionTokens;
-    /** @private */
-    private _trustedClients;
+    onStatusChange(callback: Function): () => any;
     /**
-     * Id of the server, a constant set to -1
-     * @type {Number}
-     * @readonly
+     * Attach and retrieve the global audit state of the application.
+     *
+     * 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.
+     *
+     * 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);
      */
-    readonly get id(): number;
+    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.Server#start} method.
+     * {@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.Server#start} method.
+     * the method should be called before the {@link Server#start} method.
      *
      * What it does:
      * - create the audit state
@@ -217,7 +192,7 @@ declare class Server {
      * declared in `config.app.clients`
      * - initialize all registered plugins
      *
-     * After `await server.init()` is fulfilled, the {@link server.Server#stateManager}
+     * After `await server.init()` is fulfilled, the {@link Server#stateManager}
      * and all registered plugins can be safely used.
      *
      * @example
@@ -231,11 +206,11 @@ declare class Server {
     init(): Promise<void>;
     /**
      * The `start` method is part of the initialization lifecycle of the `soundworks`
-     * server. The `start` method will implicitly call the {@link server.Server#init}
+     * server. The `start` method will implicitly call the {@link Server#init}
      * method if it has not been called manually.
      *
      * What it does:
-     * - implicitely call {@link server.Server#init} if not done manually
+     * - implicitely 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()`
@@ -267,18 +242,8 @@ declare class Server {
      * await server.stop();
      */
     stop(): Promise<void>;
-    /**
-     * Open the route for a given client.
-     * @private
-     */
-    private _openClientRoute;
     onClientConnect(callback: any): () => boolean;
     onClientDisconnect(callback: any): () => boolean;
-    /**
-     * Socket connection callback.
-     * @private
-     */
-    private _onSocketConnection;
     /**
      * Create namespaced databases for core and plugins
      * (kind of experimental API do not expose in doc for now)
@@ -288,9 +253,6 @@ declare class Server {
      * @private
      */
     private createNamespacedDb;
-    onStatusChange(callback: any): () => boolean;
-    /** @private */
-    private _dispatchStatus;
     /**
      * Configure the server to work _out-of-the-box_ within the soundworks application
      * template provided by `@soundworks/create.
@@ -317,35 +279,14 @@ declare class Server {
      * first to explain your use-case :)
      */
     setCustomApplicationTemplateOptions(options: any): void;
-    /**
-     * 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
+     * @param {ServerClient} client - Client to be tested
      * @returns {Boolean}
      */
-    isTrustedClient(client: server.Client): boolean;
+    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.
@@ -356,5 +297,10 @@ declare class Server {
      * @returns {Boolean}
      */
     isTrustedToken(clientId: number, clientIp: number, token: string): boolean;
+    #private;
 }
-//# 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 `soundworks` 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;
+    /**
+     * Is set in server[kServerOnSocketConnection]
+     * @private
+     */
+    private [kServerClientToken];
+    #private;
+}

package/types/server/{Context.d.ts → ServerContext.d.ts}

@@ -1,29 +1,31 @@
-export default Context;
+export const kServerContextStatus: unique symbol;
+export default ServerContext;
 /**
  * Base class to extend in order to implment the optionnal server-side counterpart
- * of a {@link client.Context}. If not defined, a default context will be created
+ * of a {@link ClientContext}. If not defined, a default context will be created
  * and used by the server.
  *
  * 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.). The
- * {@link client.Context} and optionnal {@link serverContext} abstractions provide
+ * {@link ClientContext} and optionnal {@link ServerContext} abstractions provide
  * a simple and unified way to model these reccuring aspects of an application.
  *
- * If a `server.Context` is recognized as the server-side counterpart of a
- * {@link client.Context}, based on their respective `name` (see {@link client.Context#name}
- * and {@link server.Context#name}), `soundworks` will ensure the logic defined
- * by the server-side Context will be executed at the beginning of the
- * {@link client.Client#enter} and {@link client.Client#exit} methods. The example
- * show how soundwords handles (and guarantees) the order of the `enter()` steps
- * between the client-side and the server-side parts of the context. The same goes
- * for the `exit()` method.
+ * If a `ServerContext` is recognized as the server-side counterpart of a
+ * {@link ClientContext}, based on their respective `name` (see {@link ClientContext#name}
+ * and {@link ServerContext#name}), `soundworks` will ensure the logic defined
+ * by the ServerContext will be executed at the beginning of the
+ * {@link ClientContext#enter} and {@link ClientContext#exit} methods.
  *
- * ```
+ * The example above shows how soundwords handles (and guarantees) the order of
+ * the `enter()` steps between the client-side and the server-side parts of the
+ * context. The same goes for the `exit()` method.
+ *
+ * ```js
  * // client-side
- * import { Context } from '@soundworks/core/client.js';
+ * import { ClientContext } from '@soundworks/core/client.js';
  *
- * class MyContext extends Context {
+ * class MyContext extends ClientContext {
  *   async enter() {
  *     // 1. client side context enter() starts
  *     //    server-side logic is triggered first
@@ -44,11 +46,11 @@ export default Context;
  * await myContext.enter();
  * ```
  *
- * ```
+ * ```js
  * // server-side
- * import { Context } from '@soundworks/core/server.js';
+ * import { ServerContext } from '@soundworks/core/server.js';
  *
- * class MyContext extends Context {
+ * class MyContext extends ServerContext {
  *   async enter(client) {
  *     // 2. server-side context enter() starts
  *     await super.enter(client);
@@ -59,14 +61,12 @@ export default Context;
  * }
  *
  * // Instantiate the context
- * const myContext = new Context(server);
+ * const myContext = new MyContext(server);
  * ```
- *
- * @memberof server
  */
-declare class Context {
+declare class ServerContext {
     /**
-     * @param {client.Client} client - The soundworks client instance.
+     * @param {Server} server - The soundworks server instance.
      * @param {string|string[]} [roles=[]] - Optionnal list of client roles that can
      *  use this context. In large applications, this may be usefull to guarantee
      *  that a context can be consumed only by specific client roles, throwing an
@@ -74,34 +74,40 @@ declare class Context {
      *  will be used.
      * @throws Will throw if the first argument is not a soundworks server instance.
      */
-    constructor(server: any, roles?: string | string[]);
+    constructor(server: Server, roles?: string | string[]);
     /**
-     * soundworks server
-     * @type {server.Server}
-     * @readonly
+     * The soundworks server instance.
+     *
+     * @type {Server}
      */
-    readonly server: server.Server;
+    get server(): Server;
     /**
-     * List of clients that are currently in this context
-     * @type {server.Client[]}
+     * List of clients that are currently in this context.
+     *
+     * @type {Set<ServerClient>}
      */
-    clients: server.Client[];
+    get clients(): Set<ServerClient>;
+    /**
+     * List of client roles that can use this context. No access policy if empty.
+     *
+     * @type {Set<string>}
+     */
+    get roles(): Set<string>;
     /**
      * Status of the context ('idle', 'inited', 'started' or 'errored')
+     *
      * @type {string}
-     * @readonly
      */
-    readonly status: string;
-    roles: Set<string>;
+    get status(): string;
     /**
      * 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
      * @type {string}
+     *
      * @example
      * // server-side and client-side contexts are matched based on their respective `name`
      * class MyContext extends Context {
@@ -110,10 +116,10 @@ declare class Context {
      *   }
      * }
      */
-    readonly get name(): string;
+    get name(): string;
     /**
      * Start the context. This method is lazilly called when a client enters the
-     * context for the first time (cf. ${server.Context#enter}). If you know some
+     * context for the first time (cf. ${ServerContext#enter}). If you know some
      * some heavy and/or potentially long job has to be done  when starting the context
      * (e.g. connect to a database, parsing a long file) it may be a good practice
      * to call it explicitely.
@@ -155,7 +161,7 @@ declare class Context {
      *
      * _WARNING: this method should never be called manually._
      *
-     * @param {server.Client} client - Server-side representation of the client
+     * @param {ServerClient} client - Server-side representation of the client
      *  that enters the context.
      * @returns {Promise} - Promise that resolves when the context is entered.
      * @example
@@ -171,14 +177,14 @@ declare class Context {
      *   }
      * }
      */
-    enter(client: server.Client): Promise<any>;
+    enter(client: ServerClient): Promise<any>;
     /**
      * Exit the context. Implement this method to define the logic that should be
      * done (e.g. delete a shared state, etc.) when a client exits the context.
      *
      * * _WARNING: this method should never be called manually._
      *
-     * @param {server.Client} client - Server-side representation of the client
+     * @param {ServerClient} client - Server-side representation of the client
      *  that exits the context.
      * @returns {Promise} - Promise that resolves when the context is exited.
      * @example
@@ -194,6 +200,10 @@ declare class Context {
      *   }
      * }
      */
-    exit(client: server.Client): Promise<any>;
+    exit(client: ServerClient): Promise<any>;
+    /** @private */
+    private [kServerContextStatus];
+    #private;
 }
-//# sourceMappingURL=Context.d.ts.map
+import Server from './Server.js';
+import ServerClient from './ServerClient.js';

package/types/server/ServerContextManager.d.ts

@@ -0,0 +1,80 @@
+export const kServerContextManagerStart: unique symbol;
+export const kServerContextManagerStop: unique symbol;
+export const kServerContextManagerAddClient: unique symbol;
+export const kServerContextManagerRemoveClient: unique symbol;
+export const kServerContextManagerRegister: unique symbol;
+export const kServerContextManagerContexts: unique symbol;
+export default ServerContextManager;
+/**
+ * Manage the different server-side contexts and their lifecycle.
+ *
+ * The `ServerContextManager` is automatically instantiated by the {@link Server}.
+ *
+ * _WARNING: Most of the time, you should not have to manipulate the context manager directly._
+ *
+ * @hideconstructor
+ */
+declare class ServerContextManager {
+    /**
+     * @param {Server} server - Instance of the soundworks server.
+     */
+    constructor(server: Server);
+    /**
+     * Retrieve a started context from its name.
+     *
+     * _WARNING: Most of the time, you should not have to call this method manually._
+     *
+     * @param {ServerContext#name} contextName - Name of the context.
+     */
+    get(contextName: any): Promise<any>;
+    /**
+     * Register a context in the manager.
+     * This method is called in the {@link ServerContext} constructor
+     *
+     * @param {ServerContext} context - Context instance to register.
+     *
+     * @private
+     */
+    private [kServerContextManagerRegister];
+    /**
+     * Start all contexts registered before `await server.start()`.
+     * Called on {@link Server#start}
+     *
+     * @private
+     */
+    private [kServerContextManagerStart];
+    /**
+     * Stop all contexts. Called on {@link Server#stop}
+     *
+     * @private
+     */
+    private [kServerContextManagerStop];
+    /**
+     * Called when a client connects to the server (websocket handshake)
+     *
+     * @param {ServerClient} client
+     *
+     * @private
+     */
+    private [kServerContextManagerAddClient];
+    /**
+     * Called when a client connects to the server (websocket 'close' event)
+     *
+     * @param {ServerClient} client
+     *
+     * @private
+     */
+    private [kServerContextManagerRemoveClient];
+    [kServerContextManagerContexts]: ContextCollection;
+    #private;
+}
+/** @private */
+declare class ContextCollection {
+    get length(): number;
+    add(context: any): void;
+    has(name: any): boolean;
+    get(name: any): any;
+    map(func: any): any[];
+    filter(func: any): any[];
+    #private;
+}