@fastls/fastls 0.0.0-stage → 0.10.1

package/dist/native.js

@@ -0,0 +1,211 @@
+"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"));
+            if (features.has("transport_context_v1")) {
+                this.functions.transport_create = lib.func("void *fastls_transport_create(void)");
+            }
+            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;

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 };
+}