@lakutata/webrtc 0.0.0-stage → 3.1.4

package/dist/cjs/whip/WHIP.d.ts

@@ -0,0 +1,426 @@
+import { Component, type ComponentOptions } from '@lakutata/core';
+import type { HTTPContext } from '@lakutata/entrypoint';
+import type { SignalingDescription, SignalingIceServer } from '../protocol/SignalingProtocol.js';
+import { type TURNSelector } from '../cluster/ClusterTURN.js';
+import type { MediaTrack } from '../peer/MediaTrack.js';
+import { PeerConnection } from '../peer/PeerConnection.js';
+/**
+ * Who publishes a stream: the stream of the URL, and the bearer token of the request.
+ */
+export interface WHIPPublisher {
+    /**
+     * The stream: the last segment of the URL of the endpoint (`/whip/:stream`).
+     */
+    readonly stream: string;
+    /**
+     * The bearer token of the `Authorization` header, if any.
+     */
+    readonly token?: string;
+}
+/**
+ * Decides whether a publisher may publish a stream (the `authorize` option of {@link WHIP}).
+ * @param publisher The stream and the bearer token.
+ * @param context The context of the HTTP request, when it comes through `WHIPController`.
+ * @returns Whether it may publish.
+ */
+export type WHIPAuthorize = (publisher: WHIPPublisher, context?: HTTPContext) => boolean | Promise<boolean>;
+/**
+ * Gives the room of the media server a stream published goes to (the `roomOf` option of {@link WHIP}).
+ * @param publisher The stream and the bearer token.
+ * @param context The context of the HTTP request, when it comes through `WHIPController`.
+ * @returns The room.
+ */
+export type WHIPRoomOf = (publisher: WHIPPublisher, context?: HTTPContext) => string | Promise<string>;
+/**
+ * A stream being published: its WHIP session.
+ */
+export interface WHIPSession {
+    /**
+     * The id of the session: the last segment of its URL (`/whip/:stream/:session`), random so that it cannot be guessed.
+     */
+    readonly id: string;
+    /**
+     * The stream.
+     */
+    readonly stream: string;
+    /**
+     * The connection to the publisher; none when the stream goes to a media server (`sfu`).
+     */
+    readonly connection?: PeerConnection;
+    /**
+     * The tracks received: their packets come with their `rtp` event; none when the stream goes to a media server (its
+     * `track()` gives them).
+     */
+    readonly tracks?: readonly MediaTrack[];
+    /**
+     * The room of the media server the stream goes to.
+     */
+    readonly room?: string;
+    /**
+     * The id of the member publishing the stream in the room of the media server (`whip:` and a random id of its own:
+     * the id of the session is the credential ending it, so the members never see it).
+     */
+    readonly peerId?: string;
+}
+/**
+ * The options of a {@link WHIP} (see {@link buildWHIPOptions}).
+ */
+export interface WHIPOptions {
+    /**
+     * Decides whether a publisher may publish a stream; anyone may publish any stream without it.
+     * @default none
+     */
+    authorize?: WHIPAuthorize;
+    /**
+     * The name of a {@link SFU} component: the streams published go to its rooms, each a member of its room (of role
+     * `whip`) sending its tracks to the other members; the application reads those tracks with the server's `track()`.
+     * @default none (the sessions give their tracks)
+     */
+    sfu?: string;
+    /**
+     * Gives the room of the media server a stream goes to.
+     * @default the stream
+     */
+    roomOf?: WHIPRoomOf;
+    /**
+     * The name of a {@link Cluster} component: a DELETE or a PATCH of a session reaching another node of the cluster
+     * (behind a load balancer) is applied on the node holding the session.
+     * @default none
+     */
+    cluster?: string;
+    /**
+     * The name of a {@link TURNServer} component: the publishers get its ICE servers, with short-lived credentials, in
+     * the `Link` headers of the answers.
+     * @default none
+     */
+    turn?: string;
+    /**
+     * The secret shared by the TURN servers of the cluster (their `secret`): with it and `cluster`, the publishers get
+     * TURN servers of the cluster, chosen by `selectTURN`, after the ones of `turn`. Without it, the TURN servers of
+     * the cluster are given only when `turn` is set, with its credentials (they share its secret).
+     * @default none
+     */
+    turnSecret?: string;
+    /**
+     * Chooses the TURN servers of the cluster given to a publisher.
+     * @default the two least loaded that are not full
+     */
+    selectTURN?: TURNSelector;
+    /**
+     * More ICE servers given to the publishers, after the ones of `turn` and of the cluster.
+     * @default []
+     */
+    iceServers?: SignalingIceServer[];
+    /**
+     * The sessions at once at most, on this node; 0 for no limit.
+     * @default 100
+     */
+    maxSessions?: number;
+    /**
+     * The origins the browsers may publish from (the `Access-Control-Allow-Origin` header).
+     * @default '*'
+     */
+    allowOrigin?: string;
+    /**
+     * The UDP ports of the candidates of the connections, as `[first, last]`: the range opened in the firewall or
+     * published by the container. Each session takes a port on each address of the machine; with `sfu`, the
+     * connections are the media server's, on its ports.
+     * @default any free port
+     */
+    icePortRange?: [number, number];
+    /**
+     * More addresses given as candidates of the connections: the public address of a NAT forwarding `icePortRange` with
+     * the same port numbers.
+     * @default none
+     */
+    iceAdditionalHostAddresses?: string[];
+    /**
+     * The audio and video codecs accepted, as MIME types in the order of preference (see `PeerConnection`).
+     * @default ['audio/opus', 'audio/PCMU', 'video/VP8', 'video/H264', 'video/VP9']
+     */
+    codecs?: string[];
+}
+/**
+ * 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']
+ * }))
+ * ```
+ */
+export declare class WHIP extends Component {
+    #private;
+    /**
+     * Who may publish which stream.
+     */
+    protected readonly authorize?: WHIPAuthorize;
+    /**
+     * The name of the TURN server component.
+     */
+    protected readonly turn?: string;
+    /**
+     * The name of the media server component.
+     */
+    protected readonly sfu?: string;
+    /**
+     * The room of the media server of a stream.
+     */
+    protected readonly roomOf?: WHIPRoomOf;
+    /**
+     * The name of the cluster component.
+     */
+    protected readonly cluster?: string;
+    /**
+     * The secret of the TURN servers of the cluster.
+     */
+    protected readonly turnSecret?: string;
+    /**
+     * How the TURN servers of the cluster are chosen.
+     */
+    protected readonly selectTURN?: TURNSelector;
+    /**
+     * The other ICE servers.
+     */
+    protected readonly iceServers: SignalingIceServer[];
+    /**
+     * The sessions at once at most.
+     */
+    protected readonly maxSessions: number;
+    /**
+     * The origins the browsers may publish from.
+     */
+    protected readonly allowOrigin: string;
+    /**
+     * The UDP ports of the candidates.
+     */
+    protected readonly icePortRange?: [number, number];
+    /**
+     * More addresses given as candidates.
+     */
+    protected readonly iceAdditionalHostAddresses?: string[];
+    /**
+     * The audio and video codecs.
+     */
+    protected readonly codecs?: string[];
+    /**
+     * Join the cluster: end the sessions of this node asked by the others.
+     * @protected
+     */
+    protected init(): Promise<void>;
+    /**
+     * End the sessions.
+     * @protected
+     */
+    protected destroy(): Promise<void>;
+    /**
+     * The sessions of this node.
+     */
+    get sessions(): WHIPSession[];
+    /**
+     * The origins the browsers may publish from.
+     */
+    get allowedOrigin(): string;
+    /**
+     * 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: string): WHIPSession | undefined;
+    /**
+     * 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)
+     * ```
+     */
+    publish(stream: string, offer: SignalingDescription, options?: {
+        token?: string;
+        context?: HTTPContext;
+    }): Promise<{
+        session: WHIPSession;
+        answer: SignalingDescription;
+    }>;
+    /**
+     * 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
+     */
+    protected publishToSFU(stream: string, offer: SignalingDescription, options: {
+        token?: string;
+        context?: HTTPContext;
+    }): Promise<{
+        session: WHIPSession;
+        answer: SignalingDescription;
+    }>;
+    /**
+     * 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)))
+     * ```
+     */
+    unpublish(id: string, stream?: string): Promise<boolean>;
+    /**
+     * 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
+     */
+    protected end(id: string, stream?: string): boolean;
+    /**
+     * 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: string): string | undefined;
+    /**
+     * 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: '*'})
+     * ```
+     */
+    patch(id: string, fragment: string, options?: {
+        stream?: string;
+        ifMatch?: string;
+    }): Promise<{
+        fragment?: string;
+        tag: string;
+        stale?: boolean;
+    }>;
+    /**
+     * 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')
+     * ```
+     */
+    iceServersOf(stream: string): Promise<SignalingIceServer[]>;
+}
+/**
+ * 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 declare function buildWHIPOptions(options?: WHIPOptions): ComponentOptions<WHIPOptions>;