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

package/dist/notifications.d.ts

@@ -0,0 +1,40 @@
+import { type Socket } from "node:net";
+import { type Native } from "./native.js";
+type State = {
+    generation: number;
+    waiters: Set<() => void>;
+};
+/** One authenticated wakeup socket per session; bytes and state stay in the ABI. */
+export declare class Notifier {
+    private readonly native;
+    private readonly session;
+    readonly states: Map<bigint, State>;
+    readonly sockets: Set<Socket>;
+    readonly token: NonSharedBuffer;
+    private server?;
+    private writer?;
+    private registered;
+    private closed;
+    private failure?;
+    private readonly pendingClose;
+    private resolveReady;
+    private rejectReady;
+    readonly ready: Promise<void>;
+    isReady: boolean;
+    setupWaiters: number;
+    constructor(native: Native, session: bigint);
+    start(): Promise<void>;
+    private accept;
+    check(): void;
+    track(handle: bigint): void;
+    generation(handle: bigint): number;
+    pulse(handle: bigint): void;
+    forget(handle: bigint): void;
+    wait(handle: bigint, generation: number, signal: AbortSignal): Promise<void>;
+    probe<T>(handle: bigint, probe: () => T | undefined, signal: AbortSignal): Promise<T>;
+    private dispose;
+    private fail;
+    close(): void;
+    closeAsync(): Promise<void>;
+}
+export {};

package/dist/notifications.js

