@soundworks/core 4.0.0-alpha.7 → 5.0.0

package/types/server/ServerContext.d.ts

@@ -0,0 +1,209 @@
+export const kServerContextStatus: unique symbol;
+export default ServerContext;
+/**
+ * Base class to extend in order to implement the optional server-side counterpart
+ * 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#role}) and can be in different "contexts" (e.g. different
+ * part of the experience such as sections of a music piece, etc.). The
+ * {@link ClientContext} and optional {@link ServerContext} abstractions provide
+ * a simple and unified way to model these recurring aspects of an application.
+ *
+ * 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 the order of  the `enter()` steps between the client-side
+ * and the server-side parts of a `context` is handled and guaranteed. The same goes for
+ * the `exit()` method.
+ *
+ * ```js
+ * // client-side
+ * import { ClientContext } from '@soundworks/core/client.js';
+ *
+ * class MyContext extends ClientContext {
+ *   async enter() {
+ *     // 1. client side context enter() starts
+ *     //    server-side logic is triggered first
+ *     await super.enter();
+ *     // 4. server-side context enter() is fully done
+ *     // some async job can be done here
+ *     await new Promise(resolve => setTimeout(resolve, 1000));
+ *     // 5. client-side context enter() ends
+ *   }
+ * }
+ *
+ * // Instantiate the context (assuming the `client.role` is 'test')
+ * const myContext = new MyContext(client);
+ *
+ * // At some point in the application, the client enters the context triggering
+ * // the steps 1 to 5 described in the client-side and server-side `enter()`
+ * // implementations. Note that the server-side `enter()` is never called manually.
+ * await myContext.enter();
+ * ```
+ *
+ * ```js
+ * // server-side
+ * import { ServerContext } from '@soundworks/core/server.js';
+ *
+ * class MyContext extends ServerContext {
+ *   async enter(client) {
+ *     // 2. server-side context enter() starts
+ *     await super.enter(client);
+ *     // some async job can be done here
+ *     await new Promise(resolve => setTimeout(resolve, 1000));
+ *     // 3. server-side context enter() ends
+ *   }
+ * }
+ *
+ * // Instantiate the context
+ * const myContext = new MyContext(server);
+ * ```
+ */
+declare class ServerContext {
+    /**
+     * @param {Server} server - The soundworks server instance.
+     * @param {string|string[]} [roles=[]] - Optional list of client roles that can
+     *  use this context. In large applications, this may be useful to guarantee
+     *  that a context can be consumed only by specific client roles, throwing an
+     *  error if any other client role tries to use it. If empty, no access policy
+     *  will be used.
+     * @throws Will throw if the first argument is not a soundworks server instance.
+     */
+    constructor(server: Server, roles?: string | string[]);
+    /**
+     * The soundworks server instance.
+     *
+     * @type {Server}
+     */
+    get server(): Server;
+    /**
+     * List of clients that are currently in this context.
+     *
+     * @type {Set<ServerClient>}
+     */
+    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}
+     */
+    get status(): string;
+    /**
+     * Optional 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 ServerContextManager} don't find a corresponding
+     * user-defined context with the same name, it will use a default (noop) context.
+     *
+     * @type {string}
+     *
+     * @example
+     * // server-side and client-side contexts are matched based on their respective `name`
+     * class MyContext extends Context {
+     *   get name() {
+     *     return 'my-user-defined-context-name';
+     *   }
+     * }
+     */
+    get name(): string;
+    /**
+     * Start the context. This method is lazily called when a client enters the
+     * 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 explicitly.
+     *
+     * This method should be implemented to perform operations that are valid for the
+     * whole lifetime of the context, regardless a client enters or exits the context.
+     *
+     * @example
+     * import { Context } from '@soundworks/core/server.js';
+     *
+     * class MyContext extends Context {
+     *   async start() {
+     *     await super.start();
+     *     await this.doSomeLongJob();
+     *   }
+     * }
+     *
+     * // Instantiate the context
+     * const myContext = new Context(server, ['test']);
+     * // manually start the context to perform the long operation before the first
+     * // client enters the context
+     * await myContext.start();
+     * ```
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the context. The method that is automatically called when the server
+     * stops. It should be used to cleanup context wise operations made in `start()`
+     * (e.g. disconnect from a database, release a file handle).
+     *
+     * _WARNING: this method should never be called manually._
+     */
+    stop(): Promise<void>;
+    /**
+     * Enter the context. Implement this method to define the logic that should be
+     * done (e.g. creating a shared state, etc.) when a client enters the context.
+     *
+     * If the context has not been started yet, the `start` method is implicitly executed.
+     *
+     * _WARNING: this method should never be called manually._
+     *
+     * @param {ServerClient} client - Server-side representation of the client
+     *  that enters the context.
+     * @returns {Promise} - Promise that resolves when the context is entered.
+     * @example
+     * class MyContext extends Context {
+     *   async enter(client) {
+     *     await super.enter(client);
+     *     registerTheClientSomewhere(client);
+     *   }
+     *
+     *   async exit(client) {
+     *     await super.exit(client);
+     *     unregisterTheClientSomewhere(client);
+     *   }
+     * }
+     */
+    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 {ServerClient} client - Server-side representation of the client
+     *  that exits the context.
+     * @returns {Promise} - Promise that resolves when the context is exited.
+     * @example
+     * class MyContext extends Context {
+     *   async enter(client) {
+     *     await super.enter(client);
+     *     this.state = await this.client.stateManager.create('my-context-state');
+     *   }
+     *
+     *   async exit(client) {
+     *     await super.exit(client);
+     *     await this.state.delete();
+     *   }
+     * }
+     */
+    exit(client: ServerClient): Promise<any>;
+    /** @private */
+    private [kServerContextStatus];
+    #private;
+}
+import Server from './Server.js';
+import ServerClient from './ServerClient.js';

