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

package/dist/response.js

@@ -0,0 +1,242 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StreamResponse = exports.Response = exports.Transfer = exports.MAX_BUFFERED_BODY = void 0;
+const errors_js_1 = require("./errors.js");
+const text_js_1 = require("./text.js");
+const headers_js_1 = require("./headers.js");
+const scheduler_js_1 = require("./scheduler.js");
+exports.MAX_BUFFERED_BODY = 32 * 1024 * 1024;
+// ABI reads are synchronous and main-thread-only. Copy each result before another
+// probe runs, so pending requests can share scratch space without retaining it.
+const READ_BUFFER = Buffer.allocUnsafe(65536);
+/** Owns one native request and all cancellation hooks. Internal to the SDK. */
+class Transfer {
+    native;
+    handle;
+    release;
+    external;
+    duplex;
+    notifier;
+    controller = new AbortController();
+    closed = false;
+    failure;
+    timer;
+    deadline;
+    externalAbort = () => this.close(new errors_js_1.AbortError(undefined, { cause: this.external?.reason }));
+    constructor(native, handle, release, external, duplex = false, notifier) {
+        this.native = native;
+        this.handle = handle;
+        this.release = release;
+        this.external = external;
+        this.duplex = duplex;
+        this.notifier = notifier;
+    }
+    wait(probe, signal) {
+        return this.notifier ? this.notifier.probe(this.handle, probe, signal) : scheduler_js_1.scheduler.wait(probe, signal);
+    }
+    attachSignal(total, started = performance.now()) {
+        this.external?.addEventListener("abort", this.externalAbort, { once: true });
+        if (this.external?.aborted)
+            this.externalAbort();
+        if (total && !this.closed) {
+            this.deadline = started + total;
+            this.timer = setTimeout(() => this.close(new errors_js_1.FastlsTimeoutError("total deadline exceeded", "total")), Math.max(1, this.deadline - performance.now()));
+        }
+    }
+    get signal() { return this.controller.signal; }
+    info() {
+        this.ensureOpen();
+        const info = this.native.call("info", this.handle);
+        if (info.state === "error")
+            throw (0, errors_js_1.responseError)(info);
+        return info;
+    }
+    write(buffer, end, signal) {
+        return this.wait(() => {
+            if (!this.canWrite())
+                return 2;
+            const code = this.native.write(this.handle, buffer, end);
+            return code === 1 ? undefined : code;
+        }, signal);
+    }
+    canWrite() {
+        const info = this.info();
+        return info.state === "pending" || (this.duplex && info.state === "headers" && info.status < 300);
+    }
+    throwFailure() { if (this.failure)
+        throw this.failure; }
+    async headers() {
+        return this.wait(() => {
+            this.ensureOpen();
+            const info = this.info();
+            return info.state === "pending" ? undefined : info;
+        }, this.controller.signal);
+    }
+    async next() {
+        this.ensureOpen();
+        const buffer = READ_BUFFER;
+        const result = await this.wait(() => {
+            this.ensureOpen();
+            const { code, length } = this.native.read(this.handle, buffer);
+            if (code === 1)
+                return undefined;
+            if (code === 2)
+                return null;
+            if (!length)
+                throw new errors_js_1.FastlsError("native data result was empty");
+            return Buffer.from(buffer.subarray(0, length));
+        }, this.controller.signal);
+        this.ensureOpen();
+        return result;
+    }
+    ensureOpen() {
+        if (!this.closed && this.deadline !== undefined && performance.now() >= this.deadline) {
+            this.close(new errors_js_1.FastlsTimeoutError("total deadline exceeded", "total"));
+        }
+        if (this.closed)
+            throw this.failure ?? new errors_js_1.FastlsError("response is closed");
+    }
+    close(error) {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.failure = error;
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.external?.removeEventListener("abort", this.externalAbort);
+        this.controller.abort(error ?? new errors_js_1.FastlsError("response is closed"));
+        try {
+            this.native.call("close", this.handle);
+        }
+        finally {
+            this.release();
+        }
+    }
+}
+exports.Transfer = Transfer;
+class Response {
+    status;
+    headers;
+    match;
+    content;
+    wireHeaders;
+    decoded;
+    httpVersion;
+    url;
+    trailers;
+    encoding;
+    constructor(status, headers, match, content, wireHeaders = headers, decoded = false, httpVersion = "", url = "", trailers = new headers_js_1.Headers()) {
+        this.status = status;
+        this.headers = headers;
+        this.match = match;
+        this.content = content;
+        this.wireHeaders = wireHeaders;
+        this.decoded = decoded;
+        this.httpVersion = httpVersion;
+        this.url = url;
+        this.trailers = trailers;
+        this.encoding = (0, text_js_1.responseEncoding)(headers.get("content-type"));
+    }
+    get ok() { return this.status < 400; }
+    raiseForStatus() { if (this.status >= 400 && this.status <= 599)
+        throw new errors_js_1.FastlsHTTPError(this); }
+    text() { return (0, text_js_1.decodeText)(this.content, this.encoding); }
+    json() { return JSON.parse((0, text_js_1.decodeJSON)(this.content)); }
+}
+exports.Response = Response;
+class StreamResponse {
+    transfer;
+    upload;
+    encoding;
+    httpVersion;
+    url;
+    trailers;
+    status;
+    headers;
+    match;
+    wireHeaders;
+    decoded;
+    body;
+    consumed = false;
+    constructor(transfer, info, upload) {
+        this.transfer = transfer;
+        this.upload = upload;
+        this.status = info.status;
+        this.httpVersion = info.protocol ?? "";
+        this.url = info.final_url ?? "";
+        this.trailers = new headers_js_1.Headers(info.trailer_values);
+        this.headers = new headers_js_1.Headers(info.header_values, info.headers);
+        this.encoding = (0, text_js_1.responseEncoding)(this.headers.get("content-type"));
+        this.wireHeaders = info.wire_header_values ? new headers_js_1.Headers(info.wire_header_values) : this.headers;
+        this.decoded = info.decoded ?? false;
+        this.match = Object.freeze({ ...info.match });
+        this.body = { [Symbol.asyncIterator]: () => this.iterate() };
+    }
+    get ok() { return this.status < 400; }
+    raiseForStatus() { if (this.status >= 400 && this.status <= 599)
+        throw new errors_js_1.FastlsHTTPError(this); }
+    /** @internal Check cancellation even when a parser still holds buffered data. */
+    ensureOpen() { this.transfer.ensureOpen(); }
+    async *iterate() {
+        if (this.consumed)
+            throw new errors_js_1.FastlsError("response body already has a consumer");
+        this.consumed = true;
+        try {
+            while (true) {
+                const chunk = await this.transfer.next();
+                if (chunk === null) {
+                    const info = this.transfer.info();
+                    this.httpVersion = info.protocol ?? this.httpVersion;
+                    this.url = info.final_url ?? this.url;
+                    this.trailers = new headers_js_1.Headers(info.trailer_values);
+                    return;
+                }
+                yield chunk;
+            }
+        }
+        finally {
+            await this.closeAsync();
+        }
+    }
+    async read() {
+        let content = Buffer.alloc(0);
+        let length = 0;
+        for await (const chunk of this.body) {
+            const required = length + chunk.length;
+            if (required > exports.MAX_BUFFERED_BODY)
+                throw new errors_js_1.FastlsError("buffered response exceeds 32MiB; use streaming");
+            if (required > content.length) {
+                const grown = Buffer.allocUnsafe(Math.min(exports.MAX_BUFFERED_BODY, Math.max(required, content.length * 2)));
+                content.copy(grown, 0, 0, length);
+                content = grown;
+            }
+            chunk.copy(content, length);
+            length = required;
+        }
+        return length === content.length ? content : Buffer.from(content.subarray(0, length));
+    }
+    async text() { return (0, text_js_1.decodeText)(await this.read(), this.encoding); }
+    async json() { return JSON.parse((0, text_js_1.decodeJSON)(await this.read())); }
+    /** Consume the response concurrently: waiting alone can block on HTTP/2 flow control. */
+    async waitUpload() {
+        if (!this.upload)
+            return;
+        await this.upload.done;
+        this.upload.check();
+        if (!this.upload.complete()) {
+            this.transfer.throwFailure();
+            throw new errors_js_1.FastlsError("upload ended before EOF was accepted");
+        }
+    }
+    cancel() { this.transfer.close(new errors_js_1.AbortError()); }
+    close() { this.transfer.close(); }
+    /** Wait for cooperative producer finalization after releasing the native request. */
+    async closeAsync() {
+        this.close();
+        if (this.upload) {
+            await this.upload.cleanup;
+            this.upload.check();
+        }
+    }
+}
+exports.StreamResponse = StreamResponse;

