@lakutata/webrtc 0.0.0-stage → 3.1.1

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/peer/Endpoints.d.ts

@@ -0,0 +1,75 @@
+import type { IncomingMessage } from 'node:http';
+import type { SignalingDescription, SignalingIceServer } from '../protocol/SignalingProtocol.js';
+import type { PeerConnection } from './PeerConnection.js';
+/**
+ * How long an answer of an HTTP endpoint (WHIP, WHEP) waits for the candidates of its connection at most, in
+ * milliseconds
+ */
+export declare const GATHERING_TIMEOUT: number;
+/**
+ * Wait for the candidates of a connection, all of them or for a time at most
+ * @param connection
+ * @param timeout
+ */
+export declare function gathered(connection: PeerConnection, timeout?: number): Promise<void>;
+/**
+ * The connection of a session of an HTTP endpoint (WHIP, WHEP) to its client, wherever it is (in a worker thread for a
+ * media server forwarding in some): the answer to the offer of the client, its PATCH requests, and the end of the
+ * session
+ */
+export interface EndpointLeg {
+    readonly answer: SignalingDescription;
+    patch(fragment: string, restart: boolean): Promise<string | undefined | null>;
+    ended(listener: () => void): void;
+    close(): void;
+}
+/**
+ * The bearer token of a request
+ * @param request
+ */
+export declare function bearerOf(request: IncomingMessage): string | undefined;
+/**
+ * The path of a request, without its query and its last slash
+ * @param request
+ */
+export declare function pathOf(request: IncomingMessage): string;
+/**
+ * A `Link` header of each ICE server (RFC 9725, section 4.6)
+ * @param iceServers
+ */
+export declare function linksOf(iceServers: SignalingIceServer[]): string[];
+/**
+ * The ICE of a fragment of SDP (RFC 8840): its credentials, and its candidates with the media they belong to
+ * @param fragment
+ */
+export declare function iceOf(fragment: string): {
+    ufrag?: string;
+    pwd?: string;
+    candidates: {
+        candidate: string;
+        sdpMid?: string;
+    }[];
+};
+/**
+ * Apply a PATCH of a session of an HTTP endpoint (RFC 9725, section 4.3) to its connection: the candidates of the
+ * client (trickle ICE), or an ICE restart when its credentials changed. The server answering the offer of the client,
+ * a restart is an offer of the client again, its credentials replaced, that the connection answers with new ones.
+ * @param connection
+ * @param fragment The fragment of SDP of the request (`application/trickle-ice-sdpfrag`).
+ * @param restart Whether the request may restart ICE (its `If-Match` is `*`): a fragment of other credentials without
+ * it is of an ICE session gone (a request sent again after a restart), not applied.
+ * @returns The fragment of the answer of a restart (its credentials, its candidates); none for trickle ICE; `null` for
+ * a fragment of an ICE session gone.
+ * @throws {Error} When the fragment has no ICE, or the connection refuses it.
+ */
+export declare function patchConnection(connection: PeerConnection, fragment: string, restart: boolean): Promise<string | undefined | null>;
+/**
+ * The fragment of SDP of the ICE of a description (RFC 8840): its credentials, and the candidates of its first media
+ * (the one the others are bundled on)
+ * @param sdp
+ */
+export declare function fragmentOf(sdp: string): string;
+/**
+ * A new entity tag of an ICE session (the `ETag` of a session of an HTTP endpoint)
+ */
+export declare function entityTag(): string;

package/dist/cjs/peer/Endpoints.js

