nixamp 0.16.0 → 0.17.0

package/dist/compression/cli.js

@@ -0,0 +1,347 @@
+/**
+ * `nixamp compression` -- measure it, see it, set it, bring a relay in.
+ *
+ *   nixamp compression analyze ./sample.ts [--seconds 30] [--format json]
+ *   nixamp compression analyze --channel main [--seconds 30]
+ *   nixamp compression status [--channel main]
+ *   nixamp compression set --channel main --mode auto [--level 1] [--ts-aware on]
+ *   nixamp compression set --channel main --hls fmp4
+ *   nixamp compression off | on
+ *   nixamp compression pull --channel cnn --from https://host:4321/api/channels/cnn/relay --from-key KEY
+ *   nixamp compression fetch URL --out FILE [--key KEY]
+ *
+ * A file is analysed here, with no server. Everything else talks to a
+ * running server over the same routes a browser would: the local daemon
+ * by default, or --url and --key for another machine, exactly as
+ * `nixamp admin` finds its target. JSON goes to stdout and only JSON;
+ * progress and complaints go to stderr; a failure is a nonzero exit.
+ */
+import { createWriteStream } from "node:fs";
+import { resolveTarget } from "../admin.js";
+import { detectTools } from "../audio.js";
+import { KEY_HEADER } from "../share.js";
+import { RelayError } from "./envelope.js";
+import { receiveRelay, RelayRefused } from "./receiver.js";
+import { analyzeFile } from "./service.js";
+const USAGE = `nixamp compression — lossless relay compression: measure it, see it, set it.
+
+  nixamp compression analyze FILE [--seconds N] [--format json|text]
+  nixamp compression analyze --channel ID [--seconds N]
+  nixamp compression status [--channel ID]
+  nixamp compression set --channel ID [--mode off|auto|zstd] [--level 1-19]
+                         [--boundary channel|source] [--ts-aware on|off] [--hls mpegts|fmp4]
+  nixamp compression off | on          the whole server's switch
+  nixamp compression pull --channel ID --from URL [--from-key KEY] [--name NAME]
+  nixamp compression fetch URL --out FILE [--key KEY]
+
+  --url U --key K  a server other than the local daemon, as for \`nixamp admin\`
+  --format json    JSON on stdout (the default when stdout is not a terminal)
+`;
+function parse(argv) {
+    const positional = [];
+    const named = new Map();
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg.startsWith("--")) {
+            const eq = arg.indexOf("=");
+            if (eq !== -1)
+                named.set(arg.slice(2, eq), arg.slice(eq + 1));
+            else if (i + 1 < argv.length && !argv[i + 1].startsWith("--"))
+                named.set(arg.slice(2), argv[(i += 1)]);
+            else
+                named.set(arg.slice(2), "true");
+        }
+        else {
+            positional.push(arg);
+        }
+    }
+    return { positional, named };
+}
+function wantsJson(flags) {
+    const format = flags.named.get("format");
+    if (format === "json")
+        return true;
+    if (format === "text")
+        return false;
+    return !process.stdout.isTTY;
+}
+/** Talk to the server the way a browser does, key in the header. */
+async function call(flags, method, path, body) {
+    const target = resolveTarget([
+        ...(flags.named.has("url") ? ["--url", flags.named.get("url")] : []),
+        ...(flags.named.has("key") ? ["--key", flags.named.get("key")] : []),
+    ]);
+    const headers = { accept: "application/json" };
+    if (target.key)
+        headers[KEY_HEADER] = target.key;
+    if (body !== undefined)
+        headers["content-type"] = "application/json";
+    const response = await fetch(`${target.url}${path}`, { method, headers, ...(body !== undefined ? { body: JSON.stringify(body) } : {}) });
+    let parsedBody = {};
+    try {
+        parsedBody = (await response.json());
+    }
+    catch {
+        parsedBody = { error: `${response.status} ${response.statusText}` };
+    }
+    return { status: response.status, body: parsedBody };
+}
+function kb(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KiB`;
+    return `${(bytes / 1024 / 1024).toFixed(2)} MiB`;
+}
+function describeAnalysis(a) {
+    const lines = [
+        `  ${a.source.kind} ${a.source.name}`,
+        `  boundary ${a.boundary}; sample ${kb(a.sampleBytes)}${a.truncated ? " (truncated)" : ""}${a.sampleMs ? ` over ${(a.sampleMs / 1000).toFixed(1)}s` : ""}; container ${a.container}`,
+    ];
+    if (a.codecs)
+        lines.push(`  ffprobe: ${a.codecs.container} video=${a.codecs.video || "-"} audio=${a.codecs.audio || "-"}${a.codecs.duration ? ` ${a.codecs.duration.toFixed(0)}s` : ""}`);
+    if (a.observedKbps)
+        lines.push(`  observed ${a.observedKbps} kbps`);
+    if (a.ts) {
+        lines.push(`  transport stream: ${a.ts.packetSize}-byte packets, ${a.ts.packets} packets, ${(a.ts.nullShare * 100).toFixed(1)}% null, ${a.ts.pids.length} PIDs${a.ts.pcrBitrateKbps ? `, PCR says ${a.ts.pcrBitrateKbps} kbps` : ""}${a.ts.scrambled ? `, ${a.ts.scrambled} scrambled` : ""}`);
+    }
+    lines.push("  mode      level  wire bytes     saving   enc ms  dec ms  round trip");
+    for (const row of a.bench) {
+        lines.push(`  ${row.mode.padEnd(9)} ${String(row.level).padStart(5)}  ${String(row.wireBytes).padStart(10)}  ${(row.savingsPercent >= 0 ? "+" : "") + row.savingsPercent.toFixed(2).padStart(6)}%  ${row.encodeMs.toFixed(1).padStart(6)}  ${row.decodeMs.toFixed(1).padStart(6)}  ${row.roundTrip ? "ok" : "FAILED"}${row.note ? `  (${row.note})` : ""}`);
+    }
+    lines.push(`  recommendation: ${a.recommendation.mode}${a.recommendation.level ? ` level ${a.recommendation.level}` : ""} — ${a.recommendation.reason}`);
+    lines.push(`  ${a.tools.runtime}, zstd ${a.tools.zstd}, sha256 ${a.sha256.slice(0, 16)}…, ${a.at}`);
+    return lines.join("\n");
+}
+function describeStatus(s) {
+    const c = s.configured.losslessCompression;
+    const e = s.effective.losslessCompression;
+    const lines = [
+        `  ${s.channel}${s.live ? "" : " (not on the air)"}`,
+        `  lossless: configured ${c.mode} at ${c.boundary}, level ${c.zstdLevel}${c.tsAware ? ", ts-aware" : ""}; effective ${e.mode}${s.effective.reason ? ` — ${s.effective.reason}` : ""}`,
+        `  hls packaging: ${s.effective.hlsPackaging}; quality: ${s.effective.qualityProfile}; policy version ${s.configured.version}`,
+        `  server switch: ${s.global.enabled ? "on" : "OFF"}`,
+    ];
+    if (s.relay)
+        lines.push(`  relaying to ${s.relay.sessions} receiver${s.relay.sessions === 1 ? "" : "s"}, generation ${s.relay.generation}`);
+    if (s.incoming)
+        lines.push(`  fed by ${s.incoming.from} (generation ${s.incoming.generation}, ${s.incoming.reconnects} redials${s.incoming.error ? `, last: ${s.incoming.error}` : ""})`);
+    const m = s.metrics;
+    if (m && m.blocks > 0) {
+        const saved = m.inputBytes - m.representationBytes;
+        lines.push(`  this generation: in ${kb(m.inputBytes)}, representation ${kb(m.representationBytes)} (${saved >= 0 ? "-" : "+"}${((Math.abs(saved) * 100) / Math.max(1, m.inputBytes)).toFixed(1)}%), wire ${kb(m.wireBytes)} across listeners`, `  blocks ${m.blocks}: ${m.compressedBlocks} ${m.activeMode === "stored" ? "compressed" : m.activeMode}, ${m.storedBlocks} stored${m.bypassed ? " (bypassed)" : ""}; latency p50 ${m.latencyMs.p50.toFixed(1)}ms p95 ${m.latencyMs.p95.toFixed(1)}ms; queue ${kb(m.queueBytes)}`);
+        if (m.fallbackReason)
+            lines.push(`  reason: ${m.fallbackReason}`);
+    }
+    return lines.join("\n");
+}
+async function analyze(flags) {
+    const json = wantsJson(flags);
+    const channel = flags.named.get("channel");
+    const seconds = Number(flags.named.get("seconds") ?? 30);
+    if (!channel) {
+        const file = flags.positional[1];
+        if (!file) {
+            console.error(USAGE);
+            return 2;
+        }
+        console.error(`  Reading ${file}…`);
+        const tools = detectTools();
+        const result = await analyzeFile(file, { ffprobe: tools.ffprobe });
+        console.log(json ? JSON.stringify(result, null, 2) : describeAnalysis(result));
+        return 0;
+    }
+    const started = await call(flags, "POST", `/api/channels/${encodeURIComponent(channel)}/compression/analyses`, { seconds });
+    if (started.status !== 202 && started.status !== 200) {
+        console.error(`nixamp: ${started.body["error"] ?? started.status}`);
+        return 1;
+    }
+    let job = started.body["job"];
+    console.error(`  Analysis ${job.id} ${started.body["existing"] ? "already running" : "started"}: up to ${seconds}s of "${channel}"…`);
+    while (job.status === "queued" || job.status === "running") {
+        await new Promise((done) => setTimeout(done, 1000));
+        const poll = await call(flags, "GET", `/api/compression/analyses/${job.id}`);
+        if (poll.status !== 200) {
+            console.error(`nixamp: ${poll.body["error"] ?? poll.status}`);
+            return 1;
+        }
+        job = poll.body["job"];
+        if (job.status === "running")
+            process.stderr.write(`\r  ${kb(job.progress.bytes)} in ${(job.progress.ms / 1000).toFixed(0)}s`);
+    }
+    process.stderr.write("\n");
+    if (job.status !== "done" || !job.result) {
+        console.error(`nixamp: analysis ${job.status}${job.error ? `: ${job.error}` : ""}`);
+        return 1;
+    }
+    console.log(json ? JSON.stringify(job.result, null, 2) : describeAnalysis(job.result));
+    return 0;
+}
+async function status(flags) {
+    const json = wantsJson(flags);
+    const channel = flags.named.get("channel");
+    const got = await call(flags, "GET", channel ? `/api/channels/${encodeURIComponent(channel)}/compression` : "/api/compression");
+    if (got.status !== 200) {
+        console.error(`nixamp: ${got.body["error"] ?? got.status}`);
+        return 1;
+    }
+    if (json) {
+        console.log(JSON.stringify(got.body, null, 2));
+        return 0;
+    }
+    if (channel) {
+        console.log(describeStatus(got.body));
+        return 0;
+    }
+    const overview = got.body;
+    console.log(`  server switch ${overview.global.enabled ? "on" : "OFF"}; hls ${overview.global.hlsPackaging}; pool running ${overview.pool["running"]} queued ${overview.pool["queued"]}${overview.cache ? `; cache ${kb(overview.cache.bytes)} in ${overview.cache.entries} files` : ""}`);
+    for (const one of overview.channels)
+        console.log(describeStatus(one));
+    if (overview.channels.length === 0)
+        console.log("  no channels with a policy or on the air");
+    return 0;
+}
+async function set(flags) {
+    const channel = flags.named.get("channel");
+    if (!channel) {
+        console.error("nixamp: say which channel: --channel ID");
+        return 2;
+    }
+    const lossless = {};
+    const change = {};
+    const mode = flags.named.get("mode");
+    if (mode)
+        lossless["mode"] = mode;
+    const boundary = flags.named.get("boundary");
+    if (boundary)
+        lossless["boundary"] = boundary;
+    const level = flags.named.get("level");
+    if (level)
+        lossless["zstdLevel"] = Number(level);
+    const ts = flags.named.get("ts-aware");
+    if (ts)
+        lossless["tsAware"] = ts === "on" || ts === "true";
+    for (const [flag, key] of [["min-savings-percent", "minSavingsPercent"], ["min-savings-bytes", "minSavingsBytes"], ["max-block-bytes", "maxBlockBytes"], ["max-hold-ms", "maxHoldMs"]]) {
+        const value = flags.named.get(flag);
+        if (value)
+            lossless[key] = Number(value);
+    }
+    if (Object.keys(lossless).length > 0)
+        change["losslessCompression"] = lossless;
+    const hls = flags.named.get("hls");
+    if (hls)
+        change["hlsPackaging"] = hls;
+    if (Object.keys(change).length === 0) {
+        console.error("nixamp: nothing to set; see `nixamp compression --help`");
+        return 2;
+    }
+    const expect = flags.named.get("expect-version");
+    const result = await call(flags, "PATCH", `/api/channels/${encodeURIComponent(channel)}/compression`, expect ? { ...change, version: Number(expect) } : change);
+    if (result.status !== 200) {
+        console.error(`nixamp: ${result.body["error"] ?? result.status}`);
+        return 1;
+    }
+    console.log(wantsJson(flags) ? JSON.stringify(result.body, null, 2) : describeStatus(result.body));
+    return 0;
+}
+async function toggle(flags, enabled) {
+    const result = await call(flags, "PATCH", "/api/compression", { enabled });
+    if (result.status !== 200) {
+        console.error(`nixamp: ${result.body["error"] ?? result.status}`);
+        return 1;
+    }
+    console.log(wantsJson(flags) ? JSON.stringify(result.body, null, 2) : `  compression is ${enabled ? "on: channels follow their own policies" : "OFF for the whole server: no new relay starts, and running ones end"}`);
+    return 0;
+}
+async function pull(flags) {
+    const channel = flags.named.get("channel");
+    const from = flags.named.get("from");
+    if (!channel || !from) {
+        console.error("nixamp: say which channel and where from: --channel ID --from URL");
+        return 2;
+    }
+    const result = await call(flags, "POST", `/api/channels/${encodeURIComponent(channel)}/relay`, {
+        from,
+        ...(flags.named.has("from-key") ? { key: flags.named.get("from-key") } : {}),
+        ...(flags.named.has("name") ? { name: flags.named.get("name") } : {}),
+    });
+    if (result.status !== 202) {
+        console.error(`nixamp: ${result.body["error"] ?? result.status}`);
+        return 1;
+    }
+    console.log(wantsJson(flags) ? JSON.stringify(result.body, null, 2) : `  "${channel}" is being brought in from ${from}; \`nixamp compression status --channel ${channel}\` says how it is going`);
+    return 0;
+}
+/** Receive one relay (or a static representation) into a file, checking every frame. */
+async function fetchRelay(flags) {
+    const url = flags.positional[1];
+    const out = flags.named.get("out");
+    if (!url || !out) {
+        console.error("nixamp: fetch URL --out FILE");
+        return 2;
+    }
+    const file = createWriteStream(out);
+    let bytes = 0;
+    const began = Date.now();
+    try {
+        const result = await receiveRelay({
+            url,
+            key: flags.named.get("key") ?? null,
+            onStart: ({ codecs, kind }) => console.error(`  Receiving${kind ? ` ${kind}` : ""} with ${codecs || "stored"}…`),
+            onBytes: (chunk) => new Promise((done) => {
+                bytes += chunk.length;
+                if (bytes % (1024 * 1024) < chunk.length)
+                    process.stderr.write(`\r  ${kb(bytes)}`);
+                if (file.write(chunk))
+                    done();
+                else
+                    file.once("drain", done);
+            }),
+        });
+        await new Promise((done) => file.end(done));
+        process.stderr.write("\n");
+        console.log(JSON.stringify({ ok: true, out, bytes: result.bytes, frames: result.frames, generation: result.generation, ms: Date.now() - began }));
+        return 0;
+    }
+    catch (error) {
+        file.destroy();
+        process.stderr.write("\n");
+        if (error instanceof RelayError)
+            console.error(`nixamp: the stream broke a rule: ${error.code}: ${error.message}`);
+        else if (error instanceof RelayRefused)
+            console.error(`nixamp: refused (${error.status}): ${error.message}`);
+        else
+            console.error(`nixamp: ${error.message}`);
+        return 1;
+    }
+}
+export async function compression(argv) {
+    const flags = parse(argv);
+    const verb = flags.positional[0];
+    try {
+        switch (verb) {
+            case "analyze":
+            case "analyse":
+                return await analyze(flags);
+            case "status":
+                return await status(flags);
+            case "set":
+                return await set(flags);
+            case "off":
+                return await toggle(flags, false);
+            case "on":
+                return await toggle(flags, true);
+            case "pull":
+                return await pull(flags);
+            case "fetch":
+                return await fetchRelay(flags);
+            default:
+                console.error(USAGE);
+                return verb === undefined || verb === "help" || flags.named.has("help") ? 0 : 2;
+        }
+    }
+    catch (error) {
+        console.error(`nixamp: ${error.message}`);
+        return 1;
+    }
+}

