@lakutata/webrtc 0.0.0-stage → 3.1.4

package/dist/cjs/sfu/SFUAccess.d.ts

@@ -0,0 +1,48 @@
+import type { EndpointLeg } from '../peer/Endpoints.js';
+import type { SignalingDescription } from '../protocol/SignalingProtocol.js';
+import type { SFU } from './SFU.js';
+import type { SFUServedRoom, SFUViewerSelect } from './SFURoom.js';
+import type { SFUWorkers } from './SFUWorkers.js';
+/**
+ * What the HTTP endpoints (WHIP, WHEP) need of a media server
+ */
+export interface SFUAccess {
+    /**
+     * A stream published with WHIP joins a room, as a member of role `whip`
+     * @param room The room.
+     * @param offer The offer of the publisher.
+     * @returns The id of the member, and its connection.
+     * @throws {SignalingLimitException} When the server takes no more members.
+     * @throws {Error} When the server does not serve the room, or the offer is refused.
+     */
+    publish(room: string, offer: SignalingDescription): Promise<{
+        peerId: string;
+        leg: EndpointLeg;
+    }>;
+    /**
+     * A viewer of WHEP receives the audio and the video of a member of a room
+     * @param room The room.
+     * @param offer The offer of the viewer.
+     * @param select Chooses the member among the tracks published; the default one without it.
+     * @returns The id of the viewer, its connection, and its source now.
+     * @throws {Error} When the server does not serve the room, or the offer is refused.
+     */
+    play(room: string, offer: SignalingDescription, select?: SFUViewerSelect): Promise<{
+        viewerId: string;
+        leg: EndpointLeg & {
+            source(): string | undefined;
+        };
+    }>;
+}
+/**
+ * What the HTTP endpoints may do with each media server
+ */
+export declare const sfuAccess: WeakMap<SFU, SFUAccess>;
+/**
+ * The worker threads of each media server forwarding in some (for the tests)
+ */
+export declare const sfuWorkers: WeakMap<SFU, SFUWorkers>;
+/**
+ * The rooms of each media server (for the tests)
+ */
+export declare const sfuRooms: WeakMap<SFU, Map<string, SFUServedRoom>>;

package/dist/cjs/sfu/SFUAccess.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sfuRooms = exports.sfuWorkers = exports.sfuAccess = void 0;
+/**
+ * What the HTTP endpoints may do with each media server
+ */
+exports.sfuAccess = new WeakMap();
+/**
+ * The worker threads of each media server forwarding in some (for the tests)
+ */
+exports.sfuWorkers = new WeakMap();
+/**
+ * The rooms of each media server (for the tests)
+ */
+exports.sfuRooms = new WeakMap();

package/dist/cjs/sfu/SFUClusterLeg.d.ts

