@lakutata/webrtc 0.0.0-stage → 3.1.4

package/dist/cjs/whep/WHEPController.js

@@ -0,0 +1,301 @@
+"use strict";
+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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WHEPController = void 0;
+const core_1 = require("@lakutata/core");
+const dto_1 = require("@lakutata/core/decorator/dto");
+const entrypoint_1 = require("@lakutata/entrypoint");
+const ctrl_1 = require("@lakutata/entrypoint/decorator/ctrl");
+const Endpoints_js_1 = require("../peer/Endpoints.js");
+const WHEPDeniedException_js_1 = require("../exceptions/WHEPDeniedException.js");
+const WHEPMediaTypeException_js_1 = require("../exceptions/WHEPMediaTypeException.js");
+const WHEPSessionNotFoundException_js_1 = require("../exceptions/WHEPSessionNotFoundException.js");
+/**
+ * The input of the requests to the endpoint of a stream
+ */
+class StreamDTO extends core_1.DTO {
+}
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.String().min(1).max(256).required()),
+    __metadata("design:type", String)
+], StreamDTO.prototype, "stream", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.String().optional()),
+    __metadata("design:type", String)
+], StreamDTO.prototype, "body", void 0);
+/**
+ * The input of a PATCH of a session
+ */
+class PatchDTO extends core_1.DTO {
+}
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.String().min(1).max(256).required()),
+    __metadata("design:type", String)
+], PatchDTO.prototype, "stream", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.String().min(1).max(64).required()),
+    __metadata("design:type", String)
+], PatchDTO.prototype, "session", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.String().optional()),
+    __metadata("design:type", String)
+], PatchDTO.prototype, "body", void 0);
+/**
+ * The input of the requests to a session
+ */
+class SessionDTO extends core_1.DTO {
+}
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.String().min(1).max(256).required()),
+    __metadata("design:type", String)
+], SessionDTO.prototype, "stream", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.String().min(1).max(64).required()),
+    __metadata("design:type", String)
+], SessionDTO.prototype, "session", void 0);
+/**
+ * The HTTP interface of WHEP for the {@link WHEP} component registered as `whep`: a player plays a stream with
+ * `POST /whep/:stream` (its SDP offer, receiving only, as `application/sdp`; its bearer token in the `Authorization`
+ * header), gets the answer with the URL of its session (`201 Created`, `Location`), and ends it with `DELETE` on that
+ * URL. It answers the CORS preflights (`OPTIONS`) of the browsers, `GET` with no content, and `PATCH` of a session
+ * (`application/trickle-ice-sdpfrag`): the candidates of the viewer (trickle ICE), or an ICE restart, whose answer has
+ * a new `ETag`. The URL of a session is the capability to end it: its id is random, and the DELETE and the PATCH are
+ * not authorized again.
+ *
+ * Add it to the controllers of an entrypoint whose HTTP adapter reads the bodies of WHEP as text (its option
+ * `body: {text: ['application/sdp', 'application/trickle-ice-sdpfrag']}`, without which Fastify refuses the PATCH
+ * requests with 415). Its routes are under `/whep`; a subclass with `@Prefix({route: …})` gives them another prefix.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildEntrypoints} from 'lakutata/com/entrypoint'
+ * import {Prefix} from 'lakutata/decorator/ctrl'
+ * import {expressHTTPEntrypoint} from 'lakutata/adapter/express'
+ * import {buildSFUOptions, buildSignalingOptions, buildWHEPOptions, WHEPController} from '@lakutata/webrtc'
+ *
+ * //The endpoints under /watch: POST /watch/:stream
+ * @Prefix({route: '/watch'})
+ * class WatchController extends WHEPController {
+ * }
+ *
+ * Application.run(() => ({
+ *     id: 'live.app',
+ *     name: 'Live',
+ *     components: {
+ *         signaling: buildSignalingOptions(),
+ *         sfu: buildSFUOptions(),
+ *         whep: buildWHEPOptions(),
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [WatchController],
+ *             http: expressHTTPEntrypoint({port: 8080, body: {text: ['application/sdp', 'application/trickle-ice-sdpfrag']}})
+ *         })
+ *     },
+ *     bootstrap: ['sfu', 'entrypoint']
+ * }))
+ * ```
+ */
+let WHEPController = class WHEPController extends entrypoint_1.Controller {
+    /**
+     * The WHEP component: the one registered as `whep`.
+     * @protected
+     */
+    async whep() {
+        return await this.getObject('whep');
+    }
+    /**
+     * The HTTP context of the request
+     * @protected
+     */
+    http() {
+        return this.context;
+    }
+    /**
+     * Set the CORS headers of the response
+     * @protected
+     */
+    async allowOrigin() {
+        const whep = await this.whep();
+        this.http().response.setHeader('Access-Control-Allow-Origin', whep.allowedOrigin);
+        this.http().response.setHeader('Access-Control-Expose-Headers', 'Location, Link, ETag');
+    }
+    /**
+     * Answer the CORS preflight of the endpoint of a stream.
+     * @returns Resolves once answered.
+     */
+    async preflight() {
+        await this.allowOrigin();
+        this.http().response.writeHead(204, {
+            'Access-Control-Allow-Methods': 'OPTIONS, GET, POST',
+            'Access-Control-Allow-Headers': 'Authorization, Content-Type',
+            'Access-Control-Max-Age': '86400',
+            'Accept-Post': 'application/sdp'
+        }).end();
+    }
+    /**
+     * Answer the CORS preflight of a session.
+     * @returns Resolves once answered.
+     */
+    async sessionPreflight() {
+        await this.allowOrigin();
+        this.http().response.writeHead(204, {
+            'Access-Control-Allow-Methods': 'OPTIONS, GET, DELETE, PATCH',
+            'Access-Control-Allow-Headers': 'Authorization, Content-Type, If-Match',
+            'Access-Control-Max-Age': '86400'
+        }).end();
+    }
+    /**
+     * Answer a GET of the endpoint of a stream with no content, as for WHIP (RFC 9725, section 4.1).
+     * @returns Resolves once answered.
+     */
+    async probe() {
+        await this.allowOrigin();
+        this.http().response.writeHead(204).end();
+    }
+    /**
+     * Answer a GET of a session with no content, as for WHIP (RFC 9725, section 4.1).
+     * @returns Resolves once answered.
+     */
+    async sessionProbe() {
+        await this.allowOrigin();
+        this.http().response.writeHead(204).end();
+    }
+    /**
+     * Play a stream: answer the offer with `201 Created`, the answer, the URL of the session (`Location`) and the ICE
+     * servers (`Link`).
+     * @param input The stream, and the offer (the body).
+     * @returns Resolves once answered.
+     * @throws {WHEPMediaTypeException} When the body is not `application/sdp`.
+     * @throws {WHEPDeniedException} When `authorize` refuses the stream (with `WWW-Authenticate: Bearer`).
+     * @throws {WHEPLimitException} When the component has `maxSessions` sessions already.
+     * @throws {WHEPOfferException} When the offer cannot be answered.
+     */
+    async play(input) {
+        await this.allowOrigin();
+        const { request, response } = this.http();
+        if ((request.headers['content-type'] ?? '').split(';')[0].trim().toLowerCase() !== 'application/sdp' || input.body === undefined) {
+            throw new WHEPMediaTypeException_js_1.WHEPMediaTypeException('The offer is not application/sdp');
+        }
+        const whep = await this.whep();
+        let played;
+        try {
+            played = await whep.play(input.stream, { type: 'offer', sdp: input.body }, { token: (0, Endpoints_js_1.bearerOf)(request), context: this.http() });
+        }
+        catch (error) {
+            if (error instanceof WHEPDeniedException_js_1.WHEPDeniedException)
+                response.setHeader('WWW-Authenticate', 'Bearer');
+            throw error;
+        }
+        const links = (0, Endpoints_js_1.linksOf)(await whep.iceServersOf(input.stream));
+        const answer = Buffer.from(played.answer.sdp ?? '');
+        //Its length given: the players read the body to its end
+        response.writeHead(201, {
+            'Content-Type': 'application/sdp',
+            'Content-Length': answer.length,
+            'Location': `${(0, Endpoints_js_1.pathOf)(request)}/${played.session.id}`,
+            'ETag': `"${whep.entityTagOf(played.session.id)}"`,
+            ...links.length ? { Link: links } : {}
+        }).end(answer);
+    }
+    /**
+     * End a session.
+     * @param input The stream and the session.
+     * @returns Resolves once answered.
+     * @throws {WHEPSessionNotFoundException} When the stream has no such session.
+     */
+    async stop(input) {
+        await this.allowOrigin();
+        const whep = await this.whep();
+        //Ended on the node of the cluster holding it
+        if (!(await whep.stop(input.session, input.stream))) {
+            throw new WHEPSessionNotFoundException_js_1.WHEPSessionNotFoundException('The stream {stream} has no session {session}', { stream: input.stream, session: input.session });
+        }
+        this.http().response.writeHead(200, { 'Content-Length': 0 }).end();
+    }
+    /**
+     * Apply the candidates of the viewer (trickle ICE: `204 No Content`), or restart ICE when its credentials
+     * changed (`200 OK`, the fragment of the answer, and a new `ETag`), as RFC 9725 (section 4.3) does: an ICE restart
+     * needs `If-Match: *`. An `If-Match` other than `*` and the `ETag` of the session, and new credentials without
+     * `If-Match: *`, are answered with `412 Precondition Failed`.
+     * @param input The stream, the session, and the fragment of SDP (the body).
+     * @returns Resolves once answered.
+     * @throws {WHEPMediaTypeException} When the body is not `application/trickle-ice-sdpfrag`.
+     * @throws {WHEPSessionNotFoundException} When the stream has no such session on any node.
+     * @throws {WHEPOfferException} When the fragment has no ICE, or the connection refuses it.
+     */
+    async patch(input) {
+        await this.allowOrigin();
+        const { request, response } = this.http();
+        if ((request.headers['content-type'] ?? '').split(';')[0].trim().toLowerCase() !== 'application/trickle-ice-sdpfrag' || input.body === undefined) {
+            throw new WHEPMediaTypeException_js_1.WHEPMediaTypeException('The fragment is not application/trickle-ice-sdpfrag');
+        }
+        const whep = await this.whep();
+        //Any ICE session: *, quoted or not
+        const ifMatch = request.headers['if-match']?.trim().replace(/^"\*"$/, '*');
+        //On the node holding the session
+        const patched = await whep.patch(input.session, input.body, { stream: input.stream, ...ifMatch === undefined ? {} : { ifMatch: ifMatch } });
+        if (patched.stale)
+            return void response.writeHead(412, { 'Content-Length': 0 }).end();
+        if (patched.fragment === undefined)
+            return void response.writeHead(204).end();
+        const fragment = Buffer.from(patched.fragment);
+        response.writeHead(200, {
+            'Content-Type': 'application/trickle-ice-sdpfrag',
+            'Content-Length': fragment.length,
+            'ETag': `"${patched.tag}"`
+        }).end(fragment);
+    }
+};
+exports.WHEPController = WHEPController;
+__decorate([
+    (0, ctrl_1.OPTIONS)('/:stream', StreamDTO),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], WHEPController.prototype, "preflight", null);
+__decorate([
+    (0, ctrl_1.OPTIONS)('/:stream/:session', SessionDTO),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], WHEPController.prototype, "sessionPreflight", null);
+__decorate([
+    (0, ctrl_1.GET)('/:stream', StreamDTO),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], WHEPController.prototype, "probe", null);
+__decorate([
+    (0, ctrl_1.GET)('/:stream/:session', SessionDTO),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], WHEPController.prototype, "sessionProbe", null);
+__decorate([
+    (0, ctrl_1.POST)('/:stream', StreamDTO),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [StreamDTO]),
+    __metadata("design:returntype", Promise)
+], WHEPController.prototype, "play", null);
+__decorate([
+    (0, ctrl_1.DELETE)('/:stream/:session', SessionDTO),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [SessionDTO]),
+    __metadata("design:returntype", Promise)
+], WHEPController.prototype, "stop", null);
+__decorate([
+    (0, ctrl_1.PATCH)('/:stream/:session', PatchDTO),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [PatchDTO]),
+    __metadata("design:returntype", Promise)
+], WHEPController.prototype, "patch", null);
+exports.WHEPController = WHEPController = __decorate([
+    (0, ctrl_1.Prefix)({ route: '/whep' })
+], WHEPController);