@lakutata/webrtc 0.0.0-stage → 3.1.4

package/dist/types/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/types/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/types/turn/TURNServer.d.ts

@@ -0,0 +1,309 @@
+import { Component, type ComponentOptions } from '@lakutata/core';
+import type { SignalingIceServer } from '../protocol/SignalingProtocol.js';
+import { type TURNCredentials } from './TURNCredentials.js';
+/**
+ * The TLS listener of a {@link TURNServer} (`turns:`), for the networks letting only TLS through (port 443).
+ */
+export interface TURNServerTLSOptions {
+    /**
+     * The certificate, in PEM.
+     */
+    cert: string | Buffer;
+    /**
+     * Its private key, in PEM.
+     */
+    key: string | Buffer;
+    /**
+     * The TCP port.
+     * @default 5349
+     */
+    port?: number;
+}
+/**
+ * The options of a {@link TURNServer} (see {@link buildTURNServerOptions}).
+ */
+export interface TURNServerOptions {
+    /**
+     * The address the server listens on.
+     * @default '0.0.0.0'
+     */
+    host?: string;
+    /**
+     * The port of STUN and TURN over UDP and TCP.
+     * @default 3478
+     */
+    port?: number;
+    /**
+     * Whether to listen over UDP.
+     * @default true
+     */
+    udp?: boolean;
+    /**
+     * Whether to listen over TCP.
+     * @default true
+     */
+    tcp?: boolean;
+    /**
+     * The TLS listener (`turns:`); none by default.
+     */
+    tls?: TURNServerTLSOptions;
+    /**
+     * The address the clients reach the server at, given in the ICE servers and the relayed addresses: the public
+     * address of the host (or of its NAT, its port mapping forwarding the ports).
+     * @default the first IPv4 address of the host that is not internal, else 127.0.0.1
+     */
+    publicAddress?: string;
+    /**
+     * The UDP ports of the relays, as `[first, last]`: the range published by the container or opened in the firewall.
+     * @default any free port
+     */
+    relayPortRange?: [number, number];
+    /**
+     * The secret of the short-lived credentials ({@link TURNServer.credentials}), shared with the TURN servers of the
+     * other instances (or with a coturn configured with `use-auth-secret`).
+     * @default a random secret, chosen when the server starts
+     */
+    secret?: string;
+    /**
+     * Users with a fixed password, `{username: password}`, besides the short-lived credentials.
+     * @default none
+     */
+    users?: Record<string, string>;
+    /**
+     * The realm of the long-term credentials.
+     * @default 'lakutata'
+     */
+    realm?: string;
+    /**
+     * How long the short-lived credentials are valid, in seconds.
+     * @default 86400 (a day)
+     */
+    credentialTtl?: number;
+    /**
+     * The allocations (relays) at once at most.
+     * @default no limit
+     */
+    maxAllocations?: number;
+    /**
+     * Worker threads that serve the clients, to use more cores: the listeners of the threads share the ports of the
+     * server (`SO_REUSEPORT`), the system keeps each client on one of them, and that thread relays its traffic.
+     * `relayPortRange`, when given, is split among the threads and needs at least one port for each; `maxAllocations`
+     * counts the allocations of all the threads. A thread that stops (only a bug stops one) loses its allocations and
+     * is started again; meanwhile the system spreads the clients over UDP among the threads left, then among all of
+     * them, so most of them find their allocation gone, as when a TURN server restarts (the connections over TCP and
+     * TLS of the other threads stay). The ports can be shared on Linux; elsewhere (macOS, Windows), the server relays
+     * in the main thread and says so in the debug messages (`webrtc/turn`, see `setDebugHandler`). With 0, the server
+     * relays in the main thread.
+     * @default 0
+     */
+    workers?: number;
+    /**
+     * The name of a {@link Cluster} component: the server tells the other nodes its address and its load, and the
+     * `Signaling` and `WHIP` components of all the nodes give it to their clients. It needs a `secret` shared by the
+     * TURN servers of the cluster.
+     * @default none
+     */
+    cluster?: string;
+}
+/**
+ * Where the clients reach a TURN server: its address, the port of UDP and TCP, the port of TLS
+ */
+export interface TURNServerLocation {
+    /**
+     * The address the clients reach it at.
+     */
+    readonly address: string;
+    /**
+     * The port of STUN and TURN over UDP and TCP.
+     */
+    readonly port: number;
+    /**
+     * Whether it listens over UDP.
+     */
+    readonly udp: boolean;
+    /**
+     * Whether it listens over TCP.
+     */
+    readonly tcp: boolean;
+    /**
+     * The port of TURN over TLS, if it listens over TLS.
+     */
+    readonly tlsPort?: number;
+}
+/**
+ * A STUN and TURN server inside the application (RFC 8489, RFC 8656): over UDP and TCP on port 3478, and over TLS when
+ * given a certificate. The browsers and the other clients use it to find their public address (STUN) and to relay their
+ * traffic when they cannot connect directly (TURN). It authenticates the clients with short-lived credentials made
+ * with its secret ({@link TURNServer.credentials}), as coturn's REST API does, and with the fixed users of its options;
+ * both use the SHA-1 integrity of RFC 5389, which the browsers require.
+ *
+ * Register it with {@link buildTURNServerOptions} and list it in `bootstrap` so that it listens when the application
+ * starts; the `Signaling` component gives its ICE servers and credentials to the members of the rooms. With a
+ * `cluster`, the server tells the other nodes where it is and how many allocations it has, and the signaling of every
+ * node gives the members the least loaded TURN servers of the cluster.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildTURNServerOptions, type TURNServer} from '@lakutata/webrtc'
+ *
+ * Application
+ *     .run(() => ({
+ *         id: 'turn.app',
+ *         name: 'TURN',
+ *         components: {
+ *             //UDP and TCP on 3478, the relays on 49160-49200, reached at the public address of the host
+ *             turn: buildTURNServerOptions({publicAddress: '203.0.113.10', relayPortRange: [49160, 49200], secret: process.env.TURN_SECRET})
+ *         },
+ *         bootstrap: ['turn']
+ *     }))
+ *     .onLaunched(async (app: Application): Promise<void> => {
+ *         const turn: TURNServer = await app.getObject<TURNServer>('turn')
+ *         //The ICE servers of a browser, with credentials for the user alice
+ *         console.log(turn.iceServers('alice'))
+ *     })
+ * ```
+ */
+export declare class TURNServer extends Component {
+    #private;
+    /**
+     * The address the server listens on.
+     */
+    protected readonly host: string;
+    /**
+     * The port of STUN and TURN over UDP and TCP.
+     */
+    protected readonly port: number;
+    /**
+     * Whether to listen over UDP.
+     */
+    protected readonly udp: boolean;
+    /**
+     * Whether to listen over TCP.
+     */
+    protected readonly tcp: boolean;
+    /**
+     * The TLS listener.
+     */
+    protected readonly tls?: TURNServerTLSOptions;
+    /**
+     * The address the clients reach the server at.
+     */
+    protected readonly publicAddress?: string;
+    /**
+     * The UDP ports of the relays.
+     */
+    protected readonly relayPortRange?: [number, number];
+    /**
+     * The secret of the short-lived credentials.
+     */
+    protected readonly secret?: string;
+    /**
+     * The users with a fixed password.
+     */
+    protected readonly users: Record<string, string>;
+    /**
+     * The realm of the long-term credentials.
+     */
+    protected readonly realm: string;
+    /**
+     * How long the short-lived credentials are valid, in seconds.
+     */
+    protected readonly credentialTtl: number;
+    /**
+     * The allocations at once at most.
+     */
+    protected readonly maxAllocations?: number;
+    /**
+     * The worker threads serving the clients.
+     */
+    protected readonly workers: number;
+    /**
+     * The name of the cluster component.
+     */
+    protected readonly cluster?: string;
+    /**
+     * Start listening.
+     * @protected
+     */
+    protected init(): Promise<void>;
+    /**
+     * Leave the cluster, stop listening and close the relays.
+     * @protected
+     */
+    protected destroy(): Promise<void>;
+    /**
+     * Tell the other nodes of the cluster where the server is and its load (sent with the next heartbeat).
+     * @protected
+     */
+    protected announce(): void;
+    /**
+     * The address and the port of STUN and TURN over UDP and TCP, as the clients reach them (the public address).
+     */
+    get address(): {
+        address: string;
+        port: number;
+    };
+    /**
+     * The address and the port of TURN over TLS, as the clients reach them; undefined without TLS.
+     */
+    get tlsAddress(): {
+        address: string;
+        port: number;
+    } | undefined;
+    /**
+     * Where the clients reach the server: its public address, its ports.
+     */
+    get location(): TURNServerLocation;
+    /**
+     * The allocations in use: the clients relaying their traffic through the server.
+     */
+    get allocations(): number;
+    /**
+     * Create short-lived credentials for a user, valid for `credentialTtl` seconds.
+     * @param user The user (the part of the username after the expiry).
+     * @returns The username, the password and their lifetime in seconds.
+     * @example
+     * ```typescript
+     * import type {TURNServer, TURNCredentials} from '@lakutata/webrtc'
+     *
+     * declare const turn: TURNServer
+     * const credentials: TURNCredentials = turn.credentials('alice')
+     * ```
+     */
+    credentials(user?: string): TURNCredentials;
+    /**
+     * The ICE servers of a client, as `RTCIceServer` objects: STUN, then TURN over UDP and TCP, then over TLS when it
+     * listens over TLS, with short-lived credentials for the user.
+     * @param user The user the credentials are for.
+     * @returns The ICE servers.
+     * @example
+     * ```typescript
+     * import type {SignalingIceServer, TURNServer} from '@lakutata/webrtc'
+     *
+     * declare const turn: TURNServer
+     * //[{urls: 'stun:203.0.113.10:3478'}, {urls: ['turn:203.0.113.10:3478?transport=udp', …], username, credential}]
+     * const iceServers: SignalingIceServer[] = turn.iceServers('alice')
+     * ```
+     */
+    iceServers(user?: string): SignalingIceServer[];
+}
+/**
+ * Build the options of a {@link TURNServer} component, for the `components` of an application.
+ * @param options Where it listens, the address the clients reach it at, the relay ports, the credentials (all optional).
+ * @returns The component options.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildTURNServerOptions} from '@lakutata/webrtc'
+ *
+ * Application.run(() => ({
+ *     id: 'turn.app',
+ *     name: 'TURN',
+ *     components: {
+ *         turn: buildTURNServerOptions({publicAddress: '203.0.113.10', secret: process.env.TURN_SECRET})
+ *     },
+ *     bootstrap: ['turn']
+ * }))
+ * ```
+ */
+export declare function buildTURNServerOptions(options?: TURNServerOptions): ComponentOptions<TURNServerOptions>;

