@lakutata/webrtc 0.0.0-stage → 3.1.4

package/dist/types/peer/PeerThreadChannel.d.ts

@@ -0,0 +1,112 @@
+/**
+ * What a side posts to and reads from: the parent port of a worker thread, or the worker
+ */
+export interface PeerThreadPort {
+    postMessage(value: unknown, transfer?: readonly ArrayBuffer[]): void;
+    on(event: 'message', listener: (value: unknown) => void): unknown;
+}
+/**
+ * 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 declare const PACKED_SIZE: number;
+/**
+ * The bytes of a message or a packet read: a buffer of its own, copied from a shared one
+ * @param bytes
+ */
+export declare function readBytes(bytes: Uint8Array): Buffer;
+/**
+ * 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 declare const RTP_IN_FLIGHT: number;
+/**
+ * An error sent to the other side: its class is lost, its name and message are kept
+ */
+export interface PeerThreadError {
+    readonly name: string;
+    readonly message: string;
+}
+/**
+ * The error of the other side, with its name (InvalidStateError, OperationError…)
+ * @param error
+ */
+export declare function threadErrorOf(error: PeerThreadError): Error;
+/**
+ * An error, as sent to the other side
+ * @param error
+ */
+export declare function sentError(error: unknown): PeerThreadError;
+/**
+ * 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 declare class PeerThreadChannel<Out extends {
+    type: string;
+}, In 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: PeerThreadPort, handle: (message: In) => unknown);
+    /**
+     * Whether the channel is closed.
+     */
+    get closed(): boolean;
+    /**
+     * 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: Out, transfer?: ArrayBuffer[]): void;
+    /**
+     * 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: Uint8Array): {
+        bytes: Uint8Array;
+        transfer?: ArrayBuffer[];
+    };
+    /**
+     * 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: (last: Out) => boolean, message: () => Out, transfer?: ArrayBuffer[]): void;
+    /**
+     * 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<Result>(message: Out, transfer?: ArrayBuffer[]): Promise<Result>;
+    /**
+     * Call a function before each sending.
+     * @param callback The function: it posts what changed.
+     */
+    beforeSending(callback: () => void): void;
+    /**
+     * Send at the end of this turn of the event loop, even with no message waiting: what the callbacks given to
+     * beforeSending post.
+     */
+    schedule(): void;
+    /**
+     * Send what is waiting now, without waiting for the end of the turn of the event loop.
+     */
+    flush(): void;
+    /**
+     * Close the channel: the requests waiting and the next ones fail, nothing is sent any more.
+     * @param error Their error.
+     */
+    close(error: Error): void;
+}

package/dist/types/peer/PeerThreadProtocol.d.ts

