nixamp 0.16.0 → 0.17.0

package/dist/compression/policy.js

@@ -0,0 +1,148 @@
+/**
+ * What an operator can set, and what a block has to achieve to be sent
+ * compressed.
+ *
+ * Three settings that must never be confused: whether to squeeze the bytes
+ * losslessly, how to package HLS, and whether to re-encode the picture.
+ * Turning one on never turns another on. The first is the only one this
+ * module measures; the other two are carried here so that one document
+ * describes a channel, and so that the API can refuse a change that mixes
+ * them up.
+ */
+import { DEFAULT_MAX_FRAME_BYTES, CEILING_FRAME_BYTES, FRAME_HEADER_BYTES } from "./envelope.js";
+import { MAX_ZSTD_LEVEL, MIN_ZSTD_LEVEL } from "./codec.js";
+export const DEFAULT_LOSSLESS = {
+    mode: "off",
+    boundary: "channel",
+    zstdLevel: 1,
+    minSavingsPercent: 3,
+    minSavingsBytes: 512,
+    maxBlockBytes: DEFAULT_MAX_FRAME_BYTES,
+    maxHoldMs: 100,
+    resampleAfterMs: 60_000,
+    maxChannelQueueBytes: 8 * 1024 * 1024,
+    maxListenerQueueBytes: 1024 * 1024,
+    tsAware: false,
+};
+export const DEFAULT_POLICY = {
+    losslessCompression: DEFAULT_LOSSLESS,
+    hlsPackaging: "mpegts",
+    qualityProfile: "source",
+    version: 0,
+};
+/** Fresh copies, so nobody edits the defaults in place. */
+export function defaultPolicy() {
+    return { ...DEFAULT_POLICY, losslessCompression: { ...DEFAULT_LOSSLESS } };
+}
+const RANGES = {
+    zstdLevel: [MIN_ZSTD_LEVEL, MAX_ZSTD_LEVEL],
+    minSavingsPercent: [0, 100],
+    minSavingsBytes: [0, CEILING_FRAME_BYTES],
+    maxBlockBytes: [1024, CEILING_FRAME_BYTES],
+    maxHoldMs: [1, 10_000],
+    resampleAfterMs: [1000, 24 * 3600 * 1000],
+    maxChannelQueueBytes: [64 * 1024, 1024 * 1024 * 1024],
+    maxListenerQueueBytes: [16 * 1024, 1024 * 1024 * 1024],
+};
+/**
+ * A change, applied over what is there, checked field by field.
+ *
+ * Unknown keys are errors rather than ignored: a typo that is silently
+ * dropped is a setting the operator believes is on and is not. The version
+ * is not settable here; the store bumps it when it accepts the result.
+ */
+export function normalizePolicy(input, base) {
+    const errors = [];
+    if (typeof input !== "object" || input === null || Array.isArray(input))
+        return { ok: false, errors: ["a policy is an object"] };
+    const change = input;
+    const policy = { ...base, losslessCompression: { ...base.losslessCompression } };
+    for (const key of Object.keys(change)) {
+        if (!["losslessCompression", "hlsPackaging", "qualityProfile", "version"].includes(key))
+            errors.push(`unknown setting: ${key}`);
+    }
+    if ("hlsPackaging" in change) {
+        const value = change["hlsPackaging"];
+        if (value === "mpegts" || value === "fmp4")
+            policy.hlsPackaging = value;
+        else
+            errors.push("hlsPackaging must be mpegts or fmp4");
+    }
+    if ("qualityProfile" in change) {
+        if (change["qualityProfile"] === "source")
+            policy.qualityProfile = "source";
+        else
+            errors.push("qualityProfile: only source is available; lower-bitrate profiles are a separate, explicit setting that this version does not ship");
+    }
+    if ("losslessCompression" in change) {
+        const lc = change["losslessCompression"];
+        if (typeof lc !== "object" || lc === null || Array.isArray(lc)) {
+            errors.push("losslessCompression is an object");
+        }
+        else {
+            const fields = lc;
+            for (const [key, value] of Object.entries(fields)) {
+                if (key === "mode") {
+                    if (value === "off" || value === "auto" || value === "zstd")
+                        policy.losslessCompression.mode = value;
+                    else
+                        errors.push("losslessCompression.mode must be off, auto or zstd");
+                }
+                else if (key === "boundary") {
+                    if (value === "channel" || value === "source")
+                        policy.losslessCompression.boundary = value;
+                    else
+                        errors.push("losslessCompression.boundary must be channel or source");
+                }
+                else if (key === "tsAware") {
+                    if (typeof value === "boolean")
+                        policy.losslessCompression.tsAware = value;
+                    else
+                        errors.push("losslessCompression.tsAware must be true or false");
+                }
+                else if (key in RANGES) {
+                    const [low, high] = RANGES[key];
+                    if (typeof value === "number" && Number.isInteger(value) && value >= low && value <= high) {
+                        policy.losslessCompression[key] = value;
+                    }
+                    else {
+                        errors.push(`losslessCompression.${key} must be an integer from ${low} to ${high}`);
+                    }
+                }
+                else {
+                    errors.push(`unknown setting: losslessCompression.${key}`);
+                }
+            }
+        }
+    }
+    if (policy.losslessCompression.minSavingsBytes >= policy.losslessCompression.maxBlockBytes) {
+        errors.push("losslessCompression.minSavingsBytes must be smaller than maxBlockBytes, or nothing can ever qualify");
+    }
+    return errors.length > 0 ? { ok: false, errors } : { ok: true, policy };
+}
+/**
+ * Whether a compressed block earns its place.
+ *
+ * Both representations carry the same frame header, so the comparison of
+ * complete representations reduces to the payloads: the saving is what the
+ * original would have cost stored, less what the encoding costs. Both
+ * thresholds must hold. A tiny block can meet the percentage and still not
+ * be worth the decode; a huge one can save half a kilobyte and still be
+ * nothing.
+ */
+export function eligible(originalLength, encodedLength, policy) {
+    if (originalLength <= 0)
+        return false;
+    const saved = originalLength - encodedLength;
+    if (saved < policy.minSavingsBytes)
+        return false;
+    return (saved * 100) / originalLength >= policy.minSavingsPercent;
+}
+/** What a block costs on the wire in each form, header included. */
+export function wireBytes(payloadLength) {
+    return FRAME_HEADER_BYTES + payloadLength;
+}
+/** Whether two policies would produce the same bytes for the same input. */
+export function variantOf(policy) {
+    return `${policy.mode}:${policy.boundary}:${policy.zstdLevel}:${policy.tsAware ? "ts" : "plain"}:${policy.maxBlockBytes}`;
+}