@@ -0,0 +1,101 @@
+import type { EndpointLeg } from '../peer/Endpoints.js';
+import type { SignalingDescription } from '../protocol/SignalingProtocol.js';
+/**
+ * The topics of the requests of the media servers of a cluster to each other
+ */
+export declare const SFU_TOPICS: {
+    readonly serve: "webrtc.sfu.serve";
+    readonly publish: "webrtc.sfu.publish";
+    readonly play: "webrtc.sfu.play";
+    readonly patch: "webrtc.sfu.leg.patch";
+    readonly end: "webrtc.sfu.leg.end";
+    readonly ended: "webrtc.sfu.leg.ended";
+    readonly source: "webrtc.sfu.leg.source";
+    readonly choose: "webrtc.sfu.leg.choose";
+};
+/**
+ * The answer of a node taking a stream of WHIP or a viewer of WHEP: the answer to its offer (and the source of a
+ * viewer), or full, or refused (the room is not served, the offer is refused)
+ */
+export type LegReply = {
+    answer: SignalingDescription;
+    source?: string | null;
+} | {
+    full: true;
+} | {
+    refused: string;
+};
+/**
+ * The answer of the node of a leg to a PATCH (see patchConnection): the fragment answering an ICE restart, or stale
+ */
+export type LegPatchReply = {
+    fragment?: string;
+    stale?: boolean;
+};
+/**
+ * How long a node may take to answer an offer or a PATCH (its candidates gathered), in milliseconds
+ */
+export declare const LEG_TIMEOUT: number;
+/**
+ * What a leg of another node needs of the media server
+ */
+export interface ClusterLegLink {
+    readonly legs: Map<string, ClusterLeg>;
+    request<Result>(node: string, topic: string, message: unknown): Promise<Result>;
+}
+/**
+ * The connection of a session of WHIP or WHEP held by this node to its client, on the media server of another node:
+ * its PATCH requests and its end go there, its end and the source of a viewer come from there
+ */
+export declare class ClusterLeg implements EndpointLeg {
+    #private;
+    /**
+     * The id of the leg: the member of the stream of WHIP, or the viewer.
+     */
+    readonly id: string;
+    /**
+     * The node of the connection.
+     */
+    readonly node: string;
+    /**
+     * The answer, with all the candidates.
+     */
+    readonly answer: SignalingDescription;
+    /**
+     * Keep a leg of another node.
+     * @param link The media server.
+     * @param node The node of the connection.
+     * @param id The id of the leg.
+     * @param answer The answer.
+     * @param source The source of a viewer.
+     */
+    constructor(link: ClusterLegLink, node: string, 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 on the node of the connection.
+     * @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, on its node.
+     */
+    close(): void;
+    /**
+     * The connection is gone (closed on its node, or its node is down).
+     */
+    end(): void;
+}

package/dist/cjs/sfu/SFUClusterLeg.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClusterLeg = exports.LEG_TIMEOUT = exports.SFU_TOPICS = void 0;
+/**
+ * The topics of the requests of the media servers of a cluster to each other
+ */
+exports.SFU_TOPICS = {
+    //Take a member in a room (answered with the id of the member of the server, null for a room not served, or full)
+    serve: 'webrtc.sfu.serve',
+    //Take a stream of WHIP, or a viewer of WHEP, in a room: its offer answered there (a LegReply)
+    publish: 'webrtc.sfu.publish',
+    play: 'webrtc.sfu.play',
+    //To the node of a leg: apply a PATCH, end the leg
+    patch: 'webrtc.sfu.leg.patch',
+    end: 'webrtc.sfu.leg.end',
+    //To the node of the session of a leg: the leg ended, the source of a viewer changed, choose the source of a viewer
+    ended: 'webrtc.sfu.leg.ended',
+    source: 'webrtc.sfu.leg.source',
+    choose: 'webrtc.sfu.leg.choose'
+};
+/**
+ * How long a node may take to answer an offer or a PATCH (its candidates gathered), in milliseconds
+ */
+exports.LEG_TIMEOUT = 10000;
+/**
+ * The connection of a session of WHIP or WHEP held by this node to its client, on the media server of another node:
+ * its PATCH requests and its end go there, its end and the source of a viewer come from there
+ */
+class ClusterLeg {
+    #link;
+    #listeners = [];
+    #ended = false;
+    #source;
+    /**
+     * Keep a leg of another node.
+     * @param link The media server.
+     * @param node The node of the connection.
+     * @param id The id of the leg.
+     * @param answer The answer.
+     * @param source The source of a viewer.
+     */
+    constructor(link, node, id, answer, source) {
+        this.#link = link;
+        this.node = node;
+        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 on the node of the connection.
+     * @param fragment
+     * @param restart
+     */
+    async patch(fragment, restart) {
+        if (this.#ended)
+            throw new Error('The session ended');
+        const reply = await this.#link.request(this.node, exports.SFU_TOPICS.patch, { id: this.id, fragment: fragment, restart: restart });
+        return reply.stale ? null : reply.fragment;
+    }
+    /**
+     * Call a listener once the leg ends.
+     * @param listener
+     */
+    ended(listener) {
+        if (this.#ended)
+            listener();
+        else
+            this.#listeners.push(listener);
+    }
+    /**
+     * Close the connection, on its node.
+     */
+    close() {
+        if (this.#ended)
+            return;
+        this.#link.request(this.node, exports.SFU_TOPICS.end, { id: this.id }).catch(() => undefined);
+        this.end();
+    }
+    /**
+     * The connection is gone (closed on its node, or its node is down).
+     */
+    end() {
+        if (this.#ended)
+            return;
+        this.#ended = true;
+        if (this.#link.legs.get(this.id) === this)
+            this.#link.legs.delete(this.id);
+        for (const listener of this.#listeners.splice(0))
+            listener();
+    }
+}
+exports.ClusterLeg = ClusterLeg;

package/dist/cjs/sfu/SFURoom.d.ts

@@ -0,0 +1,148 @@
+import { type MediaTrack } from '../peer/MediaTrack.js';
+import { type EndpointLeg } from '../peer/Endpoints.js';
+import type { PeerConnection } from '../peer/PeerConnection.js';
+import { type SignalingCandidate, type SignalingDescription, type SignalingJoinResult, type SignalingPeer, type SignalingRole, type SignalingStream } from '../protocol/SignalingProtocol.js';
+import type { SignalingReceiver } from '../signaling/Signaling.js';
+import type { SFUTrack } from './SFU.js';
+import type { SFUWorkerCodec } from './SFUWorkerChannel.js';
+/**
+ * What a room needs of the signaling (the Signaling component, or its proxy in a worker thread)
+ */
+export interface SFUSignaling {
+    join(peerId: string, room: string, options: {
+        role: SignalingRole;
+        receive: SignalingReceiver;
+    }): Promise<SignalingJoinResult>;
+    leave(peerId: string, room: string): Promise<void>;
+    signal(peerId: string, room: string, to: string, signal: {
+        description?: SignalingDescription;
+        candidate?: SignalingCandidate | null;
+        streams?: SignalingStream[];
+    }): Promise<boolean>;
+}
+/**
+ * What a room needs of its media server
+ */
+export interface SFUHost {
+    readonly id: string;
+    readonly signaling: SFUSignaling;
+    connect(): Promise<PeerConnection>;
+    select(subscriber: SignalingPeer, track: SFUTrack): boolean | Promise<boolean>;
+    emit(event: string, ...args: unknown[]): unknown;
+    emptied(room: SFURoom): void;
+    changed?(room: SFURoom): void;
+    sourced?(viewerId: string, source: string | undefined): void;
+    known?(room: SFURoom, tracks: SFUOfferedTrack[]): void;
+}
+/**
+ * A track a media server offers the ones of the other nodes of its room: a track published by one of its members, and
+ * the codec of its packets
+ */
+export interface SFUOfferedTrack {
+    readonly track: SFUTrack;
+    readonly codec?: SFUWorkerCodec;
+}
+/**
+ * Chooses the member a viewer of WHEP receives, among the tracks published (see WHEPSelect)
+ */
+export type SFUViewerSelect = (tracks: SFUTrack[]) => string | undefined | Promise<string | undefined>;
+/**
+ * A room of the media server, wherever it forwards (in the main thread, an SFURoom, or in a worker thread)
+ */
+export interface SFUServedRoom {
+    readonly name: string;
+    readonly ready: Promise<void>;
+    readonly closed: boolean;
+    readonly members: string[];
+    readonly tracks: SFUTrack[];
+    readonly viewers: number;
+    track(peerId: string, trackId: string): MediaTrack | undefined;
+    publish(id: string, offer: SignalingDescription): Promise<EndpointLeg>;
+    play(id: string, offer: SignalingDescription, select?: SFUViewerSelect): Promise<EndpointLeg & {
+        source(): string | undefined;
+    }>;
+    close(): Promise<void>;
+}
+/**
+ * The part of a room on the media server: a connection to each member (the server never gives up its offers), the
+ * tracks they publish, forwarded to the others the server selects for them
+ */
+export declare class SFURoom implements SFUServedRoom {
+    #private;
+    /**
+     * The name of the room.
+     */
+    readonly name: string;
+    /**
+     * Resolves once the server is in the room.
+     */
+    readonly ready: Promise<void>;
+    /**
+     * Create the part of a room, and join it.
+     * @param host The media server.
+     * @param name The room.
+     */
+    constructor(host: SFUHost, name: string);
+    /**
+     * Whether the room has no member and no viewer left.
+     */
+    get empty(): boolean;
+    /**
+     * The number of the viewers of WHEP.
+     */
+    get viewers(): number;
+    /**
+     * Whether the server left the room.
+     */
+    get closed(): boolean;
+    /**
+     * The ids of the members of this node (the media servers of the other nodes are not counted).
+     */
+    get members(): string[];
+    /**
+     * The tracks the members of this node publish.
+     */
+    get tracks(): SFUTrack[];
+    /**
+     * A track published in the room: received from its member, or from the media server of its node while it is read.
+     * @param peerId The member.
+     * @param trackId The id of the track.
+     * @returns The track, or undefined when it is not published.
+     */
+    track(peerId: string, trackId: string): MediaTrack | undefined;
+    /**
+     * The connections to the media servers of the other nodes: the tracks sent on each, the ones received (for the
+     * tests).
+     * @returns By the id of the member of each server.
+     */
+    cascades(): Record<string, {
+        sends: number;
+        receives: number;
+    }>;
+    /**
+     * Leave the room: the connections to the members are closed.
+     * @returns Resolves once the signaling is told.
+     */
+    close(): Promise<void>;
+    /**
+     * A viewer of WHEP: the connection answering its offer sends it an audio and a video track of a member of the room
+     * (its source), once and as long as there is one, from a key frame. Its media negotiate every codec it offers that
+     * the server has, so a source publishing later with any of them is sent too.
+     * @param id The id of the viewer.
+     * @param offer The offer of the viewer.
+     * @param select Chooses its source among the members publishing; the newest stream of WHIP, else the first member
+     * publishing, without it.
+     * @returns The connection, its answer with all its candidates, and its source now.
+     */
+    play(id: string, offer: SignalingDescription, select?: SFUViewerSelect): Promise<EndpointLeg & {
+        source(): string | undefined;
+    }>;
+    /**
+     * A stream published with WHIP joins the room: a member (of role `whip`) whose connection answers the offer of the
+     * publisher, publishing its tracks and receiving nothing
+     * @param id The id of the member.
+     * @param offer The offer of the publisher.
+     * @returns The connection, its answer with all its candidates.
+     */
+    publish(id: string, offer: SignalingDescription): Promise<EndpointLeg>;
+}