package/dist/types/turn/TURNWorker.d.ts

@@ -0,0 +1,42 @@
+import { type NodeTurnServerOptions } from '../lib/turn/node/turnServer.js';
+/**
+ * What a worker thread of the TURN server is started with
+ */
+export interface TURNWorkerData {
+    readonly thread: number;
+    readonly options: Omit<NodeTurnServerOptions, 'getPassword' | 'allocationGate' | 'reusePort'>;
+    readonly users: Record<string, string>;
+    readonly secret: string;
+    readonly allocations: SharedArrayBuffer;
+}
+/**
+ * The messages of the main thread to a worker thread of the TURN server
+ */
+export type TURNToWorker = {
+    type: 'stop';
+} | {
+    type: 'debug';
+    enabled: boolean;
+};
+/**
+ * The messages of a worker thread of the TURN server to the main thread
+ */
+export type TURNFromWorker = {
+    type: 'ready';
+    port?: number;
+    tlsPort?: number;
+} | {
+    type: 'failed';
+    error: string;
+} | {
+    type: 'stopped';
+} | {
+    type: 'log';
+    namespace: string;
+    message: string;
+};
+/**
+ * Serve TURN in a worker thread: a server whose listeners share their ports with the ones of the other threads (the
+ * system keeps each client on one), the allocations counted with theirs against maxAllocations
+ */
+export declare function runTURNWorker(): void;

