mkvpeek 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The Node.js entry point.
+ *
+ * It includes the whole browser surface.
+ */
+export type { Attachment, ContainerInfo, ListedTrack, PeekCode, PeekOptions, PeekOutcome, RefusalCode, Source, SubtitleFinder, SubtitleOptions, SubtitlePreset, SubtitleProgress, SubtitleTrack, SubtitleTuning, SubtitleVia, Target, Track, TrackFlags, TrackTag, TrackType, Trip, UrlOptions, } from "./browser.js";
+export { isRefusalCode, worthFallback } from "./browser.js";
+export { peekSubtitles, peekTracks } from "./entry/node.js";
+export { urlSource } from "./io/url-node.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { isRefusalCode, worthFallback } from "./browser.js";
+export { peekSubtitles, peekTracks } from "./entry/node.js";
+export { urlSource } from "./io/url-node.js";

package/dist/io/file.d.ts

@@ -0,0 +1,2 @@
+import { type Source } from "./source.js";
+export declare function fileSource(path: string): Promise<Source>;

package/dist/io/file.js

@@ -0,0 +1,47 @@
+import { open, statfs } from "node:fs/promises";
+import { available, LARGE_READ_BYTES, lend } from "./source.js";
+export async function fileSource(path) {
+    const handle = await open(path, "r");
+    const local = await isLocalDisk(path);
+    let cached = null;
+    const size = async () => {
+        cached ??= (await handle.stat()).size;
+        return cached;
+    };
+    const read = async (at, length, into) => {
+        const bounded = available(at, length, await size());
+        const unzeroed = bounded >= LARGE_READ_BYTES;
+        const lent = unzeroed ? lend(into, bounded) : null;
+        const buffer = lent ?? (unzeroed ? Buffer.allocUnsafeSlow(bounded) : new Uint8Array(bounded));
+        let filled = 0;
+        while (filled < bounded) {
+            const { bytesRead } = await handle.read(buffer, filled, bounded - filled, at + filled);
+            if (bytesRead === 0)
+                break;
+            filled += bytesRead;
+        }
+        return new Uint8Array(buffer.buffer, buffer.byteOffset, filled);
+    };
+    const close = () => handle.close();
+    const trip = local ? "local" : "mount";
+    return { size, read, close, trip };
+}
+const NETWORK_MAGIC = new Set([
+    0x6969,
+    0xff534d42,
+    0xfe534d42,
+    0x517b,
+    0x01021997,
+    0x00c36400,
+    0x7461636f,
+    0x5346414f,
+    0x6b414653,
+]);
+async function isLocalDisk(path) {
+    try {
+        return !NETWORK_MAGIC.has((await statfs(path)).type);
+    }
+    catch {
+        return true;
+    }
+}

package/dist/io/lanes.d.ts

@@ -0,0 +1,17 @@
+type Gathered<T extends readonly (() => Promise<unknown>)[]> = {
+    [K in keyof T]: Awaited<ReturnType<T[K]>>;
+};
+/** A queue whose halt is shared. */
+export declare class HaltableQueue<T> {
+    #private;
+    get halted(): boolean;
+    push(item: T): void;
+    close(): void;
+    halt(): void;
+    drain(concurrency: number, each: (item: T) => Promise<boolean>, signal?: AbortSignal): Promise<void>;
+}
+export declare function inParallel<T, R>(items: readonly T[], concurrency: number, each: (item: T, index: number) => Promise<R>, signal?: AbortSignal): Promise<R[]>;
+/** A heterogeneous batch, each slot answering in its own type. */
+export declare function gathered<T extends readonly (() => Promise<unknown>)[]>(tasks: T, concurrency: number, signal?: AbortSignal): Promise<Gathered<T>>;
+export declare function joinOrAbort(lanes: ReadonlyArray<Promise<unknown>>, signal: AbortSignal | undefined): Promise<void>;
+export {};

package/dist/io/lanes.js