package/dist/compression/receiver.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The receiving end of a relay, as a client: ask another nixamp for a
+ * channel in the envelope, decode it, hand the original bytes on.
+ *
+ * The negotiation is two headers. `Accept` names the envelope's media type,
+ * which is how the server knows this is a receiver and not a browser that
+ * followed a link; `X-Nixamp-Stream-Codecs` lists what this decoder can
+ * undo, and the server compresses with nothing outside that list. A server
+ * that will not or cannot relay answers with JSON and an ordinary status,
+ * which is surfaced as an error naming the reason, never as a stream of
+ * something else.
+ */
+import { type Mode, type StreamHeader } from "./envelope.ts";
+export declare const CODECS_HEADER = "x-nixamp-stream-codecs";
+export declare const KIND_HEADER = "x-nixamp-kind";
+export declare const KEY_HEADER = "x-nixamp-key";
+export interface ReceiveOptions {
+    url: string;
+    key: string | null;
+    /** What this receiver can decode. Stored is always implied. */
+    modes?: Mode[];
+    maxFrameBytes?: number;
+    /** The server said yes: what it will compress with, and what the channel carries. Before any byte. */
+    onStart?: (accepted: {
+        codecs: string;
+        kind: "audio" | "video" | "";
+    }) => void;
+    /** The stream header arrived: the generation this is. */
+    onHeader?: (header: StreamHeader) => void;
+    onBytes: (bytes: Buffer) => void | Promise<void>;
+    signal?: AbortSignal;
+    /** Injected by tests. */
+    fetchImpl?: typeof fetch;
+}
+export interface ReceiveResult {
+    generation: number;
+    frames: number;
+    bytes: number;
+}
+/** The server said no. `status` is what it said it with. */
+export declare class RelayRefused extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/**
+ * Pull one generation of a relay to its clean end. Resolves when the end
+ * frame arrives; rejects with a RelayError for a stream that broke a rule
+ * or stopped short, and with RelayRefused for a server that would not
+ * start one.
+ */
+export declare function receiveRelay(options: ReceiveOptions): Promise<ReceiveResult>;

