@lakutata/webrtc 0.0.0-stage → 3.1.4

package/dist/cjs/whep/WHEP.d.ts

@@ -0,0 +1,386 @@
+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 { SFUTrack } from '../sfu/SFU.js';
+/**
+ * Who plays a stream: the stream of the URL, and the bearer token of the request.
+ */
+export interface WHEPViewer {
+    /**
+     * The stream: the last segment of the URL of the endpoint (`/whep/:stream`).
+     */
+    readonly stream: string;
+    /**
+     * The bearer token of the `Authorization` header, if any.
+     */
+    readonly token?: string;
+}
+/**
+ * Decides whether a viewer may play a stream (the `authorize` option of {@link WHEP}).
+ * @param viewer The stream and the bearer token.
+ * @param context The context of the HTTP request, when it comes through `WHEPController`.
+ * @returns Whether it may play.
+ */
+export type WHEPAuthorize = (viewer: WHEPViewer, context?: HTTPContext) => boolean | Promise<boolean>;
+/**
+ * Gives the room of the media server a stream played comes from (the `roomOf` option of {@link WHEP}).
+ * @param viewer The stream and the bearer token.
+ * @param context The context of the HTTP request, when it comes through `WHEPController`.
+ * @returns The room.
+ */
+export type WHEPRoomOf = (viewer: WHEPViewer, context?: HTTPContext) => string | Promise<string>;
+/**
+ * Chooses the member of the room a viewer receives (the `select` option of {@link WHEP}), each time the tracks
+ * published in the room change.
+ * @param viewer The stream and the bearer token.
+ * @param tracks The tracks published in the room, with their members.
+ * @returns The id of the member; none for the default one (the newest stream published with WHIP, else the first
+ * member publishing).
+ */
+export type WHEPSelect = (viewer: WHEPViewer, tracks: SFUTrack[]) => string | undefined;
+/**
+ * A stream being played: its WHEP session.
+ */
+export interface WHEPSession {
+    /**
+     * The id of the session: the last segment of its URL (`/whep/:stream/:session`), random so that it cannot be
+     * guessed.
+     */
+    readonly id: string;
+    /**
+     * The stream.
+     */
+    readonly stream: string;
+    /**
+     * The room of the media server the stream comes from.
+     */
+    readonly room: string;
+    /**
+     * The id of the viewer at the media server (`whep:` and a random id of its own), as its events name it
+     * (`unsupported`).
+     */
+    readonly viewerId: string;
+    /**
+     * The id of the member of the room the viewer receives now; none while no member publishes.
+     */
+    readonly source?: string;
+}
+/**
+ * The options of a {@link WHEP} (see {@link buildWHEPOptions}).
+ */
+export interface WHEPOptions {
+    /**
+     * The name of the {@link SFU} component whose rooms the viewers play.
+     * @default 'sfu'
+     */
+    sfu?: string;
+    /**
+     * Gives the room of the media server a stream comes from.
+     * @default the stream
+     */
+    roomOf?: WHEPRoomOf;
+    /**
+     * Chooses the member of the room a viewer receives. When it throws, the viewer receives the default one, and the
+     * error goes to the debug messages (`webrtc/whep`, see `setDebugHandler`).
+     * @default the newest stream published with WHIP, else the first member publishing
+     */
+    select?: WHEPSelect;
+    /**
+     * Decides whether a viewer may play a stream; anyone may play any stream without it.
+     * @default none
+     */
+    authorize?: WHEPAuthorize;
+    /**
+     * 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 viewers 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 viewers get
+     * TURN servers of the cluster, chosen by `selectTURN`, after the ones of `turn`.
+     * @default none
+     */
+    turnSecret?: string;
+    /**
+     * Chooses the TURN servers of the cluster given to a viewer.
+     * @default the two least loaded that are not full
+     */
+    selectTURN?: TURNSelector;
+    /**
+     * More ICE servers given to the viewers, 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 play from (the `Access-Control-Allow-Origin` header).
+     * @default '*'
+     */
+    allowOrigin?: string;
+}
+/**
+ * The playback of WHEP: players (browsers, media players) play a stream with an HTTP POST of their offer, and receive
+ * the audio and the video of a member of a room of the media server ({@link SFU}): by default the stream published with
+ * WHIP into the room (the stream is the room unless `roomOf` says otherwise), else the first member publishing;
+ * `select` chooses another one. A viewer is not a member of the room: its connection goes to the server, which sends it
+ * the tracks of the member, from a key frame, and the ones of the next member when that one stops publishing. Its
+ * connection negotiates every codec it offers that the server has, so a stream published after it starts playing, with
+ * any of them, is sent too. The component emits `play` (the session) once it answers, and `stop` (the session) when it
+ * ends: the viewer deleted it, its connection failed or closed, or the application stopped.
+ *
+ * Register it as `whep` with {@link buildWHEPOptions} next to the media server, and add `WHEPController` to the
+ * controllers of the entrypoint, with an HTTP adapter reading the bodies of WHEP 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 viewer (trickle ICE), or restarts ICE, as for WHIP.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildEntrypoints} from 'lakutata/com/entrypoint'
+ * import {expressHTTPEntrypoint} from 'lakutata/adapter/express'
+ * import {buildSFUOptions, buildSignalingOptions, buildWHEPOptions, buildWHIPOptions, WHEPController, WHIPController} from '@lakutata/webrtc'
+ *
+ * //OBS publishes to https://live.example.com/whip/concert, the browsers play https://live.example.com/whep/concert
+ * Application.run(() => ({
+ *     id: 'live.app',
+ *     name: 'Live',
+ *     components: {
+ *         signaling: buildSignalingOptions(),
+ *         sfu: buildSFUOptions({iceAdditionalHostAddresses: ['203.0.113.10'], icePortRange: [40000, 40999]}),
+ *         whip: buildWHIPOptions({sfu: 'sfu', authorize: ({token}): boolean => token === process.env.WHIP_TOKEN}),
+ *         whep: buildWHEPOptions({maxSessions: 500}),
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [WHIPController, WHEPController],
+ *             http: expressHTTPEntrypoint({port: 8080, body: {text: ['application/sdp', 'application/trickle-ice-sdpfrag']}})
+ *         })
+ *     },
+ *     bootstrap: ['sfu', 'entrypoint']
+ * }))
+ * ```
+ */
+export declare class WHEP extends Component {
+    #private;
+    /**
+     * The name of the media server component.
+     */
+    protected readonly sfu: string;
+    /**
+     * The room of a stream.
+     */
+    protected readonly roomOf?: WHEPRoomOf;
+    /**
+     * The member a viewer receives.
+     */
+    protected readonly select?: WHEPSelect;
+    /**
+     * Who may play which stream.
+     */
+    protected readonly authorize?: WHEPAuthorize;
+    /**
+     * The name of the cluster component.
+     */
+    protected readonly cluster?: string;
+    /**
+     * The name of the TURN server component.
+     */
+    protected readonly turn?: 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 play from.
+     */
+    protected readonly allowOrigin: 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(): WHEPSession[];
+    /**
+     * The origins the browsers may play 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 {WHEP, WHEPSession} from '@lakutata/webrtc'
+     *
+     * declare const whep: WHEP
+     * const session: WHEPSession | undefined = whep.session('0b7d…')
+     * ```
+     */
+    session(id: string): WHEPSession | undefined;
+    /**
+     * Play a stream: answer the offer of its viewer, with all the candidates of the connection. `WHEPController` calls
+     * it for the POST requests.
+     * @param stream The stream.
+     * @param offer The SDP offer of the viewer.
+     * @param options The bearer token of the viewer, and the context of its request (for `authorize` and `roomOf`).
+     * @returns The session, and the answer.
+     * @throws {WHEPDeniedException} When `authorize` refuses the stream.
+     * @throws {WHEPLimitException} When there are `maxSessions` sessions already.
+     * @throws {WHEPOfferException} When the offer has no audio or video, the media server does not serve the room of
+     * the stream, or the connection refuses the offer.
+     * @example
+     * ```typescript
+     * import type {SignalingDescription, WHEP, WHEPSession} from '@lakutata/webrtc'
+     *
+     * declare const whep: WHEP
+     * declare const offer: SignalingDescription
+     * const {session, answer}: {session: WHEPSession, answer: SignalingDescription} = await whep.play('concert', offer)
+     * ```
+     */
+    play(stream: string, offer: SignalingDescription, options?: {
+        token?: string;
+        context?: HTTPContext;
+    }): Promise<{
+        session: WHEPSession;
+        answer: SignalingDescription;
+    }>;
+    /**
+     * End a session: close its connection, and emit `stop` (on the node holding it). `WHEPController` 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 {WHEP, WHEPSession} from '@lakutata/webrtc'
+     *
+     * declare const whep: WHEP
+     * //Stop the viewers of a stream on this node
+     * await Promise.all(whep.sessions.filter((session: WHEPSession): boolean => session.stream === 'concert').map((session: WHEPSession): Promise<boolean> => whep.stop(session.id)))
+     * ```
+     */
+    stop(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 {WHEP} from '@lakutata/webrtc'
+     *
+     * declare const whep: WHEP
+     * const tag: string | undefined = whep.entityTagOf('0b7d…')
+     * ```
+     */
+    entityTagOf(id: string): string | undefined;
+    /**
+     * Apply a PATCH of a session (as RFC 9725, section 4.3 does for WHIP), on the node holding it: the candidates of
+     * its viewer (trickle ICE), or an ICE restart when its credentials changed, which needs `If-Match: *`.
+     * `WHEPController` 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 {WHEPSessionNotFoundException} When no node has a session of this id, or the session is not of this
+     * stream.
+     * @throws {WHEPOfferException} When the fragment has no ICE, or the connection refuses it.
+     * @example
+     * ```typescript
+     * import type {WHEP} from '@lakutata/webrtc'
+     *
+     * declare const whep: WHEP
+     * declare const fragment: string
+     * //An ICE restart
+     * const {fragment: answer, tag} = await whep.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 viewer, with new TURN credentials.
+     * @param stream The stream (the user of the TURN credentials).
+     * @returns The ICE servers.
+     * @example
+     * ```typescript
+     * import type {SignalingIceServer, WHEP} from '@lakutata/webrtc'
+     *
+     * declare const whep: WHEP
+     * const iceServers: SignalingIceServer[] = await whep.iceServersOf('concert')
+     * ```
+     */
+    iceServersOf(stream: string): Promise<SignalingIceServer[]>;
+}
+/**
+ * Build the options of a {@link WHEP} component, for the `components` of an application (named `whep`, the name
+ * `WHEPController` uses).
+ * @param options The media server, the rooms and the members played, who may play, the ICE servers given to the
+ * viewers, the limit of sessions (all optional).
+ * @returns The component options.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildSFUOptions, buildSignalingOptions, buildWHEPOptions} from '@lakutata/webrtc'
+ *
+ * Application.run(() => ({
+ *     id: 'live.app',
+ *     name: 'Live',
+ *     components: {
+ *         signaling: buildSignalingOptions(),
+ *         sfu: buildSFUOptions(),
+ *         //The viewers of /whep/stage-2 watch the room stage, its member host
+ *         whep: buildWHEPOptions({
+ *             roomOf: ({stream}): string => stream.split('-')[0],
+ *             select: (_viewer, tracks): string | undefined => tracks.find((track): boolean => track.peerId === 'host')?.peerId
+ *         })
+ *     },
+ *     bootstrap: ['sfu']
+ * }))
+ * ```
+ */
+export declare function buildWHEPOptions(options?: WHEPOptions): ComponentOptions<WHEPOptions>;