@fastls/fastls 0.0.0-stage → 0.10.1-dev.0

package/dist/cookies.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Cookies = void 0;
+class Cookies {
+    command;
+    constructor(command) {
+        this.command = command;
+    }
+    getAll(url) {
+        return this.command({ action: "get", url });
+    }
+    get(name, url) {
+        return this.getAll(url).find(cookie => cookie.name === name)?.value;
+    }
+    set(name, value, options) {
+        this.command({ action: "set", url: options.url, cookie: {
+                name, value, path: options.path, domain: options.domain,
+                secure: options.secure, http_only: options.httpOnly,
+                max_age: options.maxAge, expires: options.expires,
+            } });
+    }
+    delete(name, options) {
+        this.set(name, "", { ...options, maxAge: 0 });
+    }
+    clear() { this.command({ action: "clear" }); }
+}
+exports.Cookies = Cookies;

package/dist/duplex.d.ts

@@ -0,0 +1,21 @@
+import { StreamResponse, Transfer } from "./response.js";
+/** A manual HTTP/2 exchange. At most one send/finish operation may be pending. */
+export declare class DuplexExchange {
+    private readonly cancelPending?;
+    private responsePromise?;
+    private writing;
+    private finished;
+    private uploadStopped;
+    private finish;
+    private readonly upload;
+    private readonly transferPromise;
+    private transfer?;
+    private closed;
+    constructor(transfer: Transfer | Promise<Transfer>, cancelPending?: (() => void) | undefined);
+    get response(): Promise<StreamResponse>;
+    private write;
+    send(bytes: Uint8Array): Promise<void>;
+    finishUpload(): Promise<void>;
+    close(): void;
+    closeAsync(): Promise<void>;
+}

package/dist/duplex.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DuplexExchange = void 0;
+const errors_js_1 = require("./errors.js");
+const response_js_1 = require("./response.js");
+/** A manual HTTP/2 exchange. At most one send/finish operation may be pending. */
+class DuplexExchange {
+    cancelPending;
+    responsePromise;
+    writing = false;
+    finished = false;
+    uploadStopped = false;
+    finish;
+    upload;
+    transferPromise;
+    transfer;
+    closed = false;
+    constructor(transfer, cancelPending) {
+        this.cancelPending = cancelPending;
+        const done = new Promise(resolve => { this.finish = resolve; });
+        this.transferPromise = Promise.resolve(transfer).then(value => {
+            this.transfer = value;
+            if (this.closed)
+                value.close();
+            const stopped = () => this.finish();
+            value.signal.addEventListener("abort", stopped, { once: true });
+            if (value.signal.aborted)
+                stopped();
+            void done.then(() => value.signal.removeEventListener("abort", stopped));
+            return value;
+        });
+        void this.transferPromise.catch(() => this.finish());
+        this.upload = { done, cleanup: Promise.resolve(), complete: () => this.finished,
+            check: () => this.transfer?.throwFailure() };
+    }
+    get response() {
+        return this.responsePromise ??= this.transferPromise.then(async (transfer) => {
+            if (this.closed)
+                throw new errors_js_1.FastlsError("exchange is closed");
+            const info = await transfer.headers();
+            return new response_js_1.StreamResponse(transfer, info, this.upload);
+        }).then(response => response, error => { this.close(); throw error; });
+    }
+    async write(bytes, end) {
+        if (this.writing)
+            throw new errors_js_1.FastlsError("another upload write is pending; await send() before sending again");
+        if (this.finished || this.uploadStopped)
+            throw new errors_js_1.FastlsError("upload is closed");
+        this.writing = true;
+        const accepted = (code) => {
+            if (code === 0)
+                return;
+            // The peer can stop receiving while its response remains readable.
+            this.uploadStopped = true;
+            this.finish();
+            throw new errors_js_1.FastlsError("server closed the upload");
+        };
+        try {
+            const transfer = await this.transferPromise;
+            if (this.closed)
+                throw new errors_js_1.FastlsError("exchange is closed");
+            transfer.ensureOpen();
+            if (end) {
+                accepted(await transfer.write(Buffer.alloc(0), true, transfer.signal));
+                this.finished = true;
+                this.finish();
+            }
+            else {
+                for (let offset = 0; offset < bytes.byteLength; offset += 65536) {
+                    accepted(await transfer.write(bytes.subarray(offset, offset + 65536), false, transfer.signal));
+                }
+            }
+        }
+        catch (error) {
+            if (!this.uploadStopped)
+                this.transfer?.close(error instanceof Error ? error : new Error(String(error)));
+            throw error;
+        }
+        finally {
+            this.writing = false;
+        }
+    }
+    send(bytes) {
+        if (!(bytes instanceof Uint8Array))
+            return Promise.reject(new TypeError("send() requires Uint8Array or Buffer"));
+        return this.write(bytes, false);
+    }
+    finishUpload() {
+        return this.finished ? Promise.resolve() : this.write(Buffer.alloc(0), true);
+    }
+    close() { this.closed = true; this.transfer?.close(); this.cancelPending?.(); }
+    async closeAsync() { this.close(); await this.transferPromise.then(transfer => transfer.close(), () => { }); }
+}
+exports.DuplexExchange = DuplexExchange;