package/types/server/ServerContextManager.d.ts

@@ -0,0 +1,75 @@
+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._
+ *
+ * @template T
+ */
+declare class ServerContextManager<T> {
+    /**
+     * @param {Server} server - Instance of the soundworks server.
+     * @hideconstructor
+     */
+    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 {string} contextName - Name of the context.
+     * @return {Promise<T<ServerContext>>}
+     */
+    get(contextName: string): Promise<T<ServerContext>>;
+    /**
+     * 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];
+    /** @private */
+    private [kServerContextManagerContexts];
+    #private;
+}
+import ServerContext from './ServerContext.js';
+import Server from './Server.js';

package/types/server/ServerPlugin.d.ts

@@ -0,0 +1,57 @@
+export default ServerPlugin;
+/**
+ * Base class to extend in order to create the server-side counterpart of a
+ * `soundworks` plugin.
+ *
+ * In the `soundworks` paradigm, a plugin is a component that allows to extend
+ * the framework capabilities by encapsulating common and reusable logic in
+ * an application wise perspective. For example, plugins are available to handle
+ * clock synchronization, to deal with the file system, etc. Plugin should always
+ * have both a client-side and a server-side part.
+ *
+ * See [https://soundworks.dev/guide/ecosystem](https://soundworks.dev/guide/ecosystem)
+ * for more information on the available plugins.
+ *
+ * _Creating new plugins should be considered an advanced usage._
+ *
+ * @extends {BasePlugin}
+ * @inheritdoc
+ */
+declare class ServerPlugin extends BasePlugin {
+    /**
+     * @param {Server} server - The soundworks server instance.
+     * @param {string} id - User defined id of the plugin as defined in
+     *  {@link ServerPluginManager#register}.
+     */
+    constructor(server: Server, id: string);
+    /**
+     * Instance of soundworks server.
+     * @type {Server}
+     * @see {@link Server}
+     */
+    get server(): Server;
+    /**
+     * Set of the clients registered in the plugin.
+     * @type {Set<ServerClient>}
+     * @see {@link ServerClient}
+     */
+    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 {ServerClient} client
+     */
+    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 {ServerClient} client
+     */
+    removeClient(client: ServerClient): Promise<void>;
+    #private;
+}
+import BasePlugin from '../common/BasePlugin.js';

package/types/server/ServerPluginManager.d.ts