@@ -0,0 +1,154 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GATHERING_TIMEOUT = void 0;
+exports.gathered = gathered;
+exports.bearerOf = bearerOf;
+exports.pathOf = pathOf;
+exports.linksOf = linksOf;
+exports.iceOf = iceOf;
+exports.patchConnection = patchConnection;
+exports.fragmentOf = fragmentOf;
+exports.entityTag = entityTag;
+const node_crypto_1 = require("node:crypto");
+/**
+ * How long an answer of an HTTP endpoint (WHIP, WHEP) waits for the candidates of its connection at most, in
+ * milliseconds
+ */
+exports.GATHERING_TIMEOUT = 5000;
+/**
+ * Wait for the candidates of a connection, all of them or for a time at most
+ * @param connection
+ * @param timeout
+ */
+function gathered(connection, timeout = exports.GATHERING_TIMEOUT) {
+    if (connection.iceGatheringState === 'complete')
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const done = () => {
+            clearTimeout(timer);
+            connection.off('icegatheringstatechange', changed);
+            resolve();
+        };
+        const changed = (state) => {
+            if (state === 'complete')
+                done();
+        };
+        const timer = setTimeout(done, timeout);
+        connection.on('icegatheringstatechange', changed);
+    });
+}
+/**
+ * The bearer token of a request
+ * @param request
+ */
+function bearerOf(request) {
+    return /^Bearer\s+(\S+)\s*$/i.exec(request.headers.authorization ?? '')?.[1];
+}
+/**
+ * The path of a request, without its query and its last slash
+ * @param request
+ */
+function pathOf(request) {
+    const url = request.originalUrl ?? request.url ?? '';
+    return url.split('?')[0].replace(/\/+$/, '');
+}
+/**
+ * A `Link` header of each ICE server (RFC 9725, section 4.6)
+ * @param iceServers
+ */
+function linksOf(iceServers) {
+    const quoted = (value) => `"${value.replace(/["\\]/g, '\\$&')}"`;
+    return iceServers.flatMap((server) => (Array.isArray(server.urls) ? server.urls : [server.urls]).map((url) => {
+        const credentials = server.username && server.credential
+            ? `; username=${quoted(server.username)}; credential=${quoted(server.credential)}; credential-type="password"`
+            : '';
+        return `<${url}>; rel="ice-server"${credentials}`;
+    }));
+}
+/**
+ * The ICE of a fragment of SDP (RFC 8840): its credentials, and its candidates with the media they belong to
+ * @param fragment
+ */
+function iceOf(fragment) {
+    const ice = { candidates: [] };
+    //The session, then each media: the candidates of a media are of its mid, before or after them
+    for (const section of fragment.split(/^(?=m=)/m)) {
+        const lines = section.split(/\r?\n/);
+        const mid = lines.find((line) => line.startsWith('a=mid:'))?.slice('a=mid:'.length).trim();
+        for (const line of lines) {
+            if (line.startsWith('a=ice-ufrag:'))
+                ice.ufrag ??= line.slice('a=ice-ufrag:'.length).trim();
+            else if (line.startsWith('a=ice-pwd:'))
+                ice.pwd ??= line.slice('a=ice-pwd:'.length).trim();
+            else if (line.startsWith('a=candidate:'))
+                ice.candidates.push({ candidate: line.slice(2).trim(), ...mid === undefined ? {} : { sdpMid: mid } });
+        }
+    }
+    return ice;
+}
+/**
+ * Apply a PATCH of a session of an HTTP endpoint (RFC 9725, section 4.3) to its connection: the candidates of the
+ * client (trickle ICE), or an ICE restart when its credentials changed. The server answering the offer of the client,
+ * a restart is an offer of the client again, its credentials replaced, that the connection answers with new ones.
+ * @param connection
+ * @param fragment The fragment of SDP of the request (`application/trickle-ice-sdpfrag`).
+ * @param restart Whether the request may restart ICE (its `If-Match` is `*`): a fragment of other credentials without
+ * it is of an ICE session gone (a request sent again after a restart), not applied.
+ * @returns The fragment of the answer of a restart (its credentials, its candidates); none for trickle ICE; `null` for
+ * a fragment of an ICE session gone.
+ * @throws {Error} When the fragment has no ICE, or the connection refuses it.
+ */
+async function patchConnection(connection, fragment, restart) {
+    const ice = iceOf(fragment);
+    const remote = connection.remoteDescription?.sdp ?? '';
+    const mids = [...remote.matchAll(/^a=mid:(\S+)/gm)].map((match) => match[1]);
+    const add = async () => {
+        for (const { candidate, sdpMid } of ice.candidates)
+            await connection.addIceCandidate({ candidate: candidate, sdpMid: sdpMid ?? mids[0] ?? null });
+    };
+    const restarting = !!ice.ufrag && ice.ufrag !== /^a=ice-ufrag:(\S+)/m.exec(remote)?.[1];
+    if (restarting && !restart)
+        return null;
+    if (!restarting) {
+        //The end of the candidates of the client has nothing to apply
+        if (!ice.ufrag && !ice.candidates.length && !/^a=end-of-candidates/m.test(fragment))
+            throw new Error('The fragment has no ICE');
+        await add();
+        return undefined;
+    }
+    if (!ice.pwd)
+        throw new Error('The fragment of an ICE restart has no password');
+    const offer = remote
+        .replace(/^a=ice-ufrag:.*$/gm, `a=ice-ufrag:${ice.ufrag}`)
+        .replace(/^a=ice-pwd:.*$/gm, `a=ice-pwd:${ice.pwd}`)
+        .replace(/^a=(candidate:.*|end-of-candidates)\r?\n/gm, '');
+    await connection.setRemoteDescription({ type: 'offer', sdp: offer });
+    await connection.setLocalDescription();
+    await add();
+    await gathered(connection);
+    return fragmentOf(connection.localDescription?.sdp ?? '');
+}
+/**
+ * The fragment of SDP of the ICE of a description (RFC 8840): its credentials, and the candidates of its first media
+ * (the one the others are bundled on)
+ * @param sdp
+ */
+function fragmentOf(sdp) {
+    const first = (sdp.split(/^(?=m=)/m)[1] ?? '').split(/\r?\n/);
+    return [
+        `a=ice-ufrag:${/^a=ice-ufrag:(\S+)/m.exec(sdp)?.[1] ?? ''}`,
+        `a=ice-pwd:${/^a=ice-pwd:(\S+)/m.exec(sdp)?.[1] ?? ''}`,
+        ...first[0] ? [
+            first[0],
+            ...first.filter((line) => line.startsWith('a=mid:')),
+            ...first.filter((line) => line.startsWith('a=candidate:')),
+            'a=end-of-candidates'
+        ] : []
+    ].join('\r\n') + '\r\n';
+}
+/**
+ * A new entity tag of an ICE session (the `ETag` of a session of an HTTP endpoint)
+ */
+function entityTag() {
+    return (0, node_crypto_1.randomBytes)(12).toString('hex');
+}

