@lakutata/webrtc 0.0.0-stage → 3.1.4

package/dist/cjs/peer/SignalingClient.d.ts

@@ -0,0 +1,236 @@
+import { Provider } from '@lakutata/core';
+import type { SignalingIceServer } from '../protocol/SignalingProtocol.js';
+import type { EmitterListener } from '../shared/Emitter.js';
+import type { Peer as SharedPeer } from '../shared/Peer.js';
+import type { Room as SharedRoom } from '../shared/Room.js';
+import { type JoinOptions, type SignalingSessionEvents } from '../shared/SignalingSession.js';
+import { type SignalingTransport } from '../shared/Transports.js';
+import { PeerConnection } from './PeerConnection.js';
+/**
+ * A room joined by a {@link SignalingClient}: its peers are {@link PeerConnection}s.
+ */
+export type Room = SharedRoom<PeerConnection>;
+/**
+ * Another member of a room joined by a {@link SignalingClient}, and the {@link PeerConnection} to it.
+ */
+export type Peer = SharedPeer<PeerConnection>;
+/**
+ * The options of a {@link SignalingClient}.
+ */
+export interface SignalingClientOptions {
+    /**
+     * The URL of the signaling: `http:` or `https:` for Socket.IO (with the package `socket.io-client`), `ws:` or `wss:`
+     * for JSON-RPC over WebSocket.
+     */
+    url: string;
+    /**
+     * The client id, the member's id in the rooms.
+     * @default a random UUID
+     */
+    id?: string;
+    /**
+     * The path of Socket.IO.
+     * @default '/socket.io'
+     */
+    path?: string;
+    /**
+     * More fields of the Socket.IO handshake's `auth` (a token), besides `id`.
+     * @default none
+     */
+    auth?: Record<string, unknown>;
+    /**
+     * How long a request waits for its answer, in milliseconds.
+     * @default 15000
+     */
+    timeout?: number;
+    /**
+     * `relay` to use only the TURN relays.
+     * @default 'all'
+     */
+    iceTransportPolicy?: 'all' | 'relay';
+    /**
+     * The UDP ports of the local candidates, as `[first, last]`.
+     * @default any free port
+     */
+    icePortRange?: [number, number];
+    /**
+     * More addresses given as local candidates (the public address of a NAT forwarding `icePortRange` with the same
+     * port numbers).
+     * @default none
+     */
+    iceAdditionalHostAddresses?: string[];
+    /**
+     * The audio and video codecs of the connections, as MIME types in the order of preference (see `PeerConnection`).
+     * @default ['audio/opus', 'audio/PCMU', 'video/VP8', 'video/H264', 'video/VP9']
+     */
+    codecs?: string[];
+    /**
+     * The name of a `PeerThreads` component: the connections to the other members run their engine in its worker
+     * threads (see the `threads` option of `PeerConnection`).
+     * @default none: the engines run in the main thread
+     */
+    threads?: string;
+}
+/**
+ * A lakutata application as a member of the rooms of a signaling server of this package (`Signaling` and
+ * `SignalingController`, on this application or another one): it joins rooms and connects to their other members,
+ * browsers or applications, with {@link PeerConnection}s. Over Socket.IO (an `http:` or `https:` URL, with the package
+ * `socket.io-client`) or JSON-RPC over WebSocket (a `ws:` or `wss:` URL, with the `WebSocket` of Node.js 22 and of Bun);
+ * it reconnects by itself and joins its rooms again, keeping the peer-to-peer connections.
+ *
+ * Get a new one with `getObject(SignalingClient, options)` (it is `@Transient`, and needs no registration); `close()`
+ * leaves the rooms and closes the connections.
+ * @example
+ * ```typescript
+ * import {Component} from 'lakutata'
+ * import {type Peer, type PeerChannel, type Room, SignalingClient} from '@lakutata/webrtc'
+ *
+ * //A service of a device: sends its telemetry to whoever joins its room
+ * class TelemetryService extends Component {
+ *     protected async init(): Promise<void> {
+ *         const signaling: SignalingClient = await this.getObject(SignalingClient, {url: 'https://example.com', id: 'device-7'})
+ *         const room: Room = await signaling.join('device-7')
+ *         room.on('peer', (peer: Peer): void => {
+ *             const channel: PeerChannel = peer.createDataChannel('telemetry')
+ *             const timer: NodeJS.Timeout = setInterval((): void => {
+ *                 if (channel.readyState === 'open') channel.send(JSON.stringify({temperature: 21.5}))
+ *             }, 1000)
+ *             peer.on('close', (): void => clearInterval(timer))
+ *         })
+ *     }
+ * }
+ * ```
+ */
+export declare class SignalingClient extends Provider {
+    #private;
+    /**
+     * The URL of the signaling.
+     */
+    protected readonly url: string;
+    /**
+     * The client id.
+     */
+    protected readonly id?: string;
+    /**
+     * The path of Socket.IO.
+     */
+    protected readonly path: string;
+    /**
+     * More fields of the Socket.IO handshake's auth.
+     */
+    protected readonly auth: Record<string, unknown>;
+    /**
+     * How long a request waits for its answer.
+     */
+    protected readonly timeout: number;
+    /**
+     * `all`, or `relay` to use only the TURN relays.
+     */
+    protected readonly iceTransportPolicy: 'all' | 'relay';
+    /**
+     * The UDP ports of the local candidates.
+     */
+    protected readonly icePortRange?: [number, number];
+    /**
+     * More addresses given as local candidates.
+     */
+    protected readonly iceAdditionalHostAddresses?: string[];
+    /**
+     * The audio and video codecs of the connections.
+     */
+    protected readonly codecs?: string[];
+    /**
+     * The name of the component of the worker threads of the connections.
+     */
+    protected readonly threads?: string;
+    /**
+     * Connect to the signaling (the requests wait for the connection).
+     * @protected
+     */
+    protected init(): Promise<void>;
+    /**
+     * Leave the rooms and disconnect.
+     * @protected
+     */
+    protected destroy(): Promise<void>;
+    /**
+     * The client id: the member's id in the rooms.
+     */
+    get clientId(): string;
+    /**
+     * Whether the signaling is connected.
+     */
+    get connected(): boolean;
+    /**
+     * The rooms joined.
+     */
+    get rooms(): Room[];
+    /**
+     * The ICE servers given by the server, with the TURN credentials (renewed before they expire).
+     */
+    get iceServers(): SignalingIceServer[];
+    /**
+     * Join a room: its `peer` event gives the other members, each with its {@link PeerConnection}.
+     * @param room The room.
+     * @param options The metadata the other members get.
+     * @returns The room.
+     * @throws {SignalingRequestError} When the server refuses (`E_SIGNALING_DENIED`, `E_SIGNALING_LIMIT`) or does not
+     * answer (`E_SIGNALING_TIMEOUT`).
+     * @example
+     * ```typescript
+     * import type {Room, SignalingClient} from '@lakutata/webrtc'
+     *
+     * declare const signaling: SignalingClient
+     * const room: Room = await signaling.join('meeting', {metadata: {name: 'Recorder'}})
+     * ```
+     */
+    join(room: string, options?: JoinOptions): Promise<Room>;
+    /**
+     * Listen to the signaling: `connected` (again, after a disconnection; the rooms are joined again), `disconnected`
+     * (the peer-to-peer connections stay up), `error` (a background task failed).
+     * @param event The event.
+     * @param listener The listener.
+     * @returns The client.
+     * @example
+     * ```typescript
+     * import type {SignalingClient} from '@lakutata/webrtc'
+     *
+     * declare const signaling: SignalingClient
+     * signaling.on('disconnected', (): void => console.log('signaling lost, reconnecting'))
+     * ```
+     */
+    on<Event extends keyof SignalingSessionEvents>(event: Event, listener: EmitterListener<SignalingSessionEvents[Event]>): this;
+    /**
+     * Remove a listener added with `on`.
+     * @param event The event.
+     * @param listener The listener.
+     * @returns The client.
+     * @example
+     * ```typescript
+     * import type {SignalingClient} from '@lakutata/webrtc'
+     *
+     * declare const signaling: SignalingClient
+     * const listener = (error: Error): void => console.error(error)
+     * signaling.on('error', listener)
+     * signaling.off('error', listener)
+     * ```
+     */
+    off<Event extends keyof SignalingSessionEvents>(event: Event, listener: EmitterListener<SignalingSessionEvents[Event]>): this;
+    /**
+     * Leave the rooms, close their connections, disconnect, and destroy the object.
+     * @returns Resolves once done.
+     * @example
+     * ```typescript
+     * import type {SignalingClient} from '@lakutata/webrtc'
+     *
+     * declare const signaling: SignalingClient
+     * await signaling.close()
+     * ```
+     */
+    close(): Promise<void>;
+    /**
+     * The transport of the URL: Socket.IO or JSON-RPC over WebSocket
+     * @protected
+     */
+    protected transport(): Promise<SignalingTransport>;
+}

