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

package/dist/text.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.responseEncoding = responseEncoding;
+exports.decodeText = decodeText;
+exports.decodeJSON = decodeJSON;
+function responseEncoding(contentType) {
+    return /(?:^|;)\s*charset\s*=\s*(?:"([^"]+)"|'([^']+)'|([^;\s]+))/i.exec(contentType ?? "")?.slice(1).find(Boolean)?.toLowerCase() ?? "utf-8";
+}
+function decodeText(bytes, encoding) {
+    // WHATWG aliases ISO-8859-1 to Windows-1252. Preserve the declared Latin-1
+    // byte mapping, matching Python for the full 0..255 range.
+    if (/^(?:iso-8859-1|latin-?1)$/i.test(encoding))
+        return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString("latin1");
+    return new TextDecoder(encoding, { ignoreBOM: true }).decode(bytes);
+}
+function decodeJSON(bytes) {
+    let encoding = "utf-8", start = 0;
+    if (bytes.length >= 4 && ((bytes[0] === 0 && bytes[1] === 0 && bytes[2] === 254 && bytes[3] === 255) || (bytes[0] === 255 && bytes[1] === 254 && bytes[2] === 0 && bytes[3] === 0))) {
+        encoding = bytes[0] === 0 ? "utf-32be" : "utf-32le";
+        start = 4;
+    }
+    else if (bytes[0] === 254 && bytes[1] === 255) {
+        encoding = "utf-16be";
+        start = 2;
+    }
+    else if (bytes[0] === 255 && bytes[1] === 254) {
+        encoding = "utf-16le";
+        start = 2;
+    }
+    else if (bytes.length >= 4) {
+        if (bytes[0] === 0)
+            encoding = bytes[1] === 0 ? "utf-32be" : "utf-16be";
+        else if (bytes[1] === 0)
+            encoding = bytes[2] === 0 && bytes[3] === 0 ? "utf-32le" : "utf-16le";
+    }
+    else if (bytes.length === 2) {
+        if (bytes[0] === 0)
+            encoding = "utf-16be";
+        else if (bytes[1] === 0)
+            encoding = "utf-16le";
+    }
+    if (encoding.startsWith("utf-32")) {
+        if ((bytes.length - start) % 4)
+            throw new TypeError("invalid UTF-32 JSON");
+        const out = [];
+        for (let offset = start; offset < bytes.length; offset += 4) {
+            const cp = encoding === "utf-32le" ? bytes.readUInt32LE(offset) : bytes.readUInt32BE(offset);
+            if (cp > 0x10ffff || (cp >= 0xd800 && cp <= 0xdfff))
+                throw new TypeError("invalid UTF-32 JSON");
+            out.push(String.fromCodePoint(cp));
+        }
+        return out.join("");
+    }
+    return new TextDecoder(encoding, { fatal: true }).decode(bytes.subarray(start));
+}

package/dist/timeout.d.ts

@@ -0,0 +1,9 @@
+export interface TimeoutPolicy {
+    total: number;
+    connect?: number;
+    write?: number;
+    headers?: number;
+    read?: number;
+}
+export type Timeout = number | Readonly<TimeoutPolicy>;
+export declare function timeoutFields(value: Timeout): Record<string, number>;

package/dist/timeout.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.timeoutFields = timeoutFields;
+function timeoutFields(value) {
+    const policy = typeof value === "number" ? { total: value } : value;
+    if (!policy || typeof policy !== "object")
+        throw new TypeError("timeoutMs must be milliseconds or a timeout policy");
+    const fields = {};
+    for (const phase of ["total", "connect", "write", "headers", "read"]) {
+        const number = policy[phase];
+        if (number === undefined && phase !== "total")
+            continue;
+        if (!Number.isSafeInteger(number) || number < 1 || number > 86400000) {
+            throw new RangeError(`${phase} timeoutMs must be an integer in 1..86400000`);
+        }
+        fields[phase === "total" ? "timeout_ms" : `${phase}_timeout_ms`] = number;
+    }
+    return fields;
+}

