@lakutata/webrtc 0.0.0-stage → 3.1.4

package/dist/types/sfu/SFUWorkerChannel.d.ts

@@ -0,0 +1,204 @@
+import type { Transferable } from 'node:worker_threads';
+import type { SignalingDescription, SignalingPeer, SignalingRole, SignalingStream, SignalingCandidate } from '../protocol/SignalingProtocol.js';
+import type { SFUTrack } from './SFU.js';
+import type { SFUOfferedTrack } from './SFURoom.js';
+/**
+ * The codec of a track published, as the worker thread gives it (the fields of the codec parameters of the engine)
+ */
+export interface SFUWorkerCodec {
+    readonly payloadType?: number;
+    readonly mimeType: string;
+    readonly clockRate: number;
+    readonly channels?: number;
+    readonly parameters?: string;
+}
+/**
+ * The track of the engine of a track published: its id and its codec
+ */
+export interface SFUWorkerMedia {
+    readonly id: string;
+    readonly codec?: SFUWorkerCodec;
+}
+/**
+ * The messages of the main thread to a worker thread forwarding rooms. `ref` is the number of a room in the pool (the
+ * same name may be served again by another), `leg` the id of a member published with WHIP or of a viewer of WHEP.
+ */
+export type SFUToWorker = {
+    type: 'open';
+    request: number;
+    ref: number;
+    room: string;
+    id: string;
+} | {
+    type: 'close';
+    request: number;
+    ref: number;
+} | {
+    type: 'publish';
+    request: number;
+    ref: number;
+    peerId: string;
+    offer: SignalingDescription;
+} | {
+    type: 'play';
+    request: number;
+    ref: number;
+    viewerId: string;
+    offer: SignalingDescription;
+    select: boolean;
+} | {
+    type: 'patch';
+    request: number;
+    leg: string;
+    fragment: string;
+    restart: boolean;
+} | {
+    type: 'end';
+    leg: string;
+} | {
+    type: 'receive';
+    ref: number;
+    peerId: string;
+    event: string;
+    payload: unknown;
+} | {
+    type: 'stream';
+    ref: number;
+    peerId: string;
+    trackId: string;
+    wanted: boolean;
+} | {
+    type: 'keyframe';
+    ref: number;
+    peerId: string;
+    trackId: string;
+} | {
+    type: 'stop';
+    request: number;
+} | {
+    type: 'debug';
+    enabled: boolean;
+};
+/**
+ * The messages of a worker thread to the main thread
+ */
+export type SFUFromWorker = {
+    type: 'ready';
+} | {
+    type: 'join';
+    request: number;
+    ref: number;
+    peerId: string;
+    role: SignalingRole;
+} | {
+    type: 'leave';
+    request: number;
+    ref: number;
+    peerId: string;
+} | {
+    type: 'signal';
+    request: number;
+    ref: number;
+    peerId: string;
+    to: string;
+    signal: {
+        description?: SignalingDescription;
+        candidate?: SignalingCandidate | null;
+        streams?: SignalingStream[];
+    };
+} | {
+    type: 'select';
+    request: number;
+    subscriber: SignalingPeer;
+    track: SFUTrack;
+} | {
+    type: 'choose';
+    request: number;
+    leg: string;
+    tracks: SFUTrack[];
+} | {
+    type: 'emit';
+    ref: number;
+    event: string;
+    args: unknown[];
+    media?: SFUWorkerMedia;
+} | {
+    type: 'state';
+    ref: number;
+    members: string[];
+    viewers: number;
+} | {
+    type: 'source';
+    leg: string;
+    source: string | undefined;
+} | {
+    type: 'ended';
+    leg: string;
+} | {
+    type: 'emptied';
+    ref: number;
+} | {
+    type: 'rtp';
+    ref: number;
+    peerId: string;
+    trackId: string;
+    packet: Uint8Array;
+    extensions?: Record<string, unknown>;
+} | {
+    type: 'log';
+    namespace: string;
+    message: string;
+} | {
+    type: 'known';
+    ref: number;
+    tracks: SFUOfferedTrack[];
+};
+/**
+ * Where the messages go and come from: the parent port in a worker thread, the worker in the main thread
+ */
+export interface SFUWorkerPort {
+    postMessage(message: unknown, transfer?: readonly Transferable[]): void;
+    on(event: 'message', listener: (message: unknown) => void): unknown;
+}
+/**
+ * The messages of a request, without their number (given by the channel)
+ */
+type Unnumbered<Message> = Message extends {
+    request: number;
+} ? Omit<Message, 'request'> : never;
+/**
+ * The messages of a side to the other: the requests are answered (their result, or the message of their error), the
+ * others are not
+ */
+export declare class SFUWorkerChannel<Incoming extends {
+    type: string;
+}, Outgoing extends {
+    type: string;
+}> {
+    #private;
+    /**
+     * 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: SFUWorkerPort, handle: (message: Incoming) => unknown);
+    /**
+     * Send a request, and wait for its reply.
+     * @param message The request.
+     * @returns Its result.
+     * @throws {Error} The error of the other side, or the one the channel closed with.
+     */
+    request<Result>(message: Unnumbered<Outgoing>): Promise<Result>;
+    /**
+     * Send a message that is not answered.
+     * @param message The message.
+     * @param transfer The buffers given to the other side.
+     */
+    post(message: Outgoing, transfer?: readonly Transferable[]): void;
+    /**
+     * Close the channel: the requests waiting and the next ones fail.
+     * @param error Their error.
+     */
+    close(error: Error): void;
+}
+export {};