package/dist/compression/codec.d.ts

@@ -0,0 +1,66 @@
+import { type Mode } from "./envelope.ts";
+export declare const MIN_ZSTD_LEVEL = 1;
+export declare const MAX_ZSTD_LEVEL = 19;
+/** Encode `bytes` in `mode`. Stored is the identity, so it never goes through the pool. */
+export declare function encode(mode: Mode, bytes: Buffer, level?: number): Promise<Buffer>;
+/**
+ * Decode a payload back to its original bytes. `maxOutputLength` is the
+ * decoded size the frame header promised; a payload that wants to be bigger
+ * than that is refused before it can be.
+ */
+export declare function decode(mode: Mode, bytes: Buffer, maxOutputLength: number): Promise<Buffer>;
+/** What did the work, for a benchmark that has to be reproducible. */
+export declare function toolVersions(): {
+    runtime: string;
+    zstd: string;
+    zlib: string;
+};
+export interface PoolOptions {
+    /** How many jobs may be in flight at once. */
+    concurrency?: number;
+    /** How many may wait their turn before a new one is refused. */
+    maxQueued?: number;
+    /** How long one job may take before it is abandoned. */
+    timeoutMs?: number;
+}
+export interface PoolStats {
+    running: number;
+    queued: number;
+    completed: number;
+    refused: number;
+    timedOut: number;
+    failed: number;
+}
+/** Thrown for a job the pool would not take, or would not wait for. */
+export declare class PoolError extends Error {
+    readonly code: "BUSY" | "TIMEOUT" | "CANCELLED";
+    constructor(code: "BUSY" | "TIMEOUT" | "CANCELLED", message: string);
+}
+/**
+ * A bounded queue in front of the codecs.
+ *
+ * The codecs themselves already run on other threads; what would hurt is a
+ * thousand blocks queued behind a slow one, each holding a quarter of a
+ * megabyte. So there is a ceiling on the queue, and a job past the deadline
+ * is dropped by whoever asked for it -- the thread finishes and its result
+ * is thrown away, which for a block of at most a quarter of a megabyte is a
+ * few milliseconds wasted, not a leak.
+ */
+export declare class Pool {
+    private readonly concurrency;
+    private readonly maxQueued;
+    private readonly timeoutMs;
+    private running;
+    private readonly waiting;
+    private readonly counts;
+    constructor(options?: PoolOptions);
+    get stats(): PoolStats;
+    run<T>(job: () => Promise<T>, options?: {
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<T>;
+    /** Take a slot now, or wait for one to be handed over by `release`. */
+    private acquire;
+    /** Give the slot to the next in line, or back to the pool if nobody is waiting. */
+    private release;
+}

package/dist/compression/codec.js

@@ -0,0 +1,178 @@
+/**
+ * The codecs, and the pool that keeps them off the event loop.
+ *
+ * Zstandard and gzip come from node:zlib, which both Node 24 and Bun ship
+ * with libzstd built in: no native module to build, nothing to pin beyond
+ * the runtime the package already requires. The asynchronous calls run on
+ * the runtime's own thread pool, so a block being squeezed never holds a
+ * request. What this file adds is the discipline around them: a ceiling on
+ * how many run at once, a queue that refuses rather than grows, a deadline
+ * on every job, and a limit on how big a decode may get before it is called
+ * a bomb.
+ */
+import { constants, gunzip, gzip, zstdCompress, zstdDecompress } from "node:zlib";
+import { RelayError } from "./envelope.js";
+import { tsJoin, tsSplit } from "./ts-transform.js";
+export const MIN_ZSTD_LEVEL = 1;
+export const MAX_ZSTD_LEVEL = 19;
+/** Encode `bytes` in `mode`. Stored is the identity, so it never goes through the pool. */
+export function encode(mode, bytes, level = 1) {
+    switch (mode) {
+        case "stored":
+            return Promise.resolve(bytes);
+        case "zstd":
+            return zstd(bytes, level);
+        case "gzip":
+            return new Promise((resolve, reject) => gzip(bytes, { level: Math.min(9, Math.max(1, level)) }, (error, out) => (error ? reject(error) : resolve(out))));
+        case "ts-zstd": {
+            const split = tsSplit(bytes);
+            if (split === null)
+                return Promise.reject(new RelayError("BAD_MODE", "not a transport stream: ts-zstd does not apply"));
+            return zstd(split, level);
+        }
+    }
+}
+/**
+ * Decode a payload back to its original bytes. `maxOutputLength` is the
+ * decoded size the frame header promised; a payload that wants to be bigger
+ * than that is refused before it can be.
+ */
+export async function decode(mode, bytes, maxOutputLength) {
+    switch (mode) {
+        case "stored":
+            return bytes;
+        case "zstd":
+            return unzstd(bytes, maxOutputLength);
+        case "gzip":
+            return new Promise((resolve, reject) => gunzip(bytes, { maxOutputLength }, (error, out) => (error ? reject(bomb(error)) : resolve(out))));
+        case "ts-zstd": {
+            // The split form is a few bytes longer than the original, never shorter.
+            const split = await unzstd(bytes, maxOutputLength + 64);
+            const joined = tsJoin(split);
+            if (joined === null)
+                throw new RelayError("DECODE_FAILED", "ts-zstd payload did not join back into packets");
+            return joined;
+        }
+    }
+}
+function zstd(bytes, level) {
+    const params = { [constants.ZSTD_c_compressionLevel]: Math.min(MAX_ZSTD_LEVEL, Math.max(MIN_ZSTD_LEVEL, level)) };
+    return new Promise((resolve, reject) => zstdCompress(bytes, { params }, (error, out) => (error ? reject(error) : resolve(out))));
+}
+function unzstd(bytes, maxOutputLength) {
+    return new Promise((resolve, reject) => zstdDecompress(bytes, { maxOutputLength }, (error, out) => (error ? reject(bomb(error)) : resolve(out))));
+}
+/** A decode that failed is a decode that failed; a decode that grew past its limit is named as such. */
+function bomb(error) {
+    if (error.code === "ERR_BUFFER_TOO_LARGE")
+        return new RelayError("FRAME_TOO_LARGE", "payload decodes to more than its frame promised");
+    return new RelayError("DECODE_FAILED", error.message);
+}
+/** What did the work, for a benchmark that has to be reproducible. */
+export function toolVersions() {
+    const versions = process.versions;
+    return {
+        runtime: versions["bun"] ? `bun ${versions["bun"]}` : `node ${process.version}`,
+        zstd: versions["zstd"] ?? "bundled",
+        zlib: versions["zlib"] ?? "bundled",
+    };
+}
+/** Thrown for a job the pool would not take, or would not wait for. */
+export class PoolError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "PoolError";
+    }
+}
+/**
+ * A bounded queue in front of the codecs.
+ *
+ * The codecs themselves already run on other threads; what would hurt is a
+ * thousand blocks queued behind a slow one, each holding a quarter of a
+ * megabyte. So there is a ceiling on the queue, and a job past the deadline
+ * is dropped by whoever asked for it -- the thread finishes and its result
+ * is thrown away, which for a block of at most a quarter of a megabyte is a
+ * few milliseconds wasted, not a leak.
+ */
+export class Pool {
+    concurrency;
+    maxQueued;
+    timeoutMs;
+    running = 0;
+    waiting = [];
+    counts = { completed: 0, refused: 0, timedOut: 0, failed: 0 };
+    constructor(options = {}) {
+        this.concurrency = Math.max(1, options.concurrency ?? 4);
+        this.maxQueued = Math.max(0, options.maxQueued ?? 64);
+        this.timeoutMs = Math.max(1, options.timeoutMs ?? 2000);
+    }
+    get stats() {
+        return { running: this.running, queued: this.waiting.length, ...this.counts };
+    }
+    async run(job, options = {}) {
+        if (options.signal?.aborted)
+            throw new PoolError("CANCELLED", "cancelled before it started");
+        await this.acquire(options.signal);
+        const deadline = options.timeoutMs ?? this.timeoutMs;
+        let timer = null;
+        let onAbort = null;
+        try {
+            const result = await Promise.race([
+                job(),
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new PoolError("TIMEOUT", `took longer than ${deadline}ms`)), deadline);
+                    timer.unref?.();
+                    if (options.signal) {
+                        onAbort = () => reject(new PoolError("CANCELLED", "cancelled"));
+                        options.signal.addEventListener("abort", onAbort, { once: true });
+                    }
+                }),
+            ]);
+            this.counts.completed += 1;
+            return result;
+        }
+        catch (error) {
+            if (error instanceof PoolError && error.code === "TIMEOUT")
+                this.counts.timedOut += 1;
+            else if (!(error instanceof PoolError))
+                this.counts.failed += 1;
+            throw error;
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+            if (onAbort && options.signal)
+                options.signal.removeEventListener("abort", onAbort);
+            this.release();
+        }
+    }
+    /** Take a slot now, or wait for one to be handed over by `release`. */
+    async acquire(signal) {
+        if (this.running < this.concurrency) {
+            this.running += 1;
+            return;
+        }
+        if (this.waiting.length >= this.maxQueued) {
+            this.counts.refused += 1;
+            throw new PoolError("BUSY", "the codec pool is full");
+        }
+        await new Promise((next) => this.waiting.push(next));
+        // Woken: the finishing job passed its slot to us without touching the
+        // count. If we no longer want it, pass it on the same way.
+        if (signal?.aborted) {
+            this.release();
+            throw new PoolError("CANCELLED", "cancelled while queued");
+        }
+    }
+    /** Give the slot to the next in line, or back to the pool if nobody is waiting. */
+    release() {
+        const next = this.waiting.shift();
+        if (next) {
+            next();
+            return;
+        }
+        this.running -= 1;
+    }
+}