package/dist/scheduler.d.ts

@@ -0,0 +1,12 @@
+/** One bounded timer queue for all pending header/read operations in this SDK. */
+declare class Scheduler {
+    private pending;
+    private timer?;
+    private immediateBudget;
+    private resetScheduled;
+    wait<T>(probe: () => T | undefined, signal: AbortSignal): Promise<T>;
+    private schedule;
+    private tick;
+}
+export declare const scheduler: Scheduler;
+export {};

package/dist/scheduler.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scheduler = void 0;
+/** One bounded timer queue for all pending header/read operations in this SDK. */
+class Scheduler {
+    pending = new Set();
+    timer;
+    immediateBudget = 32;
+    resetScheduled = false;
+    wait(probe, signal) {
+        return new Promise((resolve, reject) => {
+            const cleanup = () => {
+                this.pending.delete(check);
+                signal.removeEventListener("abort", abort);
+                if (!this.pending.size && this.timer) {
+                    clearTimeout(this.timer);
+                    this.timer = undefined;
+                }
+            };
+            const abort = () => { cleanup(); reject(signal.reason); };
+            const check = () => {
+                try {
+                    if (signal.aborted) {
+                        abort();
+                        return true;
+                    }
+                    const value = probe();
+                    if (value === undefined)
+                        return false;
+                    cleanup();
+                    resolve(value);
+                }
+                catch (error) {
+                    cleanup();
+                    reject(error);
+                }
+                return true;
+            };
+            if (this.immediateBudget > 0) {
+                this.immediateBudget--;
+                if (!this.resetScheduled) {
+                    this.resetScheduled = true;
+                    setImmediate(() => { this.immediateBudget = 32; this.resetScheduled = false; });
+                }
+                if (check())
+                    return;
+            }
+            if (signal.aborted) {
+                abort();
+                return;
+            }
+            signal.addEventListener("abort", abort, { once: true });
+            this.pending.add(check);
+            this.schedule();
+        });
+    }
+    schedule() {
+        if (!this.timer && this.pending.size)
+            this.timer = setTimeout(() => this.tick(), 10);
+    }
+    tick() {
+        this.timer = undefined;
+        const deadline = performance.now() + 4;
+        // Rotate pending work so the same slow requests cannot monopolize each tick.
+        for (const check of [...this.pending].slice(0, 32)) {
+            this.pending.delete(check);
+            if (!check())
+                this.pending.add(check);
+            if (performance.now() >= deadline)
+                break;
+        }
+        this.schedule();
+    }
+}
+exports.scheduler = new Scheduler();