@@ -0,0 +1,124 @@
+import { abortReason, onAbort, stopIfAborted } from "./source.js";
+export class HaltableQueue {
+    #items = [];
+    #next = 0;
+    #closed = false;
+    #halted = false;
+    #parked = [];
+    get halted() {
+        return this.#halted;
+    }
+    push(item) {
+        this.#items.push(item);
+        this.#parked.shift()?.();
+    }
+    close() {
+        this.#closed = true;
+        this.#wake();
+    }
+    halt() {
+        this.#halted = true;
+        this.#closed = true;
+        this.#wake();
+    }
+    async drain(concurrency, each, signal) {
+        const take = () => this.#take();
+        const halt = () => this.halt();
+        await runWorkers(take, halt, concurrency, each, signal);
+    }
+    async #take() {
+        while (!this.#halted) {
+            if (this.#next < this.#items.length) {
+                const item = this.#items[this.#next];
+                this.#next += 1;
+                return item;
+            }
+            if (this.#closed)
+                return null;
+            await new Promise((resolve) => {
+                this.#parked.push(resolve);
+            });
+        }
+        return null;
+    }
+    #wake() {
+        for (const wake of this.#parked.splice(0))
+            wake();
+    }
+}
+export async function inParallel(items, concurrency, each, signal) {
+    const out = new Array(items.length);
+    let next = 0;
+    const take = () => {
+        const index = next;
+        next += 1;
+        return Promise.resolve(index >= items.length ? null : [items[index], index]);
+    };
+    const halt = () => { };
+    const store = async ([item, index]) => {
+        out[index] = await each(item, index);
+        return true;
+    };
+    await runWorkers(take, halt, Math.min(concurrency, items.length), store, signal);
+    return out;
+}
+export async function gathered(tasks, concurrency, signal) {
+    const ran = (task) => task();
+    const out = await inParallel(tasks, concurrency, ran, signal);
+    return out;
+}
+export async function joinOrAbort(lanes, signal) {
+    const join = Promise.allSettled(lanes);
+    let settled = join;
+    let unhook = () => { };
+    if (signal !== undefined) {
+        const abortPromise = new Promise((_, reject) => {
+            unhook = onAbort(signal, () => {
+                reject(abortReason(signal));
+            });
+        });
+        settled = Promise.race([join, abortPromise]);
+    }
+    try {
+        for (const one of await settled) {
+            if (one.status === "rejected")
+                throw one.reason;
+        }
+    }
+    finally {
+        unhook();
+    }
+}
+async function runWorkers(take, halt, concurrency, each, signal) {
+    let stopped = false;
+    const stop = () => {
+        stopped = true;
+        halt();
+    };
+    const unhook = onAbort(signal, stop);
+    const worker = async () => {
+        while (!stopped) {
+            const item = await take();
+            if (item === null)
+                return;
+            try {
+                stopIfAborted(signal);
+                if (!(await each(item))) {
+                    stop();
+                    return;
+                }
+            }
+            catch (error) {
+                stop();
+                throw error;
+            }
+        }
+    };
+    try {
+        const lanes = Array.from({ length: Math.max(1, concurrency) }, worker);
+        await joinOrAbort(lanes, signal);
+    }
+    finally {
+        unhook();
+    }
+}

package/dist/io/memory.d.ts

@@ -0,0 +1,2 @@
+import { type Source } from "./source.js";
+export declare function memorySource(bytes: ArrayBufferView | ArrayBuffer): Source;

package/dist/io/memory.js

@@ -0,0 +1,16 @@
+import { available, lend } from "./source.js";
+export function memorySource(bytes) {
+    const held = ArrayBuffer.isView(bytes)
+        ? new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+        : new Uint8Array(bytes);
+    const read = async (at, length, into) => {
+        const bounded = available(at, length, held.byteLength);
+        const lent = lend(into, bounded);
+        if (lent !== null) {
+            lent.set(held.subarray(at, at + bounded));
+            return lent;
+        }
+        return new Uint8Array(held.subarray(at, at + bounded));
+    };
+    return { size: () => Promise.resolve(held.byteLength), read, trip: "local" };
+}

package/dist/io/range.d.ts