package/dist/types/turn/TURNWorkerCode.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The code of the worker threads of the TURN server: TURNWorker and the engine bundled into one script, written by the
+ * build (scripts/workers.mjs) in place of this empty one
+ */
+export declare const turnWorkerCode: string;

package/dist/types/turn/TURNWorkers.d.ts

@@ -0,0 +1,52 @@
+import type { TURNWorkerData } from './TURNWorker.js';
+/**
+ * Whether the listeners of several threads can share a port here, the system spreading the clients among them
+ * (SO_REUSEPORT): on Linux only (Bun lets the sockets of macOS share a port, but macOS gives all its datagrams to one
+ * of them), when two UDP sockets, then two TCP servers, bind to one port
+ * @param host The address the server listens on.
+ * @internal
+ */
+export declare function portsShareable(host: string): Promise<boolean>;
+/**
+ * The worker threads of each TURN server serving in some (for the tests and the benchmarks)
+ * @internal
+ */
+export declare const turnWorkers: WeakMap<object, TURNWorkers>;
+/**
+ * The worker threads of a TURN server, sharing its ports (SO_REUSEPORT) and counting their allocations together
+ * @internal
+ */
+export declare class TURNWorkers {
+    #private;
+    /**
+     * Prepare the threads.
+     * @param data What each thread is started with (they share one counter of allocations).
+     * @throws {Error} When the code of the threads was not built.
+     */
+    constructor(data: TURNWorkerData[]);
+    /**
+     * Start the threads: the first one, then the others on the ports it bound.
+     * @throws {Error} When a thread cannot serve (a port in use).
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the threads, each closing its server.
+     */
+    stop(): Promise<void>;
+    /**
+     * The allocations of all the threads.
+     */
+    get allocations(): number;
+    /**
+     * The allocations of each thread.
+     */
+    get threadAllocations(): number[];
+    /**
+     * The port of STUN and TURN over UDP and TCP.
+     */
+    get port(): number | undefined;
+    /**
+     * The port of TURN over TLS.
+     */
+    get tlsPort(): number | undefined;
+}