@fastls/fastls 0.0.0-stage → 0.10.1

package/dist/sse.js

@@ -0,0 +1,197 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SSEStream = exports.SSEDecoder = exports.ServerSentEvent = void 0;
+exports.validateSSEOptions = validateSSEOptions;
+const promises_1 = require("node:timers/promises");
+const errors_js_1 = require("./errors.js");
+class ServerSentEvent {
+    data;
+    event;
+    id;
+    retry;
+    constructor(data, event = "message", id = "", retry) {
+        this.data = data;
+        this.event = event;
+        this.id = id;
+        this.retry = retry;
+        Object.freeze(this);
+    }
+    json() { return JSON.parse(this.data); }
+}
+exports.ServerSentEvent = ServerSentEvent;
+function validateSSEOptions(maximum, initialId) {
+    if (!Number.isSafeInteger(maximum) || maximum < 1 || maximum > 64 * 1024 * 1024) {
+        throw new RangeError("maxEventBytes must be 1..67108864");
+    }
+    if (initialId !== undefined) {
+        if (typeof initialId !== "string")
+            throw new TypeError("lastEventId must be a string");
+        if (/[\0\r\n]/.test(initialId))
+            throw new TypeError("lastEventId must not contain NUL, CR or LF");
+        if (Buffer.byteLength(initialId) > maximum)
+            throw new RangeError("lastEventId exceeds maxEventBytes");
+    }
+}
+/** Internal pull parser. feed() pauses at each event, including within one chunk. */
+class SSEDecoder {
+    maximum;
+    lastEventId;
+    retry;
+    id;
+    blockRetry;
+    line = Buffer.alloc(0);
+    length = 0;
+    data = [];
+    size = 0;
+    event = "";
+    first = true;
+    skipLF = false;
+    constructor(maximum, initialId = "") {
+        this.maximum = maximum;
+        this.id = this.lastEventId = initialId;
+    }
+    append(part) {
+        const required = this.length + part.length;
+        if (required > this.maximum)
+            throw new errors_js_1.FastlsError("SSE line exceeds maxEventBytes");
+        if (required > this.line.length) {
+            const grown = Buffer.allocUnsafe(Math.min(this.maximum, Math.max(required, this.line.length * 2, 256)));
+            this.line.copy(grown, 0, 0, this.length);
+            this.line = grown;
+        }
+        this.line.set(part, this.length);
+        this.length = required;
+    }
+    processLine() {
+        let line = this.line.toString("utf8", 0, this.length);
+        this.length = 0;
+        if (this.first) {
+            if (line.startsWith("\ufeff"))
+                line = line.slice(1);
+            this.first = false;
+        }
+        if (line === "") {
+            this.lastEventId = this.id;
+            const event = this.data.length ? new ServerSentEvent(this.data.join("\n"), this.event || "message", this.id, this.blockRetry) : undefined;
+            this.data = [];
+            this.size = 0;
+            this.event = "";
+            this.blockRetry = undefined;
+            return event;
+        }
+        if (line.startsWith(":"))
+            return;
+        const colon = line.indexOf(":"), field = colon < 0 ? line : line.slice(0, colon);
+        let value = colon < 0 ? "" : line.slice(colon + 1);
+        if (value.startsWith(" "))
+            value = value.slice(1);
+        if (field === "data") {
+            const size = this.size + Buffer.byteLength(value) + (this.data.length ? 1 : 0);
+            if (size > this.maximum)
+                throw new errors_js_1.FastlsError("SSE event exceeds maxEventBytes");
+            this.size = size;
+            this.data.push(value);
+        }
+        else if (field === "event")
+            this.event = value;
+        else if (field === "id" && !value.includes("\0"))
+            this.id = value;
+        else if (field === "retry" && /^[0-9]+$/.test(value)) {
+            const digits = value.replace(/^0+/, "") || "0", ceiling = "2147483647";
+            this.retry = this.blockRetry = digits.length > ceiling.length || (digits.length === ceiling.length && digits > ceiling) ? 2147483647 : Number(digits);
+        }
+    }
+    *feed(chunk) {
+        if (!chunk.length)
+            return;
+        let start = 0;
+        if (this.skipLF) {
+            if (chunk[0] === 10)
+                start = 1;
+            this.skipLF = false;
+        }
+        for (let i = start; i < chunk.length; i++) {
+            if (chunk[i] !== 10 && chunk[i] !== 13)
+                continue;
+            this.append(chunk.subarray(start, i));
+            const event = this.processLine();
+            if (chunk[i] === 13) {
+                if (chunk[i + 1] === 10)
+                    i++;
+                else if (i + 1 === chunk.length)
+                    this.skipLF = true;
+            }
+            start = i + 1;
+            if (event)
+                yield event;
+        }
+        this.append(chunk.subarray(start));
+    }
+    finish() {
+        this.line = Buffer.alloc(0);
+        this.length = 0;
+        this.data = [];
+        this.size = 0;
+        this.event = "";
+        this.id = this.lastEventId;
+    }
+}
+exports.SSEDecoder = SSEDecoder;
+class SSEStream {
+    response;
+    decoder;
+    started = false;
+    closed = false;
+    constructor(response, maximum = 1024 * 1024, initialId) {
+        this.response = response;
+        validateSSEOptions(maximum, initialId);
+        this.decoder = new SSEDecoder(maximum, initialId);
+        if (response.status === 204)
+            return;
+        if (response.status !== 200)
+            throw new errors_js_1.FastlsError(`SSE requires HTTP 200, received ${response.status}`);
+        const types = response.headers.getAll("content-type");
+        if (types.length !== 1 || types[0].split(";", 1)[0].replace(/^[ \t]+|[ \t]+$/g, "").toLowerCase() !== "text/event-stream") {
+            throw new errors_js_1.FastlsError("SSE requires Content-Type text/event-stream");
+        }
+        const encodings = response.wireHeaders.getAll("content-encoding").flatMap(value => value.split(",")).map(value => value.trim().toLowerCase());
+        if (!response.decoded && encodings.some(value => value !== "" && value !== "identity")) {
+            throw new errors_js_1.FastlsError("SSE requires decoded content; enable decodeContent");
+        }
+    }
+    get lastEventId() { return this.decoder.lastEventId; }
+    get retry() { return this.decoder.retry; }
+    checkOpen() {
+        if (this.closed)
+            throw new errors_js_1.FastlsError("SSE stream is closed or cancelled");
+        this.response.ensureOpen();
+    }
+    [Symbol.asyncIterator]() {
+        this.checkOpen();
+        if (this.started)
+            throw new errors_js_1.FastlsError("SSE stream permits only one consumer");
+        this.started = true;
+        return this.events();
+    }
+    async *events() {
+        try {
+            if (this.response.status === 204)
+                return;
+            for await (const chunk of this.response.body) {
+                for (const event of this.decoder.feed(chunk)) {
+                    this.checkOpen();
+                    yield event;
+                    // Even many events in one native read must let timers and cancellation run.
+                    await (0, promises_1.setImmediate)();
+                }
+            }
+        }
+        finally {
+            await this.closeAsync();
+        }
+    }
+    cancel() { this.closed = true; this.decoder.finish(); this.response.cancel(); }
+    close() { this.closed = true; this.decoder.finish(); this.response.close(); }
+    async closeAsync() { this.close(); await this.response.closeAsync(); }
+}
+exports.SSEStream = SSEStream;

package/dist/text.d.ts

@@ -0,0 +1,3 @@
+export declare function responseEncoding(contentType: string | undefined): string;
+export declare function decodeText(bytes: Uint8Array, encoding: string): string;
+export declare function decodeJSON(bytes: Buffer): string;

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