package/dist/cjs/peer/EngineConfig.d.ts

@@ -0,0 +1,20 @@
+import type { RTCPeerConnectionConfig } from '../lib/peer/peerConnection.js';
+import type { SignalingIceServer } from '../protocol/SignalingProtocol.js';
+/**
+ * The options of a connection the engine is configured from, plain data (given to a worker thread as they are)
+ */
+export interface EngineOptions {
+    readonly iceServers: SignalingIceServer[];
+    readonly iceTransportPolicy: 'all' | 'relay';
+    readonly icePortRange?: [number, number];
+    readonly iceAdditionalHostAddresses?: string[];
+    readonly iceUseIpv4: boolean;
+    readonly iceUseIpv6: boolean;
+    readonly codecs: string[];
+    readonly headerExtensions: boolean;
+}
+/**
+ * The configuration of the connection of the engine of a connection
+ * @param options
+ */
+export declare function engineConfigOf(options: EngineOptions): RTCPeerConnectionConfig;

package/dist/cjs/peer/EngineConfig.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.engineConfigOf = engineConfigOf;
+const rtcpFeedback_js_1 = require("../lib/peer/media/extension/rtcpFeedback.js");
+const rtpExtension_js_1 = require("../lib/peer/media/extension/rtpExtension.js");
+const MediaCodecs_js_1 = require("./MediaCodecs.js");
+/**
+ * The configuration of the connection of the engine of a connection
+ * @param options
+ */
+function engineConfigOf(options) {
+    const config = {
+        iceServers: options.iceServers,
+        iceTransportPolicy: options.iceTransportPolicy,
+        iceUseIpv4: options.iceUseIpv4,
+        iceUseIpv6: options.iceUseIpv6,
+        codecs: (0, MediaCodecs_js_1.engineCodecsOf)(options.codecs),
+        //The largest message the other peer may send, as Chrome accepts (below the SCTP window of 1 MiB)
+        maxMessageSize: 262144
+    };
+    if (options.icePortRange)
+        config.icePortRange = options.icePortRange;
+    if (options.iceAdditionalHostAddresses)
+        config.iceAdditionalHostAddresses = options.iceAdditionalHostAddresses;
+    if (options.headerExtensions) {
+        //The ids of Chrome and Safari: a browser rolling back an offer of its own keeps its ids, and refuses others
+        config.headerExtensions = {
+            audio: [(0, rtpExtension_js_1.useAudioLevelIndication)(), (0, rtpExtension_js_1.useAbsSendTime)(), (0, rtpExtension_js_1.useTransportWideCC)(), (0, rtpExtension_js_1.useSdesMid)()],
+            video: [(0, rtpExtension_js_1.useAbsSendTime)(), (0, rtpExtension_js_1.useTransportWideCC)(), (0, rtpExtension_js_1.useSdesMid)()]
+        };
+        //The feedback of the transport-wide sequence numbers
+        for (const codec of [...config.codecs.audio, ...config.codecs.video])
+            codec.rtcpFeedback.push((0, rtcpFeedback_js_1.useTWCC)());
+    }
+    return config;
+}