package/dist/errors.d.ts

@@ -0,0 +1,28 @@
+export declare class FastlsError extends Error {
+    name: string;
+}
+export declare class FastlsHTTPError extends FastlsError {
+    readonly response: import("./response.js").Response | import("./response.js").StreamResponse;
+    name: string;
+    readonly status: number;
+    constructor(response: import("./response.js").Response | import("./response.js").StreamResponse);
+}
+export type TimeoutPhase = "connect" | "write" | "headers" | "read" | "total" | "handshake";
+export declare class FastlsTimeoutError extends FastlsError {
+    readonly phase: TimeoutPhase;
+    name: string;
+    constructor(message: string, phase: TimeoutPhase);
+}
+export declare class FastlsDecodeError extends FastlsError {
+    name: string;
+}
+export declare function responseError(info: {
+    error?: string;
+    error_code?: string;
+    timeout_phase?: string;
+}): FastlsError;
+export declare class AbortError extends FastlsError {
+    name: string;
+    readonly code = "ABORT_ERR";
+    constructor(message?: string, options?: ErrorOptions);
+}

package/dist/errors.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AbortError = exports.FastlsDecodeError = exports.FastlsTimeoutError = exports.FastlsHTTPError = exports.FastlsError = void 0;
+exports.responseError = responseError;
+class FastlsError extends Error {
+    name = "FastlsError";
+}
+exports.FastlsError = FastlsError;
+class FastlsHTTPError extends FastlsError {
+    response;
+    name = "FastlsHTTPError";
+    status;
+    constructor(response) {
+        super(`HTTP ${response.status}`);
+        this.response = response;
+        this.status = response.status;
+    }
+}
+exports.FastlsHTTPError = FastlsHTTPError;
+class FastlsTimeoutError extends FastlsError {
+    phase;
+    name = "FastlsTimeoutError";
+    constructor(message, phase) {
+        super(message);
+        this.phase = phase;
+    }
+}
+exports.FastlsTimeoutError = FastlsTimeoutError;
+class FastlsDecodeError extends FastlsError {
+    name = "FastlsDecodeError";
+}
+exports.FastlsDecodeError = FastlsDecodeError;
+function responseError(info) {
+    const message = info.error ?? "native request failed";
+    if (info.error_code === "timeout")
+        return new FastlsTimeoutError(message, (info.timeout_phase ?? "total"));
+    if (info.error_code === "decode_error")
+        return new FastlsDecodeError(message);
+    return new FastlsError(message);
+}
+class AbortError extends FastlsError {
+    name = "AbortError";
+    code = "ABORT_ERR";
+    constructor(message = "The request was aborted", options) {
+        super(message, options);
+    }
+}
+exports.AbortError = AbortError;

package/dist/headers.d.ts

@@ -0,0 +1,12 @@
+/** Read-only, case-insensitive response headers. Values are never comma-split. */
+export declare class Headers implements Iterable<[string, string]> {
+    #private;
+    constructor(values?: Record<string, string[]>, fallback?: Record<string, string>);
+    get(name: string, fallback: string): string;
+    get(name: string): string | undefined;
+    getAll(name: string): string[];
+    has(name: string): boolean;
+    entries(): IterableIterator<[string, string]>;
+    multiItems(): IterableIterator<[string, string]>;
+    [Symbol.iterator](): IterableIterator<[string, string]>;
+}