@@ -0,0 +1,325 @@
+import type { Extensions } from '../lib/rtp/index.js';
+import type { SignalingCandidate, SignalingDescription, SignalingIceServer } from '../protocol/SignalingProtocol.js';
+import type { DataChannelOptions } from '../shared/Connections.js';
+import type { EngineOptions } from './EngineConfig.js';
+import type { RtpTransceiverDirection } from './RtpTransceiver.js';
+/**
+ * What a worker thread of connections is started with
+ */
+export interface PeerWorkerData {
+    readonly thread: number;
+}
+/**
+ * A codec, as plain data
+ */
+export interface PeerCodec {
+    readonly payloadType?: number;
+    readonly mimeType: string;
+    readonly clockRate: number;
+    readonly channels?: number;
+    readonly parameters?: string;
+    readonly rtcpFeedback?: {
+        type: string;
+        parameter?: string;
+    }[];
+}
+/**
+ * A track received by a connection of a worker thread (its reference in the thread)
+ */
+export interface PeerTrackInfo {
+    readonly ref: string;
+    readonly kind: 'audio' | 'video';
+    readonly id: string;
+    readonly codec?: PeerCodec;
+}
+/**
+ * A transceiver of a connection of a worker thread (`m…` when added by the main thread, `w…` by the thread)
+ */
+export interface PeerTransceiverInfo {
+    readonly ref: string;
+    readonly kind: 'audio' | 'video';
+    readonly mid: string | null;
+    readonly direction: RtpTransceiverDirection;
+    readonly currentDirection: RtpTransceiverDirection | 'stopped' | null;
+    readonly reusable: boolean;
+    readonly sending: string | null;
+    readonly sendingCodec?: PeerCodec;
+    readonly receiving: PeerTrackInfo;
+}
+/**
+ * The state of a connection in a worker thread, sent with its events and the replies to its requests: the main thread
+ * reads its copy of it
+ */
+export interface PeerConnectionState {
+    readonly connectionState: 'new' | 'connecting' | 'connected' | 'disconnected' | 'failed' | 'closed';
+    readonly iceConnectionState: string;
+    readonly iceGatheringState: string;
+    readonly signalingState: string;
+    readonly localDescription: SignalingDescription | null;
+    readonly remoteDescription: SignalingDescription | null;
+    readonly maxMessageSize: number | null;
+    readonly configuration: {
+        iceServers: SignalingIceServer[];
+        iceTransportPolicy: 'all' | 'relay';
+    };
+    readonly transceivers: PeerTransceiverInfo[];
+    readonly ops: number;
+    readonly seq: number;
+}
+/**
+ * What the main thread knows of a data channel of a worker thread
+ */
+export interface PeerChannelInfo {
+    readonly label: string;
+    readonly protocol: string;
+    readonly ordered: boolean;
+    readonly maxRetransmits: number | null;
+    readonly maxPacketLifeTime: number | null;
+    readonly negotiated: boolean;
+    readonly id: number | null;
+    readonly readyState: 'connecting' | 'open' | 'closing' | 'closed';
+}
+/**
+ * A method of a connection the main thread calls, and waits for
+ */
+export type PeerCall = {
+    method: 'createOffer';
+    args: [options: {
+        iceRestart?: boolean;
+    }];
+} | {
+    method: 'createAnswer';
+    args: [];
+} | {
+    method: 'setLocalDescription';
+    args: [description?: SignalingDescription];
+} | {
+    method: 'setRemoteDescription';
+    args: [description: SignalingDescription];
+} | {
+    method: 'addIceCandidate';
+    args: [candidate: SignalingCandidate];
+};
+/**
+ * A change of the transceivers by the main thread, numbered (`op`)
+ */
+export type PeerTransceiverChange = {
+    type: 'addTrack';
+    conn: number;
+    op: number;
+    track: string;
+    streams: string[];
+    transceiver: string | null;
+    created: string;
+} | {
+    type: 'addTransceiver';
+    conn: number;
+    op: number;
+    created: string;
+    kind: 'audio' | 'video';
+    track?: string;
+    direction: RtpTransceiverDirection;
+    streams: string[];
+} | {
+    type: 'removeTrack';
+    conn: number;
+    op: number;
+    transceiver: string;
+} | {
+    type: 'direction';
+    conn: number;
+    op: number;
+    transceiver: string;
+    direction: RtpTransceiverDirection;
+} | {
+    type: 'stopTransceiver';
+    conn: number;
+    op: number;
+    transceiver: string;
+} | {
+    type: 'replaceTrack';
+    conn: number;
+    op: number;
+    transceiver: string;
+    track: string | null;
+} | {
+    type: 'setStreams';
+    conn: number;
+    op: number;
+    transceiver: string;
+    streams: string[];
+};
+/**
+ * The messages of the main thread to a worker thread of connections (`conn` is the connection, `ch` a channel, `track`
+ * a track of the main thread sent, or a track received in the thread)
+ */
+export type PeerToWorker = {
+    type: 'open';
+    conn: number;
+    options: EngineOptions;
+} | {
+    type: 'call';
+    conn: number;
+} & PeerCall | {
+    type: 'close';
+    conn: number;
+} | {
+    type: 'restartIce';
+    conn: number;
+} | {
+    type: 'setConfiguration';
+    conn: number;
+    configuration: {
+        iceServers?: SignalingIceServer[];
+        iceTransportPolicy?: 'all' | 'relay';
+    };
+} | {
+    type: 'channel';
+    conn: number;
+    ch: string;
+    label: string;
+    options: DataChannelOptions;
+} | {
+    type: 'send';
+    conn: number;
+    ch: string;
+    data: (string | Uint8Array)[];
+} | {
+    type: 'closeChannel';
+    conn: number;
+    ch: string;
+} | {
+    type: 'mirror';
+    conn: number;
+    track: string;
+    kind: 'audio' | 'video';
+    id: string;
+    remote: boolean;
+    codec?: PeerCodec;
+} | {
+    type: 'rtp';
+    conn: number;
+    track: string;
+    packets: Uint8Array[];
+    extensions: (Extensions | null)[];
+} | {
+    type: 'source';
+    conn: number;
+    track: string;
+    header: {
+        sequenceNumber: number;
+        timestamp: number;
+    };
+} | {
+    type: 'mirrorEnded';
+    conn: number;
+    track: string;
+} | {
+    type: 'dropTrack';
+    conn: number;
+    track: string;
+} | PeerTransceiverChange | {
+    type: 'consumed';
+    conn: number;
+    bytes: number;
+    rtp: number;
+} | {
+    type: 'keyframe';
+    conn: number;
+    track: string;
+} | {
+    type: 'want';
+    conn: number;
+    track: string;
+    wanted: boolean;
+} | {
+    type: 'debug';
+    enabled: boolean;
+} | {
+    type: 'stop';
+};
+/**
+ * The messages of a worker thread of connections to the main thread
+ */
+export type PeerFromWorker = {
+    type: 'ready';
+} | {
+    type: 'event';
+    conn: number;
+    name: 'icecandidate';
+    candidate: SignalingCandidate | null;
+    state: PeerConnectionState;
+} | {
+    type: 'event';
+    conn: number;
+    name: 'negotiationneeded';
+    state: PeerConnectionState;
+} | {
+    type: 'event';
+    conn: number;
+    name: 'connectionstatechange' | 'iceconnectionstatechange' | 'icegatheringstatechange' | 'signalingstatechange';
+    value: string;
+    state: PeerConnectionState;
+} | {
+    type: 'state';
+    conn: number;
+    state: PeerConnectionState;
+} | {
+    type: 'datachannel';
+    conn: number;
+    ch: string;
+    info: PeerChannelInfo;
+} | {
+    type: 'channelState';
+    conn: number;
+    ch: string;
+    readyState: PeerChannelInfo['readyState'];
+    id: number | null;
+} | {
+    type: 'message';
+    conn: number;
+    ch: string;
+    data: (string | Uint8Array)[];
+} | {
+    type: 'buffered';
+    conn: number;
+    ch: string;
+    amount: number;
+    applied: number;
+} | {
+    type: 'channelError';
+    conn: number;
+    ch: string;
+    error: {
+        name: string;
+        message: string;
+    };
+} | {
+    type: 'track';
+    conn: number;
+    transceiver: PeerTransceiverInfo;
+    streams: string[];
+    state: PeerConnectionState;
+} | {
+    type: 'rtp';
+    conn: number;
+    track: string;
+    packets: Uint8Array[];
+    extensions: (Extensions | null)[];
+} | {
+    type: 'trackEnded';
+    conn: number;
+    track: string;
+} | {
+    type: 'consumed';
+    conn: number;
+    rtp: number;
+} | {
+    type: 'pli';
+    conn: number;
+    transceiver: string;
+} | {
+    type: 'log';
+    namespace: string;
+    message: string;
+};

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

package/dist/types/peer/PeerWorkerCode.d.ts

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