@@ -0,0 +1,222 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Notifier = void 0;
+const node_net_1 = require("node:net");
+const node_crypto_1 = require("node:crypto");
+const promises_1 = require("node:timers/promises");
+const errors_js_1 = require("./errors.js");
+const native_js_1 = require("./native.js");
+let budget = 32, resetScheduled = false;
+function fairTurn() {
+    if (!resetScheduled) {
+        resetScheduled = true;
+        setImmediate(() => { budget = 32; resetScheduled = false; });
+    }
+    return budget-- > 0 ? undefined : (0, promises_1.setImmediate)();
+}
+/** One authenticated wakeup socket per session; bytes and state stay in the ABI. */
+class Notifier {
+    native;
+    session;
+    states = new Map();
+    sockets = new Set();
+    token = (0, node_crypto_1.randomBytes)(32);
+    server;
+    writer;
+    registered = false;
+    closed = false;
+    failure;
+    pendingClose = new Set();
+    resolveReady;
+    rejectReady;
+    ready = new Promise((resolve, reject) => { this.resolveReady = resolve; this.rejectReady = reject; });
+    isReady = false;
+    setupWaiters = 0;
+    constructor(native, session) {
+        this.native = native;
+        this.session = session;
+        void this.ready.catch(() => { });
+    }
+    start() {
+        const timeout = setTimeout(() => {
+            try {
+                if (this.registered)
+                    this.native.call("session_events", this.session);
+                this.fail(new errors_js_1.FastlsError("could not start native notifications within 3 seconds"));
+            }
+            catch (cause) {
+                this.fail(new errors_js_1.FastlsError("could not start native notifications", { cause }));
+            }
+        }, 3000);
+        void this.ready.then(() => clearTimeout(timeout), () => clearTimeout(timeout));
+        try {
+            const server = this.server = (0, node_net_1.createServer)(socket => this.accept(socket));
+            server.on("error", error => this.fail(new errors_js_1.FastlsError("could not start native notifications", { cause: error })));
+            server.listen({ host: "127.0.0.1", port: 0, backlog: 2 }, () => {
+                if (this.closed || this.failure) {
+                    server.close();
+                    return;
+                }
+                try {
+                    const address = server.address();
+                    if (!address || typeof address === "string")
+                        throw new errors_js_1.FastlsError("invalid notification endpoint");
+                    this.native.call("session_watch", this.session, address.port, this.token, this.token.length);
+                    this.registered = true;
+                }
+                catch (error) {
+                    this.fail(new errors_js_1.FastlsError("could not start native notifications", { cause: error }));
+                }
+            });
+        }
+        catch (error) {
+            this.fail(new errors_js_1.FastlsError("could not start native notifications", { cause: error }));
+        }
+        return this.ready;
+    }
+    accept(socket) {
+        socket.on("error", error => { if (socket === this.writer)
+            this.fail(new errors_js_1.FastlsError("native notification connection failed", { cause: error })); });
+        if (this.closed || this.failure || this.writer || this.sockets.size >= 2) {
+            socket.destroy();
+            return;
+        }
+        this.sockets.add(socket);
+        const closing = new Promise(resolve => socket.once("close", () => { this.sockets.delete(socket); resolve(); if (socket === this.writer && !this.closed && !this.failure)
+            this.fail(new errors_js_1.FastlsError("native notification connection closed")); }));
+        this.pendingClose.add(closing);
+        void closing.then(() => this.pendingClose.delete(closing));
+        const handshake = Buffer.alloc(32);
+        let length = 0;
+        socket.setTimeout(1000, () => socket.destroy());
+        socket.on("data", chunk => {
+            try {
+                if (this.closed || this.failure)
+                    return;
+                if (socket !== this.writer) {
+                    const take = Math.min(32 - length, chunk.length);
+                    chunk.copy(handshake, length, 0, take);
+                    length += take;
+                    chunk = chunk.subarray(take);
+                    if (length !== 32)
+                        return;
+                    if (!(0, node_crypto_1.timingSafeEqual)(handshake, this.token) || this.writer) {
+                        socket.destroy();
+                        return;
+                    }
+                    this.writer = socket;
+                    socket.setTimeout(0);
+                    this.server?.close();
+                    for (const candidate of this.sockets)
+                        if (candidate !== socket)
+                            candidate.destroy();
+                    this.isReady = true;
+                    this.resolveReady();
+                }
+                if (!chunk.length)
+                    return;
+                if (chunk.some(byte => byte !== 1))
+                    throw new errors_js_1.FastlsError("invalid native notification packet");
+                const batch = this.native.call("session_events", this.session);
+                if (!Array.isArray(batch.handles) || batch.handles.length > 256 || typeof batch.overflow !== "boolean")
+                    throw new errors_js_1.FastlsError("invalid native notification batch");
+                for (const handle of batch.overflow ? [...this.states.keys()] : batch.handles.map(native_js_1.asHandle))
+                    this.pulse(handle);
+            }
+            catch (error) {
+                this.fail(new errors_js_1.FastlsError("native notifications failed", { cause: error }));
+            }
+        });
+    }
+    check() {
+        if (this.failure)
+            throw this.failure;
+        if (this.closed)
+            throw new errors_js_1.FastlsError("notification session is closed");
+    }
+    track(handle) { this.check(); this.states.set(handle, { generation: 0, waiters: new Set() }); }
+    generation(handle) { this.check(); return this.states.get(handle)?.generation ?? 0; }
+    pulse(handle) {
+        const state = this.states.get(handle);
+        if (!state)
+            return;
+        state.generation++;
+        for (const wake of [...state.waiters])
+            wake();
+    }
+    forget(handle) { const state = this.states.get(handle); this.states.delete(handle); if (state)
+        for (const wake of [...state.waiters])
+            wake(); }
+    wait(handle, generation, signal) {
+        this.check();
+        if (signal.aborted)
+            return Promise.reject(signal.reason);
+        const state = this.states.get(handle);
+        if (!state || state.generation !== generation)
+            return Promise.resolve();
+        return new Promise((resolve, reject) => {
+            const clean = () => { state.waiters.delete(wake); signal.removeEventListener("abort", abort); };
+            const wake = () => { clean(); try {
+                this.check();
+                resolve();
+            }
+            catch (error) {
+                reject(error);
+            } };
+            const abort = () => { clean(); reject(signal.reason); };
+            state.waiters.add(wake);
+            signal.addEventListener("abort", abort, { once: true });
+        });
+    }
+    async probe(handle, probe, signal) {
+        while (true) {
+            const pause = fairTurn();
+            if (pause)
+                await pause;
+            this.check();
+            if (signal.aborted)
+                throw signal.reason;
+            const generation = this.generation(handle), value = probe();
+            if (value !== undefined)
+                return value;
+            await this.wait(handle, generation, signal);
+        }
+    }
+    dispose() {
+        if (this.registered) {
+            this.registered = false;
+            this.native.call("session_unwatch", this.session);
+        }
+        if (this.server?.listening)
+            this.server.close();
+        for (const socket of this.sockets)
+            socket.destroy();
+    }
+    fail(error) {
+        if (this.closed || this.failure)
+            return;
+        this.failure = error;
+        this.rejectReady(error);
+        for (const handle of this.states.keys())
+            this.pulse(handle);
+        // A failing ABI cleanup must not throw out of a socket event callback.
+        try {
+            this.dispose();
+        }
+        catch {
+            for (const socket of this.sockets)
+                socket.destroy();
+        }
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.rejectReady(new errors_js_1.FastlsError("notification session is closed"));
+        for (const handle of [...this.states.keys()])
+            this.forget(handle);
+        this.dispose();
+    }
+    async closeAsync() { this.close(); await Promise.all([...this.pendingClose]); }
+}
+exports.Notifier = Notifier;