package/dist/session.d.ts

@@ -0,0 +1,101 @@
+import { Cookies } from "./cookies.js";
+import { Response, StreamResponse } from "./response.js";
+import { type Timeout } from "./timeout.js";
+import { type UploadBody } from "./upload.js";
+import { DuplexExchange } from "./duplex.js";
+import { SSEStream, type SSEOptions } from "./sse.js";
+import { type QueryParams, type JSONValue, type FormFields, type MultipartFiles } from "./request-options.js";
+import { WebSocket, type WebSocketOptions } from "./websocket.js";
+export interface RequestOptions {
+    /** Undefined inherits the session proxy; null or an empty string connects directly. */
+    proxy?: string | null;
+    /** Undefined inherits proxy trust; null uses system roots. Only HTTPS proxies use this file. */
+    proxyCaFile?: string | null;
+    profile?: string;
+    headers?: Record<string, string>;
+    trailers?: Record<string, string | readonly string[]>;
+    /** Total deadline including response body consumption, in milliseconds. */
+    timeoutMs?: Timeout;
+    allowRedirects?: boolean;
+    body?: UploadBody;
+    params?: QueryParams;
+    json?: JSONValue;
+    form?: FormFields;
+    files?: MultipartFiles;
+    decodeContent?: boolean;
+    maxDecodedBytes?: number;
+    signal?: AbortSignal;
+    /** Explicit HTTP/2 simultaneous upload/download. Redirects are disabled. */
+    duplex?: boolean;
+}
+export type DuplexOptions = Omit<RequestOptions, "body" | "duplex" | "json" | "form" | "files">;
+export interface SessionOptions {
+    /** HTTP/HTTPS CONNECT, socks5 (local DNS), or socks5h (proxy DNS) URL. */
+    proxy?: string | null;
+    /** Private roots for proxy TLS, independent of the target's caFile. */
+    proxyCaFile?: string | null;
+    notifications?: "auto" | "required" | "poll";
+    profile?: string;
+    headers?: Record<string, string>;
+    timeoutMs?: Timeout;
+    library?: string;
+    /** Private CA roots replacing system roots for this session only. */
+    caFile?: string;
+    cookies?: boolean;
+    decodeContent?: boolean;
+    maxDecodedBytes?: number;
+}
+export interface Stats {
+    notifiers?: number;
+    open_requests: number;
+    open_sessions: number;
+    session_pools: number;
+    workers: number;
+    buffered_body_bytes: number;
+    buffered_upload_bytes: number;
+    goroutines: number;
+    heap_alloc_bytes: number;
+    heap_inuse_bytes: number;
+    buffered_ws_write_bytes?: number;
+}
+export declare class Session {
+    /** Construct and initialize; failed initialization closes the new session. */
+    static open(options?: SessionOptions): Promise<Session>;
+    readonly notificationMode: "async-events" | "poll";
+    readonly cookies: Cookies;
+    private readonly native;
+    private readonly handle;
+    private readonly profile;
+    private readonly proxy;
+    private readonly proxyCaPem;
+    private readonly headers;
+    private readonly timeouts;
+    private readonly decodeContent;
+    private readonly maxDecodedBytes;
+    private readonly caPem?;
+    private readonly active;
+    private readonly websockets;
+    private readonly producers;
+    private closed;
+    private notifier?;
+    private setup?;
+    constructor(options?: SessionOptions);
+    private ensureOpen;
+    /** Initialize the shared wakeup channel before any HTTP request is allocated. */
+    ready(signal?: AbortSignal): Promise<void>;
+    private begin;
+    stream(method: string, url: string, options?: RequestOptions): Promise<StreamResponse>;
+    sse(method: string, url: string, options?: SSEOptions): Promise<SSEStream>;
+    request(method: string, url: string, options?: RequestOptions): Promise<Response>;
+    /** Open a manual exchange; send() and response reads can run concurrently. */
+    duplex(method: string, url: string, options?: DuplexOptions): DuplexExchange;
+    get(url: string, options?: RequestOptions): Promise<Response>;
+    post(url: string, options?: RequestOptions): Promise<Response>;
+    websocket(url: string, options?: WebSocketOptions): Promise<WebSocket>;
+    listProfiles(): string[];
+    stats(): Stats;
+    closeIdleConnections(): void;
+    close(): void;
+    /** Release native resources immediately, then wait for cooperative upload cleanup. */
+    closeAsync(): Promise<void>;
+}