package/dist/cjs/peer/EngineConnection.d.ts

@@ -0,0 +1,22 @@
+import type { RTCDataChannel } from '../lib/peer/dataChannel.js';
+import type { RTCPeerConnection } from '../lib/peer/peerConnection.js';
+import type { PeerChannel } from './PeerChannel.js';
+import type { PeerConnection } from './PeerConnection.js';
+/**
+ * The connections of the engine of the connections
+ */
+export declare const engineConnections: WeakMap<PeerConnection, RTCPeerConnection>;
+/**
+ * The connection of the engine of a connection: its transports, its senders and receivers
+ * @param connection
+ */
+export declare function engineConnectionOf(connection: PeerConnection): RTCPeerConnection;
+/**
+ * The channels of the engine of the channels
+ */
+export declare const engineChannels: WeakMap<PeerChannel, RTCDataChannel>;
+/**
+ * The channel of the engine of a channel: its SCTP transport
+ * @param channel
+ */
+export declare function engineChannelOf(channel: PeerChannel): RTCDataChannel;

package/dist/cjs/peer/EngineConnection.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.engineChannels = exports.engineConnections = void 0;
+exports.engineConnectionOf = engineConnectionOf;
+exports.engineChannelOf = engineChannelOf;
+/**
+ * The connections of the engine of the connections
+ */
+exports.engineConnections = new WeakMap();
+/**
+ * The connection of the engine of a connection: its transports, its senders and receivers
+ * @param connection
+ */
+function engineConnectionOf(connection) {
+    return exports.engineConnections.get(connection);
+}
+/**
+ * The channels of the engine of the channels
+ */
+exports.engineChannels = new WeakMap();
+/**
+ * The channel of the engine of a channel: its SCTP transport
+ * @param channel
+ */
+function engineChannelOf(channel) {
+    return exports.engineChannels.get(channel);
+}

