@lakutata/webrtc 0.0.0-stage → 3.1.1

package/dist/types/cluster/Cluster.d.ts

@@ -0,0 +1,503 @@
+import { Component, type ComponentOptions } from '@lakutata/core';
+/**
+ * The bus in the memory of the process: the clusters of the same `prefix` in one process reach each other (the
+ * applications of a test). It needs no server and no package.
+ */
+export interface ClusterMemoryTransportOptions {
+    /**
+     * `'memory'`.
+     */
+    type: 'memory';
+}
+/**
+ * The bus on a NATS server (its core subjects, without JetStream). It needs the optional peer dependency `nats`
+ * (`npm install nats`, the client of `@lakutata/nats`).
+ */
+export interface ClusterNATSTransportOptions {
+    /**
+     * `'nats'`.
+     */
+    type: 'nats';
+    /**
+     * The server URLs (`nats://host:4222`).
+     * @default 'nats://127.0.0.1:4222'
+     */
+    servers?: string | string[];
+    /**
+     * The user name.
+     * @default none
+     */
+    user?: string;
+    /**
+     * The password.
+     * @default none
+     */
+    pass?: string;
+    /**
+     * The authentication token.
+     * @default none
+     */
+    token?: string;
+    /**
+     * The name of the connection, shown by the server.
+     * @default none
+     */
+    name?: string;
+}
+/**
+ * The bus on a Redis server (its channels: publish and subscribe). It needs the optional peer dependency `ioredis`
+ * (`npm install ioredis`).
+ */
+export interface ClusterRedisTransportOptions {
+    /**
+     * `'redis'`.
+     */
+    type: 'redis';
+    /**
+     * The server URL (`redis://user:password@host:6379/0`, `rediss://` for TLS). When set, `host`, `port` and `tls` are
+     * ignored; `username`, `password` and `database` apply when the URL does not give them.
+     * @default none
+     */
+    url?: string;
+    /**
+     * The host name or IP address of the server (without a `url`).
+     * @default '127.0.0.1'
+     */
+    host?: string;
+    /**
+     * The port of the server (without a `url`).
+     * @default 6379
+     */
+    port?: number;
+    /**
+     * The database number.
+     * @default 0
+     */
+    database?: number;
+    /**
+     * The user name (Redis 6 ACL).
+     * @default none
+     */
+    username?: string;
+    /**
+     * The password.
+     * @default none
+     */
+    password?: string;
+    /**
+     * Connect with TLS (without a `url`).
+     * @default false
+     */
+    tls?: boolean;
+}
+/**
+ * The bus of a {@link Cluster}: in the memory of the process, on a NATS server or on a Redis server.
+ */
+export type ClusterTransportOptions = ClusterMemoryTransportOptions | ClusterNATSTransportOptions | ClusterRedisTransportOptions;
+/**
+ * The options of a {@link Cluster} (see {@link buildClusterOptions}).
+ */
+export interface ClusterOptions {
+    /**
+     * The bus the nodes talk through: `{type: 'nats', servers}`, `{type: 'redis', url}`, or `{type: 'memory'}` for the
+     * applications of one process.
+     */
+    transport: ClusterTransportOptions;
+    /**
+     * The prefix of the subjects (NATS) or channels (Redis): the clusters sharing a server stay separate with it.
+     * Letters, digits, `_` and `-`, in tokens separated by dots.
+     * @default 'lakutata.webrtc'
+     */
+    prefix?: string;
+    /**
+     * The id of this node, unique in the cluster: letters, digits, `_` and `-`, 128 at most.
+     * @default the host name (the name of the pod in Kubernetes) and a random suffix
+     */
+    nodeId?: string;
+    /**
+     * The labels of this node, which the other nodes see (a zone, a region).
+     * @default {}
+     */
+    labels?: Record<string, string>;
+    /**
+     * How often this node tells the others it is there, in milliseconds; they take it as gone after three intervals
+     * without news of it.
+     * @default 2000
+     */
+    heartbeatInterval?: number;
+    /**
+     * How long `request()` and `requestAll()` wait for the answers by default, in milliseconds.
+     * @default 5000
+     */
+    requestTimeout?: number;
+}
+/**
+ * A node of a {@link Cluster}: an instance of the application.
+ */
+export interface ClusterNode {
+    /**
+     * Its id.
+     */
+    readonly id: string;
+    /**
+     * Its labels.
+     */
+    readonly labels: Readonly<Record<string, string>>;
+    /**
+     * What it offers, by service (`Cluster.announce()`): the address and the load of its TURN server under `turn`.
+     */
+    readonly services: Readonly<Record<string, unknown>>;
+    /**
+     * Whether it is this node.
+     */
+    readonly local: boolean;
+}
+/**
+ * The answer of a node to `Cluster.requestAll()`.
+ */
+export interface ClusterReply<T = unknown> {
+    /**
+     * The id of the node.
+     */
+    readonly node: string;
+    /**
+     * What its handler returned.
+     */
+    readonly result: T;
+}
+/**
+ * How a request waits.
+ */
+export interface ClusterRequestOptions {
+    /**
+     * How long to wait for the answers, in milliseconds.
+     * @default the `requestTimeout` of the cluster
+     */
+    timeout?: number;
+}
+/**
+ * A message of the bus, as JSON
+ */
+type Envelope = {
+    k: 'hb';
+    n: string;
+    i: string;
+    iv: number;
+    l: Record<string, string>;
+    s: Record<string, unknown>;
+} | {
+    k: 'bye';
+    n: string;
+    i: string;
+} | {
+    k: 'msg';
+    n: string;
+    t: string;
+    d: unknown;
+} | {
+    k: 'req';
+    n: string;
+    id: string;
+    t: string;
+    d: unknown;
+} | {
+    k: 'res';
+    n: string;
+    id: string;
+    d?: unknown;
+    e?: string;
+};
+/**
+ * Another node, as its heartbeats tell
+ */
+interface RemoteNode {
+    readonly id: string;
+    readonly incarnation: string;
+    interval: number;
+    labels: Record<string, string>;
+    services: Record<string, unknown>;
+    lastSeen: number;
+}
+/**
+ * A request waiting for its answers
+ */
+interface PendingRequest {
+    readonly topic: string;
+    readonly timer: NodeJS.Timeout;
+    readonly node?: string;
+    readonly awaited?: Set<string>;
+    readonly replies?: ClusterReply[];
+    resolve(value: unknown): void;
+    reject(error: Error): void;
+}
+/**
+ * The instances of an application working together: each instance is a node, and the nodes talk through a bus (NATS or
+ * Redis). The other components of the package use it when they are given its name (their `cluster` option): the
+ * signaling puts the members of all the nodes in the same rooms, the TURN servers tell the others their address and
+ * their load, the media servers of the nodes share the rooms, and a DELETE or a PATCH of a session of WHIP or WHEP is
+ * applied on the node holding the session. The application may use it too: messages to all the nodes (`publish`,
+ * `subscribe`), requests to one node or to all (`request`, `requestAll`, `handle`).
+ *
+ * Each node tells the others it is there every `heartbeatInterval`, with its labels and what it offers
+ * (`announce()`); the others take it as gone after three intervals without news of it, or at once when it stops. The
+ * component emits `node-up`, `node-down` and `node-update` with the {@link ClusterNode}. The bus carries only these
+ * messages: the media go directly between the clients and the nodes.
+ *
+ * Register it with {@link buildClusterOptions}; its `transport` is required.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildEntrypoints} from 'lakutata/com/entrypoint'
+ * import {socketIOServiceEntrypoint} from 'lakutata/adapter/socket.io'
+ * import {buildClusterOptions, buildSignalingOptions, SignalingController} from '@lakutata/webrtc'
+ *
+ * //Each pod of the deployment is a node; the members connected to any of them meet in the same rooms
+ * Application.run(() => ({
+ *     id: 'meet.app',
+ *     name: 'Meet',
+ *     components: {
+ *         cluster: buildClusterOptions({transport: {type: 'nats', servers: process.env.NATS_URL}}),
+ *         signaling: buildSignalingOptions({cluster: 'cluster'}),
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [SignalingController],
+ *             service: socketIOServiceEntrypoint({port: 3000})
+ *         })
+ *     },
+ *     bootstrap: ['signaling', 'entrypoint']
+ * }))
+ * ```
+ */
+export declare class Cluster extends Component {
+    #private;
+    /**
+     * The bus.
+     */
+    protected readonly transport: ClusterTransportOptions;
+    /**
+     * The prefix of the subjects.
+     */
+    protected readonly prefix: string;
+    /**
+     * The id of this node, unique in the cluster.
+     */
+    readonly nodeId: string;
+    /**
+     * The labels of this node.
+     */
+    protected readonly labels: Record<string, string>;
+    /**
+     * The heartbeat interval, in milliseconds.
+     */
+    protected readonly heartbeatInterval: number;
+    /**
+     * How long the requests wait by default, in milliseconds.
+     */
+    protected readonly requestTimeout: number;
+    /**
+     * Connect to the bus, and tell the other nodes this one is there.
+     * @protected
+     */
+    protected init(): Promise<void>;
+    /**
+     * Tell the other nodes this one stops, and close the connection to the bus.
+     * @protected
+     */
+    protected destroy(): Promise<void>;
+    /**
+     * The nodes of the cluster: this one first, then the others seen in the last three heartbeat intervals.
+     * @returns The nodes.
+     * @example
+     * ```typescript
+     * import type {Cluster, ClusterNode} from '@lakutata/webrtc'
+     *
+     * declare const cluster: Cluster
+     * //['meet-7c9f-a1b2c3d4', 'meet-7c9f-e5f60718']
+     * console.log(cluster.nodes().map((node: ClusterNode): string => node.id))
+     * ```
+     */
+    nodes(): ClusterNode[];
+    /**
+     * Tell the other nodes what this node offers for a service (they see it in the `services` of its node); `undefined`
+     * withdraws it. A new or withdrawn service is sent at once, a changed one with the next heartbeat.
+     * @param service The service.
+     * @param info What the nodes get about it, as JSON.
+     * @example
+     * ```typescript
+     * import type {Cluster} from '@lakutata/webrtc'
+     *
+     * declare const cluster: Cluster
+     * cluster.announce('recorder', {disk: 0.42})
+     * ```
+     */
+    announce(service: string, info: unknown): void;
+    /**
+     * Send a message to the other nodes: their listeners of the topic receive it (this node's do not).
+     * @param topic The topic.
+     * @param message The message, as JSON.
+     * @example
+     * ```typescript
+     * import type {Cluster} from '@lakutata/webrtc'
+     *
+     * declare const cluster: Cluster
+     * cluster.publish('announcements', {text: 'The meeting starts in 5 minutes'})
+     * ```
+     */
+    publish(topic: string, message: unknown): void;
+    /**
+     * Receive the messages of a topic from the other nodes.
+     * @param topic The topic.
+     * @param listener Called with the message and the id of the node sending it.
+     * @returns A function ending the subscription.
+     * @example
+     * ```typescript
+     * import type {Cluster} from '@lakutata/webrtc'
+     *
+     * declare const cluster: Cluster
+     * const unsubscribe: () => void = cluster.subscribe<{text: string}>('announcements', (message: {text: string}, from: string): void => console.log(from, message.text))
+     * ```
+     */
+    subscribe<T = unknown>(topic: string, listener: (message: T, from: string) => void): () => void;
+    /**
+     * Answer the requests of a topic (from `request()` and `requestAll()`), replacing the handler it had.
+     * @param topic The topic.
+     * @param handler Called with the message and the id of the node asking; what it returns (or resolves to) is the
+     * answer, as JSON, and what it throws fails the request.
+     * @returns A function removing the handler.
+     * @example
+     * ```typescript
+     * import type {Cluster} from '@lakutata/webrtc'
+     *
+     * declare const cluster: Cluster
+     * cluster.handle<{room: string}, number>('viewers', ({room}: {room: string}): number => room.length)
+     * ```
+     */
+    handle<T = unknown, R = unknown>(topic: string, handler: (message: T, from: string) => R | Promise<R>): () => void;
+    /**
+     * Ask a node, and wait for its answer. A request to this node calls its handler directly.
+     * @param node The id of the node.
+     * @param topic The topic of its handler.
+     * @param message The message, as JSON.
+     * @param options How long to wait.
+     * @returns The answer of its handler.
+     * @throws {ClusterRequestException} When the node is not in the cluster, has no handler of the topic, or its
+     * handler failed.
+     * @throws {ClusterTimeoutException} When it does not answer in time.
+     * @example
+     * ```typescript
+     * import type {Cluster} from '@lakutata/webrtc'
+     *
+     * declare const cluster: Cluster
+     * const viewers: number = await cluster.request<number>('meet-7c9f-e5f60718', 'viewers', {room: 'meeting'}, {timeout: 1000})
+     * ```
+     */
+    request<R = unknown>(node: string, topic: string, message: unknown, options?: ClusterRequestOptions): Promise<R>;
+    /**
+     * Ask all the other nodes, and wait until each answered or the time is up.
+     * @param topic The topic of their handlers.
+     * @param message The message, as JSON.
+     * @param options How long to wait at most.
+     * @returns The answers of the nodes whose handler answered (not those without a handler of the topic, those whose
+     * handler failed, or those answering late).
+     * @example
+     * ```typescript
+     * import type {Cluster, ClusterReply} from '@lakutata/webrtc'
+     *
+     * declare const cluster: Cluster
+     * const replies: ClusterReply<number>[] = await cluster.requestAll<number>('viewers', {room: 'meeting'})
+     * const viewers: number = replies.reduce((sum: number, reply: ClusterReply<number>): number => sum + reply.result, 0)
+     * ```
+     */
+    requestAll<R = unknown>(topic: string, message: unknown, options?: ClusterRequestOptions): Promise<ClusterReply<R>[]>;
+    /**
+     * The subject of a node, or of all the nodes
+     * @param node The id of the node; none for all the nodes.
+     * @protected
+     */
+    protected subjectOf(node?: string): string;
+    /**
+     * Send an envelope to a node, or to all of them
+     * @param node The id of the node; none for all the nodes.
+     * @param envelope The message.
+     * @protected
+     */
+    protected send(node: string | undefined, envelope: Envelope): void;
+    /**
+     * Send a heartbeat to all the nodes
+     * @param node Only to this node (an answer to its first heartbeat).
+     * @protected
+     */
+    protected beat(node?: string): void;
+    /**
+     * Take as gone the nodes without news for three of their heartbeat intervals
+     * @protected
+     */
+    protected expire(): void;
+    /**
+     * Forget a node: its requests fail, `requestAll()` stops waiting for it, `node-down` is emitted
+     * @param node The node.
+     * @protected
+     */
+    protected gone(node: RemoteNode): void;
+    /**
+     * Remove a pending request and settle it
+     * @param id The id of the request.
+     * @param pending The request.
+     * @param settle Resolves or rejects it.
+     * @protected
+     */
+    protected settle(id: string, pending: PendingRequest | undefined, settle: () => void): void;
+    /**
+     * Handle an envelope from the bus
+     * @param envelope The message.
+     * @protected
+     */
+    protected receive(envelope: Envelope): void;
+    /**
+     * Handle a heartbeat: a new node (or a node restarted) is up, a known one updated
+     * @param heartbeat The heartbeat.
+     * @protected
+     */
+    protected heard(heartbeat: Extract<Envelope, {
+        k: 'hb';
+    }>): void;
+    /**
+     * Answer a request with its handler
+     * @param request The request.
+     * @protected
+     */
+    protected answer(request: Extract<Envelope, {
+        k: 'req';
+    }>): Promise<void>;
+    /**
+     * Handle an answer to a request of this node
+     * @param response The answer.
+     * @protected
+     */
+    protected answered(response: Extract<Envelope, {
+        k: 'res';
+    }>): void;
+}
+/**
+ * Build the options of a {@link Cluster} component, for the `components` of an application.
+ * @param options The bus (required), the prefix of its subjects, the id and the labels of this node, the intervals.
+ * @returns The component options.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildClusterOptions} from '@lakutata/webrtc'
+ *
+ * Application.run(() => ({
+ *     id: 'meet.app',
+ *     name: 'Meet',
+ *     components: {
+ *         cluster: buildClusterOptions({
+ *             transport: {type: 'redis', url: process.env.REDIS_URL},
+ *             nodeId: process.env.POD_NAME,
+ *             labels: {zone: process.env.ZONE ?? 'default'}
+ *         })
+ *     }
+ * }))
+ * ```
+ */
+export declare function buildClusterOptions(options: ClusterOptions): ComponentOptions<ClusterOptions>;
+export {};