package/dist/request-options.d.ts

@@ -0,0 +1,28 @@
+import type { UploadBody } from "./upload.js";
+export type QueryScalar = string | Uint8Array | number | boolean | null | undefined;
+export type FormFields = Record<string, QueryScalar | readonly QueryScalar[]> | ReadonlyMap<string, QueryScalar | readonly QueryScalar[]> | readonly (readonly [string | Uint8Array, QueryScalar | readonly QueryScalar[]])[];
+export type QueryParams = FormFields | string;
+export type JSONValue = null | boolean | number | string | JSONValue[] | {
+    [key: string]: JSONValue;
+};
+/** Caller-owned binary reader. Return an empty array at EOF; never more than maxBytes. */
+export interface MultipartReader {
+    name?: string;
+    read(maxBytes: number, signal: AbortSignal): Uint8Array | Promise<Uint8Array>;
+}
+export type MultipartBody = Uint8Array | MultipartReader;
+export type MultipartFile = MultipartBody | readonly [string | null, MultipartBody, string?];
+export type MultipartFiles = Record<string, MultipartFile> | ReadonlyMap<string, MultipartFile> | readonly (readonly [string, MultipartFile])[];
+export interface EncodingOptions {
+    params?: QueryParams;
+    json?: JSONValue;
+    form?: FormFields;
+    files?: MultipartFiles;
+    body?: UploadBody;
+    duplex?: boolean;
+}
+/** Called before native handle allocation, with headers already merged. No file reads. */
+export declare function prepare(url: string, options: EncodingOptions, headers: Record<string, string>): {
+    url: string;
+    body: UploadBody | undefined;
+};

package/dist/request-options.js

