@lakutata/webrtc 0.0.0-stage → 3.1.4

package/dist/esm/whip/WHIP.js

@@ -0,0 +1,466 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { randomUUID } from 'node:crypto';
+import { Component, DTO } from '@lakutata/core';
+import { Configurable, Singleton } from '@lakutata/core/decorator/di';
+import { iceServersFor } from '../cluster/ClusterTURN.js';
+import { entityTag, gathered, patchConnection } from '../peer/Endpoints.js';
+import { PeerConnection } from '../peer/PeerConnection.js';
+import { WHIPDeniedException } from '../exceptions/WHIPDeniedException.js';
+import { WHIPLimitException } from '../exceptions/WHIPLimitException.js';
+import { WHIPOfferException } from '../exceptions/WHIPOfferException.js';
+import { WHIPSessionNotFoundException } from '../exceptions/WHIPSessionNotFoundException.js';
+import { SignalingLimitException } from '../exceptions/SignalingLimitException.js';
+import { sfuAccess } from '../sfu/SFUAccess.js';
+/**
+ * The topic of the requests ending a session on the node holding it
+ */
+const UNPUBLISH_TOPIC = 'webrtc.whip.unpublish';
+/**
+ * How long a DELETE waits for the nodes of the cluster, in milliseconds
+ */
+const UNPUBLISH_TIMEOUT = 2000;
+/**
+ * The topic of the requests applying a PATCH of a session on the node holding it
+ */
+const PATCH_TOPIC = 'webrtc.whip.patch';
+/**
+ * How long a PATCH waits for the nodes of the cluster (an ICE restart gathers candidates), in milliseconds
+ */
+const PATCH_TIMEOUT = 12000;
+/**
+ * The ingestion of WHIP (RFC 9725): encoders (OBS, GStreamer, ffmpeg) and browsers publish a stream with an HTTP POST
+ * of their offer, and the application receives their audio and video. Each publication is a session with (without a
+ * media server) a {@link PeerConnection} and its tracks; the component emits `publish` (the session) once it answers,
+ * and `unpublish` (the session) when it ends: the publisher deleted it, its connection failed or closed, or the
+ * application stopped. The tracks give their RTP packets, to record them or to send them on to other connections.
+ * With a media server (`sfu`), a stream goes to a room of the server instead (`roomOf`, the stream by default), as a
+ * member sending its tracks to the other members and to the viewers of WHEP.
+ *
+ * Register it as `whip` with {@link buildWHIPOptions}, and add `WHIPController` to the controllers of the entrypoint,
+ * with an HTTP adapter reading the bodies of WHIP as text (its option
+ * `body: {text: ['application/sdp', 'application/trickle-ice-sdpfrag']}`). The answers carry all the candidates; a
+ * PATCH of a session gives it the candidates of its publisher (trickle ICE), or restarts ICE (RFC 9725, section 4.3).
+ * Behind a load balancer, give it a `cluster`: the DELETE of a session may reach another instance, which ends it on the
+ * instance holding it.
+ * @example
+ * ```typescript
+ * import {Application, Component} from 'lakutata'
+ * import {buildEntrypoints} from 'lakutata/com/entrypoint'
+ * import {expressHTTPEntrypoint} from 'lakutata/adapter/express'
+ * import {buildWHIPOptions, type MediaTrack, type RtpPacket, type WHIP, type WHIPSession, WHIPController} from '@lakutata/webrtc'
+ *
+ * //The application's own component, receiving the streams
+ * class Recorder extends Component {
+ *     protected async init(): Promise<void> {
+ *         const whip: WHIP = await this.getObject<WHIP>('whip')
+ *         whip.on('publish', (session: WHIPSession): void => {
+ *             session.tracks?.forEach((track: MediaTrack): void => {
+ *                 track.on('rtp', (packet: RtpPacket): void => console.log(session.stream, track.kind, packet.payload.length))
+ *             })
+ *         })
+ *     }
+ * }
+ *
+ * Application.run(() => ({
+ *     id: 'ingest.app',
+ *     name: 'Ingest',
+ *     components: {
+ *         //OBS publishes to https://ingest.example.com/whip/studio with the bearer token of the environment
+ *         whip: buildWHIPOptions({
+ *             authorize: ({stream, token}): boolean => stream === 'studio' && token === process.env.WHIP_TOKEN,
+ *             iceAdditionalHostAddresses: ['203.0.113.10'],
+ *             icePortRange: [40000, 40999]
+ *         }),
+ *         recorder: {class: Recorder},
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [WHIPController],
+ *             http: expressHTTPEntrypoint({port: 8080, body: {text: ['application/sdp', 'application/trickle-ice-sdpfrag']}})
+ *         })
+ *     },
+ *     bootstrap: ['recorder', 'entrypoint']
+ * }))
+ * ```
+ */
+let WHIP = class WHIP extends Component {
+    #sessions = new Map();
+    //The connections of the sessions going to the media server
+    #legs = new Map();
+    //The entity tags of the ICE sessions of the sessions
+    #tags = new Map();
+    #clusterObject;
+    #unhandle;
+    /**
+     * Join the cluster: end the sessions of this node asked by the others.
+     * @protected
+     */
+    async init() {
+        if (!this.cluster)
+            return;
+        const cluster = await this.getObject(this.cluster);
+        this.#clusterObject = cluster;
+        const unhandle = [
+            cluster.handle(UNPUBLISH_TOPIC, ({ id, stream }) => this.end(id, stream)),
+            cluster.handle(PATCH_TOPIC, async ({ id, fragment, stream, ifMatch }) => await this.#patchHere(id, fragment, stream, ifMatch) ?? null)
+        ];
+        this.#unhandle = () => unhandle.forEach((each) => each());
+    }
+    /**
+     * End the sessions.
+     * @protected
+     */
+    async destroy() {
+        this.#unhandle?.();
+        for (const id of [...this.#sessions.keys()])
+            this.end(id);
+    }
+    /**
+     * The sessions of this node.
+     */
+    get sessions() {
+        return [...this.#sessions.values()];
+    }
+    /**
+     * The origins the browsers may publish from.
+     */
+    get allowedOrigin() {
+        return this.allowOrigin;
+    }
+    /**
+     * A session.
+     * @param id The id of the session.
+     * @returns The session, `undefined` when there is none of this id.
+     * @example
+     * ```typescript
+     * import type {WHIP, WHIPSession} from '@lakutata/webrtc'
+     *
+     * declare const whip: WHIP
+     * const session: WHIPSession | undefined = whip.session('0b7d…')
+     * ```
+     */
+    session(id) {
+        return this.#sessions.get(id);
+    }
+    /**
+     * Publish a stream: answer the offer of its publisher, with all the candidates of the connection. `WHIPController`
+     * calls it for the POST requests.
+     * @param stream The stream.
+     * @param offer The SDP offer of the publisher.
+     * @param options The bearer token of the publisher, and the context of its request (for `authorize`).
+     * @returns The session, and the answer.
+     * @throws {WHIPDeniedException} When `authorize` refuses the stream.
+     * @throws {WHIPLimitException} When there are `maxSessions` sessions already.
+     * @throws {WHIPOfferException} When the offer has no audio or video, or the connection refuses it.
+     * @example
+     * ```typescript
+     * import type {SignalingDescription, WHIP, WHIPSession} from '@lakutata/webrtc'
+     *
+     * declare const whip: WHIP
+     * declare const offer: SignalingDescription
+     * const {session, answer}: {session: WHIPSession, answer: SignalingDescription} = await whip.publish('studio', offer)
+     * ```
+     */
+    async publish(stream, offer, options = {}) {
+        if (this.authorize && !(await this.authorize({ stream: stream, token: options.token }, options.context))) {
+            throw new WHIPDeniedException('The stream {stream} may not be published', { stream: stream });
+        }
+        if (this.maxSessions && this.#sessions.size >= this.maxSessions)
+            throw new WHIPLimitException('There are {count} sessions already', { count: this.#sessions.size });
+        if (offer.type !== 'offer' || !/^m=(audio|video) /m.test(offer.sdp ?? ''))
+            throw new WHIPOfferException('The offer has no audio and no video');
+        if (this.sfu)
+            return await this.publishToSFU(stream, offer, options);
+        const connection = await this.getObject(PeerConnection, {
+            ...this.icePortRange ? { icePortRange: this.icePortRange } : {},
+            ...this.iceAdditionalHostAddresses ? { iceAdditionalHostAddresses: this.iceAdditionalHostAddresses } : {},
+            ...this.codecs ? { codecs: this.codecs } : {}
+        });
+        const tracks = [];
+        const session = { id: randomUUID(), stream: stream, connection: connection, tracks: tracks };
+        connection.on('track', (track) => void tracks.push(track));
+        //The session ends when its connection fails or closes; before the answer, the publication is refused
+        connection.on('connectionstatechange', (state) => {
+            if (state === 'failed' || state === 'closed')
+                this.end(session.id);
+        });
+        try {
+            await connection.setRemoteDescription(offer);
+            await connection.setLocalDescription();
+        }
+        catch (error) {
+            connection.close();
+            throw new WHIPOfferException('The offer is refused: {reason}', { reason: error.message });
+        }
+        await gathered(connection);
+        if (connection.connectionState === 'failed' || connection.connectionState === 'closed') {
+            connection.close();
+            throw new WHIPOfferException('The connection {state} before the answer', { state: connection.connectionState });
+        }
+        this.#sessions.set(session.id, session);
+        this.#tags.set(session.id, entityTag());
+        this.emit('publish', session);
+        return { session: session, answer: connection.localDescription };
+    }
+    /**
+     * Publish a stream to a room of the media server
+     * @param stream The stream.
+     * @param offer The SDP offer of the publisher.
+     * @param options The bearer token of the publisher, and the context of its request (for `roomOf`).
+     * @returns The session, and the answer.
+     * @protected
+     */
+    async publishToSFU(stream, offer, options) {
+        const sfu = await this.getObject(this.sfu);
+        const room = this.roomOf ? await this.roomOf({ stream: stream, token: options.token }, options.context) : stream;
+        let published;
+        try {
+            published = await sfuAccess.get(sfu).publish(room, offer);
+        }
+        catch (error) {
+            if (error instanceof SignalingLimitException)
+                throw new WHIPLimitException('The media server takes no more members');
+            throw new WHIPOfferException('The offer is refused: {reason}', { reason: error.message });
+        }
+        const session = { id: randomUUID(), stream: stream, room: room, peerId: published.peerId };
+        this.#sessions.set(session.id, session);
+        this.#tags.set(session.id, entityTag());
+        this.#legs.set(session.id, published.leg);
+        published.leg.ended(() => this.end(session.id));
+        this.emit('publish', session);
+        return { session: session, answer: published.leg.answer };
+    }
+    /**
+     * End a session: close its connection, and emit `unpublish` (on the node holding it). `WHIPController` calls it for
+     * the DELETE requests. With a cluster, a session of another node is ended there.
+     * @param id The id of the session.
+     * @param stream Only if it is a session of this stream.
+     * @returns Whether there was such a session.
+     * @example
+     * ```typescript
+     * import type {WHIP, WHIPSession} from '@lakutata/webrtc'
+     *
+     * declare const whip: WHIP
+     * //Stop the publications of a stream on this node
+     * await Promise.all(whip.sessions.filter((session: WHIPSession): boolean => session.stream === 'studio').map((session: WHIPSession): Promise<boolean> => whip.unpublish(session.id)))
+     * ```
+     */
+    async unpublish(id, stream) {
+        if (this.#sessions.has(id) || !this.#clusterObject)
+            return this.end(id, stream);
+        const replies = await this.#clusterObject.requestAll(UNPUBLISH_TOPIC, { id: id, stream: stream }, { timeout: UNPUBLISH_TIMEOUT });
+        return replies.some((reply) => reply.result === true);
+    }
+    /**
+     * End a session of this node
+     * @param id The id of the session.
+     * @param stream Only if it is a session of this stream.
+     * @returns Whether there was such a session.
+     * @protected
+     */
+    end(id, stream) {
+        const session = this.#sessions.get(id);
+        if (!session || (stream !== undefined && session.stream !== stream))
+            return false;
+        this.#sessions.delete(id);
+        this.#tags.delete(id);
+        session.connection?.close();
+        this.#legs.get(id)?.close();
+        this.#legs.delete(id);
+        this.emit('unpublish', session);
+        return true;
+    }
+    /**
+     * The entity tag of the ICE session of a session of this node (its `ETag`): a new one after each ICE restart.
+     * @param id The id of the session.
+     * @returns The tag, `undefined` when there is no session of this id.
+     * @example
+     * ```typescript
+     * import type {WHIP} from '@lakutata/webrtc'
+     *
+     * declare const whip: WHIP
+     * const tag: string | undefined = whip.entityTagOf('0b7d…')
+     * ```
+     */
+    entityTagOf(id) {
+        return this.#tags.get(id);
+    }
+    /**
+     * Apply a PATCH of a session (RFC 9725, section 4.3), on the node holding it: the candidates of its publisher
+     * (trickle ICE), or an ICE restart when its credentials changed, which needs `If-Match: *`. `WHIPController` calls
+     * it for the PATCH requests. With a cluster, a session of another node is patched there.
+     * @param id The id of the session.
+     * @param fragment The fragment of SDP of the request (`application/trickle-ice-sdpfrag`).
+     * @param options The stream the session must be of, and the `If-Match` of the request: `*` for any ICE session, or
+     * the entity tag of one, quoted.
+     * @returns The fragment of SDP answering an ICE restart (none for trickle ICE), and the entity tag of the ICE session;
+     * `stale` when the request is not applied: its `If-Match` is not the entity tag of the session, or its credentials
+     * changed without `If-Match: *` (a request sent again after a restart).
+     * @throws {WHIPSessionNotFoundException} When no node has a session of this id, or the session is not of this
+     * stream.
+     * @throws {WHIPOfferException} When the fragment has no ICE, or the connection refuses it.
+     * @example
+     * ```typescript
+     * import type {WHIP} from '@lakutata/webrtc'
+     *
+     * declare const whip: WHIP
+     * declare const fragment: string
+     * //An ICE restart
+     * const {fragment: answer, tag} = await whip.patch('0b7d…', fragment, {ifMatch: '*'})
+     * ```
+     */
+    async patch(id, fragment, options = {}) {
+        let outcome = await this.#patchHere(id, fragment, options.stream, options.ifMatch);
+        if (!outcome && this.#clusterObject) {
+            const replies = await this.#clusterObject.requestAll(PATCH_TOPIC, { id: id, fragment: fragment, ...options }, { timeout: PATCH_TIMEOUT });
+            outcome = replies.find((reply) => !!reply.result)?.result ?? undefined;
+        }
+        if (!outcome)
+            throw new WHIPSessionNotFoundException('There is no session {session}', { session: id });
+        if ('refused' in outcome)
+            throw new WHIPOfferException('The ICE fragment is refused: {reason}', { reason: outcome.refused });
+        return outcome;
+    }
+    /**
+     * Apply a PATCH of a session of this node
+     * @param id
+     * @param fragment
+     * @param stream
+     * @param ifMatch
+     * @returns What it gives, or undefined when this node has no such session.
+     */
+    async #patchHere(id, fragment, stream, ifMatch) {
+        const session = this.#sessions.get(id);
+        const connection = session?.connection;
+        const leg = this.#legs.get(id);
+        if (!session || (!connection && !leg) || (stream !== undefined && session.stream !== stream))
+            return undefined;
+        const tag = this.#tags.get(id) ?? '';
+        if (ifMatch !== undefined && ifMatch !== '*' && ifMatch !== `"${tag}"`)
+            return { tag: tag, stale: true };
+        //A restart only with If-Match: * (RFC 9725, section 4.3.2)
+        const restart = ifMatch === '*';
+        let answer;
+        try {
+            answer = connection ? await patchConnection(connection, fragment, restart) : await leg.patch(fragment, restart);
+        }
+        catch (error) {
+            return { refused: error.message };
+        }
+        if (answer === null)
+            return { tag: this.#tags.get(id) ?? '', stale: true };
+        if (answer !== undefined && this.#sessions.has(id))
+            this.#tags.set(id, entityTag());
+        return { ...answer === undefined ? {} : { fragment: answer }, tag: this.#tags.get(id) ?? '' };
+    }
+    /**
+     * The ICE servers given to a publisher, with new TURN credentials.
+     * @param stream The stream (the user of the TURN credentials).
+     * @returns The ICE servers.
+     * @example
+     * ```typescript
+     * import type {SignalingIceServer, WHIP} from '@lakutata/webrtc'
+     *
+     * declare const whip: WHIP
+     * const iceServers: SignalingIceServer[] = await whip.iceServersOf('studio')
+     * ```
+     */
+    async iceServersOf(stream) {
+        return iceServersFor(stream, {
+            turn: this.turn ? await this.getObject(this.turn) : undefined,
+            cluster: this.#clusterObject,
+            secret: this.turnSecret,
+            select: this.selectTURN,
+            iceServers: this.iceServers
+        }).iceServers;
+    }
+};
+__decorate([
+    Configurable(DTO.Function().optional()),
+    __metadata("design:type", Function)
+], WHIP.prototype, "authorize", void 0);
+__decorate([
+    Configurable(DTO.String().optional()),
+    __metadata("design:type", String)
+], WHIP.prototype, "turn", void 0);
+__decorate([
+    Configurable(DTO.String().optional()),
+    __metadata("design:type", String)
+], WHIP.prototype, "sfu", void 0);
+__decorate([
+    Configurable(DTO.Function().optional()),
+    __metadata("design:type", Function)
+], WHIP.prototype, "roomOf", void 0);
+__decorate([
+    Configurable(DTO.String().optional()),
+    __metadata("design:type", String)
+], WHIP.prototype, "cluster", void 0);
+__decorate([
+    Configurable(DTO.String().min(1).optional()),
+    __metadata("design:type", String)
+], WHIP.prototype, "turnSecret", void 0);
+__decorate([
+    Configurable(DTO.Function().optional()),
+    __metadata("design:type", Function)
+], WHIP.prototype, "selectTURN", void 0);
+__decorate([
+    Configurable(DTO.Array().items(DTO.Object({
+        urls: DTO.Alternatives(DTO.String(), DTO.Array().items(DTO.String())).required(),
+        username: DTO.String().optional(),
+        credential: DTO.String().optional()
+    })).optional().default([])),
+    __metadata("design:type", Array)
+], WHIP.prototype, "iceServers", void 0);
+__decorate([
+    Configurable(DTO.Number().integer().min(0).optional().default(100)),
+    __metadata("design:type", Number)
+], WHIP.prototype, "maxSessions", void 0);
+__decorate([
+    Configurable(DTO.String().optional().default('*')),
+    __metadata("design:type", String)
+], WHIP.prototype, "allowOrigin", void 0);
+__decorate([
+    Configurable(DTO.Array().items(DTO.Number().port()).length(2).optional()),
+    __metadata("design:type", Array)
+], WHIP.prototype, "icePortRange", void 0);
+__decorate([
+    Configurable(DTO.Array().items(DTO.String()).optional()),
+    __metadata("design:type", Array)
+], WHIP.prototype, "iceAdditionalHostAddresses", void 0);
+__decorate([
+    Configurable(DTO.Array().items(DTO.String()).optional()),
+    __metadata("design:type", Array)
+], WHIP.prototype, "codecs", void 0);
+WHIP = __decorate([
+    Singleton()
+], WHIP);
+export { WHIP };
+/**
+ * Build the options of a {@link WHIP} component, for the `components` of an application (named `whip`, the name
+ * `WHIPController` uses).
+ * @param options Who may publish, the ICE servers given to the publishers, the limit of sessions, the candidates and
+ * the codecs of the connections (all optional).
+ * @returns The component options.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildWHIPOptions} from '@lakutata/webrtc'
+ *
+ * Application.run(() => ({
+ *     id: 'ingest.app',
+ *     name: 'Ingest',
+ *     components: {
+ *         whip: buildWHIPOptions({maxSessions: 10, codecs: ['audio/opus', 'video/H264']})
+ *     }
+ * }))
+ * ```
+ */
+export function buildWHIPOptions(options = {}) {
+    return { class: WHIP, ...options };
+}