package/dist/types/cluster/ClusterFrames.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The frames carrying a message: the message itself, or its parts when it is larger than the transport carries
+ * @param message
+ * @param maxPayload
+ */
+export declare function framesOf(message: Uint8Array, maxPayload: number): Buffer[];
+/**
+ * Puts the messages back together from their frames: the parts of a message arrive in order from its publisher, those
+ * of other messages may come between them
+ */
+export declare class FrameAssembler {
+    #private;
+    protected readonly timeout: number;
+    /**
+     * @param timeout How long the parts of a message are kept, waiting for the rest, in milliseconds.
+     */
+    constructor(timeout?: number);
+    /**
+     * Add a frame
+     * @param frame
+     * @returns The message, once it is whole.
+     */
+    add(frame: Uint8Array): Buffer | undefined;
+}

package/dist/types/cluster/ClusterTURN.d.ts

@@ -0,0 +1,63 @@
+import type { SignalingIceServer } from '../protocol/SignalingProtocol.js';
+import type { TURNServer, TURNServerLocation } from '../turn/TURNServer.js';
+import type { Cluster } from './Cluster.js';
+/**
+ * A TURN server of a node of a {@link Cluster}, as it tells the other nodes.
+ */
+export interface ClusterTURNServer extends TURNServerLocation {
+    /**
+     * The id of its node.
+     */
+    readonly node: string;
+    /**
+     * The labels of its node (a zone, a region).
+     */
+    readonly labels: Readonly<Record<string, string>>;
+    /**
+     * Its allocations in use.
+     */
+    readonly allocations: number;
+    /**
+     * Its allocations at most, if it has a limit.
+     */
+    readonly maxAllocations?: number;
+    /**
+     * How long its short-lived credentials are valid, in seconds.
+     */
+    readonly credentialTtl: number;
+}
+/**
+ * Chooses the TURN servers of the cluster given to a client (the `selectTURN` option of `Signaling` and `WHIP`).
+ * @param servers The TURN servers of the cluster.
+ * @param user The client: the member of the signaling, the stream of WHIP.
+ * @returns The servers given to it.
+ */
+export type TURNSelector = (servers: ClusterTURNServer[], user: string) => ClusterTURNServer[];
+/**
+ * The TURN servers the nodes of a cluster tell about
+ * @param cluster
+ */
+export declare function turnServersOf(cluster: Cluster): ClusterTURNServer[];
+/**
+ * The least loaded TURN servers that are not full, the servers equally loaded in a random order
+ * @param servers
+ */
+export declare function leastLoadedTURN(servers: ClusterTURNServer[]): ClusterTURNServer[];
+/**
+ * The ICE servers of a client: the ones of the TURN server of this node, then the ones of the TURN servers of the
+ * cluster chosen for it (with credentials of the secret shared by the TURN servers of the cluster, or else of the
+ * TURN server of this node), then the others given
+ * @param user The client.
+ * @param options The TURN server of this node, the cluster, the shared secret, how to choose, the other ICE servers.
+ * @returns The ICE servers, and how long their credentials are valid in seconds (0 without TURN).
+ */
+export declare function iceServersFor(user: string, options: {
+    turn?: TURNServer;
+    cluster?: Cluster;
+    secret?: string;
+    select?: TURNSelector;
+    iceServers: SignalingIceServer[];
+}): {
+    iceServers: SignalingIceServer[];
+    credentialTtl: number;
+};