package/dist/cjs/peer/SignalingClient.js

@@ -0,0 +1,285 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SignalingClient = void 0;
+const node_crypto_1 = require("node:crypto");
+const core_1 = require("@lakutata/core");
+const di_1 = require("@lakutata/core/decorator/di");
+const SignalingSession_js_1 = require("../shared/SignalingSession.js");
+const Transports_js_1 = require("../shared/Transports.js");
+const SignalingConnectionException_js_1 = require("../exceptions/SignalingConnectionException.js");
+const PeerConnection_js_1 = require("./PeerConnection.js");
+/**
+ * A lakutata application as a member of the rooms of a signaling server of this package (`Signaling` and
+ * `SignalingController`, on this application or another one): it joins rooms and connects to their other members,
+ * browsers or applications, with {@link PeerConnection}s. Over Socket.IO (an `http:` or `https:` URL, with the package
+ * `socket.io-client`) or JSON-RPC over WebSocket (a `ws:` or `wss:` URL, with the `WebSocket` of Node.js 22 and of Bun);
+ * it reconnects by itself and joins its rooms again, keeping the peer-to-peer connections.
+ *
+ * Get a new one with `getObject(SignalingClient, options)` (it is `@Transient`, and needs no registration); `close()`
+ * leaves the rooms and closes the connections.
+ * @example
+ * ```typescript
+ * import {Component} from 'lakutata'
+ * import {type Peer, type PeerChannel, type Room, SignalingClient} from '@lakutata/webrtc'
+ *
+ * //A service of a device: sends its telemetry to whoever joins its room
+ * class TelemetryService extends Component {
+ *     protected async init(): Promise<void> {
+ *         const signaling: SignalingClient = await this.getObject(SignalingClient, {url: 'https://example.com', id: 'device-7'})
+ *         const room: Room = await signaling.join('device-7')
+ *         room.on('peer', (peer: Peer): void => {
+ *             const channel: PeerChannel = peer.createDataChannel('telemetry')
+ *             const timer: NodeJS.Timeout = setInterval((): void => {
+ *                 if (channel.readyState === 'open') channel.send(JSON.stringify({temperature: 21.5}))
+ *             }, 1000)
+ *             peer.on('close', (): void => clearInterval(timer))
+ *         })
+ *     }
+ * }
+ * ```
+ */
+let SignalingClient = class SignalingClient extends core_1.Provider {
+    #clientId;
+    #socket;
+    #session;
+    #closed = false;
+    /**
+     * Connect to the signaling (the requests wait for the connection).
+     * @protected
+     */
+    async init() {
+        this.#clientId = this.id ?? (0, node_crypto_1.randomUUID)();
+        const transport = await this.transport();
+        this.#session = new SignalingSession_js_1.SignalingSession(transport, {
+            iceTransportPolicy: this.iceTransportPolicy,
+            createPeerConnection: (configuration) => this.getObject(PeerConnection_js_1.PeerConnection, {
+                ...configuration,
+                icePortRange: this.icePortRange,
+                iceAdditionalHostAddresses: this.iceAdditionalHostAddresses,
+                ...this.codecs ? { codecs: this.codecs } : {},
+                ...this.threads ? { threads: this.threads } : {}
+            })
+        });
+    }
+    /**
+     * Leave the rooms and disconnect.
+     * @protected
+     */
+    async destroy() {
+        this.#closed = true;
+        await this.#session?.close();
+        this.#socket?.disconnect();
+    }
+    /**
+     * The client id: the member's id in the rooms.
+     */
+    get clientId() {
+        return this.#clientId;
+    }
+    /**
+     * Whether the signaling is connected.
+     */
+    get connected() {
+        return this.#session.connected;
+    }
+    /**
+     * The rooms joined.
+     */
+    get rooms() {
+        return this.#session.rooms;
+    }
+    /**
+     * The ICE servers given by the server, with the TURN credentials (renewed before they expire).
+     */
+    get iceServers() {
+        return this.#session.iceServers;
+    }
+    /**
+     * Join a room: its `peer` event gives the other members, each with its {@link PeerConnection}.
+     * @param room The room.
+     * @param options The metadata the other members get.
+     * @returns The room.
+     * @throws {SignalingRequestError} When the server refuses (`E_SIGNALING_DENIED`, `E_SIGNALING_LIMIT`) or does not
+     * answer (`E_SIGNALING_TIMEOUT`).
+     * @example
+     * ```typescript
+     * import type {Room, SignalingClient} from '@lakutata/webrtc'
+     *
+     * declare const signaling: SignalingClient
+     * const room: Room = await signaling.join('meeting', {metadata: {name: 'Recorder'}})
+     * ```
+     */
+    async join(room, options = {}) {
+        return await this.#session.join(room, options);
+    }
+    /**
+     * Listen to the signaling: `connected` (again, after a disconnection; the rooms are joined again), `disconnected`
+     * (the peer-to-peer connections stay up), `error` (a background task failed).
+     * @param event The event.
+     * @param listener The listener.
+     * @returns The client.
+     * @example
+     * ```typescript
+     * import type {SignalingClient} from '@lakutata/webrtc'
+     *
+     * declare const signaling: SignalingClient
+     * signaling.on('disconnected', (): void => console.log('signaling lost, reconnecting'))
+     * ```
+     */
+    on(event, listener) {
+        this.#session.on(event, listener);
+        return this;
+    }
+    /**
+     * Remove a listener added with `on`.
+     * @param event The event.
+     * @param listener The listener.
+     * @returns The client.
+     * @example
+     * ```typescript
+     * import type {SignalingClient} from '@lakutata/webrtc'
+     *
+     * declare const signaling: SignalingClient
+     * const listener = (error: Error): void => console.error(error)
+     * signaling.on('error', listener)
+     * signaling.off('error', listener)
+     * ```
+     */
+    off(event, listener) {
+        this.#session.off(event, listener);
+        return this;
+    }
+    /**
+     * Leave the rooms, close their connections, disconnect, and destroy the object.
+     * @returns Resolves once done.
+     * @example
+     * ```typescript
+     * import type {SignalingClient} from '@lakutata/webrtc'
+     *
+     * declare const signaling: SignalingClient
+     * await signaling.close()
+     * ```
+     */
+    async close() {
+        if (this.#closed)
+            return;
+        await this.dispose();
+    }
+    /**
+     * The transport of the URL: Socket.IO or JSON-RPC over WebSocket
+     * @protected
+     */
+    async transport() {
+        const url = new URL(this.url);
+        if (url.protocol === 'ws:' || url.protocol === 'wss:') {
+            const WebSocketClass = globalThis.WebSocket;
+            if (!WebSocketClass)
+                throw new SignalingConnectionException_js_1.SignalingConnectionException('JSON-RPC over WebSocket needs the global WebSocket (Node.js 22 and later)');
+            url.searchParams.set('id', this.#clientId);
+            const address = url.toString();
+            return new Transports_js_1.JSONRPCTransport(() => new WebSocketClass(address), this.timeout);
+        }
+        let io;
+        try {
+            const module = 'socket.io-client';
+            io = (await Promise.resolve(`${module}`).then(s => __importStar(require(s)))).io;
+        }
+        catch {
+            throw new SignalingConnectionException_js_1.SignalingConnectionException('Socket.IO needs the package socket.io-client: npm install socket.io-client');
+        }
+        const socket = io(this.url, {
+            path: this.path,
+            auth: { ...this.auth, id: this.#clientId },
+            transports: ['websocket']
+        });
+        this.#socket = socket;
+        return new Transports_js_1.SocketIOTransport(socket, this.timeout);
+    }
+};
+exports.SignalingClient = SignalingClient;
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.String().uri({ scheme: ['http', 'https', 'ws', 'wss'] }).required()),
+    __metadata("design:type", String)
+], SignalingClient.prototype, "url", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.String().min(1).max(200).optional()),
+    __metadata("design:type", String)
+], SignalingClient.prototype, "id", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.String().optional().default('/socket.io')),
+    __metadata("design:type", String)
+], SignalingClient.prototype, "path", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.Object().optional().default({})),
+    __metadata("design:type", Object)
+], SignalingClient.prototype, "auth", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.Number().integer().positive().optional().default(15000)),
+    __metadata("design:type", Number)
+], SignalingClient.prototype, "timeout", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.String().valid('all', 'relay').optional().default('all')),
+    __metadata("design:type", String)
+], SignalingClient.prototype, "iceTransportPolicy", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.Array().items(core_1.DTO.Number().port()).length(2).optional()),
+    __metadata("design:type", Array)
+], SignalingClient.prototype, "icePortRange", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.Array().items(core_1.DTO.String()).optional()),
+    __metadata("design:type", Array)
+], SignalingClient.prototype, "iceAdditionalHostAddresses", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.Array().items(core_1.DTO.String()).optional()),
+    __metadata("design:type", Array)
+], SignalingClient.prototype, "codecs", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.String().optional()),
+    __metadata("design:type", String)
+], SignalingClient.prototype, "threads", void 0);
+exports.SignalingClient = SignalingClient = __decorate([
+    (0, di_1.Autoload)(),
+    (0, di_1.Transient)()
+], SignalingClient);