@lakutata/webrtc 0.0.0-stage → 3.1.1

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

@@ -0,0 +1,114 @@
+import type { HeapInfo } from 'node:v8';
+import { type ResourceLimits } from 'node:worker_threads';
+import { Component, type ComponentOptions } from '@lakutata/core';
+import type { EngineOptions } from './EngineConfig.js';
+import { RemoteConnection } from './RemoteConnection.js';
+/**
+ * The options of {@link PeerThreads} (see {@link buildPeerThreadsOptions}).
+ */
+export interface PeerThreadsOptions {
+    /**
+     * The worker threads at most. They start when needed: a new connection goes to a thread serving none (a new one is
+     * started while there are fewer than this), else to the thread serving the fewest.
+     * @default the number of cores less one, at least 1
+     */
+    threads?: number;
+    /**
+     * The limits of the heap and of the stack of each thread (`resourceLimits` of `node:worker_threads`). Bun ignores
+     * them.
+     * @default the limits of V8
+     */
+    resourceLimits?: ResourceLimits;
+}
+/**
+ * Worker threads serving connections, to use more cores: a {@link PeerConnection} given the name of this component
+ * (its `threads` option) runs its ICE, DTLS, SCTP and SRTP there, while its object, its events and the messages of its
+ * channels stay in the main thread. Each connection is served by one thread for its whole life; a thread that stops
+ * (only a bug stops one) fails its connections (`failed`, then `closed`), and is started again for the next ones.
+ *
+ * Register it with {@link buildPeerThreadsOptions}; the threads stop when the application does.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildPeerThreadsOptions, PeerConnection} from '@lakutata/webrtc'
+ *
+ * Application
+ *     .run(() => ({
+ *         id: 'peers.app',
+ *         name: 'Peers',
+ *         components: {
+ *             peerThreads: buildPeerThreadsOptions({threads: 4})
+ *         }
+ *     }))
+ *     .onLaunched(async (app: Application): Promise<void> => {
+ *         //Its engine runs in one of the four threads
+ *         const connection: PeerConnection = await app.getObject(PeerConnection, {threads: 'peerThreads'})
+ *         connection.createDataChannel('data')
+ *     })
+ * ```
+ */
+export declare class PeerThreads extends Component {
+    #private;
+    /**
+     * The worker threads at most.
+     */
+    protected readonly threads?: number;
+    /**
+     * The limits of the heap and of the stack of each thread.
+     */
+    protected readonly resourceLimits?: ResourceLimits;
+    /**
+     * Prepare the threads (they start when needed).
+     * @protected
+     */
+    protected init(): Promise<void>;
+    /**
+     * Stop the threads, closing their connections.
+     * @protected
+     */
+    protected destroy(): Promise<void>;
+    /**
+     * Open a connection in a thread.
+     * @param options The options of its engine.
+     * @returns The connection, as the main thread sees it.
+     * @internal
+     */
+    open(options: EngineOptions): Promise<RemoteConnection>;
+    /**
+     * The connections of each thread.
+     * @returns Their numbers, by thread (0 for a thread not started).
+     * @internal
+     */
+    load(): number[];
+    /**
+     * The heap of each thread (to measure the memory of the threads).
+     * @returns The statistics of the heap of each thread running, by its index.
+     * @internal
+     */
+    heaps(): Promise<(HeapInfo | undefined)[]>;
+    /**
+     * Stop a thread as a bug would (for the tests).
+     * @param index The thread.
+     * @internal
+     */
+    crash(index: number): Promise<void>;
+}
+/**
+ * Build the options of a {@link PeerThreads} component, for the `components` of an application.
+ * @param options The threads at most, their limits (all optional).
+ * @returns The component options.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildPeerThreadsOptions} from '@lakutata/webrtc'
+ *
+ * Application.run(() => ({
+ *     id: 'peers.app',
+ *     name: 'Peers',
+ *     components: {
+ *         peerThreads: buildPeerThreadsOptions({threads: 4})
+ *     }
+ * }))
+ * ```
+ */
+export declare function buildPeerThreadsOptions(options?: PeerThreadsOptions): ComponentOptions<PeerThreadsOptions>;

package/dist/cjs/peer/PeerThreads.js