package/dist/cjs/peer/Events.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The options of `addEventListener`.
+ */
+export interface ListenerOptions {
+    /**
+     * Remove the listener after its first call.
+     */
+    once?: boolean;
+    /**
+     * Remove the listener when the signal aborts.
+     */
+    signal?: AbortSignal;
+    /**
+     * Unused (no capture phase), as in `EventTarget` of Node.js.
+     */
+    capture?: boolean;
+}
+/**
+ * A listener of the `on…` properties and of `addEventListener`.
+ */
+export type DOMEventListener = (event: any) => void;
+/**
+ * The events of an object, in the two styles of the peer connections and of the channels: the W3C style
+ * (`addEventListener`, the `on…` properties, given an event object) and the Node.js style (`on`, given the value of the
+ * event)
+ */
+export declare class Events {
+    #private;
+    /**
+     * The events of an object
+     * @param owner
+     */
+    constructor(owner: object);
+    /**
+     * Fire an event: the listeners of the W3C style get an event object holding the given properties, the ones of the
+     * Node.js style get the arguments
+     * @param type
+     * @param properties
+     * @param args
+     */
+    fire(type: string, properties: Record<string, unknown>, ...args: unknown[]): void;
+    /**
+     * Dispatch an event given: the listeners of the W3C style get it, the ones of the Node.js style the arguments
+     * @param event
+     * @param args
+     */
+    dispatch(event: Event, ...args: unknown[]): boolean;
+    addEventListener(type: string, listener: DOMEventListener, options?: boolean | ListenerOptions): void;
+    removeEventListener(type: string, listener: DOMEventListener, options?: boolean | ListenerOptions): void;
+    on(type: string, listener: (...args: any[]) => void): void;
+    once(type: string, listener: (...args: any[]) => void): void;
+    off(type: string, listener: (...args: any[]) => void): void;
+    handler(type: string): DOMEventListener | null;
+    setHandler(type: string, handler: DOMEventListener | null): void;
+}