package/dist/upload.d.ts

@@ -0,0 +1,11 @@
+import { Transfer, type UploadLifecycle } from "./response.js";
+export type ByteSource = Iterable<Uint8Array> | AsyncIterable<Uint8Array>;
+/** A factory can use the supplied signal to interrupt its own pending I/O. */
+export type UploadBody = string | Uint8Array | ByteSource | ((signal: AbortSignal) => ByteSource);
+/** Internal marker for a known last block; avoid an EOF race with early multipart responses. */
+export declare const terminalUploadChunks: WeakSet<Uint8Array<ArrayBufferLike>>;
+export declare function abortable<T>(promise: PromiseLike<T> | T, signal: AbortSignal): Promise<T>;
+export declare function isStreamingBody(value: UploadBody | undefined): boolean;
+export declare function startUpload(transfer: Transfer, body: UploadBody): UploadLifecycle & {
+    stop: () => void;
+};

package/dist/upload.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.terminalUploadChunks = void 0;
+exports.abortable = abortable;
+exports.isStreamingBody = isStreamingBody;
+exports.startUpload = startUpload;
+const promises_1 = require("node:timers/promises");
+/** Internal marker for a known last block; avoid an EOF race with early multipart responses. */
+exports.terminalUploadChunks = new WeakSet();
+function abortable(promise, signal) {
+    return new Promise((resolve, reject) => {
+        const abort = () => { signal.removeEventListener("abort", abort); reject(signal.reason); };
+        Promise.resolve(promise).then(value => {
+            signal.removeEventListener("abort", abort);
+            resolve(value);
+        }, error => { signal.removeEventListener("abort", abort); reject(error); });
+        if (signal.aborted)
+            abort();
+        else
+            signal.addEventListener("abort", abort, { once: true });
+    });
+}
+function* scalarChunks(value) {
+    if (typeof value === "string") {
+        for (let offset = 0; offset < value.length;) {
+            let end = Math.min(value.length, offset + 16384);
+            if (end < value.length && value.charCodeAt(end - 1) >= 0xd800 && value.charCodeAt(end - 1) <= 0xdbff)
+                end--;
+            yield Buffer.from(value.slice(offset, end), "utf8");
+            offset = end;
+        }
+    }
+    else {
+        for (let offset = 0; offset < value.byteLength; offset += 65536)
+            yield value.subarray(offset, offset + 65536);
+    }
+}
+function isStreamingBody(value) {
+    if (value === undefined)
+        return false;
+    if (typeof value === "string")
+        return value.length > 512 * 1024 || Buffer.byteLength(value) > 512 * 1024;
+    if (value instanceof Uint8Array)
+        return value.byteLength > 512 * 1024;
+    if (typeof value === "function" || (value && (Symbol.iterator in value || Symbol.asyncIterator in value)))
+        return true;
+    throw new TypeError("body must be string, Uint8Array, an iterable of bytes or an upload factory");
+}
+function startUpload(transfer, body) {
+    let completed = false;
+    let failure;
+    let clean;
+    let failCleanup;
+    const cleanup = new Promise((resolve, reject) => { clean = resolve; failCleanup = reject; });
+    // Cleanup is also awaited explicitly by closeAsync; keep synchronous close safe.
+    void cleanup.catch(() => { });
+    const controller = new AbortController();
+    const forwardAbort = () => controller.abort(transfer.signal.reason);
+    transfer.signal.addEventListener("abort", forwardAbort, { once: true });
+    if (transfer.signal.aborted)
+        forwardAbort();
+    const stop = () => controller.abort(new Error("upload finished"));
+    const done = (async () => {
+        let iterator;
+        let nextPending = false;
+        let pendingNext;
+        let source;
+        try {
+            source = typeof body === "function" ? body(controller.signal)
+                : typeof body === "string" || body instanceof Uint8Array ? scalarChunks(body) : body;
+            iterator = Symbol.asyncIterator in source ? source[Symbol.asyncIterator]() : source[Symbol.iterator]();
+            let turns = 0;
+            while (!controller.signal.aborted && transfer.canWrite()) {
+                nextPending = true;
+                pendingNext = Promise.resolve(iterator.next());
+                const result = await abortable(pendingNext, controller.signal);
+                nextPending = false;
+                pendingNext = undefined;
+                if (result.done) {
+                    completed = await transfer.write(Buffer.alloc(0), true, controller.signal) === 0;
+                    return;
+                }
+                if (!(result.value instanceof Uint8Array))
+                    throw new TypeError("upload chunks must be Uint8Array or Buffer");
+                const terminal = exports.terminalUploadChunks.has(result.value);
+                for (let offset = 0; offset < result.value.byteLength; offset += 65536) {
+                    const end = terminal && offset + 65536 >= result.value.byteLength;
+                    if (await transfer.write(result.value.subarray(offset, offset + 65536), end, controller.signal) === 2)
+                        return;
+                    if (end) {
+                        completed = true;
+                        return;
+                    }
+                }
+                if (++turns % 16 === 0)
+                    await (0, promises_1.setImmediate)();
+            }
+        }
+        catch (error) {
+            if (!controller.signal.aborted) {
+                failure = error instanceof Error ? error : new Error(String(error));
+                transfer.close(failure);
+            }
+        }
+        finally {
+            controller.abort(new Error("upload stopped"));
+            transfer.signal.removeEventListener("abort", forwardAbort);
+            const finishing = (async () => {
+                // Readable.destroy interrupts pending next(); arbitrary promises require cooperation.
+                if (source && "destroy" in source && typeof source.destroy === "function")
+                    source.destroy();
+                // Calling return() queues cleanup behind an outstanding async next().
+                // Observe both outcomes so an error thrown by finally is not swallowed
+                // when cancellation already won the abortable() race.
+                const results = await Promise.allSettled([pendingNext, iterator?.return?.()]);
+                for (const result of results) {
+                    if (result.status !== "rejected")
+                        continue;
+                    const error = result.reason;
+                    if (controller.signal.aborted && (error === controller.signal.reason || (error instanceof Error && error.name === "AbortError")))
+                        continue;
+                    throw error;
+                }
+            })();
+            void finishing.then(clean, error => {
+                failure ??= error instanceof Error ? error : new Error(String(error));
+                transfer.close(failure);
+                failCleanup(failure);
+            });
+            // A pending uncooperative next() must not delay native request cancellation.
+            if (!nextPending) {
+                try {
+                    await abortable(finishing, transfer.signal);
+                }
+                catch { /* failure retained above */ }
+            }
+        }
+    })();
+    return { done, cleanup, stop, complete: () => completed, check: () => { if (failure)
+            throw failure; } };
+}

