@fastls/fastls 0.0.0-stage → 0.10.1

package/dist/cookies.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Cookies = void 0;
+const tough_cookie_1 = require("tough-cookie");
+const errors_js_1 = require("./errors.js");
+class Cookies {
+    ensureOpen;
+    enabled;
+    jar = new tough_cookie_1.CookieJar();
+    constructor(ensureOpen, enabled = true) {
+        this.ensureOpen = ensureOpen;
+        this.enabled = enabled;
+    }
+    url(value) {
+        try {
+            const url = new URL(value.replace(/^ws:/, "http:").replace(/^wss:/, "https:"));
+            if (!["http:", "https:"].includes(url.protocol) || url.username || url.password)
+                throw new Error();
+            return url.href;
+        }
+        catch {
+            throw new errors_js_1.FastlsError("cookie URL must be absolute HTTP(S) without credentials");
+        }
+    }
+    getAll(url) {
+        this.ensureOpen();
+        const target = this.url(url);
+        return this.enabled ? this.jar.getCookiesSync(target).map(cookie => ({ name: cookie.key, value: cookie.value })) : [];
+    }
+    get(name, url) {
+        return this.getAll(url).find(cookie => cookie.name === name)?.value;
+    }
+    set(name, value, options) {
+        this.ensureOpen();
+        if (!this.enabled)
+            throw new errors_js_1.FastlsError("cookie store is disabled");
+        if (!/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(name) || /[^\x20-\x7e]|[;"\\]/.test(value) || Buffer.byteLength(name + value) > 4096)
+            throw new errors_js_1.FastlsError("invalid cookie name or value");
+        if (options.path !== undefined && (!options.path.startsWith("/") || /[\x00-\x1f;]/.test(options.path)))
+            throw new errors_js_1.FastlsError("invalid cookie path");
+        if (options.maxAge !== undefined && (!Number.isInteger(options.maxAge) || options.maxAge < -2147483648 || options.maxAge > 2147483647))
+            throw new errors_js_1.FastlsError("invalid cookie maxAge");
+        const expires = options.expires === undefined ? undefined : new Date(options.expires);
+        if (expires && (!Number.isFinite(expires.getTime()) || !/^\d{4}-\d\d-\d\dT.*(?:Z|[+-]\d\d:\d\d)$/.test(options.expires)))
+            throw new errors_js_1.FastlsError("expires must use RFC3339 format");
+        const cookie = new tough_cookie_1.Cookie({ key: name, value, path: options.path, domain: options.domain?.replace(/^\./, ""), secure: options.secure, httpOnly: options.httpOnly, maxAge: options.maxAge, expires });
+        try {
+            this.jar.setCookieSync(cookie, this.url(options.url));
+        }
+        catch {
+            throw new errors_js_1.FastlsError("invalid cookie domain or attributes");
+        }
+    }
+    delete(name, options) {
+        this.set(name, "", { ...options, maxAge: 0 });
+    }
+    clear() { this.ensureOpen(); this.jar.removeAllCookiesSync(); }
+    /** @internal */
+    header(url) { return this.getAll(url).map(cookie => `${cookie.name}=${cookie.value}`).join("; "); }
+    /** @internal */
+    extract(url, fields) {
+        this.ensureOpen();
+        if (!this.enabled)
+            return;
+        const target = this.url(url);
+        for (const field of fields)
+            this.jar.setCookieSync(field, target, { ignoreError: true });
+    }
+}
+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/fetch.d.ts

@@ -0,0 +1,20 @@
+import { Session, type RequestOptions } from "./session.js";
+export interface FetchOptions extends RequestInit {
+    duplex?: "half";
+    profile?: string;
+    proxy?: string | null;
+    proxyCaFile?: string | null;
+    caFile?: string;
+    library?: string;
+    timeoutMs?: RequestOptions["timeoutMs"];
+    maxRedirects?: number;
+}
+/** A standard Node Response with Fastls transport metadata. */
+export interface FetchResponse extends globalThis.Response {
+    readonly match: Readonly<Record<string, unknown>>;
+    readonly httpVersion: string;
+}
+/** @internal Used by Session.fetch; ownership is explicit to avoid closing shared pools. */
+export declare function fetchWithSession(session: Session, input: string | URL | Request, init?: FetchOptions, owned?: boolean): Promise<FetchResponse>;
+/** Fetch-compatible entry point. No persistent cookie jar is created. */
+export declare function fetch(input: string | URL | Request, init?: FetchOptions): Promise<FetchResponse>;

package/dist/fetch.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchWithSession = fetchWithSession;
+exports.fetch = fetch;
+const node_stream_1 = require("node:stream");
+const session_js_1 = require("./session.js");
+/** @internal Used by Session.fetch; ownership is explicit to avoid closing shared pools. */
+async function fetchWithSession(session, input, init = {}, owned = false) {
+    try {
+        for (const key of ["cache", "credentials", "integrity", "keepalive", "mode", "referrer", "referrerPolicy"]) {
+            if (init[key] !== undefined)
+                throw new TypeError(`Fastls fetch does not support ${key}`);
+        }
+        const allowed = new Set(["method", "headers", "body", "redirect", "signal", "duplex", "profile", "proxy", "proxyCaFile", "caFile", "library", "timeoutMs", "maxRedirects"]);
+        for (const key of Object.keys(init))
+            if (!allowed.has(key))
+                throw new TypeError(`Fastls fetch does not support ${key}`);
+        // Request performs the platform's normal URL/method/header validation and
+        // serializes URLSearchParams, Blob and FormData without a second encoder.
+        const request = new Request(input, init);
+        const headers = Object.fromEntries(request.headers);
+        let body;
+        if (request.body) {
+            if (typeof init.body === "string" || init.body instanceof Uint8Array)
+                body = init.body;
+            else if (init.body instanceof URLSearchParams)
+                body = init.body.toString();
+            else
+                body = node_stream_1.Readable.fromWeb(request.body);
+        }
+        const stream = await session.stream(request.method, request.url, {
+            headers, body, profile: init.profile, proxy: init.proxy, proxyCaFile: init.proxyCaFile,
+            timeoutMs: init.timeoutMs, maxRedirects: init.maxRedirects,
+            allowRedirects: request.redirect === "follow", signal: request.signal,
+        });
+        let closing;
+        const close = () => closing ??= (async () => {
+            stream.closedSignal.removeEventListener("abort", abort);
+            try {
+                await stream.closeAsync();
+            }
+            finally {
+                if (owned)
+                    await session.closeAsync();
+            }
+        })();
+        const abort = () => { void close().catch(() => { }); };
+        stream.closedSignal.addEventListener("abort", abort, { once: true });
+        if (stream.closedSignal.aborted) {
+            await close();
+            throw stream.closedSignal.reason;
+        }
+        try {
+            if (request.redirect === "error" && [301, 302, 303, 307, 308].includes(stream.status))
+                throw new TypeError("redirect encountered with redirect: error");
+            const responseHeaders = new globalThis.Headers();
+            for (const [name, value] of stream.headers.multiItems())
+                responseHeaders.append(name, value);
+            const empty = request.method === "HEAD" || [204, 205, 304].includes(stream.status);
+            const iterator = stream.body[Symbol.asyncIterator]();
+            const responseBody = empty ? null : new ReadableStream({
+                async pull(controller) {
+                    try {
+                        const item = await iterator.next();
+                        if (item.done) {
+                            await close();
+                            controller.close();
+                        }
+                        else
+                            controller.enqueue(item.value);
+                    }
+                    catch (error) {
+                        try {
+                            await close();
+                        }
+                        finally {
+                            controller.error(error);
+                        }
+                    }
+                },
+                async cancel() { try {
+                    await iterator.return?.();
+                }
+                finally {
+                    await close();
+                } },
+            }, { highWaterMark: 0 });
+            const response = new globalThis.Response(responseBody, { status: stream.status, headers: responseHeaders });
+            Object.defineProperties(response, {
+                url: { value: stream.url }, redirected: { value: stream.url !== request.url },
+                match: { value: stream.match }, httpVersion: { value: stream.httpVersion },
+            });
+            if (empty)
+                await close();
+            return response;
+        }
+        catch (error) {
+            await close();
+            throw error;
+        }
+    }
+    catch (error) {
+        if (owned)
+            await session.closeAsync();
+        throw error;
+    }
+}
+/** Fetch-compatible entry point. No persistent cookie jar is created. */
+async function fetch(input, init = {}) {
+    const options = { cookies: false, profile: init.profile, proxy: init.proxy,
+        proxyCaFile: init.proxyCaFile, caFile: init.caFile, library: init.library, timeoutMs: init.timeoutMs };
+    return fetchWithSession(new session_js_1.Session(options), input, init, true);
+}

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,18 @@
+export { Session } from "./session.js";
+export { fetch } from "./fetch.js";
+export type { FetchOptions, FetchResponse } from "./fetch.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,28 @@
+"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 fetch_js_1 = require("./fetch.js");
+Object.defineProperty(exports, "fetch", { enumerable: true, get: function () { return fetch_js_1.fetch; } });
+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,3 @@
+import sdk from './index.js';
+export const fetch = sdk.fetch;
+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;
+}