package/dist/compression/receiver.js

@@ -0,0 +1,92 @@
+/**
+ * The receiving end of a relay, as a client: ask another nixamp for a
+ * channel in the envelope, decode it, hand the original bytes on.
+ *
+ * The negotiation is two headers. `Accept` names the envelope's media type,
+ * which is how the server knows this is a receiver and not a browser that
+ * followed a link; `X-Nixamp-Stream-Codecs` lists what this decoder can
+ * undo, and the server compresses with nothing outside that list. A server
+ * that will not or cannot relay answers with JSON and an ordinary status,
+ * which is surfaced as an error naming the reason, never as a stream of
+ * something else.
+ */
+import { MEDIA_TYPE, RelayError } from "./envelope.js";
+import { RelayDecoder } from "./relay.js";
+export const CODECS_HEADER = "x-nixamp-stream-codecs";
+export const KIND_HEADER = "x-nixamp-kind";
+export const KEY_HEADER = "x-nixamp-key";
+/** The server said no. `status` is what it said it with. */
+export class RelayRefused extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = "RelayRefused";
+    }
+}
+/**
+ * Pull one generation of a relay to its clean end. Resolves when the end
+ * frame arrives; rejects with a RelayError for a stream that broke a rule
+ * or stopped short, and with RelayRefused for a server that would not
+ * start one.
+ */
+export async function receiveRelay(options) {
+    const modes = new Set(["stored", ...(options.modes ?? ["zstd", "ts-zstd"])]);
+    const headers = {
+        accept: MEDIA_TYPE,
+        [CODECS_HEADER]: [...modes].join(","),
+    };
+    if (options.key)
+        headers[KEY_HEADER] = options.key;
+    const send = options.fetchImpl ?? fetch;
+    const response = await send(options.url, { headers, ...(options.signal ? { signal: options.signal } : {}) });
+    const type = response.headers.get("content-type") ?? "";
+    if (response.status !== 200 || !type.startsWith(MEDIA_TYPE)) {
+        let reason = `${response.status}`;
+        try {
+            const body = (await response.json());
+            if (typeof body.error === "string")
+                reason = body.error;
+        }
+        catch {
+            // Not JSON; the status is the message.
+        }
+        throw new RelayRefused(response.status, reason);
+    }
+    if (!response.body)
+        throw new RelayRefused(response.status, "no body");
+    const kindSaid = response.headers.get(KIND_HEADER);
+    options.onStart?.({
+        codecs: response.headers.get(CODECS_HEADER) ?? "",
+        kind: kindSaid === "audio" || kindSaid === "video" ? kindSaid : "",
+    });
+    const decoder = new RelayDecoder({
+        modes,
+        ...(options.maxFrameBytes !== undefined ? { maxFrameBytes: options.maxFrameBytes } : {}),
+        onBytes: options.onBytes,
+    });
+    let told = false;
+    const reader = response.body.getReader();
+    try {
+        for (;;) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            await decoder.feed(Buffer.from(value));
+            if (!told && decoder.header) {
+                told = true;
+                options.onHeader?.(decoder.header);
+            }
+        }
+    }
+    catch (error) {
+        if (options.signal?.aborted)
+            throw new RelayError("TRUNCATED", "cancelled");
+        throw error;
+    }
+    finally {
+        reader.releaseLock();
+    }
+    await decoder.end();
+    return { generation: decoder.header?.generation ?? 0, frames: decoder.frames, bytes: decoder.bytes };
+}

package/dist/compression/relay.d.ts

