@lakutata/webrtc 0.0.0-stage → 3.1.1

package/dist/cjs/shared/SignalingSession.d.ts

@@ -0,0 +1,97 @@
+import { type SignalingIceServer } from '../protocol/SignalingProtocol.js';
+import type { PeerConnectionFactory, PeerConnectionLike } from './Connections.js';
+import { Emitter } from './Emitter.js';
+import { Room } from './Room.js';
+import { type SignalingTransport } from './Transports.js';
+/**
+ * The events of a signaling session.
+ */
+export type SignalingSessionEvents = {
+    /**
+     * The signaling is connected again (after a disconnection): the rooms are joined again.
+     */
+    connected: [];
+    /**
+     * The signaling is disconnected; the peer-to-peer connections stay up.
+     */
+    disconnected: [];
+    /**
+     * A background task failed: joining a room again, renewing the TURN credentials.
+     */
+    error: [error: Error];
+};
+/**
+ * The options of a signaling session.
+ */
+export interface SignalingSessionOptions<Connection extends PeerConnectionLike<any>> {
+    /**
+     * Creates the peer connections.
+     */
+    createPeerConnection: PeerConnectionFactory<Connection>;
+    /**
+     * `relay` to use only the TURN relays.
+     * @default 'all'
+     */
+    iceTransportPolicy?: 'all' | 'relay';
+    /**
+     * The session: a random string by default.
+     */
+    session?: string;
+}
+/**
+ * The options of joining a room.
+ */
+export interface JoinOptions {
+    /**
+     * What the other members get about the local member (a name, a role).
+     */
+    metadata?: unknown;
+}
+/**
+ * The signaling of a client: it joins rooms, relays the signals of their peers, keeps the membership alive (heartbeats
+ * for the transports needing them), renews the TURN credentials before they expire, and joins the rooms again after a
+ * reconnection of its transport (with the same session, so the other members keep their connections).
+ */
+export declare class SignalingSession<Connection extends PeerConnectionLike<any> = PeerConnectionLike> extends Emitter<SignalingSessionEvents> {
+    #private;
+    /**
+     * Create a session on a transport.
+     * @param transport The transport.
+     * @param options How to create the peer connections.
+     */
+    constructor(transport: SignalingTransport, options: SignalingSessionOptions<Connection>);
+    /**
+     * The local member's id (its client id), known once a room is joined.
+     */
+    get id(): string | undefined;
+    /**
+     * The session: the other members keep their connections when the client joins again with it.
+     */
+    get session(): string;
+    /**
+     * Whether the signaling is connected.
+     */
+    get connected(): boolean;
+    /**
+     * The ICE servers given by the server, with the TURN credentials.
+     */
+    get iceServers(): SignalingIceServer[];
+    /**
+     * The rooms joined.
+     */
+    get rooms(): Room<Connection>[];
+    /**
+     * Join a room: a {@link Room}, whose `peer` event gives the other members. Joining a room already joined updates the
+     * metadata and gives the same room.
+     * @param room The room.
+     * @param options The metadata the other members get.
+     * @returns The room.
+     */
+    join(room: string, options?: JoinOptions): Promise<Room<Connection>>;
+    /**
+     * Close the session: the rooms are left and their peers closed. A socket given by the application stays open (its
+     * listeners are removed); a WebSocket created by the function given is closed.
+     * @returns Resolves once the rooms are left.
+     */
+    close(): Promise<void>;
+}

package/dist/cjs/shared/SignalingSession.js