@@ -0,0 +1,115 @@
+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#start} or {@link Server#start}
+ * to be properly initialized.
+ *
+ * In some situations, you might want to register the same plugin factory several times
+ * using different ids (e.g. for watching several parts of the file system, etc.).
+ *
+ * Refer to the plugins' documentation for more precise examples, and the specific API
+ * they expose. See [https://soundworks.dev/guide/ecosystem](https://soundworks.dev/guide/ecosystem)
+ * for more information on the available plugins.
+ *
+ * ```
+ * // client-side
+ * import { Client } from '@soundworks/core/client.js';
+ * import syncPlugin from '@soundworks/plugin-sync/client.js';
+ *
+ * const client = new Client(config);
+ * // register the plugin before `client.start()`
+ * client.pluginManager.register('sync', syncPlugin);
+ *
+ * await client.start();
+ *
+ * const sync = await client.pluginManager.get('sync');
+ *
+ * setInterval(() => {
+ *   // log the estimated global synced clock alongside the local clock.
+ *   console.log(sync.getSyncTime(), sync.getLocalTime());
+ * }, 1000);
+ * ```
+ *
+ * ```
+ * // server-side
+ * import { Server } from '@soundworks/core/server.js';
+ * import syncPlugin from '@soundworks/plugin-sync/server.js';
+ *
+ * const server = new Server(config);
+ * // register the plugin before `server.start()`
+ * server.pluginManager.register('sync', syncPlugin);
+ *
+ * await server.start();
+ *
+ * const sync = await server.pluginManager.get('sync');
+ *
+ * setInterval(() => {
+ *   // log the estimated global synced clock alongside the local clock.
+ *   console.log(sync.getSyncTime(), sync.getLocalTime());
+ * }, 1000);
+ * ```
+ *
+ * @extends BasePluginManager
+ * @inheritdoc
+ * @template T
+ */
+declare class ServerPluginManager<T> extends BasePluginManager {
+    /** @hideconstructor */
+    constructor(server: any);
+    /**
+     * 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 {T<ServerPlugin>} ctor - The server-side Class of the plugin.
+     * @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, ctor: T<ServerPlugin>, options?: object, deps?: any[]): void;
+    /**
+     * 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
+     * to be stuck in some kind of Promise dead lock, this method will throw if
+     * used before `server.init()` (or `server.start()`).
+     *
+     * To handle the remaining 0.01% cases and access plugin instances during their
+     * initialization (e.g. to display initialization screen, etc.), you should rely
+     * on the `onStateChange` method.
+     *
+     * _Note: the async API is designed to enable the dynamic creation of plugins
+     * (hopefully without breaking changes) in a future release._
+     *
+     * @param {ServerPlugin#id} id - Id of the plugin as defined when registered.
+     * @returns {Promise<T<ServerPlugin>>}
+     */
+    get(id: any): Promise<T<ServerPlugin>>;
+    /** @private */
+    private [kServerPluginManagerCheckRegisteredPlugins];
+    /** @private */
+    private [kServerPluginManagerAddClient];
+    /** @private */
+    private [kServerPluginManagerRemoveClient];
+}
+import BasePluginManager from '../common/BasePluginManager.js';
+import ServerPlugin from './ServerPlugin.js';

package/types/server/ServerSocket.d.ts

@@ -0,0 +1,69 @@
+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.
+     */
+    get sockets(): any;
+    /**
+     * Ready 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;
+    /**
+     * 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,42 @@
+export const kSocketsStart: unique symbol;
+export const kSocketsStop: unique symbol;
+export const kSocketsDeleteSocket: 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);
+    /** @private */
+    private entries;
+    /** @private */
+    private keys;
+    /** @private */
+    private values;
+    forEach(func: any): void;
+    /**
+     * Initialize sockets, all sockets are added to two rooms by default:
+     * - to the room corresponding to the client `role`
+     * - to the '*' room that holds all connected sockets
+     * @private
+     */
+    private [kSocketsStart];
+    /**
+     * Terminate all existing sockets.
+     * @private
+     */
+    private [kSocketsStop];
+    /**
+     * Remove given socket from all rooms.
+     * @private
+     */
+    private [kSocketsDeleteSocket];
+    [kSocketsLatencyStatsWorker]: any;
+    [kSocketsDebugPreventHeartBeat]: boolean;
+    #private;
+}