@lakutata/webrtc 0.0.0-stage → 3.1.4

package/dist/cjs/client/SignalingConnection.d.ts

@@ -0,0 +1,81 @@
+/// <reference lib="dom" preserve="true" />
+import type { Peer as SharedPeer } from '../shared/Peer.js';
+import type { Room as SharedRoom } from '../shared/Room.js';
+import { SignalingSession } from '../shared/SignalingSession.js';
+import { type SocketIOSocketLike, type WebSocketLike } from '../shared/Transports.js';
+/**
+ * A room joined by a {@link SignalingConnection}: its peers are `RTCPeerConnection`s.
+ */
+export type Room = SharedRoom<RTCPeerConnection>;
+/**
+ * Another member of a room joined by a {@link SignalingConnection}, and the `RTCPeerConnection` to it.
+ */
+export type Peer = SharedPeer<RTCPeerConnection>;
+/**
+ * The options of a {@link SignalingConnection}.
+ */
+export interface SignalingConnectionOptions {
+    /**
+     * `relay` to use only the TURN relays.
+     * @default 'all'
+     */
+    iceTransportPolicy?: 'all' | 'relay';
+    /**
+     * More options of the peer connections (`bundlePolicy`, `certificates`…); the ICE servers come from the server.
+     * @default none
+     */
+    configuration?: RTCConfiguration;
+    /**
+     * Creates the peer connections, instead of `new RTCPeerConnection()` (for an implementation of another
+     * environment).
+     * @default none
+     */
+    createPeerConnection?: (configuration: RTCConfiguration) => RTCPeerConnection;
+    /**
+     * How long a request waits for its answer, in milliseconds.
+     * @default 15000
+     */
+    timeout?: number;
+}
+/**
+ * The signaling of a browser (or of the renderer of Electron) for the signaling servers of `@lakutata/webrtc`: it joins
+ * rooms and connects to their other members with the `RTCPeerConnection` of the browser. Give it the connection of the
+ * application: a Socket.IO socket (`io()` of socket.io-client, its `auth.id` being the member's id), a `WebSocket`
+ * speaking JSON-RPC (its `id` query parameter being the member's id), or a function creating the `WebSocket`, to
+ * reconnect. After a reconnection the rooms are joined again, the peer-to-peer connections kept.
+ *
+ * In a room, the offers and the answers are exchanged as the W3C "perfect negotiation" does it: any member may add
+ * channels and tracks at any time. The ICE servers (with TURN credentials, renewed before they expire) come from the
+ * server.
+ * @example
+ * ```typescript
+ * import {io} from 'socket.io-client'
+ * import {type Peer, type Room, SignalingConnection} from '@lakutata/webrtc/client'
+ *
+ * const signaling: SignalingConnection = new SignalingConnection(io('https://example.com', {auth: {id: 'alice'}}))
+ * const room: Room = await signaling.join('room-1')
+ * room.on('peer', (peer: Peer): void => {
+ *     //Unordered and unreliable: a lost position is not sent again
+ *     const channel: RTCDataChannel = peer.createDataChannel('position', {ordered: false, maxRetransmits: 0})
+ *     channel.addEventListener('open', (): void => channel.send(JSON.stringify({x: 1, y: 2})))
+ *     peer.on('datachannel', (remote: RTCDataChannel): void => {
+ *         remote.addEventListener('message', (event: MessageEvent): void => console.log(peer.id, event.data))
+ *     })
+ * })
+ * ```
+ */
+export declare class SignalingConnection extends SignalingSession<RTCPeerConnection> {
+    /**
+     * Use a connection to the signaling.
+     * @param socket A Socket.IO socket, a `WebSocket` speaking JSON-RPC, or a function creating one (to reconnect).
+     * @param options The options of the peer connections, the timeout of the requests.
+     * @example
+     * ```typescript
+     * import {SignalingConnection} from '@lakutata/webrtc/client'
+     *
+     * //JSON-RPC over WebSocket, reconnecting: the member's id is the id query parameter
+     * const signaling: SignalingConnection = new SignalingConnection((): WebSocket => new WebSocket('wss://example.com/rpc?id=alice'))
+     * ```
+     */
+    constructor(socket: SocketIOSocketLike | WebSocketLike | (() => WebSocketLike), options?: SignalingConnectionOptions);
+}