@@ -0,0 +1,172 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prepare = prepare;
+const node_crypto_1 = require("node:crypto");
+const node_path_1 = require("node:path");
+const upload_js_1 = require("./upload.js");
+function pairs(value, name) {
+    if (value instanceof Map)
+        return [...value];
+    if (Array.isArray(value) && value.every(p => Array.isArray(p) && p.length === 2))
+        return value;
+    if (value && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null))
+        return Object.entries(value);
+    throw new TypeError(`${name} must be an object, Map or array of pairs`);
+}
+function scalar(value) {
+    if (typeof value === "string" || value instanceof Uint8Array)
+        return value;
+    if (typeof value === "boolean")
+        return value ? "True" : "False";
+    if (typeof value === "number" && Number.isFinite(value))
+        return String(value);
+    throw new TypeError("form/query values must be strings, bytes, finite numbers or booleans");
+}
+function values(value, name) {
+    const result = [];
+    for (const [key, item] of pairs(value, name)) {
+        if (typeof key !== "string" && !(key instanceof Uint8Array))
+            throw new TypeError(`${name} names must be strings or bytes`);
+        for (const part of Array.isArray(item) ? item : [item])
+            if (part !== null && part !== undefined)
+                result.push([key, scalar(part)]);
+    }
+    return result;
+}
+function quote(value) {
+    const bytes = typeof value === "string" ? Buffer.from(value) : value;
+    let encoded = "";
+    for (const b of bytes)
+        encoded += b === 32 ? "+" : (b >= 65 && b <= 90) || (b >= 97 && b <= 122) || (b >= 48 && b <= 57) || [45, 46, 95, 126].includes(b) ? String.fromCharCode(b) : `%${b.toString(16).toUpperCase().padStart(2, "0")}`;
+    return encoded;
+}
+function form(value) { return values(value, "form").map(([k, v]) => `${quote(k)}=${quote(v)}`).join("&"); }
+function metadata(value) {
+    if (typeof value !== "string" || /[\x00-\x1f\x7f]/.test(value))
+        throw new TypeError("multipart metadata must be strings without control characters");
+    return value.replaceAll("\\", "\\\\").replaceAll('"', "%22");
+}
+function validateJSON(value, stack = new Set()) {
+    if (value === null || typeof value === "string" || typeof value === "boolean" || (typeof value === "number" && Number.isFinite(value)))
+        return;
+    if (!value || typeof value !== "object" || (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null))
+        throw new TypeError("json must contain only JSON values and finite numbers");
+    if (stack.has(value))
+        throw new TypeError("json must not contain cycles");
+    if ("toJSON" in value)
+        throw new TypeError("json does not support toJSON hooks");
+    stack.add(value);
+    if (Array.isArray(value)) {
+        for (let i = 0; i < value.length; i++)
+            validateJSON(value[i], stack);
+    }
+    else {
+        for (const entry of Object.values(value))
+            validateJSON(entry, stack);
+    }
+    stack.delete(value);
+}
+class Multipart {
+    boundary = "fastls-" + (0, node_crypto_1.randomBytes)(24).toString("hex");
+    parts = [];
+    used = false;
+    constructor(fields, files) {
+        for (const [key, value] of fields === undefined ? [] : values(fields, "form")) {
+            const name = typeof key === "string" ? key : new TextDecoder("utf-8", { fatal: true }).decode(key);
+            this.add(`Content-Disposition: form-data; name="${metadata(name)}"\r\n`, typeof value === "string" ? Buffer.from(value) : value);
+        }
+        for (const [key, spec] of pairs(files, "files")) {
+            let filename, body, kind;
+            if (Array.isArray(spec)) {
+                if (spec.length !== 2 && spec.length !== 3)
+                    throw new TypeError("files tuples must be [filename, body, contentType?]");
+                [filename, body, kind] = spec;
+            }
+            else {
+                body = spec;
+                filename = (0, node_path_1.basename)(String(body?.name ?? key).replaceAll("\\", "/"));
+            }
+            if (!(body instanceof Uint8Array) && (!body || typeof body.read !== "function"))
+                throw new TypeError("files bodies must be bytes or binary readers");
+            let header = `Content-Disposition: form-data; name="${metadata(key)}"`;
+            if (filename !== null)
+                header += `; filename="${metadata(filename)}"`;
+            // Stable cross-platform subset; callers supply other media types explicitly.
+            const extension = typeof filename === "string" ? filename.slice(filename.lastIndexOf(".")).toLowerCase() : "";
+            kind ??= { ".txt": "text/plain", ".json": "application/json", ".html": "text/html", ".csv": "text/csv", ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".pdf": "application/pdf" }[extension] ?? "application/octet-stream";
+            metadata(kind);
+            this.add(header + `\r\nContent-Type: ${kind}\r\n`, body);
+        }
+    }
+    add(header, body) { this.parts.push({ header: Buffer.from(`--${this.boundary}\r\n${header}\r\n`), body }); }
+    async *chunks(signal) {
+        if (this.used)
+            throw new TypeError("multipart bodies cannot be replayed");
+        this.used = true;
+        for (const { header, body } of this.parts) {
+            signal.throwIfAborted();
+            yield header;
+            if (body instanceof Uint8Array) {
+                for (let offset = 0; offset < body.byteLength; offset += 65536)
+                    yield body.subarray(offset, offset + 65536);
+            }
+            else {
+                while (true) {
+                    signal.throwIfAborted();
+                    const block = await body.read(65536, signal);
+                    if (!(block instanceof Uint8Array) || block.byteLength > 65536)
+                        throw new TypeError("multipart readers must return at most 64KiB of bytes");
+                    if (!block.byteLength)
+                        break;
+                    yield block;
+                }
+            }
+            yield Buffer.from("\r\n");
+        }
+        const terminal = Buffer.from(`--${this.boundary}--\r\n`);
+        upload_js_1.terminalUploadChunks.add(terminal);
+        yield terminal;
+    }
+}
+/** Called before native handle allocation, with headers already merged. No file reads. */
+function prepare(url, options, headers) {
+    const hasJSON = Object.hasOwn(options, "json");
+    if (hasJSON && (options.body !== undefined || options.form !== undefined || options.files !== undefined))
+        throw new TypeError("json cannot be combined with body, form or files");
+    if (options.body !== undefined && (options.form !== undefined || options.files !== undefined))
+        throw new TypeError("body cannot be combined with form or files");
+    if (options.params !== undefined) {
+        const query = typeof options.params === "string" ? options.params : form(options.params);
+        if (/[^\x00-\x7f]|#/.test(query))
+            throw new TypeError("raw params must be an ASCII query without a fragment");
+        if (query) {
+            const fragment = url.indexOf("#"), base = fragment < 0 ? url : url.slice(0, fragment), hash = fragment < 0 ? "" : url.slice(fragment);
+            url = base + (base.includes("?") ? base.endsWith("?") ? "" : "&" : "?") + query + hash;
+        }
+    }
+    let body = options.body, kind;
+    if (options.files !== undefined) {
+        if (options.duplex)
+            throw new TypeError("multipart cannot be combined with duplex");
+        if ("content-type" in headers)
+            throw new TypeError("multipart manages Content-Type and its boundary");
+        const multipart = new Multipart(options.form, options.files);
+        body = signal => multipart.chunks(signal);
+        kind = `multipart/form-data; boundary=${multipart.boundary}`;
+    }
+    else if (hasJSON) {
+        validateJSON(options.json);
+        body = JSON.stringify(options.json);
+        kind = "application/json";
+    }
+    else if (options.form !== undefined) {
+        body = form(options.form);
+        kind = "application/x-www-form-urlencoded";
+    }
+    if (kind) {
+        if ("content-length" in headers || "transfer-encoding" in headers)
+            throw new TypeError("encoded bodies manage Content-Length and Transfer-Encoding");
+        headers["content-type"] ??= kind;
+    }
+    return { url, body };
+}

package/dist/response.d.ts

@@ -0,0 +1,84 @@
+import { Headers } from "./headers.js";
+import { Native, type NativeInfo } from "./native.js";
+import type { Notifier } from "./notifications.js";
+export declare const MAX_BUFFERED_BODY: number;
+export interface UploadLifecycle {
+    done: Promise<void>;
+    cleanup: Promise<void>;
+    complete(): boolean;
+    check(): void;
+}
+/** Owns one native request and all cancellation hooks. Internal to the SDK. */
+export declare class Transfer {
+    private readonly native;
+    private readonly handle;
+    private readonly release;
+    private readonly external?;
+    readonly duplex: boolean;
+    private readonly notifier?;
+    private readonly controller;
+    private closed;
+    private failure?;
+    private timer?;
+    private deadline?;
+    private readonly externalAbort;
+    constructor(native: Native, handle: bigint, release: () => void, external?: AbortSignal | undefined, duplex?: boolean, notifier?: Notifier | undefined);
+    private wait;
+    attachSignal(total?: number, started?: number): void;
+    get signal(): AbortSignal;
+    info(): NativeInfo;
+    write(buffer: Uint8Array, end: boolean, signal: AbortSignal): Promise<number>;
+    canWrite(): boolean;
+    throwFailure(): void;
+    headers(): Promise<NativeInfo>;
+    next(): Promise<Buffer | null>;
+    ensureOpen(): void;
+    close(error?: Error): void;
+}
+export declare class Response {
+    readonly status: number;
+    readonly headers: Headers;
+    readonly match: Readonly<Record<string, unknown>>;
+    readonly content: Buffer;
+    readonly wireHeaders: Headers;
+    readonly decoded: boolean;
+    readonly httpVersion: string;
+    readonly url: string;
+    readonly trailers: Headers;
+    encoding: string;
+    constructor(status: number, headers: Headers, match: Readonly<Record<string, unknown>>, content: Buffer, wireHeaders?: Headers, decoded?: boolean, httpVersion?: string, url?: string, trailers?: Headers);
+    get ok(): boolean;
+    raiseForStatus(): void;
+    text(): string;
+    json<T = unknown>(): T;
+}
+export declare class StreamResponse {
+    private readonly transfer;
+    private readonly upload?;
+    encoding: string;
+    httpVersion: string;
+    url: string;
+    trailers: Headers;
+    readonly status: number;
+    readonly headers: Headers;
+    readonly match: Readonly<Record<string, unknown>>;
+    readonly wireHeaders: Headers;
+    readonly decoded: boolean;
+    readonly body: AsyncIterable<Buffer>;
+    private consumed;
+    constructor(transfer: Transfer, info: NativeInfo, upload?: UploadLifecycle | undefined);
+    get ok(): boolean;
+    raiseForStatus(): void;
+    /** @internal Check cancellation even when a parser still holds buffered data. */
+    ensureOpen(): void;
+    private iterate;
+    read(): Promise<Buffer>;
+    text(): Promise<string>;
+    json<T = unknown>(): Promise<T>;
+    /** Consume the response concurrently: waiting alone can block on HTTP/2 flow control. */
+    waitUpload(): Promise<void>;
+    cancel(): void;
+    close(): void;
+    /** Wait for cooperative producer finalization after releasing the native request. */
+    closeAsync(): Promise<void>;
+}