nixamp 0.16.0 → 0.17.0

package/dist/compression/routes.js

@@ -0,0 +1,266 @@
+/**
+ * The HTTP face of the compression service.
+ *
+ * Under a channel: its policy (read, and change with the version you
+ * saw), an analysis of it (a job), and its relay -- out to another nixamp
+ * that asks in the envelope's media type, or in from one. Under
+ * /api/compression: the server-wide switch and the jobs. All of it is
+ * translation; the rules live in the service. The server's own helpers
+ * for answering (JSON, counting a stream) are handed in, so this file
+ * imports nothing from the server and the server one thing from it.
+ */
+import { createReadStream } from "node:fs";
+import { MEDIA_TYPE, parseModes } from "./envelope.js";
+import { CODECS_HEADER, KIND_HEADER } from "./receiver.js";
+/** Who a diagnostic job belongs to. Every control holder shares them. */
+const CONTROL = "control";
+/** The header a conditional change names the version in, or the body's own field. */
+function expectedVersion(request, body) {
+    const header = request.headers["if-match"];
+    const raw = typeof header === "string" ? header.replace(/^W\//, "").replace(/"/g, "") : body["version"];
+    const version = Number(raw);
+    return raw === undefined || raw === "" || !Number.isInteger(version) ? undefined : version;
+}
+async function parsed(request, ctx) {
+    try {
+        const text = await ctx.readBody(request);
+        const body = text === "" ? {} : JSON.parse(text);
+        return typeof body === "object" && body !== null && !Array.isArray(body) ? body : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Routes under /api/channels/:id/. True when the request was answered.
+ * `action` and `file` are the path segments after the id.
+ */
+export async function handleChannelCompression(request, response, ctx, id, action, file) {
+    const { service, json } = ctx;
+    if (action === "compression") {
+        if (file === undefined && request.method === "GET") {
+            json(response, 200, service.status(id));
+            return true;
+        }
+        if (file === undefined && request.method === "PATCH") {
+            if (!(await ctx.controls())) {
+                json(response, 403, { error: "the controls are needed to change a policy" });
+                return true;
+            }
+            const body = await parsed(request, ctx);
+            if (body === null) {
+                json(response, 400, { error: "send a JSON object" });
+                return true;
+            }
+            const { version: _version, ...change } = body;
+            const result = service.set(id, change, expectedVersion(request, body));
+            if (!result.ok) {
+                json(response, result.status, { error: result.errors.join("; "), errors: result.errors, status: service.status(id) });
+                return true;
+            }
+            json(response, 200, service.status(id));
+            return true;
+        }
+        if (file === "analyses" && request.method === "POST") {
+            if (!(await ctx.controls())) {
+                json(response, 403, { error: "the controls are needed to start an analysis" });
+                return true;
+            }
+            const body = await parsed(request, ctx);
+            const seconds = Number(body?.["seconds"] ?? 30);
+            const started = service.analyzeChannel(id, Number.isFinite(seconds) ? seconds : 30, CONTROL);
+            if ("error" in started) {
+                json(response, started.status, { error: started.error });
+                return true;
+            }
+            json(response, started.existing ? 200 : 202, { job: started.job, existing: started.existing });
+            return true;
+        }
+        json(response, 405, { error: "GET or PATCH the policy; POST to analyses" });
+        return true;
+    }
+    if (action === "relay" && file === undefined) {
+        if (request.method === "GET") {
+            const accept = String(request.headers["accept"] ?? "");
+            if (!accept.includes(MEDIA_TYPE)) {
+                json(response, 406, {
+                    error: `this is a relay for another nixamp, sent as ${MEDIA_TYPE}; a player wants the ordinary channel URL`,
+                    playback: `/api/channels/${id}`,
+                });
+                return true;
+            }
+            if (request.headers["range"] !== undefined) {
+                json(response, 416, { error: "a relay is a live stream and cannot be asked for a range" });
+                return true;
+            }
+            const offered = parseModes(String(request.headers[CODECS_HEADER] ?? ""));
+            const listener = {
+                write: (chunk) => response.write(chunk),
+                end: () => {
+                    response.end();
+                },
+                pending: () => response.writableLength,
+            };
+            const answer = service.relay(id, listener, offered);
+            if (!answer.ok) {
+                json(response, answer.status, { error: answer.error, code: answer.code, playback: `/api/channels/${id}` });
+                return true;
+            }
+            ctx.watch(request, response, id);
+            response.writeHead(200, {
+                ...ctx.cors,
+                "content-type": `${MEDIA_TYPE}; version=1`,
+                "cache-control": "no-store",
+                // Never squeezed again by anything in the way: it is already framed.
+                "content-encoding": "identity",
+                [CODECS_HEADER]: answer.codecs.join(","),
+                [KIND_HEADER]: answer.kind,
+                "x-nixamp-generation": String(answer.generation),
+            });
+            const leave = () => answer.session.leave();
+            request.on("close", leave);
+            response.on("close", leave);
+            return true;
+        }
+        if (request.method === "POST") {
+            if (!(await ctx.controls())) {
+                json(response, 403, { error: "the controls are needed to bring a relay in" });
+                return true;
+            }
+            const body = await parsed(request, ctx);
+            const from = typeof body?.["from"] === "string" ? body["from"] : "";
+            if (from === "") {
+                json(response, 400, { error: "say where from: { from: \"https://host:port/api/channels/<id>/relay\" }" });
+                return true;
+            }
+            const key = typeof body?.["key"] === "string" ? body["key"] : null;
+            const name = typeof body?.["name"] === "string" ? body["name"] : id;
+            const started = service.pull(id, from, key, name);
+            if (!started.ok) {
+                json(response, started.status, { error: started.error });
+                return true;
+            }
+            json(response, 202, { ok: true, channel: id, from });
+            return true;
+        }
+        if (request.method === "DELETE") {
+            if (!(await ctx.controls())) {
+                json(response, 403, { error: "the controls are needed to stop a relay" });
+                return true;
+            }
+            const stopped = service.stopPull(id);
+            json(response, stopped ? 200 : 404, { ok: stopped });
+            return true;
+        }
+        json(response, 405, { error: "GET to receive, POST to bring one in, DELETE to stop it" });
+        return true;
+    }
+    return false;
+}
+/** Routes under /api/compression. True when the request was answered. */
+export async function handleCompressionApi(request, response, ctx, path) {
+    const { service, json } = ctx;
+    if (path === "/api/compression") {
+        if (request.method === "GET") {
+            json(response, 200, service.overview());
+            return true;
+        }
+        if (request.method === "PATCH") {
+            if (!(await ctx.controls())) {
+                json(response, 403, { error: "the controls are needed to change the server's compression" });
+                return true;
+            }
+            const body = await parsed(request, ctx);
+            if (body === null) {
+                json(response, 400, { error: "send a JSON object" });
+                return true;
+            }
+            const change = {};
+            if ("enabled" in body) {
+                if (typeof body["enabled"] !== "boolean") {
+                    json(response, 400, { error: "enabled must be true or false" });
+                    return true;
+                }
+                change.enabled = body["enabled"];
+            }
+            if ("hlsPackaging" in body) {
+                if (body["hlsPackaging"] !== "mpegts" && body["hlsPackaging"] !== "fmp4") {
+                    json(response, 400, { error: "hlsPackaging must be mpegts or fmp4" });
+                    return true;
+                }
+                change.hlsPackaging = body["hlsPackaging"];
+            }
+            json(response, 200, { global: service.setGlobal(change) });
+            return true;
+        }
+        json(response, 405, { error: "GET or PATCH" });
+        return true;
+    }
+    const job = /^\/api\/compression\/analyses\/([a-z0-9]+)$/.exec(path);
+    if (job) {
+        if (!(await ctx.controls())) {
+            json(response, 403, { error: "the controls are needed to see an analysis" });
+            return true;
+        }
+        const jobId = job[1];
+        if (request.method === "GET") {
+            const found = service.jobs.get(jobId, CONTROL);
+            if (!found) {
+                json(response, 404, { error: "no such analysis" });
+                return true;
+            }
+            json(response, 200, { job: found });
+            return true;
+        }
+        if (request.method === "DELETE") {
+            const cancelled = service.jobs.cancel(jobId, CONTROL);
+            json(response, cancelled ? 200 : 404, { ok: cancelled });
+            return true;
+        }
+        json(response, 405, { error: "GET or DELETE" });
+        return true;
+    }
+    return false;
+}
+/**
+ * The static representation of a library file, at /api/media/N/relay.
+ * The caller has already resolved N to a path and checked that media may
+ * be streamed at all.
+ */
+export function handleStaticRelay(request, response, ctx, file, title) {
+    const { service, json } = ctx;
+    const accept = String(request.headers["accept"] ?? "");
+    if (!accept.includes(MEDIA_TYPE)) {
+        json(response, 406, { error: `this is the file's relay representation, sent as ${MEDIA_TYPE}; a player wants the ordinary media URL` });
+        return;
+    }
+    if (request.headers["range"] !== undefined) {
+        json(response, 416, { error: "the relay representation cannot be asked for a range; the ordinary media URL can" });
+        return;
+    }
+    const state = service.representation(file);
+    if (state.state === "off") {
+        json(response, 409, { error: "compression is off for static files on this server", code: "COMPRESSION_OFF" });
+        return;
+    }
+    if (state.state === "failed") {
+        json(response, 503, { error: state.reason });
+        return;
+    }
+    if (state.state === "building") {
+        response.writeHead(202, { ...ctx.cors, "content-type": "application/json; charset=utf-8", "retry-after": "5" });
+        response.end(JSON.stringify({ building: true }));
+        return;
+    }
+    ctx.watch(request, response, title);
+    response.writeHead(200, {
+        ...ctx.cors,
+        "content-type": `${MEDIA_TYPE}; version=1`,
+        "content-length": String(state.entry.bytes),
+        "content-encoding": "identity",
+        "cache-control": "no-store",
+        "x-nixamp-sha256": state.entry.sha256,
+        "x-nixamp-original-length": String(state.entry.size),
+    });
+    createReadStream(state.path).pipe(response);
+}

package/dist/compression/service.d.ts

@@ -0,0 +1,162 @@
+import { type Channels } from "../channels.ts";
+import { type Analysis } from "./analyze.ts";
+import { Pool } from "./codec.ts";
+import { type Mode } from "./envelope.ts";
+import { AnalysisJobs, type Job } from "./jobs.ts";
+import { type ChannelMetricsSnapshot } from "./metrics.ts";
+import { type ChannelPolicy, type LosslessPolicy } from "./policy.ts";
+import { type RelayListener, type RelaySession } from "./relay.ts";
+import { type GlobalSettings, PolicyStore } from "./store.ts";
+import { StaticCache } from "./static.ts";
+/** The pseudo-channel whose policy governs static file representations. */
+export declare const STATIC_CHANNEL = "static";
+export interface AnalyzeFileOptions {
+    policy?: LosslessPolicy;
+    ffprobe?: string[];
+    signal?: AbortSignal;
+}
+/**
+ * A file's first bytes, up to the sample limit, analysed at the source
+ * boundary: these are the bytes as they sit on disk, before any ffmpeg.
+ * Shared by the service and the CLI, which runs it with no server at all.
+ */
+export declare function analyzeFile(path: string, options?: AnalyzeFileOptions): Promise<Analysis>;
+export interface CompressionServiceOptions {
+    channels: Channels;
+    /** Where settings live; null for a server that remembers nothing. */
+    stateDir: string | null;
+    port: number;
+    pool?: Pool;
+    ffprobe?: string[];
+    /** Where static representations go; null to keep none. */
+    cacheDir?: string | null;
+    maxCacheBytes?: number;
+    onEvent?: (message: string) => void;
+}
+export interface EffectivePolicy {
+    /** The policy as it applies right now, after the global switch. */
+    losslessCompression: LosslessPolicy;
+    hlsPackaging: ChannelPolicy["hlsPackaging"];
+    qualityProfile: ChannelPolicy["qualityProfile"];
+    /** Why it differs from what is configured, when it does. */
+    reason: string | null;
+}
+export interface ChannelStatus {
+    channel: string;
+    live: boolean;
+    configured: ChannelPolicy;
+    effective: EffectivePolicy;
+    global: GlobalSettings;
+    metrics: ChannelMetricsSnapshot | null;
+    relay: {
+        sessions: number;
+        generation: number;
+    } | null;
+    /** An incoming relay this channel is fed by, when it is. */
+    incoming: {
+        from: string;
+        generation: number;
+        reconnects: number;
+        error: string | null;
+    } | null;
+}
+export type RelayAnswer = {
+    ok: true;
+    session: RelaySession;
+    codecs: Mode[];
+    generation: number;
+    kind: "audio" | "video" | "";
+} | {
+    ok: false;
+    status: 404 | 406 | 409 | 503;
+    code: string;
+    error: string;
+};
+export declare class CompressionService {
+    private readonly options;
+    readonly store: PolicyStore;
+    readonly jobs: AnalysisJobs;
+    readonly pool: Pool;
+    readonly statics: StaticCache | null;
+    private readonly running;
+    private readonly metrics;
+    private readonly incoming;
+    private generation;
+    constructor(options: CompressionServiceOptions);
+    private get channels();
+    /** What applies to a channel right now, and why that is not what is configured, if it is not. */
+    effective(id: string): EffectivePolicy;
+    /** For the HLS packager: how to wrap this channel. */
+    packagingOf(id: string): ChannelPolicy["hlsPackaging"];
+    status(id: string): ChannelStatus;
+    /** The whole server at a glance. */
+    overview(): {
+        global: GlobalSettings;
+        pool: Pool["stats"];
+        jobs: AnalysisJobs["counts"];
+        channels: ChannelStatus[];
+        cache: {
+            bytes: number;
+            entries: number;
+        } | null;
+    };
+    /** Change a channel's policy. A live relay under a different variant is ended; receivers reconnect. */
+    set(id: string, change: unknown, expectVersion?: number): ReturnType<PolicyStore["set"]>;
+    setGlobal(change: Partial<GlobalSettings>): GlobalSettings;
+    /** The kill switch, and its opposite. */
+    private applyPolicy;
+    /**
+     * A receiver asking for a channel. Everything that can go wrong is
+     * answered before a byte of stream: no such channel, compression off,
+     * a boundary this server cannot provide, a receiver that cannot decode
+     * anything worth sending.
+     */
+    relay(id: string, listener: RelayListener, offered: Set<Mode>): RelayAnswer;
+    private startEncoder;
+    /** Start listening to another nixamp's channel as one of ours. */
+    pull(id: string, from: string, key: string | null, name: string): {
+        ok: true;
+    } | {
+        ok: false;
+        status: 409 | 400;
+        error: string;
+    };
+    /** Stop an incoming relay, and the channel it feeds. */
+    stopPull(id: string): boolean;
+    /**
+     * Analyse a live channel: up to `seconds` of it, or the byte limit,
+     * whichever comes first, as a job. The listener is one more on the
+     * channel; the channel is not touched.
+     */
+    analyzeChannel(id: string, seconds: number, owner: string): {
+        job: Job;
+        existing: boolean;
+    } | {
+        error: string;
+        status: 404 | 429;
+    };
+    private sampleChannel;
+    /** Analyse a file on this machine: its first bytes, up to the sample limit. */
+    analyzeFile(path: string, signal?: AbortSignal): Promise<Analysis>;
+    /**
+     * The static representation of a file. Ready when it is on disk and
+     * still describes the file; building when this call started it (or
+     * found it being built); failed when the last build said why; off when
+     * this server keeps no cache or the static policy is off. Never a wait:
+     * a film takes minutes to read, and a request is not held for that.
+     */
+    representation(file: string): {
+        state: "off";
+    } | {
+        state: "building";
+    } | {
+        state: "failed";
+        reason: string;
+    } | {
+        state: "ready";
+        path: string;
+        entry: NonNullable<ReturnType<StaticCache["lookup"]>>["entry"];
+    };
+    private readonly failed;
+    stopAll(): void;
+}