package/dist/cjs/client/SignalingConnection.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SignalingConnection = void 0;
+const SignalingSession_js_1 = require("../shared/SignalingSession.js");
+const Transports_js_1 = require("../shared/Transports.js");
+/**
+ * The transport of a socket
+ * @param socket
+ * @param timeout
+ */
+function transportOf(socket, timeout) {
+    if (typeof socket === 'function')
+        return new Transports_js_1.JSONRPCTransport(socket, timeout);
+    if ('send' in socket && 'readyState' in socket)
+        return new Transports_js_1.JSONRPCTransport(socket, timeout);
+    return new Transports_js_1.SocketIOTransport(socket, timeout);
+}
+/**
+ * The signaling of a browser (or of the renderer of Electron) for the signaling servers of `@lakutata/webrtc`: it joins
+ * rooms and connects to their other members with the `RTCPeerConnection` of the browser. Give it the connection of the
+ * application: a Socket.IO socket (`io()` of socket.io-client, its `auth.id` being the member's id), a `WebSocket`
+ * speaking JSON-RPC (its `id` query parameter being the member's id), or a function creating the `WebSocket`, to
+ * reconnect. After a reconnection the rooms are joined again, the peer-to-peer connections kept.
+ *
+ * In a room, the offers and the answers are exchanged as the W3C "perfect negotiation" does it: any member may add
+ * channels and tracks at any time. The ICE servers (with TURN credentials, renewed before they expire) come from the
+ * server.
+ * @example
+ * ```typescript
+ * import {io} from 'socket.io-client'
+ * import {type Peer, type Room, SignalingConnection} from '@lakutata/webrtc/client'
+ *
+ * const signaling: SignalingConnection = new SignalingConnection(io('https://example.com', {auth: {id: 'alice'}}))
+ * const room: Room = await signaling.join('room-1')
+ * room.on('peer', (peer: Peer): void => {
+ *     //Unordered and unreliable: a lost position is not sent again
+ *     const channel: RTCDataChannel = peer.createDataChannel('position', {ordered: false, maxRetransmits: 0})
+ *     channel.addEventListener('open', (): void => channel.send(JSON.stringify({x: 1, y: 2})))
+ *     peer.on('datachannel', (remote: RTCDataChannel): void => {
+ *         remote.addEventListener('message', (event: MessageEvent): void => console.log(peer.id, event.data))
+ *     })
+ * })
+ * ```
+ */
+class SignalingConnection extends SignalingSession_js_1.SignalingSession {
+    /**
+     * Use a connection to the signaling.
+     * @param socket A Socket.IO socket, a `WebSocket` speaking JSON-RPC, or a function creating one (to reconnect).
+     * @param options The options of the peer connections, the timeout of the requests.
+     * @example
+     * ```typescript
+     * import {SignalingConnection} from '@lakutata/webrtc/client'
+     *
+     * //JSON-RPC over WebSocket, reconnecting: the member's id is the id query parameter
+     * const signaling: SignalingConnection = new SignalingConnection((): WebSocket => new WebSocket('wss://example.com/rpc?id=alice'))
+     * ```
+     */
+    constructor(socket, options = {}) {
+        const create = options.createPeerConnection ?? ((configuration) => new RTCPeerConnection(configuration));
+        super(transportOf(socket, options.timeout), {
+            iceTransportPolicy: options.iceTransportPolicy,
+            //The browsers negotiate the header extensions of a media server by themselves
+            createPeerConnection: ({ headerExtensions: _headerExtensions, ...configuration }) => create({ ...options.configuration, ...configuration })
+        });
+    }
+}
+exports.SignalingConnection = SignalingConnection;

package/dist/cjs/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 {};