@lakutata/webrtc 0.0.0-stage → 3.1.4

package/dist/cjs/sfu/SFUWorkers.js

@@ -0,0 +1,552 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SFUWorkers = exports.SFUWorkerRoom = void 0;
+const node_worker_threads_1 = require("node:worker_threads");
+const log_js_1 = require("../lib/common/log.js");
+const parameters_js_1 = require("../lib/peer/media/parameters.js");
+const rtp_js_1 = require("../lib/rtp/rtp/rtp.js");
+const MediaTrack_js_1 = require("../peer/MediaTrack.js");
+const SFUWorkerChannel_js_1 = require("./SFUWorkerChannel.js");
+const SFUWorkerCode_js_1 = require("./SFUWorkerCode.js");
+const log = (0, log_js_1.debug)('webrtc/sfu/workers');
+/**
+ * How long a worker thread may take to leave its rooms when the server stops, in milliseconds
+ */
+const STOP_TIMEOUT = 5000;
+/**
+ * The key of several values
+ * @param parts
+ */
+function keyOf(...parts) {
+    return parts.join('\n');
+}
+/**
+ * The channel of a running thread
+ * @param slot
+ */
+function channelOf(slot) {
+    if (!slot.channel)
+        throw new Error('The worker thread of the media server is not running');
+    return slot.channel;
+}
+/**
+ * The connection of a session of WHIP or WHEP in a worker thread
+ */
+class WorkerLeg {
+    #link;
+    #id;
+    #listeners = [];
+    #ended = false;
+    #source;
+    /**
+     * Keep a leg.
+     * @param link The pool.
+     * @param id The id of its member or viewer.
+     * @param answer The answer.
+     * @param source The source of a viewer.
+     */
+    constructor(link, id, answer, source) {
+        this.#link = link;
+        this.#id = id;
+        this.answer = answer;
+        this.#source = source;
+        link.legs.set(id, this);
+    }
+    /**
+     * The source of a viewer of WHEP.
+     */
+    source() {
+        return this.#source;
+    }
+    /**
+     * The source of a viewer changed.
+     * @param source
+     */
+    sourced(source) {
+        this.#source = source;
+    }
+    /**
+     * Apply a PATCH in the worker thread.
+     * @param fragment
+     * @param restart
+     */
+    patch(fragment, restart) {
+        if (this.#ended)
+            return Promise.reject(new Error('The session ended'));
+        return channelOf(this.#link.slot).request({ type: 'patch', leg: this.#id, fragment: fragment, restart: restart });
+    }
+    /**
+     * Call a listener once the leg ends.
+     * @param listener
+     */
+    ended(listener) {
+        if (this.#ended)
+            listener();
+        else
+            this.#listeners.push(listener);
+    }
+    /**
+     * Close the connection.
+     */
+    close() {
+        if (this.#ended)
+            return;
+        this.#link.slot.channel?.post({ type: 'end', leg: this.#id });
+        this.end();
+    }
+    /**
+     * The connection is gone.
+     */
+    end() {
+        if (this.#ended)
+            return;
+        this.#ended = true;
+        if (this.#link.legs.get(this.#id) === this)
+            this.#link.legs.delete(this.#id);
+        this.#link.choosers.delete(this.#id);
+        for (const listener of this.#listeners.splice(0))
+            listener();
+    }
+}
+/**
+ * A room forwarded in a worker thread, from the main thread: its members, its tracks and its viewers as the thread
+ * tells them, the tracks read here, and its sessions of WHIP and WHEP
+ */
+class SFUWorkerRoom {
+    #link;
+    #ref;
+    #closed = false;
+    #closing;
+    #members = [];
+    #viewers = 0;
+    //The tracks published, the ids and the codecs of their tracks of the engine, the ones read here (by member and track)
+    #tracks = new Map();
+    #media = new Map();
+    //The tracks of the other nodes of the room, as the thread knows them
+    #known = new Map();
+    #relayed = new Map();
+    #legs = new Set();
+    /**
+     * Open a room in a worker thread.
+     * @param link The pool.
+     * @param ref The number of the room in the pool.
+     * @param name The room.
+     */
+    constructor(link, ref, name) {
+        this.#link = link;
+        this.#ref = ref;
+        this.name = name;
+        this.ready = link.slot.ready.then(() => channelOf(link.slot).request({ type: 'open', ref: ref, room: name, id: link.id }));
+        this.ready.catch(() => undefined);
+    }
+    /**
+     * Whether the server left the room.
+     */
+    get closed() {
+        return this.#closed;
+    }
+    /**
+     * The ids of the members.
+     */
+    get members() {
+        return this.#members;
+    }
+    /**
+     * The tracks published.
+     */
+    get tracks() {
+        return [...this.#tracks.values()];
+    }
+    /**
+     * The number of the viewers of WHEP.
+     */
+    get viewers() {
+        return this.#viewers;
+    }
+    /**
+     * A track published: its packets come from the worker thread while they are read, or sent on, here.
+     * @param peerId
+     * @param trackId
+     */
+    track(peerId, trackId) {
+        const key = keyOf(peerId, trackId);
+        //A track of a member of this node, else of another node of the room
+        const published = this.#tracks.get(key) ?? this.#known.get(key)?.track;
+        if (!published || this.#closed)
+            return undefined;
+        let relayed = this.#relayed.get(key);
+        if (!relayed) {
+            const codec = (this.#media.get(key) ?? this.#known.get(key))?.codec ?? { mimeType: published.codec, clockRate: published.kind === 'audio' ? 48000 : 90000 };
+            relayed = (0, MediaTrack_js_1.relayedTrack)(published.kind, new parameters_js_1.RTCRtpCodecParameters(codec), this.#media.get(key)?.id ?? (this.#known.has(key) ? trackId : undefined), {
+                requestKeyFrame: () => this.#link.slot.channel?.post({ type: 'keyframe', ref: this.#ref, peerId: peerId, trackId: trackId }),
+                wanted: (wanted) => this.#link.slot.channel?.post({ type: 'stream', ref: this.#ref, peerId: peerId, trackId: trackId, wanted: wanted })
+            });
+            this.#relayed.set(key, relayed);
+        }
+        return relayed.track;
+    }
+    /**
+     * A stream published with WHIP joins the room.
+     * @param id
+     * @param offer
+     */
+    async publish(id, offer) {
+        const { answer } = await channelOf(this.#link.slot).request({ type: 'publish', ref: this.#ref, peerId: id, offer: offer });
+        return this.#keep(new WorkerLeg(this.#link, id, answer));
+    }
+    /**
+     * A viewer of WHEP receives a member of the room.
+     * @param id
+     * @param offer
+     * @param select
+     */
+    async play(id, offer, select) {
+        if (select)
+            this.#link.choosers.set(id, select);
+        let played;
+        try {
+            played = await channelOf(this.#link.slot).request({ type: 'play', ref: this.#ref, viewerId: id, offer: offer, select: !!select });
+        }
+        catch (error) {
+            this.#link.choosers.delete(id);
+            throw error;
+        }
+        return this.#keep(new WorkerLeg(this.#link, id, played.answer, played.source));
+    }
+    /**
+     * Leave the room.
+     */
+    close() {
+        this.#closing ??= (async () => {
+            this.#closed = true;
+            try {
+                await this.ready;
+                await channelOf(this.#link.slot).request({ type: 'close', ref: this.#ref });
+            }
+            catch {
+                //Not opened, or its thread stopped
+            }
+            if (this.#link.slot.rooms.get(this.#ref) === this)
+                this.#link.slot.rooms.delete(this.#ref);
+            this.#end();
+        })();
+        return this.#closing;
+    }
+    /**
+     * Its thread stopped: the room is closed, its tracks unpublished.
+     */
+    lose() {
+        this.#closed = true;
+        const tracks = [...this.#tracks.values()];
+        this.#tracks.clear();
+        this.#media.clear();
+        for (const track of tracks)
+            this.#link.emit('unpublish', track);
+        this.#end();
+    }
+    /**
+     * An event of the room: the tracks published are kept.
+     * @param event
+     * @param args
+     * @param media The track of the engine of a track published.
+     */
+    emitted(event, args, media) {
+        const track = args[0];
+        if (event === 'publish' && track) {
+            this.#tracks.set(keyOf(track.peerId, track.id), track);
+            if (media)
+                this.#media.set(keyOf(track.peerId, track.id), media);
+        }
+        else if (event === 'unpublish' && track) {
+            const key = keyOf(track.peerId, track.id);
+            this.#tracks.delete(key);
+            this.#media.delete(key);
+            this.#relayed.get(key)?.track.stop();
+            this.#relayed.delete(key);
+        }
+    }
+    /**
+     * The tracks of the other nodes of the room changed: the ones gone end here.
+     * @param tracks
+     */
+    knew(tracks) {
+        this.#known = new Map(tracks.map((offered) => [keyOf(offered.track.peerId, offered.track.id), offered]));
+        for (const [key, relayed] of [...this.#relayed]) {
+            if (this.#tracks.has(key) || this.#known.has(key))
+                continue;
+            relayed.track.stop();
+            this.#relayed.delete(key);
+        }
+    }
+    /**
+     * The members and the number of the viewers changed.
+     * @param members
+     * @param viewers
+     */
+    state(members, viewers) {
+        this.#members = members;
+        this.#viewers = viewers;
+    }
+    /**
+     * A packet of a track read here.
+     * @param peerId
+     * @param trackId
+     * @param packet
+     * @param extensions
+     */
+    received(peerId, trackId, packet, extensions) {
+        this.#relayed.get(keyOf(peerId, trackId))?.receive(rtp_js_1.RtpPacket.deSerialize(Buffer.from(packet.buffer, packet.byteOffset, packet.byteLength)), extensions);
+    }
+    /**
+     * Keep a leg of the room
+     * @param leg
+     */
+    #keep(leg) {
+        this.#legs.add(leg);
+        leg.ended(() => this.#legs.delete(leg));
+        return leg;
+    }
+    /**
+     * The tracks read here end, the legs are gone
+     */
+    #end() {
+        for (const relayed of this.#relayed.values())
+            relayed.track.stop();
+        this.#relayed.clear();
+        for (const leg of [...this.#legs])
+            leg.end();
+    }
+}
+exports.SFUWorkerRoom = SFUWorkerRoom;
+/**
+ * The worker threads of a media server: each forwards the rooms placed in it, the one forwarding the fewest members
+ * and viewers taking the next room. A thread stopping (a bug) loses its rooms; it is started again.
+ */
+class SFUWorkers {
+    #host;
+    #data;
+    #slots;
+    //The legs of WHIP and WHEP, the choices of source of the viewers (by their ids)
+    #legs = new Map();
+    #choosers = new Map();
+    #next = 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 });
+    };
+    /**
+     * Start the threads.
+     * @param host The media server.
+     * @param data What each thread is started with.
+     * @throws {Error} When the code of the threads was not built.
+     */
+    constructor(host, data) {
+        if (!SFUWorkerCode_js_1.sfuWorkerCode)
+            throw new Error('The code of the worker threads of the media server is not built (scripts/workers.mjs)');
+        this.#host = host;
+        this.#data = data;
+        this.#slots = data.map((_, index) => ({ index: index, rooms: new Map(), ready: Promise.resolve(), ran: false, dead: false }));
+        log_js_1.debugHandlerWatchers.add(this.#debugging);
+        for (const slot of this.#slots)
+            this.#start(slot);
+    }
+    /**
+     * Resolves once all the threads run.
+     * @throws {Error} When one fails to start.
+     */
+    get ready() {
+        return Promise.all(this.#slots.map((slot) => slot.ready)).then(() => undefined);
+    }
+    /**
+     * Open a room in the thread forwarding the fewest members and viewers.
+     * @param name The room.
+     * @returns The room.
+     */
+    room(name) {
+        const load = (slot) => [...slot.rooms.values()].reduce((sum, room) => sum + 1 + room.members.length + room.viewers, 0);
+        const live = this.#slots.filter((slot) => !slot.dead);
+        if (!live.length)
+            throw new Error('No worker thread of the media server runs');
+        const slot = live.reduce((least, each) => load(each) < load(least) ? each : least);
+        const ref = this.#next++;
+        const room = new SFUWorkerRoom({
+            id: this.#host.id,
+            slot: slot,
+            legs: this.#legs,
+            choosers: this.#choosers,
+            emit: (event, ...args) => this.#host.emit(event, ...args)
+        }, ref, name);
+        slot.rooms.set(ref, room);
+        return room;
+    }
+    /**
+     * The number of rooms of each thread.
+     * @returns The numbers, in the order of the threads.
+     */
+    get rooms() {
+        return this.#slots.map((slot) => slot.rooms.size);
+    }
+    /**
+     * Stop the threads (their rooms closed before).
+     */
+    async stop() {
+        this.#stopping = true;
+        log_js_1.debugHandlerWatchers.delete(this.#debugging);
+        await Promise.all(this.#slots.map(async (slot) => {
+            const worker = slot.worker;
+            if (!worker)
+                return;
+            let timer;
+            await Promise.race([
+                channelOf(slot).request({ type: 'stop' }).catch(() => undefined),
+                new Promise((resolve) => {
+                    timer = setTimeout(resolve, STOP_TIMEOUT);
+                })
+            ]);
+            clearTimeout(timer);
+            await worker.terminate();
+        }));
+    }
+    /**
+     * The thread forwarding a room.
+     * @param name The room.
+     * @returns The index of the thread, or undefined when no thread forwards the room.
+     */
+    threadOf(name) {
+        return this.#slots.find((slot) => [...slot.rooms.values()].some((room) => room.name === name && !room.closed))?.index;
+    }
+    /**
+     * Stop a thread now, as a bug would (to test what follows).
+     * @param index The thread.
+     * @internal
+     */
+    async crash(index) {
+        await this.#slots[index]?.worker?.terminate();
+    }
+    /**
+     * 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)));
+    }
+    /**
+     * The limits each thread runs with.
+     * @returns The limits of each thread running, by its index.
+     * @internal
+     */
+    limits() {
+        return this.#slots.map((slot) => slot.worker?.resourceLimits);
+    }
+    /**
+     * Start the thread of a slot
+     * @param slot
+     */
+    #start(slot) {
+        //Running once it says so: a thread failing to start is not started again
+        slot.ran = false;
+        const resourceLimits = this.#host.resourceLimits;
+        const worker = new node_worker_threads_1.Worker(SFUWorkerCode_js_1.sfuWorkerCode, { eval: true, workerData: this.#data[slot.index], ...resourceLimits ? { resourceLimits: resourceLimits } : {} });
+        slot.worker = worker;
+        slot.channel = new SFUWorkerChannel_js_1.SFUWorkerChannel(worker, (message) => this.#handle(slot, message));
+        slot.ready = new Promise((resolve, reject) => {
+            slot.started = { resolve: resolve, reject: reject };
+        });
+        slot.ready.catch(() => undefined);
+        if ((0, log_js_1.hasDebugHandler)())
+            slot.channel.post({ type: 'debug', enabled: true });
+        //Its exit follows
+        worker.on('error', (error) => log('the worker thread %d failed: %O', slot.index, error));
+        worker.on('exit', (code) => {
+            if (!this.#stopping)
+                log('the worker thread %d stopped (exit code %d)', slot.index, code);
+            this.#exited(slot, worker);
+        });
+    }
+    /**
+     * A thread stopped: its rooms are lost, and it is started again, unless it never ran
+     * @param slot
+     * @param worker
+     */
+    #exited(slot, worker) {
+        if (slot.worker !== worker)
+            return;
+        const error = new Error('The worker thread of the media server stopped');
+        slot.channel?.close(error);
+        slot.started?.reject(error);
+        slot.started = undefined;
+        slot.worker = undefined;
+        slot.channel = undefined;
+        const lost = [...slot.rooms.values()];
+        slot.rooms.clear();
+        for (const room of lost)
+            room.lose();
+        if (this.#stopping)
+            return;
+        if (slot.ran)
+            this.#start(slot);
+        else
+            slot.dead = true;
+        for (const room of lost)
+            this.#host.lost(room);
+    }
+    /**
+     * A message of a thread
+     * @param slot
+     * @param message
+     */
+    #handle(slot, message) {
+        switch (message.type) {
+            case 'ready':
+                slot.ran = true;
+                slot.started?.resolve();
+                return undefined;
+            case 'join': {
+                const room = slot.rooms.get(message.ref);
+                if (!room)
+                    throw new Error('The room is not served any more');
+                const channel = channelOf(slot);
+                return this.#host.signaling.join(message.peerId, room.name, {
+                    role: message.role,
+                    receive: (event, payload) => channel.post({ type: 'receive', ref: message.ref, peerId: message.peerId, event: event, payload: payload })
+                });
+            }
+            case 'leave': {
+                const room = slot.rooms.get(message.ref);
+                return room ? this.#host.signaling.leave(message.peerId, room.name) : undefined;
+            }
+            case 'signal': {
+                const room = slot.rooms.get(message.ref);
+                return room ? this.#host.signaling.signal(message.peerId, room.name, message.to, message.signal) : false;
+            }
+            case 'select':
+                return this.#host.select ? this.#host.select(message.subscriber, message.track) : true;
+            case 'choose':
+                return this.#choosers.get(message.leg)?.(message.tracks);
+            case 'emit':
+                slot.rooms.get(message.ref)?.emitted(message.event, message.args, message.media);
+                return this.#host.emit(message.event, ...message.args);
+            case 'state':
+                return slot.rooms.get(message.ref)?.state(message.members, message.viewers);
+            case 'source':
+                this.#legs.get(message.leg)?.sourced(message.source);
+                return this.#host.sourced?.(message.leg, message.source);
+            case 'ended':
+                return this.#legs.get(message.leg)?.end();
+            case 'emptied': {
+                const room = slot.rooms.get(message.ref);
+                return room ? this.#host.emptied(room) : undefined;
+            }
+            case 'rtp':
+                return slot.rooms.get(message.ref)?.received(message.peerId, message.trackId, message.packet, message.extensions);
+            case 'log':
+                return (0, log_js_1.debug)(message.namespace)(message.message);
+            case 'known':
+                return slot.rooms.get(message.ref)?.knew(message.tracks);
+        }
+    }
+}
+exports.SFUWorkers = SFUWorkers;

package/dist/cjs/shared/ChunkedChannel.d.ts

@@ -0,0 +1,122 @@
+import { Emitter } from './Emitter.js';
+/**
+ * What a {@link ChunkedChannel} needs of a data channel: `RTCDataChannel` of the browsers, `PeerChannel` of Node.js.
+ */
+export interface ChunkableChannel {
+    /**
+     * `connecting`, `open`, `closing` or `closed`.
+     */
+    readonly readyState: string;
+    /**
+     * Whether the messages arrive in order.
+     */
+    readonly ordered: boolean;
+    /**
+     * The bytes waiting to be sent.
+     */
+    readonly bufferedAmount: number;
+    /**
+     * The value of `bufferedAmount` at which `bufferedamountlow` fires.
+     */
+    bufferedAmountLowThreshold: number;
+    /**
+     * The type of the binary messages received.
+     */
+    binaryType: string;
+    /**
+     * Send a binary message.
+     * @param data The message.
+     */
+    send(data: ArrayBufferView<ArrayBuffer>): void;
+    /**
+     * Close the channel.
+     */
+    close(): void;
+    /**
+     * Add a listener.
+     * @param type The event.
+     * @param listener The listener.
+     */
+    addEventListener(type: string, listener: (event: any) => void): void;
+    /**
+     * Remove a listener.
+     * @param type The event.
+     * @param listener The listener.
+     */
+    removeEventListener(type: string, listener: (event: any) => void): void;
+}
+/**
+ * The options of a {@link ChunkedChannel}.
+ */
+export interface ChunkedChannelOptions {
+    /**
+     * The size of a chunk, in bytes: 16 KiB goes through every implementation without being split.
+     * @default 16384
+     */
+    chunkSize?: number;
+    /**
+     * The bytes waiting to be sent above which sending waits (`bufferedamountlow`), so a large message is not all held
+     * in memory.
+     * @default 1048576
+     */
+    highWaterMark?: number;
+    /**
+     * The size of a message received at most, in bytes: a larger one is dropped with an `error`.
+     * @default 67108864 (64 MiB)
+     */
+    maxMessageSize?: number;
+}
+/**
+ * The events of a {@link ChunkedChannel}.
+ */
+export type ChunkedChannelEvents = {
+    /**
+     * A whole message: a string, or the bytes of a binary message.
+     */
+    message: [data: string | Uint8Array<ArrayBuffer>];
+    /**
+     * A message received was over `maxMessageSize`, or a frame was not one of a chunked channel.
+     */
+    error: [error: Error];
+};
+/**
+ * Messages of any size over a data channel: each message is cut into chunks (a byte of flags, then up to `chunkSize`
+ * bytes), sent as the channel's buffer empties, and put back together on the other side, so the size limit of the
+ * implementations (64 KiB to 256 KiB) does not apply and a large message does not hold the memory. Both sides wrap the
+ * channel with it; the channel must be ordered and reliable (the default of a data channel). A `Blob` (a file of a
+ * browser) is read a chunk at a time.
+ * @example
+ * ```typescript
+ * import {ChunkedChannel, type PeerChannel} from '@lakutata/webrtc'
+ *
+ * declare const channel: PeerChannel
+ * const files: ChunkedChannel = new ChunkedChannel(channel)
+ * files.on('message', (data: string | Uint8Array): void => console.log(`received ${data.length} bytes`))
+ * await files.send(new Uint8Array(10 * 1024 * 1024))
+ * ```
+ */
+export declare class ChunkedChannel extends Emitter<ChunkedChannelEvents> {
+    #private;
+    /**
+     * Wrap a data channel.
+     * @param channel The channel: ordered and reliable.
+     * @param options The size of the chunks, of the buffer, of a message received.
+     * @throws {TypeError} When the channel is not ordered.
+     */
+    constructor(channel: ChunkableChannel, options?: ChunkedChannelOptions);
+    /**
+     * The data channel.
+     */
+    get channel(): ChunkableChannel;
+    /**
+     * Send a message, after the ones sent before.
+     * @param data A string, bytes, or a `Blob`.
+     * @returns Resolves once all its chunks are handed to the channel.
+     * @throws {Error} When the channel closes before.
+     */
+    send(data: string | ArrayBuffer | ArrayBufferView | Blob): Promise<void>;
+    /**
+     * Stop listening to the channel, and close it.
+     */
+    close(): void;
+}