@@ -0,0 +1,22 @@
+import { type Source } from "./source.js";
+export interface RangeReply {
+    status: number;
+    header(name: string): string | null;
+    body: AsyncIterable<Uint8Array>;
+    cancel(): Promise<void>;
+}
+export type RangeTransport = (from: number, to: number, signal: AbortSignal | undefined) => Promise<RangeReply>;
+export type OwnedTransport = RangeTransport & {
+    dispose?: () => void;
+};
+export interface RangeOptions {
+    /**
+     * How long the source may deliver nothing before the read is refused.
+     *
+     * Unset, a socket that has gone quiet waits until {@linkcode signal} cuts it.
+     */
+    stallMs?: number | null;
+    signal?: AbortSignal | undefined;
+}
+export declare const bytesRange: (from: number, to: number) => string;
+export declare function rangeSource(url: string, transport: OwnedTransport, { stallMs, signal }: RangeOptions): Promise<Source>;

package/dist/io/range.js

@@ -0,0 +1,190 @@
+import { abortReason, available, HEAD_BYTES, lend, onAbort, stopIfAborted, } from "./source.js";
+export const bytesRange = (from, to) => `bytes=${String(from)}-${String(to)}`;
+export async function rangeSource(url, transport, { stallMs, signal }) {
+    const stall = stallMs !== null && stallMs !== undefined && Number.isFinite(stallMs) && stallMs > 0
+        ? stallMs
+        : null;
+    const invariants = {
+        url,
+        transport,
+        stallMs: stall,
+        signal: signal ?? undefined,
+    };
+    const { dispose } = transport;
+    let headRead;
+    try {
+        stopIfAborted(signal);
+        headRead = await readHead(invariants);
+    }
+    catch (error) {
+        try {
+            dispose?.();
+        }
+        catch { }
+        throw error;
+    }
+    const { total, head } = headRead;
+    const size = () => Promise.resolve(total);
+    const read = async (at, length, into) => {
+        const bounded = available(at, length, total);
+        if (bounded === 0)
+            return new Uint8Array(0);
+        const borrowed = lend(into, bounded);
+        if (at + bounded <= head.length) {
+            if (borrowed === null)
+                return new Uint8Array(head.subarray(at, at + bounded));
+            borrowed.set(head.subarray(at, at + bounded));
+            return borrowed;
+        }
+        if (at < head.length) {
+            const fromHead = head.length - at;
+            const out = borrowed ?? new Uint8Array(bounded);
+            out.set(head.subarray(at, head.length));
+            const room = out.subarray(fromHead);
+            const tail = await readOverRanges(invariants, head.length, bounded - fromHead, room);
+            return out.subarray(0, fromHead + tail.length);
+        }
+        return readOverRanges(invariants, at, bounded, borrowed);
+    };
+    return {
+        size,
+        read,
+        ...(dispose === undefined ? {} : { close: () => Promise.resolve(dispose()) }),
+        trip: "remote",
+    };
+}
+const IDLE_CHUNK_LIMIT = 1000;
+const MAX_RESPONSES_PER_READ = 64;
+async function requestRange(invariants, dog, from, to) {
+    const reply = await invariants.transport(from, to, dog.signal);
+    const dropped = async (why) => {
+        await reply.cancel();
+        return new Error(why);
+    };
+    if (reply.status !== 206) {
+        throw await dropped(`${invariants.url} answered HTTP ${String(reply.status)} to a Range request; this reader needs a server that serves ranges`);
+    }
+    const encoding = reply.header("content-encoding");
+    const recoded = encoding !== null && encoding.trim().toLowerCase() !== "identity";
+    if (recoded) {
+        throw await dropped(`${invariants.url} answered a range encoded as ${encoding}, and this reader asked for identity`);
+    }
+    const contentRange = /^bytes\s+(\d+)-\d+\/(\d+)\s*$/.exec(reply.header("content-range") ?? "");
+    const total = Number(contentRange?.[2]);
+    if (contentRange === null || !Number.isSafeInteger(total)) {
+        throw await dropped(`${invariants.url} did not state a countable total length in Content-Range`);
+    }
+    const start = Number(contentRange[1]);
+    if (start !== from) {
+        throw await dropped(`${invariants.url} answered a range from ${String(start)} for one asked from ${String(from)}; this reader needs the bytes it asked for`);
+    }
+    const body = watched(invariants.url, reply.body, dog);
+    return { ...reply, total, body };
+}
+async function readHead(invariants) {
+    const dog = watchdog(invariants.url, invariants.stallMs, invariants.signal);
+    try {
+        const first = await requestRange(invariants, dog, 0, HEAD_BYTES - 1);
+        const into = new Uint8Array(available(0, HEAD_BYTES, first.total));
+        const landed = await readBodyInto(first, into, 0);
+        return { total: first.total, head: into.subarray(0, landed) };
+    }
+    finally {
+        dog.off();
+    }
+}
+async function readOverRanges(invariants, at, bounded, into = null) {
+    const out = into ?? new Uint8Array(bounded);
+    let written = 0;
+    let rounds = 0;
+    const dog = watchdog(invariants.url, invariants.stallMs, invariants.signal);
+    try {
+        while (written < bounded) {
+            rounds += 1;
+            if (rounds > MAX_RESPONSES_PER_READ) {
+                throw new Error(`${invariants.url} dribbled ${String(written)} bytes over ${String(MAX_RESPONSES_PER_READ)} responses for one read; this reader does not pay a request per byte`);
+            }
+            const from = at + written;
+            const response = await requestRange(invariants, dog, from, at + bounded - 1);
+            const landed = await readBodyInto(response, out, written);
+            if (landed === 0) {
+                throw new Error(`${invariants.url} answered a range from ${String(from)} with no bytes in it`);
+            }
+            written += landed;
+        }
+        return out.subarray(0, written);
+    }
+    finally {
+        dog.off();
+    }
+}
+async function readBodyInto(reply, into, at) {
+    let written = 0;
+    try {
+        for await (const value of reply.body) {
+            const room = into.length - at - written;
+            if (room <= 0)
+                break;
+            const kept = Math.min(value.length, room);
+            const taken = value.subarray(0, kept);
+            into.set(taken, at + written);
+            written += kept;
+        }
+    }
+    finally {
+        await reply.cancel().catch(() => { });
+    }
+    return written;
+}
+async function* watched(url, body, dog) {
+    let idle = 0;
+    let raisedHere = false;
+    try {
+        for await (const chunk of body) {
+            if (chunk.length > 0) {
+                idle = 0;
+                dog.alive();
+                yield chunk;
+                continue;
+            }
+            await new Promise((resolve) => setTimeout(resolve, 0));
+            idle += 1;
+            if (idle > IDLE_CHUNK_LIMIT) {
+                raisedHere = true;
+                throw new Error(`${url} sent ${String(idle)} empty chunks in a row and no bytes`);
+            }
+            const stop = abortReason(dog.signal);
+            if (stop !== null) {
+                raisedHere = true;
+                throw stop;
+            }
+        }
+    }
+    catch (error) {
+        if (raisedHere)
+            throw error;
+        throw (abortReason(dog.signal) ?? new Error(`${url} stopped sending mid-body (${String(error)})`));
+    }
+}
+function watchdog(url, stallMs, caller) {
+    if (stallMs === null)
+        return { signal: caller, alive: () => { }, off: () => { } };
+    const controller = new AbortController();
+    let timer;
+    const alive = () => {
+        clearTimeout(timer);
+        const stall = () => {
+            const silent = new Error(`${url} sent nothing for ${String(stallMs)}ms`);
+            controller.abort(silent);
+        };
+        timer = setTimeout(stall, stallMs);
+    };
+    alive();
+    const forward = () => controller.abort(caller?.reason);
+    const unhook = onAbort(caller, forward);
+    const off = () => {
+        clearTimeout(timer);
+        unhook();
+    };
+    return { signal: controller.signal, alive, off };
+}