package/dist/types/cluster/Rendezvous.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The node responsible for a key among some nodes (rendezvous hashing): every node computes the same one, and only the
+ * keys of a node leaving or joining change hands
+ * @param key
+ * @param nodes The ids of the nodes.
+ * @returns The id of the node, undefined without nodes.
+ */
+export declare function rendezvous(key: string, nodes: readonly string[]): string | undefined;

package/dist/types/cluster/transports/ClusterTransport.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The bus under a cluster: subjects that every subscriber receives the messages of, in the order of each publisher
+ */
+export interface ClusterTransport {
+    /**
+     * The size of a message at most, in bytes: the larger ones are sent in parts
+     */
+    readonly maxPayload: number;
+    /**
+     * Connect to the server
+     */
+    connect(): Promise<void>;
+    /**
+     * Publish a message, without waiting; one that cannot be sent is lost
+     * @param subject
+     * @param data
+     */
+    publish(subject: string, data: Uint8Array): void;
+    /**
+     * Receive the messages of a subject
+     * @param subject
+     * @param handler
+     */
+    subscribe(subject: string, handler: (data: Uint8Array) => void): Promise<void>;
+    /**
+     * Call a listener each time the connection comes back after it was lost (the messages meanwhile may be lost)
+     * @param listener
+     */
+    onReconnect(listener: () => void): void;
+    /**
+     * Close the connection, once the messages published are sent
+     */
+    close(): Promise<void>;
+}