@@ -0,0 +1,347 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SignalingSession = void 0;
+const SignalingProtocol_js_1 = require("../protocol/SignalingProtocol.js");
+const Emitter_js_1 = require("./Emitter.js");
+const Room_js_1 = require("./Room.js");
+const SignalingError_js_1 = require("./SignalingError.js");
+const Transports_js_1 = require("./Transports.js");
+/**
+ * How many times a signal refused for its rate is sent again
+ */
+const LIMIT_RETRIES = 3;
+/**
+ * How long a room joined again for a new media server waits before it is joined again once more, after a failure (no
+ * media server takes the member), in milliseconds: twice longer after each failure, up to MAX_REJOIN_DELAY
+ */
+const REJOIN_DELAY = 1000;
+const MAX_REJOIN_DELAY = 10000;
+/**
+ * A random session id
+ */
+function randomSession() {
+    const bytes = new Uint8Array(12);
+    globalThis.crypto.getRandomValues(bytes);
+    return Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+/**
+ * The signaling of a client: it joins rooms, relays the signals of their peers, keeps the membership alive (heartbeats
+ * for the transports needing them), renews the TURN credentials before they expire, and joins the rooms again after a
+ * reconnection of its transport (with the same session, so the other members keep their connections).
+ */
+class SignalingSession extends Emitter_js_1.Emitter {
+    #transport;
+    #options;
+    #session;
+    #rooms = new Map();
+    //The events of the rooms being joined, arrived before the answer (the media server of the room offers at once)
+    #early = new Map();
+    //The rooms being joined again for a new media server
+    #rejoining = new Set();
+    #unsubscribe = [];
+    #id;
+    #iceServers = [];
+    #heartbeat;
+    #heartbeatInterval = 0;
+    #refresh;
+    #wasConnected;
+    #closed = false;
+    /**
+     * Create a session on a transport.
+     * @param transport The transport.
+     * @param options How to create the peer connections.
+     */
+    constructor(transport, options) {
+        super();
+        this.#transport = transport;
+        this.#options = options;
+        this.#session = options.session ?? randomSession();
+        this.#wasConnected = transport.connected;
+        this.#unsubscribe.push(transport.listen((event, payload) => this.#event(event, payload)));
+        this.#unsubscribe.push(transport.watch((connected) => this.#status(connected)));
+    }
+    /**
+     * The local member's id (its client id), known once a room is joined.
+     */
+    get id() {
+        return this.#id;
+    }
+    /**
+     * The session: the other members keep their connections when the client joins again with it.
+     */
+    get session() {
+        return this.#session;
+    }
+    /**
+     * Whether the signaling is connected.
+     */
+    get connected() {
+        return this.#transport.connected;
+    }
+    /**
+     * The ICE servers given by the server, with the TURN credentials.
+     */
+    get iceServers() {
+        return [...this.#iceServers];
+    }
+    /**
+     * The rooms joined.
+     */
+    get rooms() {
+        return [...this.#rooms.values()];
+    }
+    /**
+     * Join a room: a {@link Room}, whose `peer` event gives the other members. Joining a room already joined updates the
+     * metadata and gives the same room.
+     * @param room The room.
+     * @param options The metadata the other members get.
+     * @returns The room.
+     */
+    async join(room, options = {}) {
+        if (this.#closed)
+            throw new SignalingError_js_1.SignalingRequestError('The signaling is closed', 'E_SIGNALING_CLOSED');
+        const early = [];
+        if (!this.#rooms.has(room))
+            this.#early.set(room, early);
+        let result;
+        try {
+            result = await this.#transport.request(SignalingProtocol_js_1.SignalingMethod.join, { room: room, metadata: options.metadata, session: this.#session });
+        }
+        finally {
+            if (this.#early.get(room) === early)
+                this.#early.delete(room);
+        }
+        this.#joinedWith(result);
+        let joined = this.#rooms.get(room);
+        if (!joined) {
+            joined = new Room_js_1.Room(this.#roomHost(), room, options.metadata);
+            this.#rooms.set(room, joined);
+        }
+        joined.members(result.peers, options.metadata, result.sfu);
+        for (const [event, payload] of early)
+            this.#event(event, payload);
+        return joined;
+    }
+    /**
+     * Close the session: the rooms are left and their peers closed. A socket given by the application stays open (its
+     * listeners are removed); a WebSocket created by the function given is closed.
+     * @returns Resolves once the rooms are left.
+     */
+    async close() {
+        if (this.#closed)
+            return;
+        const rooms = [...this.#rooms.values()];
+        await Promise.allSettled(rooms.map((room) => room.leave()));
+        this.#closed = true;
+        clearInterval(this.#heartbeat);
+        clearTimeout(this.#refresh);
+        for (const unsubscribe of this.#unsubscribe)
+            unsubscribe();
+        this.#transport.close();
+    }
+    /**
+     * What the rooms need of the session
+     */
+    #roomHost() {
+        const session = this;
+        return {
+            get localId() {
+                return session.#id ?? '';
+            },
+            get signalingUp() {
+                return session.#transport.connected;
+            },
+            create: (configuration = {}) => this.#options.createPeerConnection({
+                ...configuration,
+                iceServers: this.#iceServers,
+                iceTransportPolicy: this.#options.iceTransportPolicy ?? 'all'
+            }),
+            send: (room, to, signal) => this.#signal(room, to, signal),
+            leave: async (room) => {
+                if (this.#rooms.get(room.name) === room)
+                    this.#rooms.delete(room.name);
+                if (!this.#transport.connected)
+                    return;
+                await this.#transport.request(SignalingProtocol_js_1.SignalingMethod.leave, { room: room.name }).catch(() => undefined);
+            },
+            //Joined again once the transport is up, if it is not; again and again while it fails (no media server takes
+            //the member), until the room is left
+            rejoin: (room) => {
+                if (this.#closed || !this.#transport.connected || this.#rejoining.has(room.name))
+                    return;
+                this.#rejoining.add(room.name);
+                const attempt = async () => {
+                    for (let attempts = 0;; attempts++) {
+                        try {
+                            return await this.#joinAgain(room);
+                        }
+                        catch (error) {
+                            this.emit('error', error);
+                        }
+                        await new Promise((resolve) => void (0, Transports_js_1.unrefTimer)(setTimeout(resolve, Math.min(REJOIN_DELAY * 2 ** attempts, MAX_REJOIN_DELAY))));
+                        if (this.#closed || room.left || this.#rooms.get(room.name) !== room || !this.#transport.connected)
+                            return;
+                    }
+                };
+                void attempt().finally(() => this.#rejoining.delete(room.name));
+            }
+        };
+    }
+    /**
+     * Join a room again, with the same session: its events wait for the answer
+     * @param room
+     */
+    async #joinAgain(room) {
+        const early = [];
+        this.#early.set(room.name, early);
+        try {
+            const result = await this.#transport.request(SignalingProtocol_js_1.SignalingMethod.join, { room: room.name, metadata: room.metadata, session: this.#session });
+            this.#joinedWith(result);
+            if (this.#rooms.get(room.name) === room)
+                room.members(result.peers, room.metadata, result.sfu);
+        }
+        finally {
+            if (this.#early.get(room.name) === early)
+                this.#early.delete(room.name);
+            for (const [event, payload] of early)
+                this.#event(event, payload);
+        }
+    }
+    /**
+     * Send a signal; a signal refused for the rate is sent again a second later
+     * @param room
+     * @param to
+     * @param signal
+     */
+    async #signal(room, to, signal) {
+        for (let attempt = 0;; attempt++) {
+            try {
+                await this.#transport.request(SignalingProtocol_js_1.SignalingMethod.signal, { room: room, to: to, ...signal });
+                return;
+            }
+            catch (error) {
+                //The member left in between
+                if (error.errno === 'E_SIGNALING_NOT_A_MEMBER')
+                    return;
+                if (error.errno !== 'E_SIGNALING_LIMIT' || attempt >= LIMIT_RETRIES)
+                    throw error;
+                await new Promise((resolve) => void (0, Transports_js_1.unrefTimer)(setTimeout(resolve, 1000)));
+            }
+        }
+    }
+    /**
+     * The answer of a join: the id, the ICE servers, the heartbeats, the renewal of the credentials
+     * @param result
+     */
+    #joinedWith(result) {
+        this.#id = result.peerId;
+        this.#iceServers = result.iceServers;
+        if (result.heartbeatInterval !== this.#heartbeatInterval) {
+            clearInterval(this.#heartbeat);
+            this.#heartbeatInterval = result.heartbeatInterval;
+            if (result.heartbeatInterval > 0) {
+                this.#heartbeat = (0, Transports_js_1.unrefTimer)(setInterval(() => {
+                    if (this.#transport.connected && this.#rooms.size)
+                        this.#transport.request(SignalingProtocol_js_1.SignalingMethod.heartbeat, {}).catch(() => undefined);
+                }, result.heartbeatInterval));
+            }
+        }
+        this.#scheduleRefresh(result.credentialTtl);
+    }
+    /**
+     * Renew the TURN credentials when four fifths of their lifetime are gone
+     * @param ttl
+     */
+    #scheduleRefresh(ttl) {
+        clearTimeout(this.#refresh);
+        if (!ttl)
+            return;
+        //setTimeout holds at most 2^31 - 1 milliseconds
+        const delay = Math.min(ttl * 800, 2 ** 31 - 1);
+        this.#refresh = (0, Transports_js_1.unrefTimer)(setTimeout(() => void this.#renew(), delay));
+    }
+    /**
+     * Get new ICE servers and give them to the connections
+     */
+    async #renew() {
+        if (this.#closed || !this.#rooms.size)
+            return;
+        try {
+            const result = await this.#transport.request(SignalingProtocol_js_1.SignalingMethod.iceServers, {});
+            this.#iceServers = result.iceServers;
+            for (const room of this.#rooms.values()) {
+                for (const peer of room.peers) {
+                    try {
+                        peer.connection.setConfiguration({ ...peer.connection.getConfiguration(), iceServers: result.iceServers });
+                    }
+                    catch (error) {
+                        this.emit('error', error);
+                    }
+                }
+            }
+            this.#scheduleRefresh(result.credentialTtl);
+        }
+        catch (error) {
+            this.emit('error', error);
+            //Try again in a minute
+            this.#refresh = (0, Transports_js_1.unrefTimer)(setTimeout(() => void this.#renew(), 60000));
+        }
+    }
+    /**
+     * An event pushed by the server
+     * @param event
+     * @param payload
+     */
+    #event(event, payload) {
+        if (this.#closed || !payload || typeof payload !== 'object')
+            return;
+        const name = payload.room ?? '';
+        //The events of a room being joined wait for the answer
+        const early = this.#early.get(name);
+        if (early)
+            return void early.push([event, payload]);
+        const room = this.#rooms.get(name);
+        if (!room)
+            return;
+        switch (event) {
+            case SignalingProtocol_js_1.SignalingEvent.peerJoined:
+                return room.joined(payload);
+            case SignalingProtocol_js_1.SignalingEvent.peerLeft:
+                return room.departed(payload);
+            case SignalingProtocol_js_1.SignalingEvent.signal:
+                return room.signal(payload);
+        }
+    }
+    /**
+     * The transport connected or disconnected: after a reconnection, the rooms are joined again
+     * @param connected
+     */
+    #status(connected) {
+        if (this.#closed)
+            return;
+        if (!connected) {
+            this.emit('disconnected');
+            return;
+        }
+        if (!this.#wasConnected) {
+            this.#wasConnected = true;
+            return;
+        }
+        void this.#rejoin();
+    }
+    /**
+     * Join the rooms again, with the same session
+     */
+    async #rejoin() {
+        for (const room of [...this.#rooms.values()]) {
+            try {
+                await this.#joinAgain(room);
+            }
+            catch (error) {
+                this.emit('error', error);
+            }
+        }
+        this.emit('connected');
+    }
+}
+exports.SignalingSession = SignalingSession;

package/dist/cjs/shared/Transports.d.ts

@@ -0,0 +1,139 @@
+/**
+ * How a signaling session talks to the server: requests, the events pushed by the server, and the state of the
+ * connection.
+ */
+export interface SignalingTransport {
+    /**
+     * Whether the connection is up.
+     */
+    readonly connected: boolean;
+    /**
+     * Send a request.
+     * @param method The method (`webrtc.join`…).
+     * @param params Its parameters.
+     * @returns The answer.
+     */
+    request<Result>(method: string, params: Record<string, unknown>): Promise<Result>;
+    /**
+     * Listen to the events pushed by the server.
+     * @param listener Given the event and its payload.
+     * @returns A function removing the listener.
+     */
+    listen(listener: (event: string, payload: unknown) => void): () => void;
+    /**
+     * Listen to the connections and disconnections.
+     * @param listener Given whether the connection is up.
+     * @returns A function removing the listener.
+     */
+    watch(listener: (connected: boolean) => void): () => void;
+    /**
+     * Stop: the requests in progress fail, the connection is closed when the transport opened it.
+     */
+    close(): void;
+}
+/**
+ * What the signaling needs of a Socket.IO client socket (`io()` of socket.io-client): the socket is given by the
+ * application, its client id being its `auth.id`.
+ */
+export interface SocketIOSocketLike {
+    /**
+     * Whether it is connected.
+     */
+    readonly connected: boolean;
+    /**
+     * Send an event.
+     * @param event The event.
+     * @param args Its arguments, the last one an acknowledgement callback.
+     */
+    emit(event: string, ...args: any[]): unknown;
+    /**
+     * Add a listener.
+     * @param event The event.
+     * @param listener The listener.
+     */
+    on(event: string, listener: (...args: any[]) => void): unknown;
+    /**
+     * Remove a listener.
+     * @param event The event.
+     * @param listener The listener.
+     */
+    off(event: string, listener?: (...args: any[]) => void): unknown;
+}
+/**
+ * What the signaling needs of a WebSocket (`WebSocket` of the browsers, of Node.js 22 and of Bun) speaking JSON-RPC to
+ * the server; its client id is the `id` query parameter of its URL.
+ */
+export interface WebSocketLike {
+    /**
+     * 0 connecting, 1 open, 2 closing, 3 closed.
+     */
+    readonly readyState: number;
+    /**
+     * Send a text message.
+     * @param data The message.
+     */
+    send(data: string): void;
+    /**
+     * Close it.
+     * @param code The close code.
+     * @param reason The reason.
+     */
+    close(code?: number, reason?: string): void;
+    /**
+     * Add a listener: `open`, `message`, `close`, `error`.
+     * @param type The event.
+     * @param listener The listener.
+     */
+    addEventListener(type: string, listener: (event: any) => void): void;
+    /**
+     * Remove a listener.
+     * @param type The event.
+     * @param listener The listener.
+     */
+    removeEventListener(type: string, listener: (event: any) => void): void;
+}
+/**
+ * The timers of Node.js are not to hold the process
+ * @param timer
+ */
+export declare function unrefTimer<Timer>(timer: Timer): Timer;
+/**
+ * The signaling over a Socket.IO socket: a request is the event `message`, `{method, ...params}`, answered by its
+ * acknowledgement `{success, error, payload}`; the events are Socket.IO events. A request sent when the socket
+ * disconnects fails at once (its answer cannot come any more); one made while it is disconnected is sent once it
+ * connects again.
+ */
+export declare class SocketIOTransport implements SignalingTransport {
+    #private;
+    /**
+     * Use a socket.
+     * @param socket The socket of the application.
+     * @param timeout How long a request waits for its answer, in milliseconds.
+     */
+    constructor(socket: SocketIOSocketLike, timeout?: number);
+    get connected(): boolean;
+    request<Result>(method: string, params: Record<string, unknown>): Promise<Result>;
+    listen(listener: (event: string, payload: unknown) => void): () => void;
+    watch(listener: (connected: boolean) => void): () => void;
+    close(): void;
+}
+/**
+ * The signaling over JSON-RPC 2.0 on a WebSocket: the requests are JSON-RPC requests, the events are notifications whose
+ * `params` hold the payload. Given a function creating the WebSocket, it reconnects after a disconnection, waiting 1
+ * second, then twice as long each time, 30 seconds at most. A request sent on a socket that closes fails at once (its
+ * answer cannot come any more); one made while the socket is not open is sent once it opens.
+ */
+export declare class JSONRPCTransport implements SignalingTransport {
+    #private;
+    /**
+     * Use a WebSocket.
+     * @param socket The WebSocket, or a function creating one (to reconnect).
+     * @param timeout How long a request waits for its answer, in milliseconds.
+     */
+    constructor(socket: WebSocketLike | (() => WebSocketLike), timeout?: number);
+    get connected(): boolean;
+    request<Result>(method: string, params: Record<string, unknown>): Promise<Result>;
+    listen(listener: (event: string, payload: unknown) => void): () => void;
+    watch(listener: (connected: boolean) => void): () => void;
+    close(): void;
+}