package/dist/io/source.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Anything addressable by offset and length can be a source.
+ *
+ * - a file
+ * - an HTTP server that honours Range requests
+ * - an object store
+ * - a buffer already in memory
+ */
+export interface Source {
+    size(): Promise<number>;
+    /**
+     * Returns as much as was asked for.
+     *
+     * A short answer anywhere but at the end of the file is read as the source having stopped.
+     *
+     * @param into A reuse hint.
+     * A cooperating source writes there and returns that subarray, and may ignore it;
+     * either way the returned view is the truth.
+     * Touching it again after resolve breaks the contract,
+     * and a late write changes the bytes of whoever holds the borrowed window.
+     */
+    read(at: number, length: number, into?: Uint8Array): Promise<Uint8Array>;
+    close?(): Promise<void>;
+    trip?: Trip;
+}
+/** What kind of round trip a read to this source is. */
+export type Trip = "local" | "mount" | "remote";
+/** A source whose size has been asked. */
+export interface SizedSource {
+    source: Source;
+    fileSize: number;
+}
+export interface Range {
+    at: number;
+    length: number;
+}
+/** The index path's knobs, the shape of a planned read of scattered ranges. */
+export interface IndexFetch {
+    /**
+     * Two ranges closer than this are fetched as one, gap included.
+     *
+     * Raising it trades bytes for round trips; at 0 only ranges that already touch are merged.
+     */
+    gapBytes: number;
+    /**
+     * How far past its stated size to look at each point the plan names.
+     *
+     * Raising it makes more points finish in one read at the cost of bytes,
+     * and a window this wide sits on the heap per point.
+     */
+    cueAheadBytes: number;
+    /**
+     * Concurrent range requests.
+     *
+     * WARN: on a network path this is the number of open connections,
+     * so **mind the target server's socket limit.**
+     */
+    concurrency: number;
+}
+/** The walk path's knobs, the shape of a scan that starts at the front. */
+export interface WalkFetch {
+    /**
+     * How far past a block the walk reads ahead when it reads that block.
+     *
+     * Raising it trades bytes for round trips; at 0 it reads only what was asked for.
+     */
+    blockAheadBytes: number;
+    /**
+     * Walk lanes.
+     *
+     * On a network path it means the same as {@linkcode IndexFetch.concurrency}.
+     */
+    concurrency: number;
+}
+export type ReportBytes = (done: number, total: number) => void;
+export interface Watch {
+    onProgress: ReportBytes;
+    signal: AbortSignal | undefined;
+}
+/**
+ * How much the opening read fetches.
+ *
+ * A number that usually finishes a typical header in one round trip.
+ */
+export declare const HEAD_BYTES: number;
+/**
+ * From this size a file Source stops zero-filling, and the pool makes no slot or loan below it.
+ *
+ * On a large read the zero-fill costs as much as the read.
+ */
+export declare const LARGE_READ_BYTES: number;
+export declare const MAX_SPAN_BYTES: number;
+/**
+ * Lends the front of the hint when it can hold the clamped answer.
+ *
+ * Otherwise null, and the caller allocates.
+ */
+export declare const lend: (into: Uint8Array | undefined, bounded: number) => Uint8Array | null;
+export declare function abortReason(signal: AbortSignal | undefined): Error | null;
+export declare function stopIfAborted(signal: AbortSignal | undefined): void;
+export declare function available(at: number, length: number, size: number): number;
+export declare function onAbort(signal: AbortSignal | undefined, run: () => void): () => void;

