@lakutata/webrtc 0.0.0-stage → 3.1.4

package/dist/esm/peer/PeerThreadChannel.js

@@ -0,0 +1,266 @@
+import { debug } from '../lib/common/log.js';
+const log = debug('webrtc/peer/threads');
+/**
+ * The size below which the copies of messages and packets sent together share buffers (one allocation for many, rather
+ * than one each); the side reading them copies them into buffers of their own (of the pool of Node.js), so a message
+ * kept does not keep the others
+ */
+export const PACKED_SIZE = 4096;
+/**
+ * The size of the buffers shared by the copies
+ */
+const CHUNK_SIZE = 65536;
+/**
+ * The bytes of a message or a packet read: a buffer of its own, copied from a shared one
+ * @param bytes
+ */
+export function readBytes(bytes) {
+    return bytes.byteOffset === 0 && bytes.byteLength === bytes.buffer.byteLength
+        ? Buffer.from(bytes.buffer, 0, bytes.byteLength)
+        : Buffer.from(bytes);
+}
+/**
+ * The bytes of RTP packets of a connection on their way to the other side at most, in each direction: beyond, the next
+ * ones are dropped, as a full UDP buffer would (the packets of the channels are not: their receive window waits)
+ */
+export const RTP_IN_FLIGHT = 2 * 1024 * 1024;
+/**
+ * A copy of bytes in a buffer of its own, transferred to the other side (a view of a buffer would send all of it)
+ * @param data
+ */
+function ownCopy(data) {
+    const bytes = new Uint8Array(data);
+    return { bytes: bytes, transfer: [bytes.buffer] };
+}
+/**
+ * The error of the other side, with its name (InvalidStateError, OperationError…)
+ * @param error
+ */
+export function threadErrorOf(error) {
+    return Object.assign(new Error(error.message), { name: error.name });
+}
+/**
+ * An error, as sent to the other side
+ * @param error
+ */
+export function sentError(error) {
+    return error instanceof Error ? { name: error.name, message: error.message } : { name: 'Error', message: String(error) };
+}
+/**
+ * The messages of a side to the other, sent together once per turn of the event loop and in their order (requests,
+ * replies, events, data), with the buffers given transferred. A request is answered by the result of its handler, or
+ * by its error
+ */
+export class PeerThreadChannel {
+    #port;
+    #handle;
+    #pending = new Map();
+    //Called before each sending, to add what a turn of the event loop changed (the amounts buffered)
+    #flushing = new Set();
+    #queue = [];
+    #transfer = [];
+    #scheduled = false;
+    #next = 1;
+    #closed;
+    //The buffer the copies of small messages and packets of this sending share, and its bytes used
+    #chunk;
+    #used = 0;
+    /**
+     * Read the messages of a port.
+     * @param port The port.
+     * @param handle Handles a message; the result of a request (or its promise) is its reply.
+     */
+    constructor(port, handle) {
+        this.#port = port;
+        this.#handle = handle;
+        port.on('message', (batch) => {
+            if (!Array.isArray(batch))
+                return;
+            for (const item of batch)
+                this.#read(item);
+        });
+    }
+    /**
+     * Whether the channel is closed.
+     */
+    get closed() {
+        return !!this.#closed;
+    }
+    /**
+     * Send a message that is not answered.
+     * @param message The message.
+     * @param transfer The buffers given to the other side (allocated by the sender for it: never one shared).
+     */
+    post(message, transfer) {
+        if (this.#closed)
+            return;
+        this.#queue.push(message);
+        if (transfer)
+            this.#transfer.push(...transfer);
+        this.#schedule();
+    }
+    /**
+     * A copy of bytes to send with this sending: in a buffer shared with the other small ones, transferred once.
+     * @param data The bytes.
+     * @returns The copy, and the buffer to transfer with the message holding it.
+     */
+    pack(data) {
+        if (data.byteLength >= PACKED_SIZE)
+            return ownCopy(data);
+        let transfer;
+        if (!this.#chunk || this.#used + data.byteLength > CHUNK_SIZE) {
+            this.#chunk = new Uint8Array(CHUNK_SIZE);
+            this.#used = 0;
+            transfer = [this.#chunk.buffer];
+        }
+        const bytes = this.#chunk.subarray(this.#used, this.#used + data.byteLength);
+        bytes.set(data);
+        this.#used += data.byteLength;
+        return { bytes: bytes, transfer: transfer };
+    }
+    /**
+     * Add to the last message waiting when it is one of the same kind (the messages of a channel, the packets of a
+     * track, sent together: one message for many is much cheaper to send), else send a new one; the order holds.
+     * @param extend Adds to the last message waiting, when it may: whether it did.
+     * @param message The new message, else.
+     * @param transfer The buffers given to the other side.
+     */
+    postOrExtend(extend, message, transfer) {
+        if (this.#closed)
+            return;
+        const last = this.#queue.at(-1);
+        if (!last || !extend(last))
+            this.#queue.push(message());
+        if (transfer)
+            this.#transfer.push(...transfer);
+        this.#schedule();
+    }
+    /**
+     * Send a request, and wait for its reply.
+     * @param message The request.
+     * @param transfer The buffers given to the other side.
+     * @returns Its result.
+     * @throws {Error} The error of the other side, or the one the channel closed with.
+     */
+    request(message, transfer) {
+        if (this.#closed)
+            return Promise.reject(this.#closed);
+        const request = this.#next++;
+        return new Promise((resolve, reject) => {
+            this.#pending.set(request, { resolve: resolve, reject: reject });
+            this.post({ ...message, request: request }, transfer);
+        });
+    }
+    /**
+     * Call a function before each sending.
+     * @param callback The function: it posts what changed.
+     */
+    beforeSending(callback) {
+        this.#flushing.add(callback);
+    }
+    /**
+     * Send at the end of this turn of the event loop, even with no message waiting: what the callbacks given to
+     * beforeSending post.
+     */
+    schedule() {
+        if (!this.#closed)
+            this.#schedule();
+    }
+    /**
+     * Send what is waiting now, without waiting for the end of the turn of the event loop.
+     */
+    flush() {
+        this.#scheduled = false;
+        if (this.#closed)
+            return;
+        for (const callback of this.#flushing)
+            callback();
+        //The shared buffer goes with this sending
+        this.#chunk = undefined;
+        if (!this.#queue.length)
+            return;
+        const queue = this.#queue;
+        const transfer = this.#transfer;
+        this.#queue = [];
+        this.#transfer = [];
+        try {
+            this.#port.postMessage(queue, transfer);
+        }
+        catch (error) {
+            //A value that cannot be sent: the requests among the messages fail, the others are lost
+            log('a batch could not be sent: %O', error);
+            for (const item of queue)
+                if (item.request !== undefined)
+                    this.#reply(item.request, undefined, error);
+        }
+    }
+    /**
+     * Close the channel: the requests waiting and the next ones fail, nothing is sent any more.
+     * @param error Their error.
+     */
+    close(error) {
+        this.#closed ??= error;
+        this.#queue = [];
+        this.#transfer = [];
+        for (const { reject } of this.#pending.values())
+            reject(error);
+        this.#pending.clear();
+    }
+    /**
+     * Send at the end of the turn of the event loop
+     */
+    #schedule() {
+        if (this.#scheduled)
+            return;
+        this.#scheduled = true;
+        setImmediate(() => this.flush());
+    }
+    /**
+     * Read a message: a reply, a request, or a message not answered. A handler throwing does not stop the others
+     * @param item
+     */
+    #read(item) {
+        if (item.type === 'reply') {
+            const pending = this.#pending.get(item.reply);
+            this.#pending.delete(item.reply);
+            if (item.error === undefined)
+                pending?.resolve(item.result);
+            else
+                pending?.reject(threadErrorOf(item.error));
+            return;
+        }
+        const request = item.request;
+        let result;
+        try {
+            result = this.#handle(item);
+        }
+        catch (error) {
+            if (request === undefined)
+                log('a message failed: %O', error);
+            else
+                this.#reply(request, undefined, error);
+            return;
+        }
+        if (request === undefined) {
+            if (result instanceof Promise)
+                result.catch((error) => log('a message failed: %O', error));
+            return;
+        }
+        if (result instanceof Promise)
+            result.then((value) => this.#reply(request, value), (error) => this.#reply(request, undefined, error));
+        else
+            this.#reply(request, result);
+    }
+    /**
+     * Answer a request
+     * @param request
+     * @param result
+     * @param error
+     */
+    #reply(request, result, error) {
+        if (this.#closed)
+            return;
+        this.#queue.push(error === undefined ? { type: 'reply', reply: request, result: result } : { type: 'reply', reply: request, error: sentError(error) });
+        this.#schedule();
+    }
+}

package/dist/esm/peer/PeerThreadProtocol.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/peer/PeerThreads.js

@@ -0,0 +1,264 @@
+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);
+};
+import { availableParallelism } from 'node:os';
+import { Worker } from 'node:worker_threads';
+import { Component, DTO } from '@lakutata/core';
+import { Configurable, Singleton } from '@lakutata/core/decorator/di';
+import { debug, debugHandlerWatchers, hasDebugHandler } from '../lib/common/log.js';
+import { PeerThreadChannel } from './PeerThreadChannel.js';
+import { peerWorkerCode } from './PeerWorkerCode.js';
+import { RemoteConnection } from './RemoteConnection.js';
+const log = 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 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)
+            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, availableParallelism() - 1);
+        this.#slots = Array.from({ length: count }, (_, index) => ({ index: index, connections: new Map(), opening: 0 }));
+        debugHandlerWatchers.add(this.#debugging);
+    }
+    /**
+     * Stop the threads, closing their connections.
+     * @protected
+     */
+    async destroy() {
+        this.#stopping = true;
+        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(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 Worker(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(worker, (message) => {
+            switch (message.type) {
+                case 'ready':
+                    return ready();
+                case 'log':
+                    return debug(message.namespace)(message.message);
+                default:
+                    return slot.connections.get(message.conn)?.handle(message);
+            }
+        });
+        slot.channel = channel;
+        if (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();
+    }
+};
+__decorate([
+    Configurable(DTO.Number().integer().positive().optional()),
+    __metadata("design:type", Number)
+], PeerThreads.prototype, "threads", void 0);
+__decorate([
+    Configurable(DTO.Object({
+        maxYoungGenerationSizeMb: DTO.Number().positive().optional(),
+        maxOldGenerationSizeMb: DTO.Number().positive().optional(),
+        codeRangeSizeMb: DTO.Number().positive().optional(),
+        stackSizeMb: DTO.Number().positive().optional()
+    }).optional()),
+    __metadata("design:type", Object)
+], PeerThreads.prototype, "resourceLimits", void 0);
+PeerThreads = __decorate([
+    Singleton()
+], PeerThreads);
+export { 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})
+ *     }
+ * }))
+ * ```
+ */
+export function buildPeerThreadsOptions(options = {}) {
+    return { class: PeerThreads, ...options };
+}