@lakutata/webrtc 0.0.0-stage → 3.1.4

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

@@ -0,0 +1,128 @@
+import { DTO } from '@lakutata/core';
+import { Controller } from '@lakutata/entrypoint';
+import { type SignalingCandidate, type SignalingDescription, type SignalingIceServer, type SignalingJoinResult } from '../protocol/SignalingProtocol.js';
+import type { Signaling } from './Signaling.js';
+/**
+ * The input of `webrtc.join`
+ */
+declare class JoinDTO extends DTO {
+    room: string;
+    metadata?: unknown;
+    session?: string;
+}
+/**
+ * The input of `webrtc.leave`
+ */
+declare class LeaveDTO extends DTO {
+    room: string;
+}
+/**
+ * The input of `webrtc.signal`: a description or a candidate (null or an empty candidate for the end of the candidates)
+ */
+declare class SignalDTO extends DTO {
+    room: string;
+    to: string;
+    description?: SignalingDescription;
+    candidate?: SignalingCandidate | null;
+}
+/**
+ * The controller serving the requests of the signaling ({@link Signaling}), registered as `signaling`): `webrtc.join`,
+ * `webrtc.signal`, `webrtc.leave`, `webrtc.iceServers` and `webrtc.heartbeat`. Their pattern is `{method}`: the method
+ * of a JSON-RPC request, the `method` field of a Socket.IO message (`{method: 'webrtc.join', room: 'meeting'}`). The
+ * member of a request is its client (`clientId` of the context). The events are pushed to the clients, so the requests
+ * coming without a connection to push them through (JSON-RPC over HTTP, the HTTP service adapter) fail with
+ * {@link SignalingClientRequiredException}.
+ *
+ * Add it to the controllers of an entrypoint serving Socket.IO or JSON-RPC over WebSocket; the browser client of
+ * `@lakutata/webrtc/client` and the `SignalingClient` of Node.js speak this protocol.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildEntrypoints} from 'lakutata/com/entrypoint'
+ * import {jsonRPCServiceEntrypoint} from 'lakutata/adapter/jsonrpc'
+ * import {socketIOServiceEntrypoint} from 'lakutata/adapter/socket.io'
+ * import {buildSignalingOptions, SignalingController} from '@lakutata/webrtc'
+ *
+ * Application.run(() => ({
+ *     id: 'meet.app',
+ *     name: 'Meet',
+ *     components: {
+ *         signaling: buildSignalingOptions(),
+ *         //The browsers over Socket.IO on 3000, the other clients over JSON-RPC (WebSocket) on 3001
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [SignalingController],
+ *             service: [socketIOServiceEntrypoint({port: 3000}), jsonRPCServiceEntrypoint({transport: 'websocket', port: 3001})]
+ *         })
+ *     },
+ *     bootstrap: ['entrypoint']
+ * }))
+ * ```
+ */
+export declare class SignalingController extends Controller {
+    /**
+     * The signaling component: the one registered as `signaling`.
+     * @protected
+     */
+    protected signaling(): Promise<Signaling>;
+    /**
+     * The member of the request: its client id
+     * @protected
+     */
+    protected peerId(): string;
+    /**
+     * `webrtc.join`: join a room.
+     * @param input The room, and the metadata the other members get.
+     * @returns The members already in the room, the ICE servers and the heartbeat interval.
+     * @example
+     * ```typescript
+     * //Socket.IO: socket.emit('message', {method: 'webrtc.join', room: 'meeting', metadata: {name: 'Ada'}}, ack)
+     * //JSON-RPC: {"jsonrpc": "2.0", "id": 1, "method": "webrtc.join", "params": {"room": "meeting"}}
+     * ```
+     */
+    join(input: JoinDTO): Promise<SignalingJoinResult>;
+    /**
+     * `webrtc.signal`: send a description or a candidate to a member of a room.
+     * @param input The room, the receiver, the description or the candidate.
+     * @returns Whether the event reached the receiver.
+     * @example
+     * ```typescript
+     * //{method: 'webrtc.signal', room: 'meeting', to: 'bob', description: {type: 'offer', sdp: '…'}}
+     * //{method: 'webrtc.signal', room: 'meeting', to: 'bob', candidate: {candidate: 'candidate:…', sdpMid: '0'}}
+     * ```
+     */
+    sendSignal(input: SignalDTO): Promise<{
+        delivered: boolean;
+    }>;
+    /**
+     * `webrtc.leave`: leave a room.
+     * @param input The room.
+     * @returns Nothing.
+     * @example
+     * ```typescript
+     * //{method: 'webrtc.leave', room: 'meeting'}
+     * ```
+     */
+    leave(input: LeaveDTO): Promise<Record<string, never>>;
+    /**
+     * `webrtc.iceServers`: get the ICE servers again, with new TURN credentials (before the ones given expire).
+     * @returns The ICE servers, and how long their credentials are valid in seconds.
+     * @example
+     * ```typescript
+     * //{method: 'webrtc.iceServers'}
+     * ```
+     */
+    iceServers(): Promise<{
+        iceServers: SignalingIceServer[];
+        credentialTtl: number;
+    }>;
+    /**
+     * `webrtc.heartbeat`: tell the server the client is still there.
+     * @returns Nothing.
+     * @example
+     * ```typescript
+     * //{method: 'webrtc.heartbeat'}, every heartbeatInterval milliseconds of the join result when it is not 0
+     * ```
+     */
+    heartbeat(): Promise<Record<string, never>>;
+}
+export {};