package/dist/websocket.d.ts

@@ -0,0 +1,63 @@
+import { FastlsError } from "./errors.js";
+import { Headers } from "./headers.js";
+import type { Native, NativeInfo } from "./native.js";
+import type { Notifier } from "./notifications.js";
+import type { QueryParams } from "./request-options.js";
+export interface WebSocketOptions {
+    headers?: Record<string, string>;
+    profile?: string;
+    params?: QueryParams;
+    proxy?: string | null;
+    proxyCaFile?: string | null;
+    subprotocols?: readonly string[];
+    handshakeTimeoutMs?: number;
+    readTimeoutMs?: number | null;
+    writeTimeoutMs?: number;
+    cookieMode?: "session" | "manual";
+    closeTimeoutMs?: number;
+    maxMessageBytes?: number;
+    signal?: AbortSignal;
+}
+export declare class WebSocketClosed extends FastlsError {
+    readonly code: number;
+    readonly reason: string;
+    name: string;
+    constructor(code?: number, reason?: string);
+}
+export declare function wsBudget(value: number, name: string, maximum?: number): number;
+export declare class WebSocket {
+    private readonly native;
+    private readonly handle;
+    private readonly release;
+    readonly maxMessageBytes: number;
+    private readonly closeTimeoutMs;
+    private readonly notifier?;
+    private readonly external?;
+    private readonly controller;
+    private closed;
+    private reading;
+    private writing;
+    private failure?;
+    private last?;
+    private closing?;
+    private readonly externalAbort;
+    headers: Headers;
+    subprotocol: string;
+    constructor(native: Native, handle: bigint, release: () => void, maxMessageBytes: number, closeTimeoutMs: number, notifier?: Notifier | undefined, external?: AbortSignal | undefined);
+    private ensure;
+    get info(): NativeInfo;
+    get closeCode(): number;
+    get closeReason(): string;
+    private check;
+    private wait;
+    /** @internal */
+    opened(): Promise<this>;
+    private write;
+    send(message: string | Uint8Array): Promise<void>;
+    private control;
+    ping(data?: Uint8Array): Promise<void>;
+    pong(data?: Uint8Array): Promise<void>;
+    recv(): Promise<string | Buffer>;
+    closeAsync(code?: number, reason?: string): Promise<void>;
+    abort(error?: Error): void;
+}