package/dist/types/cluster/transports/LoadClient.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Load the client package of a transport (an optional dependency)
+ * @param member A member of its API, to find it in the ESM namespace or the CommonJS exports.
+ * @param packageName The package.
+ */
+export declare function loadClient<T = any>(member: string, packageName: string): Promise<T>;

package/dist/types/cluster/transports/MemoryClusterTransport.d.ts

@@ -0,0 +1,13 @@
+import type { ClusterTransport } from './ClusterTransport.js';
+/**
+ * The bus in the memory of the process: the clusters of the same prefix in one process (the applications of a test)
+ */
+export declare class MemoryClusterTransport implements ClusterTransport {
+    #private;
+    readonly maxPayload: number;
+    connect(): Promise<void>;
+    publish(subject: string, data: Uint8Array): void;
+    subscribe(subject: string, handler: (data: Uint8Array) => void): Promise<void>;
+    onReconnect(): void;
+    close(): Promise<void>;
+}

package/dist/types/cluster/transports/NATSClusterTransport.d.ts

@@ -0,0 +1,23 @@
+import type { NatsConnection } from 'nats';
+import type { ClusterNATSTransportOptions } from '../Cluster.js';
+import type { ClusterTransport } from './ClusterTransport.js';
+/**
+ * The bus on a NATS server: its core subjects (no JetStream)
+ */
+export declare class NATSClusterTransport implements ClusterTransport {
+    #private;
+    protected readonly options: Omit<ClusterNATSTransportOptions, 'type'>;
+    maxPayload: number;
+    constructor(options: Omit<ClusterNATSTransportOptions, 'type'>);
+    connect(): Promise<void>;
+    publish(subject: string, data: Uint8Array): void;
+    subscribe(subject: string, handler: (data: Uint8Array) => void): Promise<void>;
+    onReconnect(listener: () => void): void;
+    close(): Promise<void>;
+    /**
+     * Tell the listeners when the connection comes back
+     * @param connection
+     * @protected
+     */
+    protected watch(connection: NatsConnection): Promise<void>;
+}