package/dist/headers.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Headers = void 0;
+/** Read-only, case-insensitive response headers. Values are never comma-split. */
+class Headers {
+    #values = new Map();
+    constructor(values = {}, fallback = {}) {
+        for (const [name, value] of Object.entries(fallback))
+            this.#values.set(name.toLowerCase(), [value]);
+        for (const [name, list] of Object.entries(values))
+            this.#values.set(name.toLowerCase(), [...list]);
+    }
+    get(name, fallback) { return this.#values.get(name.toLowerCase())?.[0] ?? fallback; }
+    getAll(name) { return [...(this.#values.get(name.toLowerCase()) ?? [])]; }
+    has(name) { return this.#values.has(name.toLowerCase()); }
+    *entries() {
+        for (const [name, values] of this.#values)
+            if (values.length)
+                yield [name, values[0]];
+    }
+    *multiItems() {
+        for (const [name, values] of this.#values)
+            for (const value of values)
+                yield [name, value];
+    }
+    [Symbol.iterator]() { return this.entries(); }
+}
+exports.Headers = Headers;

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export { Session } from "./session.js";
+export type { SessionOptions, RequestOptions, DuplexOptions, Stats } from "./session.js";
+export { DuplexExchange } from "./duplex.js";
+export { WebSocket, WebSocketClosed } from "./websocket.js";
+export type { WebSocketOptions } from "./websocket.js";
+export { ServerSentEvent, SSEStream } from "./sse.js";
+export type { SSEOptions } from "./sse.js";
+export { Response, StreamResponse } from "./response.js";
+export { Headers } from "./headers.js";
+export { Cookies } from "./cookies.js";
+export type { Cookie, CookieOptions } from "./cookies.js";
+export { FastlsError, FastlsHTTPError, AbortError, FastlsDecodeError, FastlsTimeoutError } from "./errors.js";
+export type { QueryScalar, QueryParams, FormFields, JSONValue, MultipartReader, MultipartBody, MultipartFile, MultipartFiles } from "./request-options.js";
+export type { TimeoutPhase } from "./errors.js";
+export type { TimeoutPolicy, Timeout } from "./timeout.js";
+export type { UploadBody, ByteSource } from "./upload.js";

package/dist/index.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FastlsTimeoutError = exports.FastlsDecodeError = exports.AbortError = exports.FastlsHTTPError = exports.FastlsError = exports.Cookies = exports.Headers = exports.StreamResponse = exports.Response = exports.SSEStream = exports.ServerSentEvent = exports.WebSocketClosed = exports.WebSocket = exports.DuplexExchange = exports.Session = void 0;
+var session_js_1 = require("./session.js");
+Object.defineProperty(exports, "Session", { enumerable: true, get: function () { return session_js_1.Session; } });
+var duplex_js_1 = require("./duplex.js");
+Object.defineProperty(exports, "DuplexExchange", { enumerable: true, get: function () { return duplex_js_1.DuplexExchange; } });
+var websocket_js_1 = require("./websocket.js");
+Object.defineProperty(exports, "WebSocket", { enumerable: true, get: function () { return websocket_js_1.WebSocket; } });
+Object.defineProperty(exports, "WebSocketClosed", { enumerable: true, get: function () { return websocket_js_1.WebSocketClosed; } });
+var sse_js_1 = require("./sse.js");
+Object.defineProperty(exports, "ServerSentEvent", { enumerable: true, get: function () { return sse_js_1.ServerSentEvent; } });
+Object.defineProperty(exports, "SSEStream", { enumerable: true, get: function () { return sse_js_1.SSEStream; } });
+var response_js_1 = require("./response.js");
+Object.defineProperty(exports, "Response", { enumerable: true, get: function () { return response_js_1.Response; } });
+Object.defineProperty(exports, "StreamResponse", { enumerable: true, get: function () { return response_js_1.StreamResponse; } });
+var headers_js_1 = require("./headers.js");
+Object.defineProperty(exports, "Headers", { enumerable: true, get: function () { return headers_js_1.Headers; } });
+var cookies_js_1 = require("./cookies.js");
+Object.defineProperty(exports, "Cookies", { enumerable: true, get: function () { return cookies_js_1.Cookies; } });
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "FastlsError", { enumerable: true, get: function () { return errors_js_1.FastlsError; } });
+Object.defineProperty(exports, "FastlsHTTPError", { enumerable: true, get: function () { return errors_js_1.FastlsHTTPError; } });
+Object.defineProperty(exports, "AbortError", { enumerable: true, get: function () { return errors_js_1.AbortError; } });
+Object.defineProperty(exports, "FastlsDecodeError", { enumerable: true, get: function () { return errors_js_1.FastlsDecodeError; } });
+Object.defineProperty(exports, "FastlsTimeoutError", { enumerable: true, get: function () { return errors_js_1.FastlsTimeoutError; } });

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import sdk from './index.js';
+export const { Session, Response, StreamResponse, DuplexExchange, WebSocket, WebSocketClosed, ServerSentEvent, SSEStream, Headers, Cookies, FastlsError, FastlsHTTPError, AbortError, FastlsDecodeError, FastlsTimeoutError } = sdk;

package/dist/library-path.d.ts

@@ -0,0 +1,2 @@
+/** Explicit overrides take priority; a present candidate manifest must validate. */
+export declare function libraryPath(library?: string, packageRoot?: string): string;

package/dist/library-path.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.libraryPath = libraryPath;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_module_1 = require("node:module");
+const errors_js_1 = require("./errors.js");
+const verified = new Set();
+let glibcRuntime;
+let glibcChecked = false;
+/** Explicit overrides take priority; a present candidate manifest must validate. */
+function libraryPath(library, packageRoot = (0, node_path_1.resolve)(__dirname, "..")) {
+    const override = library ?? process.env.FASTLS_LIBRARY;
+    const name = process.platform === "win32" ? "fastls.dll"
+        : process.platform === "darwin" ? "libfastls.dylib" : "libfastls.so";
+    try {
+        if (override !== undefined)
+            return (0, node_fs_1.realpathSync)((0, node_path_1.resolve)(override));
+        let nativeRoot = packageRoot;
+        let manifestPath = (0, node_path_1.resolve)(nativeRoot, "native/manifest.json");
+        if (!(0, node_fs_1.existsSync)(manifestPath) && !(0, node_fs_1.existsSync)((0, node_path_1.resolve)(packageRoot, "src/native.ts"))) {
+            const suffix = `${process.platform}-${process.arch}${process.platform === "linux" ? "-glibc" : ""}`;
+            const require = (0, node_module_1.createRequire)((0, node_path_1.resolve)(packageRoot, "package.json"));
+            let metadataPath;
+            try {
+                metadataPath = require.resolve(`@fastls/fastls-${suffix}/package.json`);
+            }
+            catch (cause) {
+                throw new Error(`no native manifest or optional package for ${suffix}; reinstall with optional dependencies enabled or supply an external library`, { cause });
+            }
+            const installed = JSON.parse((0, node_fs_1.readFileSync)(metadataPath, "utf8"));
+            const wrapper = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.resolve)(packageRoot, "package.json"), "utf8"));
+            if (installed.name !== `@fastls/fastls-${suffix}` || installed.version !== wrapper.version) {
+                throw new Error("native package version mismatch; reinstall matching Fastls packages");
+            }
+            nativeRoot = (0, node_path_1.resolve)(metadataPath, "..");
+            manifestPath = (0, node_path_1.resolve)(nativeRoot, "native/manifest.json");
+        }
+        if (!(0, node_fs_1.existsSync)(manifestPath)) {
+            if (!(0, node_fs_1.existsSync)((0, node_path_1.resolve)(packageRoot, "src/native.ts")))
+                throw new Error("installed package has no native manifest; supply an external library");
+            return (0, node_fs_1.realpathSync)((0, node_path_1.resolve)(packageRoot, "../dist", name));
+        }
+        const manifest = JSON.parse((0, node_fs_1.readFileSync)(manifestPath, "utf8"));
+        if (manifest.schema !== 1 || manifest.abi !== 1 || manifest.platform !== process.platform || manifest.arch !== process.arch) {
+            throw new Error(`candidate platform mismatch: expected ${process.platform}/${process.arch}, received ${manifest.platform}/${manifest.arch}`);
+        }
+        if (manifest.file !== name || !/^[a-f0-9]{64}$/.test(manifest.sha256))
+            throw new Error("invalid candidate library manifest");
+        if (process.platform === "linux") {
+            if (!glibcChecked) {
+                const report = process.report.getReport();
+                glibcRuntime = report.header?.glibcVersionRuntime;
+                glibcChecked = true;
+            }
+            const current = glibcRuntime;
+            const minimum = manifest.requirements?.glibc;
+            if (!current || !/^\d+\.\d+$/.test(minimum))
+                throw new Error("this candidate requires Linux glibc; musl is not supported");
+            const [major, minor] = current.split(".").map(Number), [minMajor, minMinor] = minimum.split(".").map(Number);
+            if (major < minMajor || (major === minMajor && minor < minMinor))
+                throw new Error(`candidate requires glibc >= ${minimum}; found ${current}`);
+        }
+        const path = (0, node_fs_1.realpathSync)((0, node_path_1.resolve)(nativeRoot, "native", name)), stat = (0, node_fs_1.statSync)(path);
+        const key = `${path}:${stat.size}:${stat.mtimeMs}:${stat.ctimeMs}:${manifest.sha256}`;
+        if (!verified.has(key)) {
+            if ((0, node_crypto_1.createHash)("sha256").update((0, node_fs_1.readFileSync)(path)).digest("hex") !== manifest.sha256)
+                throw new Error("candidate library SHA-256 mismatch");
+            verified.add(key);
+        }
+        return path;
+    }
+    catch (cause) {
+        throw new errors_js_1.FastlsError("Cannot find Fastls library or validate native candidate; set FASTLS_LIBRARY or pass { library: absolutePath }", { cause });
+    }
+}

package/dist/native.d.ts

@@ -0,0 +1,54 @@
+export declare function parseNativeJSON(text: string): unknown;
+export declare function encodeNativeJSON(value: unknown, limit?: number): Buffer;
+export declare function asHandle(value: unknown): bigint;
+export interface NativeInfo {
+    state: "pending" | "headers" | "eof" | "error";
+    status?: number;
+    headers?: Record<string, string>;
+    header_values?: Record<string, string[]>;
+    match: Readonly<Record<string, unknown>>;
+    error?: string;
+    error_code?: string;
+    timeout_phase?: string;
+    decoded?: boolean;
+    protocol?: string;
+    final_url?: string;
+    trailer_values?: Record<string, string[]>;
+    wire_header_values?: Record<string, string[]>;
+    upload_discarded?: boolean;
+    websocket?: {
+        subprotocol: string;
+        write_pending: boolean;
+        close_code: number;
+        close_reason: string;
+        close_received: boolean;
+        pings: number;
+        pongs: number;
+        last_pong_base64: string;
+        max_message_bytes: number;
+        alpn_policy: string;
+    };
+}
+export declare class Native {
+    private functions;
+    readonly notificationsAvailable: boolean;
+    readonly websocketAvailable: boolean;
+    readonly path: string;
+    static load(library?: string): Native;
+    private constructor();
+    call<T = unknown>(name: string, ...args: unknown[]): T;
+    start(input: unknown): bigint;
+    wsStart(input: unknown): bigint;
+    wsSend(handle: bigint, opcode: number, data: Uint8Array): number;
+    wsRead(handle: bigint, buffer: Buffer): {
+        code: number;
+        length: number;
+        opcode: number;
+        end: boolean;
+    };
+    read(handle: bigint, buffer: Buffer): {
+        code: number;
+        length: number;
+    };
+    write(handle: bigint, buffer: Uint8Array, end?: boolean): number;
+}

package/dist/native.js

@@ -0,0 +1,208 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Native = void 0;
+exports.parseNativeJSON = parseNativeJSON;
+exports.encodeNativeJSON = encodeNativeJSON;
+exports.asHandle = asHandle;
+const koffi_1 = __importDefault(require("koffi"));
+const lossless_json_1 = require("lossless-json");
+const library_path_js_1 = require("./library-path.js");
+const node_worker_threads_1 = require("node:worker_threads");
+const errors_js_1 = require("./errors.js");
+function parseNativeJSON(text) {
+    return (0, lossless_json_1.parse)(text, undefined, (token) => {
+        const number = Number(token);
+        return /^-?\d+$/.test(token) && !Number.isSafeInteger(number) ? BigInt(token) : number;
+    });
+}
+function encodeNativeJSON(value, limit = 1024 * 1024) {
+    const raw = Buffer.from((0, lossless_json_1.stringify)(value), "utf8");
+    if (!raw.length || raw.length > limit)
+        throw new RangeError(`native JSON exceeds ${limit} bytes`);
+    return raw;
+}
+function asHandle(value) {
+    if (typeof value !== "bigint" && !(typeof value === "number" && Number.isSafeInteger(value))) {
+        throw new errors_js_1.FastlsError("native library returned an invalid handle");
+    }
+    const handle = BigInt(value);
+    if (handle < 1n || handle > 0xffffffffffffffffn)
+        throw new errors_js_1.FastlsError("invalid uint64 handle");
+    return handle;
+}
+// Keep successful and partially loaded libraries alive until process exit.
+// Worker teardown may unload a Go runtime, so worker_threads are not yet supported.
+const libraries = new Map();
+const bindings = new Map();
+const pinned = new Set();
+let systemLoader;
+function pinLibrary(path) {
+    if (pinned.has(path))
+        return;
+    // N-API finalizers can unload libraries during environment teardown even when
+    // JavaScript retained them. Go runtime threads require OS-level process lifetime.
+    systemLoader ??= koffi_1.default.load(process.platform === "win32" ? "kernel32.dll" : null);
+    if (process.platform === "win32") {
+        const module = [null];
+        const pin = systemLoader.func("int __stdcall GetModuleHandleExW(uint32_t flags, str16 name, _Out_ void **module)");
+        if (!pin(1, path, module))
+            throw new errors_js_1.FastlsError("cannot pin the Go runtime library for process lifetime");
+    }
+    else {
+        const dlopen = systemLoader.func("void *dlopen(str path, int flags)");
+        // RTLD_NOW | RTLD_NODELETE; values from Darwin / glibc dlfcn.h.
+        if (!dlopen(path, 2 | (process.platform === "darwin" ? 0x80 : 0x1000))) {
+            throw new errors_js_1.FastlsError("cannot pin the Go runtime library for process lifetime");
+        }
+    }
+    pinned.add(path);
+}
+class Native {
+    functions = {};
+    notificationsAvailable;
+    websocketAvailable;
+    path;
+    static load(library) {
+        if (!node_worker_threads_1.isMainThread)
+            throw new errors_js_1.FastlsError("Fastls must be loaded on the main thread; worker_threads are not supported yet");
+        const path = (0, library_path_js_1.libraryPath)(library);
+        let native = bindings.get(path);
+        if (!native) {
+            native = new Native(path);
+            bindings.set(path, native);
+        }
+        return native;
+    }
+    constructor(path) {
+        this.path = path;
+        try {
+            let lib = libraries.get(path);
+            if (!lib) {
+                lib = koffi_1.default.load(path);
+                libraries.set(path, lib);
+            }
+            pinLibrary(path);
+            if (lib.func("uint32_t fastls_abi_version(void)")() !== 1) {
+                throw new errors_js_1.FastlsError("unsupported Fastls ABI version (expected 1)");
+            }
+            const signatures = {
+                profiles: [], stats: [], features: [], session_create: [],
+                session_close: ["uint64_t"], session_close_idle: ["uint64_t"],
+                session_cookies: ["uint64_t", "void *", "size_t"],
+                start: ["void *", "size_t"], info: ["uint64_t"],
+                cancel: ["uint64_t"], close: ["uint64_t"],
+            };
+            for (const [name, args] of Object.entries(signatures)) {
+                // Return an owned pointer, never an auto-converted string: we must free it.
+                this.functions[name] = lib.func(`fastls_${name}`, "void *", args);
+            }
+            this.functions.free = lib.func("void fastls_free(void *ptr)");
+            this.functions.read = lib.func("int fastls_read(uint64_t handle, _Out_ void *buffer, size_t capacity, _Out_ size_t *length)");
+            this.functions.write = lib.func("int fastls_write(uint64_t handle, const void *buffer, size_t length, int end)");
+            const features = new Set(this.call("features"));
+            let websocketAvailable = false;
+            if (features.has("websocket_v1")) {
+                try {
+                    const start = lib.func("void *fastls_ws_start(void *json, size_t length)");
+                    const send = lib.func("int fastls_ws_send(uint64_t handle, int opcode, const void *data, size_t length)");
+                    const read = lib.func("int fastls_ws_read(uint64_t handle, _Out_ void *buffer, size_t capacity, _Out_ size_t *length, _Out_ int *opcode, _Out_ int *end)");
+                    Object.assign(this.functions, { ws_start: start, ws_send: send, ws_read: read });
+                    websocketAvailable = true;
+                }
+                catch { /* Optional as a group; HTTP stays available with old libraries. */ }
+            }
+            this.websocketAvailable = websocketAvailable;
+            let notificationsAvailable = false;
+            if (features.has("session_notifications")) {
+                try {
+                    for (const [name, args] of Object.entries({ session_watch: ["uint64_t", "uint16_t", "void *", "size_t"], session_events: ["uint64_t"], session_unwatch: ["uint64_t"] })) {
+                        this.functions[name] = lib.func(`fastls_${name}`, "void *", args);
+                    }
+                    this.functions.wait = lib.func("int fastls_wait(uint64_t handle, uint32_t events, uint32_t timeout_ms)");
+                    notificationsAvailable = true;
+                }
+                catch { /* Old ABI-v1 libraries can still use polling. */ }
+            }
+            this.notificationsAvailable = notificationsAvailable;
+            for (const feature of ["stream_decode", "phase_timeouts", "stream_upload", "write_timeout"]) {
+                if (!features.has(feature))
+                    throw new errors_js_1.FastlsError(`native feature required: ${feature}`);
+            }
+        }
+        catch (cause) {
+            throw new errors_js_1.FastlsError(`Cannot bind Fastls library at ${path}; ABI v1 with decoding, phase timeouts and streaming uploads is required`, { cause });
+        }
+    }
+    call(name, ...args) {
+        const pointer = this.functions[name](...args);
+        if (!pointer)
+            throw new errors_js_1.FastlsError("native library returned a null result");
+        let envelope;
+        try {
+            const json = koffi_1.default.decode.string(pointer);
+            // Starts, sessions and notification batches contain uint64 handles. Catalogs, headers
+            // and info metadata use strings and bounded numeric fields; avoid the
+            // allocating JS numeric parser on every poll and catalog lookup.
+            envelope = (name === "start" || name === "ws_start" || name === "session_create" || name === "session_events" ? parseNativeJSON(json) : JSON.parse(json));
+        }
+        finally {
+            this.functions.free(pointer);
+        }
+        if (!envelope?.ok)
+            throw new errors_js_1.FastlsError(envelope?.error ?? "invalid native result");
+        return envelope.result;
+    }
+    start(input) {
+        const raw = encodeNativeJSON(input);
+        return asHandle(this.call("start", raw, raw.length));
+    }
+    wsStart(input) {
+        if (!this.websocketAvailable)
+            throw new errors_js_1.FastlsError("WebSocket requires a newer Fastls native library");
+        const raw = encodeNativeJSON(input);
+        return asHandle(this.call("ws_start", raw, raw.length));
+    }
+    wsSend(handle, opcode, data) {
+        return this.functions.ws_send(handle, opcode, data, data.byteLength);
+    }
+    wsRead(handle, buffer) {
+        const length = [0], opcode = [0], end = [0];
+        const code = this.functions.ws_read(handle, buffer, buffer.length, length, opcode, end);
+        if (![0, 1, 2].includes(code) && code >= 0)
+            throw new errors_js_1.FastlsError("invalid WebSocket read status");
+        if (!Number.isSafeInteger(Number(length[0])) || Number(length[0]) < 0 || Number(length[0]) > buffer.length || ![0, 1].includes(end[0]))
+            throw new errors_js_1.FastlsError("invalid WebSocket read result");
+        return { code, length: Number(length[0]), opcode: opcode[0], end: end[0] === 1 };
+    }
+    read(handle, buffer) {
+        const out = [0];
+        const code = this.functions.read(handle, buffer, buffer.length, out);
+        const length = Number(out[0]);
+        if (!Number.isSafeInteger(length) || length < 0 || length > buffer.length) {
+            throw new errors_js_1.FastlsError("native library returned an invalid read length");
+        }
+        if (code < 0) {
+            const info = this.call("info", handle);
+            throw (0, errors_js_1.responseError)(info);
+        }
+        if (![0, 1, 2].includes(code))
+            throw new errors_js_1.FastlsError("native library returned an invalid read status");
+        return { code, length };
+    }
+    write(handle, buffer, end = false) {
+        const code = this.functions.write(handle, buffer, buffer.byteLength, Number(end));
+        if (code < 0) {
+            const info = this.call("info", handle);
+            if (info.state === "error")
+                throw (0, errors_js_1.responseError)(info);
+            if (info.state === "headers" || info.state === "eof")
+                return 2;
+            throw new errors_js_1.FastlsError("upload is closed or invalid");
+        }
+        return code;
+    }
+}
+exports.Native = Native;