package/dist/io/source.js

@@ -0,0 +1,31 @@
+export const HEAD_BYTES = 128 * 1024;
+export const LARGE_READ_BYTES = 16 * 1024;
+export const MAX_SPAN_BYTES = 4 * 1024 ** 2;
+export const lend = (into, bounded) => into !== undefined && into.length >= bounded ? into.subarray(0, bounded) : null;
+export function abortReason(signal) {
+    if (signal?.aborted !== true)
+        return null;
+    return signal.reason instanceof Error ? signal.reason : new Error(String(signal.reason));
+}
+export function stopIfAborted(signal) {
+    const stopped = abortReason(signal);
+    if (stopped !== null)
+        throw stopped;
+}
+export function available(at, length, size) {
+    const addressable = Number.isInteger(at) && at >= 0 && Number.isInteger(length) && length >= 0;
+    if (!addressable) {
+        throw new RangeError(`a read asked for ${String(length)} bytes at ${String(at)}`);
+    }
+    return Math.max(0, Math.min(length, size - at));
+}
+export function onAbort(signal, run) {
+    if (signal === undefined)
+        return () => { };
+    if (signal.aborted) {
+        run();
+        return () => { };
+    }
+    signal.addEventListener("abort", run, { once: true });
+    return () => signal.removeEventListener("abort", run);
+}

package/dist/io/url-node.d.ts