package/dist/cjs/signaling/SignalingController.js

@@ -0,0 +1,229 @@
+"use strict";
+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 __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.SignalingController = void 0;
+const core_1 = require("@lakutata/core");
+const dto_1 = require("@lakutata/core/decorator/dto");
+const entrypoint_1 = require("@lakutata/entrypoint");
+const ctrl_1 = require("@lakutata/entrypoint/decorator/ctrl");
+const SignalingProtocol_js_1 = require("../protocol/SignalingProtocol.js");
+const SignalingClientRequiredException_js_1 = require("../exceptions/SignalingClientRequiredException.js");
+/**
+ * The input of `webrtc.join`
+ */
+class JoinDTO extends core_1.DTO {
+}
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.String().min(1).max(256).required()),
+    __metadata("design:type", String)
+], JoinDTO.prototype, "room", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.Any().optional()),
+    __metadata("design:type", Object)
+], JoinDTO.prototype, "metadata", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.String().max(128).optional()),
+    __metadata("design:type", String)
+], JoinDTO.prototype, "session", void 0);
+/**
+ * The input of `webrtc.leave`
+ */
+class LeaveDTO extends core_1.DTO {
+}
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.String().min(1).max(256).required()),
+    __metadata("design:type", String)
+], LeaveDTO.prototype, "room", void 0);
+/**
+ * The input of `webrtc.signal`: a description or a candidate (null or an empty candidate for the end of the candidates)
+ */
+class SignalDTO extends core_1.DTO {
+}
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.String().min(1).max(256).required()),
+    __metadata("design:type", String)
+], SignalDTO.prototype, "room", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.String().min(1).max(256).required()),
+    __metadata("design:type", String)
+], SignalDTO.prototype, "to", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.Object({
+        type: core_1.DTO.String().valid('offer', 'answer', 'pranswer', 'rollback').required(),
+        sdp: core_1.DTO.String().allow('').optional()
+    }).optional()),
+    __metadata("design:type", Object)
+], SignalDTO.prototype, "description", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.Object({
+        candidate: core_1.DTO.String().allow('').required(),
+        sdpMid: core_1.DTO.String().allow('', null).optional(),
+        sdpMLineIndex: core_1.DTO.Number().integer().min(0).allow(null).optional(),
+        usernameFragment: core_1.DTO.String().allow('', null).optional()
+    }).allow(null).optional()),
+    __metadata("design:type", Object)
+], SignalDTO.prototype, "candidate", void 0);
+/**
+ * The controller serving the requests of the signaling ({@link Signaling}), registered as `signaling`): `webrtc.join`,
+ * `webrtc.signal`, `webrtc.leave`, `webrtc.iceServers` and `webrtc.heartbeat`. Their pattern is `{method}`: the method
+ * of a JSON-RPC request, the `method` field of a Socket.IO message (`{method: 'webrtc.join', room: 'meeting'}`). The
+ * member of a request is its client (`clientId` of the context). The events are pushed to the clients, so the requests
+ * coming without a connection to push them through (JSON-RPC over HTTP, the HTTP service adapter) fail with
+ * {@link SignalingClientRequiredException}.
+ *
+ * Add it to the controllers of an entrypoint serving Socket.IO or JSON-RPC over WebSocket; the browser client of
+ * `@lakutata/webrtc/client` and the `SignalingClient` of Node.js speak this protocol.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildEntrypoints} from 'lakutata/com/entrypoint'
+ * import {jsonRPCServiceEntrypoint} from 'lakutata/adapter/jsonrpc'
+ * import {socketIOServiceEntrypoint} from 'lakutata/adapter/socket.io'
+ * import {buildSignalingOptions, SignalingController} from '@lakutata/webrtc'
+ *
+ * Application.run(() => ({
+ *     id: 'meet.app',
+ *     name: 'Meet',
+ *     components: {
+ *         signaling: buildSignalingOptions(),
+ *         //The browsers over Socket.IO on 3000, the other clients over JSON-RPC (WebSocket) on 3001
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [SignalingController],
+ *             service: [socketIOServiceEntrypoint({port: 3000}), jsonRPCServiceEntrypoint({transport: 'websocket', port: 3001})]
+ *         })
+ *     },
+ *     bootstrap: ['entrypoint']
+ * }))
+ * ```
+ */
+class SignalingController extends entrypoint_1.Controller {
+    /**
+     * The signaling component: the one registered as `signaling`.
+     * @protected
+     */
+    async signaling() {
+        return await this.getObject('signaling');
+    }
+    /**
+     * The member of the request: its client id
+     * @protected
+     */
+    peerId() {
+        const context = this.context;
+        //JSON-RPC over HTTP gives a client id (the id header) but has no connection to push the events through; a data
+        //channel of webrtcServiceEntrypoint is set up by the signaling itself (a member joining through it as itself
+        //would replace its own session)
+        if (!context.clientId || context.jsonrpc?.transport === 'http' || context.jsonrpc?.transport === 'webrtc') {
+            throw new SignalingClientRequiredException_js_1.SignalingClientRequiredException('The signaling needs a transport with clients (Socket.IO, JSON-RPC over WebSocket)');
+        }
+        return context.clientId;
+    }
+    /**
+     * `webrtc.join`: join a room.
+     * @param input The room, and the metadata the other members get.
+     * @returns The members already in the room, the ICE servers and the heartbeat interval.
+     * @example
+     * ```typescript
+     * //Socket.IO: socket.emit('message', {method: 'webrtc.join', room: 'meeting', metadata: {name: 'Ada'}}, ack)
+     * //JSON-RPC: {"jsonrpc": "2.0", "id": 1, "method": "webrtc.join", "params": {"room": "meeting"}}
+     * ```
+     */
+    async join(input) {
+        return await (await this.signaling()).join(this.peerId(), input.room, { metadata: input.metadata, session: input.session, context: this.context });
+    }
+    /**
+     * `webrtc.signal`: send a description or a candidate to a member of a room.
+     * @param input The room, the receiver, the description or the candidate.
+     * @returns Whether the event reached the receiver.
+     * @example
+     * ```typescript
+     * //{method: 'webrtc.signal', room: 'meeting', to: 'bob', description: {type: 'offer', sdp: '…'}}
+     * //{method: 'webrtc.signal', room: 'meeting', to: 'bob', candidate: {candidate: 'candidate:…', sdpMid: '0'}}
+     * ```
+     */
+    async sendSignal(input) {
+        const delivered = await (await this.signaling()).signal(this.peerId(), input.room, input.to, {
+            description: input.description,
+            candidate: input.candidate
+        });
+        return { delivered: delivered };
+    }
+    /**
+     * `webrtc.leave`: leave a room.
+     * @param input The room.
+     * @returns Nothing.
+     * @example
+     * ```typescript
+     * //{method: 'webrtc.leave', room: 'meeting'}
+     * ```
+     */
+    async leave(input) {
+        await (await this.signaling()).leave(this.peerId(), input.room);
+        return {};
+    }
+    /**
+     * `webrtc.iceServers`: get the ICE servers again, with new TURN credentials (before the ones given expire).
+     * @returns The ICE servers, and how long their credentials are valid in seconds.
+     * @example
+     * ```typescript
+     * //{method: 'webrtc.iceServers'}
+     * ```
+     */
+    async iceServers() {
+        const signaling = await this.signaling();
+        const peerId = this.peerId();
+        signaling.heartbeat(peerId);
+        return await signaling.iceServersOf(peerId);
+    }
+    /**
+     * `webrtc.heartbeat`: tell the server the client is still there.
+     * @returns Nothing.
+     * @example
+     * ```typescript
+     * //{method: 'webrtc.heartbeat'}, every heartbeatInterval milliseconds of the join result when it is not 0
+     * ```
+     */
+    async heartbeat() {
+        (await this.signaling()).heartbeat(this.peerId());
+        return {};
+    }
+}
+exports.SignalingController = SignalingController;
+__decorate([
+    (0, ctrl_1.ServiceAction)({ method: SignalingProtocol_js_1.SignalingMethod.join }, JoinDTO),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [JoinDTO]),
+    __metadata("design:returntype", Promise)
+], SignalingController.prototype, "join", null);
+__decorate([
+    (0, ctrl_1.ServiceAction)({ method: SignalingProtocol_js_1.SignalingMethod.signal }, SignalDTO),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [SignalDTO]),
+    __metadata("design:returntype", Promise)
+], SignalingController.prototype, "sendSignal", null);
+__decorate([
+    (0, ctrl_1.ServiceAction)({ method: SignalingProtocol_js_1.SignalingMethod.leave }, LeaveDTO),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [LeaveDTO]),
+    __metadata("design:returntype", Promise)
+], SignalingController.prototype, "leave", null);
+__decorate([
+    (0, ctrl_1.ServiceAction)({ method: SignalingProtocol_js_1.SignalingMethod.iceServers }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], SignalingController.prototype, "iceServers", null);
+__decorate([
+    (0, ctrl_1.ServiceAction)({ method: SignalingProtocol_js_1.SignalingMethod.heartbeat }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], SignalingController.prototype, "heartbeat", null);

package/dist/cjs/turn/TURNCredentials.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Short-lived TURN credentials (the REST API of coturn): the username is `<expiry>:<user>` (the expiry in seconds since
+ * the epoch), the password `base64(HMAC-SHA1(secret, username))`. A TURN server holding the secret checks them without
+ * storing them; an external coturn configured with the same secret (`use-auth-secret`) accepts them as well.
+ */
+export interface TURNCredentials {
+    /**
+     * The username: `<expiry>:<user>`.
+     */
+    username: string;
+    /**
+     * The password.
+     */
+    credential: string;
+    /**
+     * How long they are valid from now, in seconds.
+     */
+    ttl: number;
+}
+/**
+ * Create short-lived TURN credentials.
+ * @param secret The secret shared with the TURN server.
+ * @param user The user the credentials are for (the part of the username after the expiry); it may not hold `:`.
+ * @param ttl How long they are valid, in seconds.
+ * @param now The current time in milliseconds (for tests).
+ * @returns The credentials.
+ * @example
+ * ```typescript
+ * import {createTURNCredentials, type TURNCredentials} from '@lakutata/webrtc'
+ *
+ * //Valid for an hour, for the user alice: {username: '1767229200:alice', credential: '…', ttl: 3600}
+ * const credentials: TURNCredentials = createTURNCredentials('the shared secret', 'alice', 3600)
+ * ```
+ */
+export declare function createTURNCredentials(secret: string, user: string, ttl: number, now?: number): TURNCredentials;
+/**
+ * The password of a username of short-lived credentials
+ * @param secret
+ * @param username
+ */
+export declare function turnPassword(secret: string, username: string): string;
+/**
+ * The password of a username when its credentials are short-lived ones of the secret and not expired; undefined
+ * otherwise (for the TURN server: an unknown user)
+ * @param secret
+ * @param username
+ * @param now
+ */
+export declare function turnPasswordIfValid(secret: string, username: string, now?: number): string | undefined;

package/dist/cjs/turn/TURNCredentials.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTURNCredentials = createTURNCredentials;
+exports.turnPassword = turnPassword;
+exports.turnPasswordIfValid = turnPasswordIfValid;
+const node_crypto_1 = require("node:crypto");
+/**
+ * Create short-lived TURN credentials.
+ * @param secret The secret shared with the TURN server.
+ * @param user The user the credentials are for (the part of the username after the expiry); it may not hold `:`.
+ * @param ttl How long they are valid, in seconds.
+ * @param now The current time in milliseconds (for tests).
+ * @returns The credentials.
+ * @example
+ * ```typescript
+ * import {createTURNCredentials, type TURNCredentials} from '@lakutata/webrtc'
+ *
+ * //Valid for an hour, for the user alice: {username: '1767229200:alice', credential: '…', ttl: 3600}
+ * const credentials: TURNCredentials = createTURNCredentials('the shared secret', 'alice', 3600)
+ * ```
+ */
+function createTURNCredentials(secret, user, ttl, now = Date.now()) {
+    const username = `${Math.floor(now / 1000) + Math.floor(ttl)}:${user.replaceAll(':', '_')}`;
+    return { username: username, credential: turnPassword(secret, username), ttl: Math.floor(ttl) };
+}
+/**
+ * The password of a username of short-lived credentials
+ * @param secret
+ * @param username
+ */
+function turnPassword(secret, username) {
+    return (0, node_crypto_1.createHmac)('sha1', secret).update(username).digest('base64');
+}
+/**
+ * The password of a username when its credentials are short-lived ones of the secret and not expired; undefined
+ * otherwise (for the TURN server: an unknown user)
+ * @param secret
+ * @param username
+ * @param now
+ */
+function turnPasswordIfValid(secret, username, now = Date.now()) {
+    const separator = username.indexOf(':');
+    if (separator <= 0)
+        return undefined;
+    const expiry = Number(username.slice(0, separator));
+    if (!Number.isFinite(expiry) || expiry * 1000 < now)
+        return undefined;
+    return turnPassword(secret, username);
+}

package/dist/cjs/turn/TURNIceServers.d.ts

@@ -0,0 +1,11 @@
+import type { SignalingIceServer } from '../protocol/SignalingProtocol.js';
+import type { TURNServerLocation } from './TURNServer.js';
+/**
+ * The ICE servers of a TURN server, as `RTCIceServer` objects: STUN, then TURN over UDP and TCP, then over TLS
+ * @param location Where the clients reach it.
+ * @param credentials The username and the password.
+ */
+export declare function iceServersOfTURN(location: TURNServerLocation, credentials: {
+    username: string;
+    credential: string;
+}): SignalingIceServer[];

package/dist/cjs/turn/TURNIceServers.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.iceServersOfTURN = iceServersOfTURN;
+/**
+ * The ICE servers of a TURN server, as `RTCIceServer` objects: STUN, then TURN over UDP and TCP, then over TLS
+ * @param location Where the clients reach it.
+ * @param credentials The username and the password.
+ */
+function iceServersOfTURN(location, credentials) {
+    const { address, port, udp, tcp, tlsPort } = location;
+    const host = address.includes(':') ? `[${address}]` : address;
+    const urls = [];
+    if (udp)
+        urls.push(`turn:${host}:${port}?transport=udp`);
+    if (tcp)
+        urls.push(`turn:${host}:${port}?transport=tcp`);
+    if (tlsPort !== undefined)
+        urls.push(`turns:${host}:${tlsPort}?transport=tcp`);
+    const servers = [];
+    if (udp)
+        servers.push({ urls: `stun:${host}:${port}` });
+    if (urls.length)
+        servers.push({ urls: urls, username: credentials.username, credential: credentials.credential });
+    return servers;
+}