@@ -0,0 +1,134 @@
+import { Pool } from "./codec.ts";
+import { type Boundary, type Mode, type StreamHeader } from "./envelope.ts";
+import type { ChannelMetrics, FallbackReason } from "./metrics.ts";
+import { type LosslessPolicy } from "./policy.ts";
+/** Somewhere frames go: a response, in practice. `pending` is how far behind it is. */
+export interface RelayListener {
+    write(chunk: Buffer): boolean;
+    end(): void;
+    pending?(): number;
+}
+export interface EncodedBlock {
+    /** Offset of this block's first byte since the encoder attached. */
+    start: number;
+    mode: Mode;
+    original: Buffer;
+    digest: Buffer;
+    payload: Buffer;
+}
+/** How many blocks in a row may fail to pay before `auto` stops trying, for a while. */
+export declare const GIVE_UP_AFTER = 8;
+export interface RelayEncoderOptions {
+    generation: number;
+    policy: LosslessPolicy;
+    pool: Pool;
+    metrics: ChannelMetrics;
+    boundary: Boundary;
+    /** The compressor fell too far behind, or the channel ended: this relay is over. */
+    onAbort: (reason: FallbackReason | "ended") => void;
+    /** The last session left. */
+    onIdle: () => void;
+    now?: () => number;
+}
+export declare class RelayEncoder {
+    private readonly options;
+    private attached;
+    private readonly blocker;
+    private chain;
+    private pushed;
+    private readonly sessions;
+    private ineligibleRun;
+    private bypassUntil;
+    private closed;
+    private readonly now;
+    readonly streamHeader: Buffer;
+    constructor(options: RelayEncoderOptions);
+    get generation(): number;
+    get sessionCount(): number;
+    /**
+     * Call once `Channel.listen` has returned. What it wrote before then was
+     * the opening bytes, which every session gets for itself as its preface;
+     * taking them here too would send them twice to the first session.
+     */
+    attach(): void;
+    /** The channel's listener face. */
+    write(chunk: Buffer): boolean;
+    /** The channel ended, or started over: finish every session cleanly. */
+    end(): void;
+    /**
+     * A new receiver. `preface` is what the channel would write first to an
+     * ordinary listener, snapshotted by the caller in the same tick as this
+     * call, so that the shared blocks from here on follow it exactly.
+     */
+    join(listener: RelayListener, preface: Buffer[]): RelaySession;
+    private onBlock;
+    /**
+     * The bytes in the mode the policy picks: compressed when that pays,
+     * stored when it does not or cannot be done in time.
+     */
+    encodeBytes(bytes: Buffer): Promise<{
+        mode: Mode;
+        payload: Buffer;
+    }>;
+    private abort;
+}
+/** One receiver's view of the relay: its own frame numbers, its own end marker. */
+export declare class RelaySession {
+    private readonly listener;
+    private readonly encoder;
+    private readonly from;
+    private readonly maxQueueBytes;
+    private readonly onClose;
+    private seq;
+    private total;
+    private readonly digest;
+    private queue;
+    private queuedBytes;
+    private ready;
+    closed: boolean;
+    constructor(listener: RelayListener, encoder: RelayEncoder, from: number, maxQueueBytes: number, onClose: (session: RelaySession, reason: FallbackReason | null) => void);
+    start(preface: Buffer[]): Promise<void>;
+    private get maxBlockBytes();
+    deliver(block: EncodedBlock): void;
+    private send;
+    /** Clean end: the end frame, then the socket. */
+    finish(): void;
+    close(reason: FallbackReason): void;
+    /** The receiver hung up. Not a fault of anybody's; nothing is counted against it. */
+    leave(): void;
+    private put;
+}
+export interface DecoderOptions {
+    /** What this decoder can undo. Anything else in a frame is refused. */
+    modes: ReadonlySet<Mode>;
+    /** The most a stream may negotiate; a header asking for more is refused. */
+    maxFrameBytes?: number;
+    /** The boundary the caller expects, when it matters. */
+    boundary?: Boundary;
+    onBytes: (bytes: Buffer) => void | Promise<void>;
+}
+/**
+ * The receiving end: bytes in, original bytes out, every rule checked on
+ * the way. Frames are validated before their payload is read, payloads are
+ * decoded under the size the frame promised, and the result is checked
+ * against the length and the digest before it is handed on. A stream that
+ * stops without its end frame is reported as cut off by `end()`.
+ */
+export declare class RelayDecoder {
+    private readonly options;
+    header: StreamHeader | null;
+    frames: number;
+    bytes: number;
+    ended: boolean;
+    private buffer;
+    private seq;
+    private pending;
+    private readonly digest;
+    private busy;
+    constructor(options: DecoderOptions);
+    /** Feed bytes as they arrive. Serialised, so callers need not await between chunks, though they may. */
+    feed(chunk: Buffer): Promise<void>;
+    private consume;
+    /** The connection closed. Fine after the end frame; a cut-off otherwise. */
+    end(): Promise<void>;
+}