package/dist/cjs/peer/Events.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Events = void 0;
+const node_events_1 = require("node:events");
+/**
+ * The events of an object, in the two styles of the peer connections and of the channels: the W3C style
+ * (`addEventListener`, the `on…` properties, given an event object) and the Node.js style (`on`, given the value of the
+ * event)
+ */
+class Events {
+    #target = new EventTarget();
+    #emitter = new node_events_1.EventEmitter();
+    #handlers = new Map();
+    #owner;
+    /**
+     * The events of an object
+     * @param owner
+     */
+    constructor(owner) {
+        this.#owner = owner;
+        //More listeners than the warning threshold of Node.js are expected (a channel per peer…)
+        this.#emitter.setMaxListeners(0);
+    }
+    /**
+     * Fire an event: the listeners of the W3C style get an event object holding the given properties, the ones of the
+     * Node.js style get the arguments
+     * @param type
+     * @param properties
+     * @param args
+     */
+    fire(type, properties, ...args) {
+        const event = type === 'message' ? new MessageEvent('message', { data: properties.data }) : new Event(type);
+        for (const [key, value] of Object.entries(properties)) {
+            if (key !== 'data')
+                Object.defineProperty(event, key, { value: value, enumerable: true });
+        }
+        Object.defineProperty(event, 'currentTarget', { value: this.#owner });
+        this.#target.dispatchEvent(event);
+        const handler = this.#handlers.get(type);
+        if (handler)
+            handler.call(this.#owner, event);
+        //An error without listeners would throw
+        if (type !== 'error' || this.#emitter.listenerCount('error'))
+            this.#emitter.emit(type, ...args);
+    }
+    /**
+     * Dispatch an event given: the listeners of the W3C style get it, the ones of the Node.js style the arguments
+     * @param event
+     * @param args
+     */
+    dispatch(event, ...args) {
+        const dispatched = this.#target.dispatchEvent(event);
+        this.#handlers.get(event.type)?.call(this.#owner, event);
+        if (event.type !== 'error' || this.#emitter.listenerCount('error'))
+            this.#emitter.emit(event.type, ...args);
+        return dispatched && !event.defaultPrevented;
+    }
+    addEventListener(type, listener, options) {
+        this.#target.addEventListener(type, listener, options);
+    }
+    removeEventListener(type, listener, options) {
+        this.#target.removeEventListener(type, listener, options);
+    }
+    on(type, listener) {
+        this.#emitter.on(type, listener);
+    }
+    once(type, listener) {
+        this.#emitter.once(type, listener);
+    }
+    off(type, listener) {
+        this.#emitter.off(type, listener);
+    }
+    handler(type) {
+        return this.#handlers.get(type) ?? null;
+    }
+    setHandler(type, handler) {
+        if (handler) {
+            this.#handlers.set(type, handler);
+        }
+        else {
+            this.#handlers.delete(type);
+        }
+    }
+}
+exports.Events = Events;

package/dist/cjs/peer/MediaCodecs.d.ts

@@ -0,0 +1,27 @@
+import type { RTCRtpCodecParameters } from '../lib/peer/media/parameters.js';
+/**
+ * The MIME types of the codecs supported
+ */
+export declare const SUPPORTED_CODECS: string[];
+/**
+ * The codecs offered by default, in the order of preference: the ones of the browsers, VP8 first as Chrome does
+ */
+export declare const DEFAULT_CODECS: string[];
+/**
+ * The MIME type of a codec as written in SUPPORTED_CODECS (`video/H264`, `audio/opus`), whatever its case
+ * @param mimeType
+ */
+export declare function canonicalCodec(mimeType: string): string;
+/**
+ * The codec of the engine of a MIME type
+ * @param mimeType
+ */
+export declare function engineCodecOf(mimeType: string): RTCRtpCodecParameters;
+/**
+ * The codecs of the engine of a list of MIME types, by kind
+ * @param mimeTypes
+ */
+export declare function engineCodecsOf(mimeTypes: string[]): {
+    audio: RTCRtpCodecParameters[];
+    video: RTCRtpCodecParameters[];
+};

package/dist/cjs/peer/MediaCodecs.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CODECS = exports.SUPPORTED_CODECS = void 0;
+exports.canonicalCodec = canonicalCodec;
+exports.engineCodecOf = engineCodecOf;
+exports.engineCodecsOf = engineCodecsOf;
+const codec_js_1 = require("../lib/peer/media/codec.js");
+/**
+ * The codecs the connections negotiate, by their MIME type in lower case
+ */
+const CODECS = {
+    'audio/opus': () => (0, codec_js_1.useOPUS)(),
+    'audio/pcmu': () => (0, codec_js_1.usePCMU)(),
+    'video/vp8': () => (0, codec_js_1.useVP8)(),
+    'video/vp9': () => (0, codec_js_1.useVP9)(),
+    'video/h264': () => (0, codec_js_1.useH264)()
+};
+/**
+ * The MIME types of the codecs supported
+ */
+exports.SUPPORTED_CODECS = ['audio/opus', 'audio/PCMU', 'video/VP8', 'video/VP9', 'video/H264'];
+/**
+ * The codecs offered by default, in the order of preference: the ones of the browsers, VP8 first as Chrome does
+ */
+exports.DEFAULT_CODECS = ['audio/opus', 'audio/PCMU', 'video/VP8', 'video/H264', 'video/VP9'];
+/**
+ * The MIME type of a codec as written in SUPPORTED_CODECS (`video/H264`, `audio/opus`), whatever its case
+ * @param mimeType
+ */
+function canonicalCodec(mimeType) {
+    return exports.SUPPORTED_CODECS.find((codec) => codec.toLowerCase() === mimeType.toLowerCase()) ?? mimeType;
+}
+/**
+ * The codec of the engine of a MIME type
+ * @param mimeType
+ */
+function engineCodecOf(mimeType) {
+    const codec = CODECS[mimeType.toLowerCase()];
+    if (!codec)
+        throw new TypeError(`The codec ${mimeType} is not supported: ${exports.SUPPORTED_CODECS.join(', ')}`);
+    return codec();
+}
+/**
+ * The codecs of the engine of a list of MIME types, by kind
+ * @param mimeTypes
+ */
+function engineCodecsOf(mimeTypes) {
+    const codecs = mimeTypes.map(engineCodecOf);
+    return {
+        audio: codecs.filter((codec) => codec.mimeType.toLowerCase().startsWith('audio/')),
+        video: codecs.filter((codec) => codec.mimeType.toLowerCase().startsWith('video/'))
+    };
+}