package/dist/compression/envelope.d.ts

@@ -0,0 +1,77 @@
+export declare const MAGIC = "NXS1";
+export declare const ENVELOPE_VERSION = 1;
+export declare const MEDIA_TYPE = "application/vnd.nixamp.stream";
+export declare const STREAM_HEADER_BYTES = 16;
+export declare const FRAME_HEADER_BYTES = 48;
+/** Where the bytes were captured: before ffmpeg, or after the channel pipeline. */
+export type Boundary = "source" | "channel";
+/** How one block's payload was encoded. `stored` is the bytes as they were. */
+export type Mode = "stored" | "zstd" | "gzip" | "ts-zstd";
+export declare const MODE_CODE: Record<Mode, number>;
+export declare const MODES: readonly Mode[];
+export declare const FRAME_DATA = 1;
+export declare const FRAME_END = 2;
+/** The decoded size one frame may claim, unless negotiated otherwise. */
+export declare const DEFAULT_MAX_FRAME_BYTES: number;
+/** The most a stream header may negotiate, whatever it asks for. */
+export declare const CEILING_FRAME_BYTES: number;
+/**
+ * How much bigger than its original an encoded payload may be. A codec that
+ * cannot beat stored is stored, so anything past a small fixed allowance is
+ * either a bug or an attack.
+ */
+export declare const EXPANSION_ALLOWANCE = 1024;
+export interface StreamHeader {
+    version: number;
+    boundary: Boundary;
+    /** Which run of the source this is; changes on every restart. */
+    generation: number;
+    /** The decoded-size limit every frame in this stream honours. */
+    maxFrameBytes: number;
+}
+export interface FrameHeader {
+    type: typeof FRAME_DATA | typeof FRAME_END;
+    mode: Mode;
+    seq: number;
+    originalLength: number;
+    encodedLength: number;
+    /** Of the original bytes for a data frame; of the whole generation for the end. */
+    sha256: Buffer;
+}
+export type RelayErrorCode = "BAD_MAGIC" | "BAD_VERSION" | "BAD_BOUNDARY" | "BAD_LIMIT" | "BAD_FRAME_TYPE" | "BAD_MODE" | "UNSUPPORTED_MODE" | "BAD_SEQUENCE" | "FRAME_TOO_LARGE" | "EXPANSION_BUDGET" | "CHECKSUM_MISMATCH" | "LENGTH_MISMATCH" | "DECODE_FAILED" | "AFTER_END" | "TRUNCATED";
+/** A stream that broke one of the rules, and which rule. Never silently. */
+export declare class RelayError extends Error {
+    readonly code: RelayErrorCode;
+    constructor(code: RelayErrorCode, message: string);
+}
+export declare function sha256(bytes: Uint8Array): Buffer;
+export declare function encodeStreamHeader(header: StreamHeader): Buffer;
+/** Read a stream header from the front of `bytes`. Throws on anything off. */
+export declare function decodeStreamHeader(bytes: Buffer): StreamHeader;
+export declare function encodeFrameHeader(header: FrameHeader): Buffer;
+/** A data frame: header then payload, as one buffer. */
+export declare function encodeDataFrame(seq: number, mode: Mode, original: Buffer, encoded: Buffer): Buffer;
+/** Just the header of a data frame, for a payload that is shared between listeners. */
+export declare function dataFrameHeader(seq: number, mode: Mode, original: Buffer, encodedLength: number, digest?: Buffer): Buffer;
+/**
+ * The end marker: no payload, the generation's total original byte count in
+ * the two length fields (high word, low word) and the SHA-256 of every
+ * original byte in order. A stream that stops without one was cut off.
+ */
+export declare function encodeEndFrame(seq: number, totalOriginalBytes: number, digest: Buffer): Buffer;
+/** The total an end frame carries, from its two halves. */
+export declare function endFrameTotal(header: FrameHeader): number;
+export interface FrameLimits {
+    maxFrameBytes: number;
+    /** Modes this decoder can undo. A frame in any other mode is refused. */
+    modes: ReadonlySet<Mode>;
+    /** The sequence number expected next. */
+    expectSeq: number;
+}
+/**
+ * Read a frame header, checking every field against the limits before the
+ * caller allocates anything for the payload.
+ */
+export declare function decodeFrameHeader(bytes: Buffer, limits: FrameLimits): FrameHeader;
+/** The codec names a peer lists in a negotiation header, kept to the ones we know. */
+export declare function parseModes(header: string | undefined | null): Set<Mode>;