package/dist/websocket.js

@@ -0,0 +1,248 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebSocket = exports.WebSocketClosed = void 0;
+exports.wsBudget = wsBudget;
+const promises_1 = require("node:timers/promises");
+const errors_js_1 = require("./errors.js");
+const headers_js_1 = require("./headers.js");
+const scheduler_js_1 = require("./scheduler.js");
+class WebSocketClosed extends errors_js_1.FastlsError {
+    code;
+    reason;
+    name = "WebSocketClosed";
+    constructor(code = 1006, reason = "") {
+        super(`WebSocket closed (${code})`);
+        this.code = code;
+        this.reason = reason;
+    }
+}
+exports.WebSocketClosed = WebSocketClosed;
+function wsBudget(value, name, maximum = 86400000) {
+    if (!Number.isSafeInteger(value) || value < 1 || value > maximum)
+        throw new RangeError(`${name} must be 1..${maximum} milliseconds`);
+    return value;
+}
+function closePayload(code, reason) {
+    if (!Number.isInteger(code) || !([1000, 1001, 1002, 1003, 1007, 1008, 1009, 1010, 1011, 1012, 1013, 1014].includes(code) || (code >= 3000 && code <= 4999)))
+        throw new RangeError("invalid WebSocket close code");
+    if (typeof reason !== "string" || /[\uD800-\uDFFF]/u.test(reason))
+        throw new TypeError("close reason must be well-formed Unicode");
+    const text = Buffer.from(reason);
+    if (text.length > 123)
+        throw new RangeError("close reason exceeds 123 UTF-8 bytes");
+    const out = Buffer.allocUnsafe(text.length + 2);
+    out.writeUInt16BE(code);
+    text.copy(out, 2);
+    return out;
+}
+const scratch = Buffer.allocUnsafe(65536);
+class WebSocket {
+    native;
+    handle;
+    release;
+    maxMessageBytes;
+    closeTimeoutMs;
+    notifier;
+    external;
+    controller = new AbortController();
+    closed = false;
+    reading = false;
+    writing = false;
+    failure;
+    last;
+    closing;
+    externalAbort = () => this.abort(new errors_js_1.AbortError(undefined, { cause: this.external?.reason }));
+    headers = new headers_js_1.Headers();
+    subprotocol = "";
+    constructor(native, handle, release, maxMessageBytes, closeTimeoutMs, notifier, external) {
+        this.native = native;
+        this.handle = handle;
+        this.release = release;
+        this.maxMessageBytes = maxMessageBytes;
+        this.closeTimeoutMs = closeTimeoutMs;
+        this.notifier = notifier;
+        this.external = external;
+        external?.addEventListener("abort", this.externalAbort, { once: true });
+        if (external?.aborted)
+            this.externalAbort();
+    }
+    ensure() { if (this.closed)
+        throw this.failure ?? new errors_js_1.FastlsError("WebSocket is closed"); }
+    get info() { if (this.closed && this.last)
+        return this.last; this.ensure(); return this.last = this.native.call("info", this.handle); }
+    get closeCode() { return (this.closed ? this.last : this.info)?.websocket?.close_code ?? 1006; }
+    get closeReason() { return (this.closed ? this.last : this.info)?.websocket?.close_reason ?? ""; }
+    check(info) {
+        if (info.state === "error")
+            throw (0, errors_js_1.responseError)(info);
+        if (info.state === "eof")
+            throw new WebSocketClosed(info.websocket?.close_code, info.websocket?.close_reason);
+    }
+    wait(probe, signal = this.controller.signal) {
+        return this.notifier ? this.notifier.probe(this.handle, probe, signal) : scheduler_js_1.scheduler.wait(probe, signal);
+    }
+    /** @internal */
+    async opened() {
+        try {
+            const info = await this.wait(() => { const i = this.info; if (i.status === 101 && (i.state === "headers" || i.state === "eof"))
+                return i; this.check(i); return i.state === "pending" ? undefined : i; });
+            this.headers = new headers_js_1.Headers(info.header_values, info.headers);
+            this.subprotocol = info.websocket?.subprotocol ?? "";
+            return this;
+        }
+        catch (error) {
+            this.abort(error instanceof Error ? error : undefined);
+            throw error;
+        }
+    }
+    async write(opcode, data, signal = this.controller.signal) {
+        this.ensure();
+        if (this.writing)
+            throw new errors_js_1.FastlsError("another WebSocket send is active");
+        this.writing = true;
+        try {
+            let accepted = false;
+            await this.wait(() => {
+                const info = this.info;
+                this.check(info);
+                if (accepted)
+                    return !info.websocket.write_pending ? true : undefined;
+                const code = this.native.wsSend(this.handle, opcode, data);
+                if (code < 0) {
+                    this.check(this.info);
+                    throw new errors_js_1.FastlsError("invalid WebSocket send or connection is closing");
+                }
+                if (code !== 0 && code !== 1)
+                    throw new errors_js_1.FastlsError("invalid WebSocket send status");
+                if (code === 0) {
+                    accepted = true;
+                    const next = this.info;
+                    this.check(next);
+                    if (!next.websocket.write_pending)
+                        return true;
+                }
+                return undefined;
+            }, signal);
+        }
+        catch (error) {
+            this.abort(error instanceof Error ? error : undefined);
+            throw error;
+        }
+        finally {
+            this.writing = false;
+        }
+    }
+    send(message) {
+        if (typeof message !== "string" && !(message instanceof Uint8Array))
+            return Promise.reject(new TypeError("WebSocket messages must be strings or bytes"));
+        if (typeof message === "string" && /[\uD800-\uDFFF]/u.test(message))
+            return Promise.reject(new TypeError("WebSocket text must be well-formed Unicode"));
+        if ((typeof message === "string" ? Buffer.byteLength(message) : message.byteLength) > this.maxMessageBytes)
+            return Promise.reject(new RangeError("WebSocket message exceeds maxMessageBytes"));
+        // Copy before any await: accepted data must not observe caller mutation.
+        return this.write(typeof message === "string" ? 1 : 2, Buffer.from(message));
+    }
+    control(opcode, data) {
+        if (!(data instanceof Uint8Array))
+            return Promise.reject(new TypeError("control payload must be bytes"));
+        if (data.byteLength > 125)
+            return Promise.reject(new RangeError("control payload exceeds 125 bytes"));
+        return this.write(opcode, Buffer.from(data));
+    }
+    ping(data = Buffer.alloc(0)) { return this.control(9, data); }
+    pong(data = Buffer.alloc(0)) { return this.control(10, data); }
+    async recv() {
+        this.ensure();
+        if (this.reading)
+            throw new errors_js_1.FastlsError("another WebSocket recv is active");
+        this.reading = true;
+        try {
+            let content = Buffer.alloc(0), length = 0, kind, turns = 0;
+            while (true) {
+                const block = await this.wait(() => {
+                    this.ensure();
+                    const r = this.native.wsRead(this.handle, scratch);
+                    if (r.code === 1)
+                        return undefined;
+                    if (r.code !== 0) {
+                        this.check(this.info);
+                        throw new WebSocketClosed();
+                    }
+                    if (![1, 2].includes(r.opcode))
+                        throw new errors_js_1.FastlsError("invalid WebSocket message opcode");
+                    return { ...r, data: Buffer.from(scratch.subarray(0, r.length)) };
+                });
+                kind ??= block.opcode;
+                if (block.opcode !== kind)
+                    throw new errors_js_1.FastlsError("WebSocket message opcode changed mid-message");
+                const size = length + block.length;
+                if (size > this.maxMessageBytes)
+                    throw new errors_js_1.FastlsError("WebSocket message exceeds maxMessageBytes");
+                if (size > content.length) {
+                    const grown = Buffer.allocUnsafe(Math.min(this.maxMessageBytes, Math.max(size, content.length * 2)));
+                    content.copy(grown, 0, 0, length);
+                    content = grown;
+                }
+                block.data.copy(content, length);
+                length = size;
+                if (block.end) {
+                    const bytes = content.subarray(0, length);
+                    return kind === 1 ? new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes) : Buffer.from(bytes);
+                }
+                if (++turns % 16 === 0)
+                    await (0, promises_1.setImmediate)();
+            }
+        }
+        catch (error) {
+            this.abort(error instanceof Error ? error : undefined);
+            throw error;
+        }
+        finally {
+            this.reading = false;
+        }
+    }
+    closeAsync(code = 1000, reason = "") {
+        const data = closePayload(code, reason);
+        if (this.closing)
+            return this.closing;
+        if (this.closed)
+            return Promise.resolve();
+        this.closing = (async () => {
+            const budget = new AbortController(), timer = setTimeout(() => budget.abort(new errors_js_1.FastlsError("WebSocket close timed out")), this.closeTimeoutMs);
+            const signal = AbortSignal.any([this.controller.signal, budget.signal]);
+            try {
+                if (this.info.state === "headers") {
+                    // A close may interrupt a pending reader/writer after its total budget.
+                    if (!this.writing)
+                        await this.write(8, data, signal);
+                    await this.wait(() => { const info = this.info; return info.state !== "headers" ? true : undefined; }, signal);
+                }
+            }
+            catch { /* Closing always releases the handle, including a stalled peer. */ }
+            finally {
+                clearTimeout(timer);
+                this.abort();
+            }
+        })();
+        return this.closing;
+    }
+    abort(error) {
+        if (this.closed)
+            return;
+        try {
+            this.last = this.native.call("info", this.handle);
+        }
+        catch { /* Retain last metadata on teardown. */ }
+        this.closed = true;
+        this.failure = error;
+        this.external?.removeEventListener("abort", this.externalAbort);
+        this.controller.abort(error ?? new errors_js_1.FastlsError("WebSocket is closed"));
+        try {
+            this.native.call("close", this.handle);
+        }
+        finally {
+            this.release();
+        }
+    }
+}
+exports.WebSocket = WebSocket;

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@fastls/fastls",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.10.1-dev.0",
+  "description": "Node.js bindings for the Fastls C ABI",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "koffi": "3.3.3",
+    "lossless-json": "4.3.3"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FastTLS/fastls-ffi.git",
+    "directory": "node"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "optionalDependencies": {
+    "@fastls/fastls-win32-x64": "0.10.1-dev.0",
+    "@fastls/fastls-linux-x64-glibc": "0.10.1-dev.0",
+    "@fastls/fastls-linux-arm64-glibc": "0.10.1-dev.0",
+    "@fastls/fastls-darwin-x64": "0.10.1-dev.0",
+    "@fastls/fastls-darwin-arm64": "0.10.1-dev.0"
+  }
+}