@lakutata/webrtc 0.0.0-stage → 3.1.1

package/dist/cjs/signaling/Signaling.d.ts

@@ -0,0 +1,573 @@
+import { Component, type ComponentOptions } from '@lakutata/core';
+import type { ServiceContext } from '@lakutata/entrypoint';
+import { type SignalingCandidate, type SignalingDescription, type SignalingIceServer, type SignalingJoinResult, type SignalingPeer, type SignalingPeerLeftEvent, type SignalingRole, type SignalingSignalEvent, type SignalingStream } from '../protocol/SignalingProtocol.js';
+import type { Cluster } from '../cluster/Cluster.js';
+import { type TURNSelector } from '../cluster/ClusterTURN.js';
+/**
+ * Decides whether a member may join a room (the `authorize` option of {@link Signaling}).
+ * @param peer The member: its id (the client id of its connection) and the metadata it gave.
+ * @param room The room it asks to join.
+ * @param context The context of its request (`clientId`, the input, and the transport's objects).
+ * @returns Whether it may join.
+ */
+export type SignalingAuthorize = (peer: SignalingPeer, room: string, context?: ServiceContext) => boolean | Promise<boolean>;
+/**
+ * The options of a {@link Signaling} (see {@link buildSignalingOptions}).
+ */
+export interface SignalingOptions {
+    /**
+     * The name of the entrypoint component pushing the events to the clients.
+     * @default 'entrypoint'
+     */
+    entrypoint?: string;
+    /**
+     * The name of a {@link Cluster} component: the members connected to all the nodes of the cluster meet in the same
+     * rooms.
+     * @default none (the rooms of this instance only)
+     */
+    cluster?: string;
+    /**
+     * The name of a {@link TURNServer} component: the members get its ICE servers, with short-lived credentials.
+     * @default none
+     */
+    turn?: string;
+    /**
+     * The secret shared by the TURN servers of the cluster (their `secret`): with it and `cluster`, the members get
+     * TURN servers of the cluster, chosen by `selectTURN`, after the ones of `turn`. Without it, the TURN servers of
+     * the cluster are given only when `turn` is set, with its credentials (they share its secret).
+     * @default none
+     */
+    turnSecret?: string;
+    /**
+     * Chooses the TURN servers of the cluster given to a member.
+     * @default the two least loaded that are not full
+     */
+    selectTURN?: TURNSelector;
+    /**
+     * More ICE servers given to the members (an external STUN or TURN server), after the ones of `turn` and of the
+     * cluster.
+     * @default []
+     */
+    iceServers?: SignalingIceServer[];
+    /**
+     * Decides whether a member may join a room; every member may join any room without it.
+     * @default none
+     */
+    authorize?: SignalingAuthorize;
+    /**
+     * The members of a room at most; 0 for no limit.
+     * @default 0
+     */
+    maxPeers?: number;
+    /**
+     * The size of a signal (its description or candidate as JSON) and of the metadata of a member at most, in bytes.
+     * @default 65536
+     */
+    maxMessageSize?: number;
+    /**
+     * The signals a member may send in a second, on average (bursts of twice as many are allowed).
+     * @default 50
+     */
+    maxMessagesPerSecond?: number;
+    /**
+     * How often the clients send `webrtc.heartbeat` when the server cannot see their disconnection (the transports
+     * other than Socket.IO and JSON-RPC over WebSocket), in milliseconds; such a client is taken out of its rooms after
+     * three intervals without a request.
+     * @default 10000
+     */
+    heartbeatInterval?: number;
+}
+/**
+ * How a member joins a room ({@link Signaling.join}).
+ */
+export interface SignalingJoinOptions {
+    /**
+     * What the other members get about it (a name, a role).
+     */
+    metadata?: unknown;
+    /**
+     * The session of its client: the other members keep their connections to it when it joins again with the same one.
+     */
+    session?: string;
+    /**
+     * The context of its request: the transport's objects, given to `authorize`, and the Socket.IO socket whose
+     * disconnection takes the member out of its rooms.
+     */
+    context?: ServiceContext;
+    /**
+     * The role of a member the server adds itself (a media server, a stream published with WHIP): it is not checked by
+     * `authorize`, not counted by `maxPeers`, and its signals are not limited. The ids starting with `sfu:` or `whip:`
+     * are kept for such members.
+     */
+    role?: SignalingRole;
+    /**
+     * Receives the events of a member of the application itself (`webrtc:peer-joined`, `webrtc:peer-left`,
+     * `webrtc:signal`), instead of a client of the entrypoint; such a member stays until it leaves.
+     */
+    receive?: SignalingReceiver;
+}
+/**
+ * Receives the events of a member of the application itself ({@link SignalingJoinOptions.receive}).
+ * @param event The event: `webrtc:peer-joined`, `webrtc:peer-left` or `webrtc:signal`.
+ * @param payload Its payload.
+ */
+export type SignalingReceiver = (event: string, payload: unknown) => void;
+/**
+ * A member of the rooms
+ */
+interface Member {
+    readonly peerId: string;
+    readonly rooms: Map<string, unknown>;
+    readonly joinedAt: Map<string, number>;
+    session?: string;
+    heartbeats: boolean;
+    socket?: unknown;
+    lastSeen: number;
+    tokens: number;
+    refilledAt: number;
+    role?: SignalingRole;
+    receive?: SignalingReceiver;
+    readonly sfus: Map<string, string>;
+}
+/**
+ * A member connected to another node of the cluster
+ */
+interface RemoteMember {
+    readonly node: string;
+    readonly metadata: unknown;
+    readonly session?: string;
+    readonly joinedAt: number;
+    readonly role?: SignalingRole;
+    readonly sfu?: string;
+}
+/**
+ * A member of a node, as the node tells the others
+ */
+interface MemberRecord {
+    room: string;
+    peerId: string;
+    metadata?: unknown;
+    session?: string;
+    joinedAt: number;
+    role?: SignalingRole;
+    sfu?: string;
+}
+/**
+ * A change of the members of a node, numbered in the order of the node: a member joined (`join`), left (`leave`), or
+ * joined the room through another node (`yield`: nobody is told it left)
+ */
+type MembershipEvent = ({
+    kind: 'join';
+    seq: number;
+} & MemberRecord) | {
+    kind: 'leave';
+    seq: number;
+    room: string;
+    peerId: string;
+    reason: SignalingPeerLeftEvent['reason'];
+} | {
+    kind: 'yield';
+    seq: number;
+    room: string;
+    peerId: string;
+};
+/**
+ * The members of a node, and the number of its last change
+ */
+interface MembershipSnapshot {
+    seq: number;
+    members: MemberRecord[];
+}
+/**
+ * The signaling of WebRTC: rooms whose members exchange the descriptions and the candidates of their connections. A
+ * member is a client of the entrypoint (its `clientId`): it joins a room with `webrtc.join`, gets the members already
+ * in it and the ICE servers, sends its offers, answers and candidates to a member with `webrtc.signal`, and receives
+ * the events of the room (`webrtc:peer-joined`, `webrtc:peer-left`, `webrtc:signal`). The requests are served by
+ * {@link SignalingController}, over Socket.IO or JSON-RPC over WebSocket (the protocol is in the guide, for the clients
+ * of other languages).
+ *
+ * A member leaves its rooms when it asks, when its connection closes (Socket.IO, JSON-RPC over WebSocket), when an
+ * event cannot reach it any more, or, for the clients sending heartbeats (over the other transports), after three
+ * heartbeat intervals without a request. The signals are checked: only between members of the same room, of a limited
+ * size and rate.
+ *
+ * With a {@link Cluster} (its `cluster` option), the instances of the application share the rooms: each node tells the
+ * others who joins and leaves through it, a signal to a member of another node goes through that node, and the members
+ * of a node that stops or cannot be reached any more leave their rooms (`disconnected`). `maxPeers` is counted over the
+ * whole cluster, by the node each room falls to.
+ *
+ * Register it as `signaling` with {@link buildSignalingOptions}, and add {@link SignalingController} to the
+ * controllers of the entrypoint.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildEntrypoints} from 'lakutata/com/entrypoint'
+ * import {socketIOServiceEntrypoint} from 'lakutata/adapter/socket.io'
+ * import {buildSignalingOptions, buildTURNServerOptions, SignalingController} from '@lakutata/webrtc'
+ *
+ * Application.run(() => ({
+ *     id: 'meet.app',
+ *     name: 'Meet',
+ *     components: {
+ *         turn: buildTURNServerOptions({publicAddress: '203.0.113.10', secret: process.env.TURN_SECRET}),
+ *         //The members get the ICE servers of turn; only the users of the meeting may join its room
+ *         signaling: buildSignalingOptions({
+ *             turn: 'turn',
+ *             authorize: (peer, room): boolean => room === 'meeting' && peer.peerId.startsWith('user-')
+ *         }),
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [SignalingController],
+ *             service: socketIOServiceEntrypoint({port: 3000})
+ *         })
+ *     },
+ *     bootstrap: ['turn', 'entrypoint']
+ * }))
+ * ```
+ */
+export declare class Signaling extends Component {
+    #private;
+    /**
+     * The name of the entrypoint component.
+     */
+    protected readonly entrypoint: string;
+    /**
+     * The name of the cluster component.
+     */
+    protected readonly cluster?: string;
+    /**
+     * The name of the TURN server component.
+     */
+    protected readonly turn?: string;
+    /**
+     * The secret of the TURN servers of the cluster.
+     */
+    protected readonly turnSecret?: string;
+    /**
+     * How the TURN servers of the cluster are chosen.
+     */
+    protected readonly selectTURN?: TURNSelector;
+    /**
+     * The other ICE servers.
+     */
+    protected readonly iceServers: SignalingIceServer[];
+    /**
+     * Who may join which room.
+     */
+    protected readonly authorize?: SignalingAuthorize;
+    /**
+     * The members of a room at most.
+     */
+    protected readonly maxPeers: number;
+    /**
+     * The size of a signal and of the metadata of a member at most, in bytes.
+     */
+    protected readonly maxMessageSize: number;
+    /**
+     * The signals of a member per second.
+     */
+    protected readonly maxMessagesPerSecond: number;
+    /**
+     * The heartbeat interval of the clients without a disconnection event, in milliseconds.
+     */
+    protected readonly heartbeatInterval: number;
+    /**
+     * Start the sweep of the members without heartbeats, and join the cluster.
+     * @protected
+     */
+    protected init(): Promise<void>;
+    /**
+     * Stop the sweep, leave the cluster and forget the rooms.
+     * @protected
+     */
+    protected destroy(): Promise<void>;
+    /**
+     * The rooms and their members (of all the nodes, with a cluster).
+     * @returns For each room, the ids of its members.
+     * @example
+     * ```typescript
+     * import type {Signaling} from '@lakutata/webrtc'
+     *
+     * declare const signaling: Signaling
+     * //{meeting: ['alice', 'bob']}
+     * console.log(signaling.rooms())
+     * ```
+     */
+    rooms(): Record<string, string[]>;
+    /**
+     * Add a member to a room: the other members get `webrtc:peer-joined`. Joining a room again updates its metadata and
+     * its session.
+     * @param peerId The member's id (its client id).
+     * @param room The room.
+     * @param options Its metadata, its session, the context of its request.
+     * @returns The members already in the room, the ICE servers and how to keep the membership alive.
+     * @throws {SignalingDeniedException} When `authorize` refuses the room, or the id is kept for the members of the
+     * server (`sfu:`, `whip:`) and no role is given.
+     * @throws {SignalingLimitException} When the room is full, or the metadata is over `maxMessageSize`.
+     * @example
+     * ```typescript
+     * import type {Signaling, SignalingJoinResult} from '@lakutata/webrtc'
+     *
+     * declare const signaling: Signaling
+     * //A member added by the application itself (SignalingController does it for the clients)
+     * const result: SignalingJoinResult = await signaling.join('device-7', 'device-7', {metadata: {kind: 'camera'}})
+     * ```
+     */
+    join(peerId: string, room: string, options?: SignalingJoinOptions): Promise<SignalingJoinResult>;
+    /**
+     * Send a description or a candidate to a member of a room, as `webrtc:signal` from the sender.
+     * @param peerId The sender's id.
+     * @param room The room both are in.
+     * @param to The receiver's id.
+     * @param signal The description (with the streams of the media server of the room, from it), or the candidate.
+     * @returns Whether the event reached the receiver.
+     * @throws {SignalingNotAMemberException} When the sender or the receiver is not in the room.
+     * @throws {SignalingLimitException} When the signal is too large, or the sender sends too many (a member of the
+     * server is not limited).
+     * @example
+     * ```typescript
+     * import type {Signaling} from '@lakutata/webrtc'
+     *
+     * declare const signaling: Signaling
+     * declare const offer: string
+     * const delivered: boolean = await signaling.signal('device-7', 'device-7', 'alice', {description: {type: 'offer', sdp: offer}})
+     * ```
+     */
+    signal(peerId: string, room: string, to: string, signal: {
+        description?: SignalingDescription;
+        candidate?: SignalingCandidate | null;
+        streams?: SignalingStream[];
+    }): Promise<boolean>;
+    /**
+     * Take a member out of a room: the other members get `webrtc:peer-left`.
+     * @param peerId The member's id.
+     * @param room The room.
+     * @returns Resolves once the other members are told.
+     * @example
+     * ```typescript
+     * import type {Signaling} from '@lakutata/webrtc'
+     *
+     * declare const signaling: Signaling
+     * await signaling.leave('device-7', 'device-7')
+     * ```
+     */
+    leave(peerId: string, room: string): Promise<void>;
+    /**
+     * Take a member out of all its rooms (its client went away).
+     * @param peerId The member's id.
+     * @returns Resolves once the other members are told.
+     * @example
+     * ```typescript
+     * import type {Signaling} from '@lakutata/webrtc'
+     *
+     * declare const signaling: Signaling
+     * await signaling.disconnect('device-7')
+     * ```
+     */
+    disconnect(peerId: string): Promise<void>;
+    /**
+     * Note that a member's client is still there (`webrtc.heartbeat`, and any request).
+     * @param peerId The member's id.
+     * @example
+     * ```typescript
+     * import type {Signaling} from '@lakutata/webrtc'
+     *
+     * declare const signaling: Signaling
+     * signaling.heartbeat('device-7')
+     * ```
+     */
+    heartbeat(peerId: string): void;
+    /**
+     * The ICE servers of a member, with new TURN credentials: the ones of `turn`, of the TURN servers of the cluster
+     * chosen for it, then the others.
+     * @param peerId The member's id (the user of the TURN credentials).
+     * @returns The ICE servers, and how long their credentials are valid in seconds (0 without TURN).
+     * @example
+     * ```typescript
+     * import type {Signaling, SignalingIceServer} from '@lakutata/webrtc'
+     *
+     * declare const signaling: Signaling
+     * const {iceServers} = await signaling.iceServersOf('device-7')
+     * ```
+     */
+    iceServersOf(peerId: string): Promise<{
+        iceServers: SignalingIceServer[];
+        credentialTtl: number;
+    }>;
+    /**
+     * Take a member out of a room, telling the other members why.
+     * @param peerId The member's id.
+     * @param room The room.
+     * @param reason `left` when it asked, `disconnected` when its client went away.
+     * @returns Resolves once the other members are told.
+     * @protected
+     */
+    protected remove(peerId: string, room: string, reason: SignalingPeerLeftEvent['reason']): Promise<void>;
+    /**
+     * Take a member of this node out of a room, without telling anyone
+     * @param room The room.
+     * @param member The member.
+     * @protected
+     */
+    protected forgetLocal(room: string, member: Member): void;
+    /**
+     * Take a member of another node out of a room, without telling anyone
+     * @param room The room.
+     * @param peerId The member's id.
+     * @param node Only if it is a member through this node.
+     * @returns The member taken out.
+     * @protected
+     */
+    protected forgetRemote(room: string, peerId: string, node?: string): RemoteMember | undefined;
+    /**
+     * Join the cluster: receive the changes of the other nodes, answer their requests, fetch their members when they
+     * come up or when changes of theirs were missed, and take out the members of the nodes going down
+     * @param cluster The cluster component.
+     * @protected
+     */
+    protected attach(cluster: Cluster): Promise<void>;
+    /**
+     * Tell the other nodes of a change of the members of this node
+     * @param event The change, numbered here.
+     * @protected
+     */
+    protected announceChange(event: MembershipEvent): void;
+    /**
+     * The members of this node, for another node
+     * @protected
+     */
+    protected snapshot(): MembershipSnapshot;
+    /**
+     * Fetch the members of a node, replacing what this node knew of them; the changes received meanwhile are applied
+     * after
+     * @param node The id of the node.
+     * @protected
+     */
+    protected sync(node: string): Promise<void>;
+    /**
+     * Receive a change of another node, in its order: a change missed makes this node fetch its members
+     * @param node The id of the node.
+     * @param event The change.
+     * @protected
+     */
+    protected received(node: string, event: MembershipEvent): Promise<void>;
+    /**
+     * Apply a change of another node
+     * @param node The id of the node.
+     * @param event The change.
+     * @protected
+     */
+    protected apply(node: string, event: MembershipEvent): Promise<void>;
+    /**
+     * A member joined a room through another node: of two nodes having it, the later join wins (the node of the earlier
+     * one gives it up); the members of this node in the room are told
+     * @param node The id of the node.
+     * @param record The member, its room and when it joined.
+     * @protected
+     */
+    protected joinedRemote(node: string, record: MemberRecord): Promise<void>;
+    /**
+     * A member of another node left a room: the members of this node in the room are told
+     * @param node The id of the node.
+     * @param room The room.
+     * @param peerId The member's id.
+     * @param reason `left` when it asked, `disconnected` when its client or its node went away.
+     * @protected
+     */
+    protected leftRemote(node: string, room: string, peerId: string, reason: SignalingPeerLeftEvent['reason']): Promise<void>;
+    /**
+     * A node went down: its members leave their rooms (`disconnected`)
+     * @param node The id of the node.
+     * @protected
+     */
+    protected dropNode(node: string): Promise<void>;
+    /**
+     * Push a signal from another node to a member of this node
+     * @param to The receiver's id.
+     * @param event The signal.
+     * @protected
+     */
+    protected deliver(to: string, event: SignalingSignalEvent): Promise<boolean>;
+    /**
+     * Whether a member may join a room of `maxPeers` members at most: counted by this node without a cluster, by the
+     * node the room falls to with one (another one when that node does not answer)
+     * @param room The room.
+     * @param peerId The member's id.
+     * @protected
+     */
+    protected admit(room: string, peerId: string): Promise<boolean>;
+    /**
+     * Hold a place for a member in a room falling to this node, if the room has one: its members of all the nodes and
+     * the places held count
+     * @param room The room.
+     * @param peerId The member's id.
+     * @protected
+     */
+    protected reserve(room: string, peerId: string): boolean;
+    /**
+     * The media server a member joining a room connects to: the one of this node, else, in a cluster, one of the media
+     * servers of the other nodes (the least loaded answering), which chooses as it would for a member of its own node
+     * @param room The room.
+     * @param peerId The member's id.
+     * @returns The id of the member of the media server, none for a room without one.
+     * @throws {SignalingLimitException} When no media server takes the member.
+     * @protected
+     */
+    protected mediaServerOf(room: string, peerId: string): Promise<string | undefined>;
+    /**
+     * The role of a member of another node, in any room
+     * @param peerId The member's id.
+     * @protected
+     */
+    protected remoteRoleOf(peerId: string): SignalingRole | undefined;
+    /**
+     * The member of a client, created on its first request; its Socket.IO socket, when its request came through one,
+     * takes it out of its rooms when it disconnects (unless the client reconnected through another socket first).
+     * @param peerId The member's id.
+     * @param context The context of its request.
+     * @returns The member.
+     * @protected
+     */
+    protected member(peerId: string, context?: ServiceContext): Member;
+    /**
+     * Take a token of the member's rate (refilled at maxMessagesPerSecond, up to twice as many).
+     * @param member The member.
+     * @throws {SignalingLimitException} When no token is left.
+     * @protected
+     */
+    protected consume(member: Member): void;
+    /**
+     * Push an event to a member; a member it cannot reach any more leaves its rooms.
+     * @param peerId The member's id.
+     * @param event The event.
+     * @param payload Its payload.
+     * @returns Whether the event reached the member.
+     * @protected
+     */
+    protected push(peerId: string, event: string, payload: unknown): Promise<boolean>;
+    /**
+     * Take out the members sending heartbeats that were not seen for three intervals.
+     * @protected
+     */
+    protected sweep(): void;
+}
+/**
+ * Build the options of a {@link Signaling} component, for the `components` of an application (named `signaling`, the
+ * name {@link SignalingController} uses).
+ * @param options The TURN server, the other ICE servers, who may join which room, the limits (all optional).
+ * @returns The component options.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildSignalingOptions} from '@lakutata/webrtc'
+ *
+ * Application.run(() => ({
+ *     id: 'meet.app',
+ *     name: 'Meet',
+ *     components: {
+ *         signaling: buildSignalingOptions({iceServers: [{urls: 'stun:stun.example.com:3478'}], maxPeers: 8})
+ *     }
+ * }))
+ * ```
+ */
+export declare function buildSignalingOptions(options?: SignalingOptions): ComponentOptions<SignalingOptions>;
+export {};