@@ -0,0 +1,10 @@
+/** URL policy over a node:http transport. */
+import type { Source } from "./source.js";
+import { type UrlOptions } from "./url.js";
+/**
+ * An HTTP source over `node:http`, or over `fetch` when one is passed.
+ *
+ * A server answering a Range request with anything but 206 is not read;
+ * the read throws, which the envelope reports as `source-failed`.
+ */
+export declare function urlSource(url: string, options?: UrlOptions): Promise<Source>;

package/dist/io/url-node.js

@@ -0,0 +1,99 @@
+import http from "node:http";
+import https from "node:https";
+import { bytesRange, rangeSource, } from "./range.js";
+import { abortReason, onAbort } from "./source.js";
+import { httpTarget, TRANSPORT_OWNED_HEADERS, urlSource as viaFetch, whyInadmissible, withoutHeaders, } from "./url.js";
+export async function urlSource(url, options = {}) {
+    if (options.fetch !== undefined)
+        return viaFetch(url, options);
+    const transport = nodeTransport(url, options);
+    return rangeSource(url, transport, options);
+}
+const MAX_SOCKETS = 64;
+const MAX_REDIRECTS = 20;
+const CROSS_ORIGIN_STRIPPED = new Set(["authorization", "cookie", "proxy-authorization"]);
+const REDIRECT_STATUS = new Set([301, 302, 303, 307, 308]);
+function nodeTransport(url, options) {
+    const startUrl = httpTarget(url);
+    const agent = {
+        "http:": new http.Agent({ keepAlive: true, maxSockets: MAX_SOCKETS }),
+        "https:": new https.Agent({ keepAlive: true, maxSockets: MAX_SOCKETS }),
+    };
+    const headers = withoutHeaders(options.headers ?? {}, TRANSPORT_OWNED_HEADERS);
+    const sendRange = (parsed, carrying, from, to, signal) => new Promise((resolve, reject) => {
+        const secure = parsed.protocol === "https:";
+        const lib = secure ? https : http;
+        const host = parsed.hostname;
+        const requestOptions = {
+            hostname: host.startsWith("[") ? host.slice(1, -1) : host,
+            port: parsed.port,
+            path: parsed.pathname + parsed.search,
+            agent: agent[secure ? "https:" : "http:"],
+            headers: {
+                ...carrying,
+                "accept-encoding": "identity",
+                range: bytesRange(from, to),
+            },
+        };
+        const settle = (response) => {
+            resolve(replyOver(response));
+        };
+        const request = lib.request(requestOptions, settle);
+        const stop = () => {
+            request.destroy(abortReason(signal) ?? undefined);
+        };
+        const unhook = onAbort(signal, stop);
+        request.on("close", unhook);
+        request.on("error", (error) => {
+            unhook();
+            reject(error);
+        });
+        request.end();
+    });
+    const transport = async (from, to, signal) => {
+        let current = startUrl;
+        let carrying = headers;
+        for (let left = MAX_REDIRECTS;; left -= 1) {
+            const reply = await sendRange(current, carrying, from, to, signal);
+            const location = reply.header("location");
+            if (!REDIRECT_STATUS.has(reply.status) || location === null)
+                return reply;
+            await reply.cancel();
+            if (left === 0) {
+                throw new Error(`${url} redirected more than ${String(MAX_REDIRECTS)} times`);
+            }
+            const next = URL.parse(location, current.href);
+            if (next === null) {
+                throw new Error(`${url} redirected to ${location}, which is not a URL`);
+            }
+            const why = whyInadmissible(next);
+            if (why !== null)
+                throw new Error(`${url} redirected to one that ${why}`);
+            if (next.origin !== current.origin) {
+                carrying = withoutHeaders(carrying, CROSS_ORIGIN_STRIPPED);
+            }
+            current = next;
+        }
+    };
+    const dispose = () => {
+        for (const key of ["http:", "https:"]) {
+            try {
+                agent[key].destroy();
+            }
+            catch { }
+        }
+    };
+    const owned = { dispose };
+    return Object.assign(transport, owned);
+}
+function replyOver(response) {
+    const header = (name) => {
+        const value = response.headers[name.toLowerCase()];
+        return typeof value === "string" ? value : null;
+    };
+    const cancel = () => {
+        response.destroy();
+        return Promise.resolve();
+    };
+    return { status: response.statusCode ?? 0, header, body: response, cancel };
+}