package/dist/types/sfu/SFUWorkerCode.d.ts

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

package/dist/types/sfu/SFUWorkers.d.ts

@@ -0,0 +1,247 @@
+import { type HeapInfo } from 'node:v8';
+import { type ResourceLimits, Worker } from 'node:worker_threads';
+import type { EndpointLeg } from '../peer/Endpoints.js';
+import { type MediaTrack } from '../peer/MediaTrack.js';
+import type { SignalingDescription, SignalingPeer } from '../protocol/SignalingProtocol.js';
+import type { Signaling } from '../signaling/Signaling.js';
+import type { SFUTrack } from './SFU.js';
+import type { SFUOfferedTrack, SFUServedRoom, SFUViewerSelect } from './SFURoom.js';
+import type { SFUWorkerData } from './SFUWorker.js';
+import { type SFUFromWorker, type SFUToWorker, SFUWorkerChannel, type SFUWorkerMedia } from './SFUWorkerChannel.js';
+/**
+ * What the worker threads need of the media server
+ */
+export interface SFUWorkersHost {
+    readonly id: string;
+    readonly signaling: Signaling;
+    readonly select?: (subscriber: SignalingPeer, track: SFUTrack) => boolean;
+    emit(event: string, ...args: unknown[]): unknown;
+    emptied(room: SFUServedRoom): void;
+    lost(room: SFUServedRoom): void;
+    sourced?(viewerId: string, source: string | undefined): void;
+    readonly resourceLimits?: ResourceLimits;
+}
+/**
+ * A worker thread, and the rooms it forwards
+ */
+interface Slot {
+    readonly index: number;
+    readonly rooms: Map<number, SFUWorkerRoom>;
+    worker?: Worker;
+    channel?: SFUWorkerChannel<SFUFromWorker, SFUToWorker>;
+    ready: Promise<void>;
+    started?: {
+        resolve(): void;
+        reject(error: Error): void;
+    };
+    ran: boolean;
+    dead: boolean;
+}
+/**
+ * What a room in a worker thread needs of the pool
+ */
+interface RoomLink {
+    readonly id: string;
+    readonly slot: Slot;
+    readonly legs: Map<string, WorkerLeg>;
+    readonly choosers: Map<string, SFUViewerSelect>;
+    emit(event: string, ...args: unknown[]): unknown;
+}
+/**
+ * The connection of a session of WHIP or WHEP in a worker thread
+ */
+declare class WorkerLeg implements EndpointLeg {
+    #private;
+    /**
+     * The answer, with all the candidates.
+     */
+    readonly answer: SignalingDescription;
+    /**
+     * 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: RoomLink, id: string, answer: SignalingDescription, source?: string);
+    /**
+     * The source of a viewer of WHEP.
+     */
+    source(): string | undefined;
+    /**
+     * The source of a viewer changed.
+     * @param source
+     */
+    sourced(source: string | undefined): void;
+    /**
+     * Apply a PATCH in the worker thread.
+     * @param fragment
+     * @param restart
+     */
+    patch(fragment: string, restart: boolean): Promise<string | undefined | null>;
+    /**
+     * Call a listener once the leg ends.
+     * @param listener
+     */
+    ended(listener: () => void): void;
+    /**
+     * Close the connection.
+     */
+    close(): void;
+    /**
+     * The connection is gone.
+     */
+    end(): void;
+}
+/**
+ * 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
+ */
+export declare class SFUWorkerRoom implements SFUServedRoom {
+    #private;
+    /**
+     * The name of the room.
+     */
+    readonly name: string;
+    /**
+     * Resolves once the server is in the room.
+     */
+    readonly ready: Promise<void>;
+    /**
+     * 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: RoomLink, ref: number, name: string);
+    /**
+     * Whether the server left the room.
+     */
+    get closed(): boolean;
+    /**
+     * The ids of the members.
+     */
+    get members(): string[];
+    /**
+     * The tracks published.
+     */
+    get tracks(): SFUTrack[];
+    /**
+     * The number of the viewers of WHEP.
+     */
+    get viewers(): number;
+    /**
+     * A track published: its packets come from the worker thread while they are read, or sent on, here.
+     * @param peerId
+     * @param trackId
+     */
+    track(peerId: string, trackId: string): MediaTrack | undefined;
+    /**
+     * A stream published with WHIP joins the room.
+     * @param id
+     * @param offer
+     */
+    publish(id: string, offer: SignalingDescription): Promise<EndpointLeg>;
+    /**
+     * A viewer of WHEP receives a member of the room.
+     * @param id
+     * @param offer
+     * @param select
+     */
+    play(id: string, offer: SignalingDescription, select?: SFUViewerSelect): Promise<EndpointLeg & {
+        source(): string | undefined;
+    }>;
+    /**
+     * Leave the room.
+     */
+    close(): Promise<void>;
+    /**
+     * Its thread stopped: the room is closed, its tracks unpublished.
+     */
+    lose(): void;
+    /**
+     * 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: string, args: unknown[], media?: SFUWorkerMedia): void;
+    /**
+     * The tracks of the other nodes of the room changed: the ones gone end here.
+     * @param tracks
+     */
+    knew(tracks: SFUOfferedTrack[]): void;
+    /**
+     * The members and the number of the viewers changed.
+     * @param members
+     * @param viewers
+     */
+    state(members: string[], viewers: number): void;
+    /**
+     * A packet of a track read here.
+     * @param peerId
+     * @param trackId
+     * @param packet
+     * @param extensions
+     */
+    received(peerId: string, trackId: string, packet: Uint8Array, extensions?: Record<string, unknown>): void;
+}
+/**
+ * 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.
+ */
+export declare class SFUWorkers {
+    #private;
+    /**
+     * 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: SFUWorkersHost, data: SFUWorkerData[]);
+    /**
+     * Resolves once all the threads run.
+     * @throws {Error} When one fails to start.
+     */
+    get ready(): Promise<void>;
+    /**
+     * Open a room in the thread forwarding the fewest members and viewers.
+     * @param name The room.
+     * @returns The room.
+     */
+    room(name: string): SFUWorkerRoom;
+    /**
+     * The number of rooms of each thread.
+     * @returns The numbers, in the order of the threads.
+     */
+    get rooms(): number[];
+    /**
+     * Stop the threads (their rooms closed before).
+     */
+    stop(): Promise<void>;
+    /**
+     * 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: string): number | undefined;
+    /**
+     * Stop a thread now, as a bug would (to test what follows).
+     * @param index The thread.
+     * @internal
+     */
+    crash(index: number): Promise<void>;
+    /**
+     * 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)[]>;
+    /**
+     * The limits each thread runs with.
+     * @returns The limits of each thread running, by its index.
+     * @internal
+     */
+    limits(): (ResourceLimits | undefined)[];
+}
+export {};

package/dist/types/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;
+}