@@ -0,0 +1,268 @@
+"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.PeerThreads = void 0;
+exports.buildPeerThreadsOptions = buildPeerThreadsOptions;
+const node_os_1 = require("node:os");
+const node_worker_threads_1 = require("node:worker_threads");
+const core_1 = require("@lakutata/core");
+const di_1 = require("@lakutata/core/decorator/di");
+const log_js_1 = require("../lib/common/log.js");
+const PeerThreadChannel_js_1 = require("./PeerThreadChannel.js");
+const PeerWorkerCode_js_1 = require("./PeerWorkerCode.js");
+const RemoteConnection_js_1 = require("./RemoteConnection.js");
+const log = (0, log_js_1.debug)('webrtc/peer/threads');
+/**
+ * How long a thread asked to stop has to close its connections, in milliseconds
+ */
+const STOP_TIMEOUT = 5000;
+/**
+ * Worker threads serving connections, to use more cores: a {@link PeerConnection} given the name of this component
+ * (its `threads` option) runs its ICE, DTLS, SCTP and SRTP there, while its object, its events and the messages of its
+ * channels stay in the main thread. Each connection is served by one thread for its whole life; a thread that stops
+ * (only a bug stops one) fails its connections (`failed`, then `closed`), and is started again for the next ones.
+ *
+ * Register it with {@link buildPeerThreadsOptions}; the threads stop when the application does.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildPeerThreadsOptions, PeerConnection} from '@lakutata/webrtc'
+ *
+ * Application
+ *     .run(() => ({
+ *         id: 'peers.app',
+ *         name: 'Peers',
+ *         components: {
+ *             peerThreads: buildPeerThreadsOptions({threads: 4})
+ *         }
+ *     }))
+ *     .onLaunched(async (app: Application): Promise<void> => {
+ *         //Its engine runs in one of the four threads
+ *         const connection: PeerConnection = await app.getObject(PeerConnection, {threads: 'peerThreads'})
+ *         connection.createDataChannel('data')
+ *     })
+ * ```
+ */
+let PeerThreads = class PeerThreads extends core_1.Component {
+    #slots = [];
+    #nextConnection = 1;
+    #stopping = false;
+    //Tells the threads whether the main thread has a debug handler
+    #debugging = (set) => {
+        for (const slot of this.#slots)
+            slot.channel?.post({ type: 'debug', enabled: set });
+    };
+    /**
+     * Prepare the threads (they start when needed).
+     * @protected
+     */
+    async init() {
+        if (!PeerWorkerCode_js_1.peerWorkerCode)
+            throw new Error('The code of the worker threads of the connections is not built (scripts/workers.mjs)');
+        const count = this.threads ?? Math.max(1, (0, node_os_1.availableParallelism)() - 1);
+        this.#slots = Array.from({ length: count }, (_, index) => ({ index: index, connections: new Map(), opening: 0 }));
+        log_js_1.debugHandlerWatchers.add(this.#debugging);
+    }
+    /**
+     * Stop the threads, closing their connections.
+     * @protected
+     */
+    async destroy() {
+        this.#stopping = true;
+        log_js_1.debugHandlerWatchers.delete(this.#debugging);
+        await Promise.all(this.#slots.map((slot) => this.#stop(slot)));
+    }
+    /**
+     * Open a connection in a thread.
+     * @param options The options of its engine.
+     * @returns The connection, as the main thread sees it.
+     * @internal
+     */
+    async open(options) {
+        if (this.#stopping)
+            throw Object.assign(new Error('The worker threads of the connections are stopping'), { name: 'InvalidStateError' });
+        const slot = this.#choose();
+        slot.opening++;
+        try {
+            await this.#start(slot);
+            const conn = this.#nextConnection++;
+            const channel = slot.channel;
+            const link = {
+                request: (message, transfer) => channel.request(message, transfer),
+                post: (message, transfer) => channel.post(message, transfer),
+                postOrExtend: (extend, message, transfer) => channel.postOrExtend(extend, message, transfer),
+                pack: (data) => channel.pack(data),
+                release: (released) => slot.connections.delete(released)
+            };
+            //Known before it is opened: its first events may come before the reply
+            const connection = new RemoteConnection_js_1.RemoteConnection(link, conn);
+            slot.connections.set(conn, connection);
+            try {
+                connection.opened(await channel.request({ type: 'open', conn: conn, options: options }));
+            }
+            catch (error) {
+                slot.connections.delete(conn);
+                throw error;
+            }
+            return connection;
+        }
+        finally {
+            slot.opening--;
+        }
+    }
+    /**
+     * The connections of each thread.
+     * @returns Their numbers, by thread (0 for a thread not started).
+     * @internal
+     */
+    load() {
+        return this.#slots.map((slot) => slot.connections.size);
+    }
+    /**
+     * The heap of each thread (to measure the memory of the threads).
+     * @returns The statistics of the heap of each thread running, by its index.
+     * @internal
+     */
+    async heaps() {
+        return await Promise.all(this.#slots.map((slot) => slot.worker ? slot.worker.getHeapStatistics().catch(() => undefined) : Promise.resolve(undefined)));
+    }
+    /**
+     * Stop a thread as a bug would (for the tests).
+     * @param index The thread.
+     * @internal
+     */
+    async crash(index) {
+        await this.#slots[index]?.worker?.terminate();
+    }
+    /**
+     * The thread of a new connection: one serving none (started first), else a new one while there are fewer than the
+     * threads at most, else the one serving the fewest
+     */
+    #choose() {
+        const loadOf = (slot) => slot.connections.size + slot.opening;
+        const started = this.#slots.filter((slot) => !!slot.worker);
+        const idle = started.find((slot) => loadOf(slot) === 0);
+        if (idle)
+            return idle;
+        const free = this.#slots.find((slot) => !slot.worker);
+        if (free)
+            return free;
+        return started.reduce((least, slot) => loadOf(slot) < loadOf(least) ? slot : least);
+    }
+    /**
+     * Start the thread of a slot, unless it runs
+     * @param slot
+     */
+    #start(slot) {
+        if (slot.ready)
+            return slot.ready;
+        const worker = new node_worker_threads_1.Worker(PeerWorkerCode_js_1.peerWorkerCode, {
+            eval: true,
+            workerData: { thread: slot.index },
+            ...this.resourceLimits ? { resourceLimits: this.resourceLimits } : {}
+        });
+        slot.worker = worker;
+        let ready;
+        let failed;
+        slot.ready = new Promise((resolve, reject) => {
+            ready = resolve;
+            failed = reject;
+        });
+        const channel = new PeerThreadChannel_js_1.PeerThreadChannel(worker, (message) => {
+            switch (message.type) {
+                case 'ready':
+                    return ready();
+                case 'log':
+                    return (0, log_js_1.debug)(message.namespace)(message.message);
+                default:
+                    return slot.connections.get(message.conn)?.handle(message);
+            }
+        });
+        slot.channel = channel;
+        if ((0, log_js_1.hasDebugHandler)())
+            channel.post({ type: 'debug', enabled: true });
+        worker.on('error', (error) => log('the worker thread %d failed: %O', slot.index, error));
+        worker.on('exit', (code) => {
+            if (slot.worker !== worker)
+                return;
+            if (!this.#stopping)
+                log('the worker thread %d stopped (exit code %d)', slot.index, code);
+            const error = Object.assign(new Error('The worker thread of the connection stopped'), { name: 'InvalidStateError' });
+            failed(error);
+            channel.close(error);
+            slot.worker = undefined;
+            slot.channel = undefined;
+            slot.ready = undefined;
+            const lost = [...slot.connections.values()];
+            slot.connections.clear();
+            for (const connection of lost)
+                connection.lost(!this.#stopping);
+        });
+        return slot.ready;
+    }
+    /**
+     * Stop the thread of a slot, closing its connections
+     * @param slot
+     */
+    async #stop(slot) {
+        const worker = slot.worker;
+        const channel = slot.channel;
+        if (!worker || !channel)
+            return;
+        let timer;
+        await Promise.race([
+            channel.request({ type: 'stop' }).catch(() => undefined),
+            new Promise((resolve) => {
+                timer = setTimeout(resolve, STOP_TIMEOUT);
+            })
+        ]);
+        clearTimeout(timer);
+        await worker.terminate();
+    }
+};
+exports.PeerThreads = PeerThreads;
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.Number().integer().positive().optional()),
+    __metadata("design:type", Number)
+], PeerThreads.prototype, "threads", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.Object({
+        maxYoungGenerationSizeMb: core_1.DTO.Number().positive().optional(),
+        maxOldGenerationSizeMb: core_1.DTO.Number().positive().optional(),
+        codeRangeSizeMb: core_1.DTO.Number().positive().optional(),
+        stackSizeMb: core_1.DTO.Number().positive().optional()
+    }).optional()),
+    __metadata("design:type", Object)
+], PeerThreads.prototype, "resourceLimits", void 0);
+exports.PeerThreads = PeerThreads = __decorate([
+    (0, di_1.Singleton)()
+], PeerThreads);
+/**
+ * Build the options of a {@link PeerThreads} component, for the `components` of an application.
+ * @param options The threads at most, their limits (all optional).
+ * @returns The component options.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildPeerThreadsOptions} from '@lakutata/webrtc'
+ *
+ * Application.run(() => ({
+ *     id: 'peers.app',
+ *     name: 'Peers',
+ *     components: {
+ *         peerThreads: buildPeerThreadsOptions({threads: 4})
+ *     }
+ * }))
+ * ```
+ */
+function buildPeerThreadsOptions(options = {}) {
+    return { class: PeerThreads, ...options };
+}

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

@@ -0,0 +1,6 @@
+/**
+ * Serve the connections the main thread opens in this worker thread (the `threads` option of a connection): their
+ * engines run here, their methods are called from the main thread, their events, their state, the messages of their
+ * channels and the packets of the tracks received go to it, the packets of the tracks sent come from it
+ */
+export declare function runPeerWorker(): void;