@lakutata/webrtc 0.0.0-stage → 3.1.4

package/dist/cjs/shared/ChunkedChannel.js

@@ -0,0 +1,182 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChunkedChannel = void 0;
+const Emitter_js_1 = require("./Emitter.js");
+/**
+ * The flag of the last chunk of a message
+ */
+const FINAL = 0x01;
+/**
+ * The flag of a text message
+ */
+const TEXT = 0x02;
+/**
+ * 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))
+ * ```
+ */
+class ChunkedChannel extends Emitter_js_1.Emitter {
+    #channel;
+    #chunkSize;
+    #highWaterMark;
+    #maxMessageSize;
+    #onMessage;
+    //The sends, one after the other: the chunks of two messages do not mix
+    #sending = Promise.resolve();
+    #parts = [];
+    #received = 0;
+    #dropping = false;
+    /**
+     * 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, options = {}) {
+        super();
+        if (!channel.ordered)
+            throw new TypeError('A chunked channel must be ordered');
+        this.#channel = channel;
+        this.#chunkSize = Math.max(1, options.chunkSize ?? 16384);
+        this.#highWaterMark = options.highWaterMark ?? 1048576;
+        this.#maxMessageSize = options.maxMessageSize ?? 67108864;
+        channel.binaryType = 'arraybuffer';
+        if (!channel.bufferedAmountLowThreshold)
+            channel.bufferedAmountLowThreshold = Math.floor(this.#highWaterMark / 2);
+        this.#onMessage = (event) => this.#receive(event.data);
+        channel.addEventListener('message', this.#onMessage);
+    }
+    /**
+     * The data channel.
+     */
+    get channel() {
+        return this.#channel;
+    }
+    /**
+     * 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) {
+        const sending = this.#sending.then(() => this.#send(data));
+        this.#sending = sending.catch(() => undefined);
+        return sending;
+    }
+    /**
+     * Stop listening to the channel, and close it.
+     */
+    close() {
+        this.#channel.removeEventListener('message', this.#onMessage);
+        this.#channel.close();
+    }
+    /**
+     * Send the chunks of a message
+     * @param data
+     */
+    async #send(data) {
+        if (typeof Blob !== 'undefined' && data instanceof Blob) {
+            if (!data.size)
+                return this.#frame(FINAL, new Uint8Array(0));
+            for (let offset = 0; offset < data.size; offset += this.#chunkSize) {
+                const chunk = new Uint8Array(await data.slice(offset, offset + this.#chunkSize).arrayBuffer());
+                await this.#frame(offset + this.#chunkSize >= data.size ? FINAL : 0, chunk);
+            }
+            return;
+        }
+        const text = typeof data === 'string';
+        const bytes = typeof data === 'string'
+            ? new TextEncoder().encode(data)
+            : ArrayBuffer.isView(data) ? new Uint8Array(data.buffer, data.byteOffset, data.byteLength) : new Uint8Array(data);
+        const flags = text ? TEXT : 0;
+        if (!bytes.length)
+            return this.#frame(flags | FINAL, new Uint8Array(0));
+        for (let offset = 0; offset < bytes.length; offset += this.#chunkSize) {
+            const end = Math.min(offset + this.#chunkSize, bytes.length);
+            await this.#frame(flags | (end === bytes.length ? FINAL : 0), bytes.subarray(offset, end));
+        }
+    }
+    /**
+     * Send a frame once the buffer of the channel is below the high water mark
+     * @param flags
+     * @param chunk
+     */
+    async #frame(flags, chunk) {
+        if (this.#channel.bufferedAmount > this.#highWaterMark)
+            await this.#drain();
+        if (this.#channel.readyState !== 'open')
+            throw new Error(`The channel is ${this.#channel.readyState}`);
+        const frame = new Uint8Array(chunk.length + 1);
+        frame[0] = flags;
+        frame.set(chunk, 1);
+        this.#channel.send(frame);
+    }
+    /**
+     * Wait for the buffer of the channel to empty, or for the channel to close
+     */
+    #drain() {
+        return new Promise((resolve) => {
+            const done = () => {
+                this.#channel.removeEventListener('bufferedamountlow', done);
+                this.#channel.removeEventListener('close', done);
+                resolve();
+            };
+            this.#channel.addEventListener('bufferedamountlow', done);
+            this.#channel.addEventListener('close', done);
+        });
+    }
+    /**
+     * A frame received
+     * @param data
+     */
+    #receive(data) {
+        if (typeof data === 'string' || !data)
+            return void this.emit('error', new Error('A chunked channel received a text frame'));
+        const frame = data instanceof ArrayBuffer ? new Uint8Array(data) : new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+        if (!frame.length)
+            return void this.emit('error', new Error('A chunked channel received an empty frame'));
+        const flags = frame[0];
+        const chunk = frame.subarray(1);
+        if (!this.#dropping) {
+            this.#received += chunk.length;
+            if (this.#received > this.#maxMessageSize) {
+                this.#dropping = true;
+                this.#parts = [];
+                this.emit('error', new Error(`A message over ${this.#maxMessageSize} bytes was dropped`));
+            }
+            else {
+                this.#parts.push(chunk.slice());
+            }
+        }
+        if (!(flags & FINAL))
+            return;
+        const parts = this.#parts;
+        const dropped = this.#dropping;
+        this.#parts = [];
+        this.#received = 0;
+        this.#dropping = false;
+        if (dropped)
+            return;
+        const message = parts.length === 1 ? parts[0] : new Uint8Array(parts.reduce((size, part) => size + part.length, 0));
+        if (parts.length > 1) {
+            let offset = 0;
+            for (const part of parts) {
+                message.set(part, offset);
+                offset += part.length;
+            }
+        }
+        this.emit('message', flags & TEXT ? new TextDecoder().decode(message) : message);
+    }
+}
+exports.ChunkedChannel = ChunkedChannel;

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

@@ -0,0 +1,231 @@
+import type { SignalingCandidate, SignalingDescription, SignalingIceServer } from '../protocol/SignalingProtocol.js';
+/**
+ * What the rooms need of a data channel: `RTCDataChannel` of the browsers, `PeerChannel` of Node.js.
+ */
+export interface DataChannelLike {
+    /**
+     * Its label.
+     */
+    readonly label: string;
+    /**
+     * `connecting`, `open`, `closing` or `closed`.
+     */
+    readonly readyState: string;
+    /**
+     * Send a message.
+     * @param data The message.
+     */
+    send(data: string): void;
+    /**
+     * Add a listener of an event: `open`, `message`, `close`.
+     * @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;
+    /**
+     * Dispatch an event to the listeners.
+     * @param event The event.
+     */
+    dispatchEvent(event: Event): boolean;
+    /**
+     * Close it.
+     */
+    close(): void;
+}
+/**
+ * What the rooms need of a transceiver: `RTCRtpTransceiver` of the browsers, `RtpTransceiver` of Node.js.
+ */
+export interface TransceiverLike {
+    /**
+     * The media id of its line in the description; `null` until negotiated.
+     */
+    readonly mid: string | null;
+    /**
+     * The direction wanted.
+     */
+    direction: string;
+    /**
+     * The direction negotiated.
+     */
+    readonly currentDirection: string | null;
+    /**
+     * Its sending side.
+     */
+    readonly sender: {
+        readonly track: {
+            readonly kind: string;
+        } | null;
+        replaceTrack(track: any): Promise<void>;
+        setStreams(...streams: any[]): void;
+    };
+    /**
+     * Its receiving side.
+     */
+    readonly receiver: {
+        readonly track: {
+            readonly kind: string;
+        };
+    };
+}
+/**
+ * The options of a data channel, as `RTCDataChannelInit`.
+ */
+export interface DataChannelOptions {
+    /**
+     * Whether the messages arrive in order.
+     * @default true
+     */
+    ordered?: boolean;
+    /**
+     * How many times a message is sent again at most; none for a reliable channel.
+     */
+    maxRetransmits?: number;
+    /**
+     * How long a message is sent again at most, in milliseconds; none for a reliable channel.
+     */
+    maxPacketLifeTime?: number;
+    /**
+     * The subprotocol.
+     * @default ''
+     */
+    protocol?: string;
+    /**
+     * Whether both peers create the channel themselves with the same `id`, instead of one of them announcing it.
+     * @default false
+     */
+    negotiated?: boolean;
+    /**
+     * The id of a negotiated channel.
+     */
+    id?: number;
+}
+/**
+ * The configuration of a peer connection that the rooms set: the ICE servers, and whether to use only the TURN relays.
+ */
+export interface PeerConnectionConfiguration {
+    /**
+     * The ICE servers.
+     */
+    iceServers?: SignalingIceServer[];
+    /**
+     * `all`, or `relay` to use only the TURN relays.
+     */
+    iceTransportPolicy?: 'all' | 'relay';
+    /**
+     * Whether it is the connection to the media server of a room: it negotiates the RTP header extensions the server
+     * uses (the `headerExtensions` of `PeerConnection`; the browsers always do).
+     */
+    headerExtensions?: boolean;
+}
+/**
+ * What the rooms need of a peer connection: `RTCPeerConnection` of the browsers, `PeerConnection` of Node.js.
+ */
+export interface PeerConnectionLike<Channel extends DataChannelLike = DataChannelLike> {
+    /**
+     * The state of the offer and answer exchange.
+     */
+    readonly signalingState: string;
+    /**
+     * The state of the connection.
+     */
+    readonly connectionState: string;
+    /**
+     * The local description.
+     */
+    readonly localDescription: SignalingDescription | null;
+    /**
+     * Add a listener of an event: `negotiationneeded`, `icecandidate`, `connectionstatechange`, `datachannel`, `track`.
+     * @param type The event.
+     * @param listener The listener.
+     */
+    addEventListener(type: string, listener: (event: any) => void): void;
+    /**
+     * Set the local description: the offer or the answer it creates, or a rollback.
+     * @param description A rollback; none for the offer or the answer.
+     */
+    setLocalDescription(description?: {
+        type: 'rollback';
+    }): Promise<unknown>;
+    /**
+     * Set the remote description.
+     * @param description The description.
+     */
+    setRemoteDescription(description: SignalingDescription): Promise<unknown>;
+    /**
+     * Add a remote candidate.
+     * @param candidate The candidate.
+     */
+    addIceCandidate(candidate: SignalingCandidate): Promise<unknown>;
+    /**
+     * Create a data channel.
+     * @param label Its label.
+     * @param options Its options.
+     */
+    createDataChannel(label: string, options?: DataChannelOptions): Channel;
+    /**
+     * Add a track to send (the rooms use it for the types of the tracks and the streams).
+     * @param track The track.
+     * @param streams Its streams.
+     */
+    addTrack(track: any, ...streams: any[]): unknown;
+    /**
+     * Add a transceiver sending a track.
+     * @param track The track.
+     * @param init Its direction and its streams.
+     */
+    addTransceiver(track: any, init: {
+        direction: 'sendonly';
+        streams: any[];
+    }): TransceiverLike;
+    /**
+     * The transceivers.
+     */
+    getTransceivers(): TransceiverLike[];
+    /**
+     * Restart ICE: the next offer gathers new candidates.
+     */
+    restartIce(): void;
+    /**
+     * The configuration.
+     */
+    getConfiguration(): object;
+    /**
+     * Change the configuration (the ICE servers).
+     * @param configuration The whole configuration.
+     */
+    setConfiguration(configuration: object): void;
+    /**
+     * Close the connection.
+     */
+    close(): unknown;
+}
+/**
+ * Creates the peer connections of the rooms.
+ * @param configuration The ICE servers given by the signaling, and the transport policy.
+ * @returns The connection.
+ */
+export type PeerConnectionFactory<Connection extends PeerConnectionLike<any>> = (configuration: PeerConnectionConfiguration) => Connection | Promise<Connection>;
+/**
+ * The track type of a peer connection type: `MediaStreamTrack` in the browsers, `MediaTrack` in Node.js
+ */
+export type TrackOf<Connection extends PeerConnectionLike<any>> = Parameters<Connection['addTrack']>[0];
+/**
+ * The stream type of a peer connection type: `MediaStream` in the browsers, a stream id in Node.js
+ */
+export type StreamOf<Connection extends PeerConnectionLike<any>> = Parameters<Connection['addTrack']> extends [any, ...infer Streams] ? Streams[number] : never;
+/**
+ * The data channel type of a peer connection type
+ */
+export type ChannelOf<Connection extends PeerConnectionLike<any>> = ReturnType<Connection['createDataChannel']>;
+/**
+ * The track event type of a peer connection type: `RTCTrackEvent` in the browsers, `PeerTrackEvent` in Node.js
+ */
+export type TrackEventOf<Connection> = Connection extends {
+    ontrack: ((event: infer Event) => any) | null;
+} ? Event : never;

package/dist/cjs/shared/Connections.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,50 @@
+/**
+ * The events of an emitter: for each event, the arguments of its listeners.
+ */
+export type EmitterEvents = Record<string, unknown[]>;
+/**
+ * A listener of an event.
+ */
+export type EmitterListener<Args extends unknown[]> = (...args: Args) => void;
+/**
+ * A small typed event emitter, the same in the browsers and in Node.js (it does not use `node:events`). A listener
+ * throwing does not stop the other listeners: its error is reported as an uncaught one, as the listeners of an
+ * `EventTarget` are.
+ */
+export declare class Emitter<Events extends EmitterEvents> {
+    #private;
+    /**
+     * Add a listener of an event.
+     * @param event The event.
+     * @param listener The listener, given the arguments of the event.
+     * @returns This emitter.
+     */
+    on<Event extends keyof Events>(event: Event, listener: EmitterListener<Events[Event]>): this;
+    /**
+     * Add a listener of the next emission of an event only.
+     * @param event The event.
+     * @param listener The listener, given the arguments of the event.
+     * @returns This emitter.
+     */
+    once<Event extends keyof Events>(event: Event, listener: EmitterListener<Events[Event]>): this;
+    /**
+     * Remove a listener of an event.
+     * @param event The event.
+     * @param listener The listener.
+     * @returns This emitter.
+     */
+    off<Event extends keyof Events>(event: Event, listener: EmitterListener<Events[Event]>): this;
+    /**
+     * Call the listeners of an event
+     * @param event
+     * @param args
+     * @protected
+     */
+    protected emit<Event extends keyof Events>(event: Event, ...args: Events[Event]): boolean;
+    /**
+     * Whether an event has listeners
+     * @param event
+     * @protected
+     */
+    protected listened(event: keyof Events): boolean;
+}

package/dist/cjs/shared/Emitter.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Emitter = void 0;
+/**
+ * A small typed event emitter, the same in the browsers and in Node.js (it does not use `node:events`). A listener
+ * throwing does not stop the other listeners: its error is reported as an uncaught one, as the listeners of an
+ * `EventTarget` are.
+ */
+class Emitter {
+    #listeners = new Map();
+    /**
+     * Add a listener of an event.
+     * @param event The event.
+     * @param listener The listener, given the arguments of the event.
+     * @returns This emitter.
+     */
+    on(event, listener) {
+        let listeners = this.#listeners.get(event);
+        if (!listeners) {
+            listeners = new Set();
+            this.#listeners.set(event, listeners);
+        }
+        listeners.add(listener);
+        return this;
+    }
+    /**
+     * Add a listener of the next emission of an event only.
+     * @param event The event.
+     * @param listener The listener, given the arguments of the event.
+     * @returns This emitter.
+     */
+    once(event, listener) {
+        const wrapper = (...args) => {
+            this.off(event, wrapper);
+            listener(...args);
+        };
+        return this.on(event, wrapper);
+    }
+    /**
+     * Remove a listener of an event.
+     * @param event The event.
+     * @param listener The listener.
+     * @returns This emitter.
+     */
+    off(event, listener) {
+        this.#listeners.get(event)?.delete(listener);
+        return this;
+    }
+    /**
+     * Call the listeners of an event
+     * @param event
+     * @param args
+     * @protected
+     */
+    emit(event, ...args) {
+        const listeners = this.#listeners.get(event);
+        if (!listeners?.size)
+            return false;
+        for (const listener of [...listeners]) {
+            try {
+                listener(...args);
+            }
+            catch (error) {
+                queueMicrotask(() => {
+                    throw error;
+                });
+            }
+        }
+        return true;
+    }
+    /**
+     * Whether an event has listeners
+     * @param event
+     * @protected
+     */
+    listened(event) {
+        return !!this.#listeners.get(event)?.size;
+    }
+}
+exports.Emitter = Emitter;