@fastls/fastls 0.0.0-stage → 0.10.1

package/dist/session.js

@@ -0,0 +1,455 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Session = void 0;
+const node_fs_1 = require("node:fs");
+const cookies_js_1 = require("./cookies.js");
+const headers_js_1 = require("./headers.js");
+const errors_js_1 = require("./errors.js");
+const native_js_1 = require("./native.js");
+const response_js_1 = require("./response.js");
+const timeout_js_1 = require("./timeout.js");
+const upload_js_1 = require("./upload.js");
+const duplex_js_1 = require("./duplex.js");
+const sse_js_1 = require("./sse.js");
+const notifications_js_1 = require("./notifications.js");
+const request_options_js_1 = require("./request-options.js");
+const websocket_js_1 = require("./websocket.js");
+const fetch_js_1 = require("./fetch.js");
+function decoding(decode, maximum) {
+    if (typeof decode !== "boolean")
+        throw new TypeError("decodeContent must be a boolean");
+    if (!Number.isSafeInteger(maximum) || maximum < 1 || maximum > 2 ** 40)
+        throw new RangeError("maxDecodedBytes must be 1..1099511627776");
+}
+function proxyValue(value) {
+    if (value !== undefined && value !== null && typeof value !== "string")
+        throw new TypeError("proxy must be a URL string or null");
+    // The native validator owns URL parsing and redacted errors. Do not include
+    // credentials in JavaScript URL parser errors or normalize invalid input.
+    return value;
+}
+function proxyTrust(path) {
+    if (path === null || path === undefined)
+        return undefined;
+    if (typeof path !== "string")
+        throw new TypeError("proxyCaFile must be a path string or null");
+    const pem = (0, node_fs_1.readFileSync)(path, "utf8");
+    if (!pem.trim())
+        throw new TypeError("proxyCaFile is empty");
+    return pem;
+}
+function mergeHeaders(...sources) {
+    const merged = Object.create(null);
+    for (const source of sources) {
+        for (const [key, value] of Object.entries(source ?? {})) {
+            if (typeof value !== "string")
+                throw new TypeError("header values must be strings");
+            merged[key.toLowerCase()] = value;
+        }
+    }
+    return merged;
+}
+class Session {
+    /** Construct and initialize; failed initialization closes the new session. */
+    static async open(options = {}) {
+        const session = new Session(options);
+        try {
+            await session.ready();
+            return session;
+        }
+        catch (error) {
+            await session.closeAsync();
+            throw error;
+        }
+    }
+    notificationMode;
+    cookies;
+    native;
+    handle;
+    profile;
+    proxy;
+    proxyCaPem;
+    headers;
+    timeouts;
+    decodeContent;
+    maxDecodedBytes;
+    caPem;
+    active = new Set();
+    websockets = new Set();
+    producers = new Set();
+    closed = false;
+    notifier;
+    setup;
+    constructor(options = {}) {
+        this.proxy = proxyValue(options.proxy);
+        this.proxyCaPem = proxyTrust(options.proxyCaFile);
+        const notifications = options.notifications === undefined ? "auto" : options.notifications;
+        if (!["auto", "required", "poll"].includes(notifications))
+            throw new TypeError("notifications must be auto, required or poll");
+        this.profile = options.profile ?? "chrome/156/windows";
+        this.timeouts = (0, timeout_js_1.timeoutFields)(options.timeoutMs ?? 30000);
+        this.decodeContent = options.decodeContent ?? true;
+        this.maxDecodedBytes = options.maxDecodedBytes ?? 256 * 1024 * 1024;
+        decoding(this.decodeContent, this.maxDecodedBytes);
+        this.headers = mergeHeaders(options.headers);
+        if (options.cookies !== undefined && typeof options.cookies !== "boolean")
+            throw new TypeError("cookies must be a boolean");
+        this.caPem = options.caFile === undefined ? undefined : (0, node_fs_1.readFileSync)(options.caFile, "utf8");
+        if (this.caPem !== undefined && !this.caPem.trim())
+            throw new TypeError("caFile is empty");
+        this.native = native_js_1.Native.load(options.library);
+        const supported = this.native.notificationsAvailable && this.native.call("features").includes("session_notifications");
+        if (notifications === "required" && !supported)
+            throw new errors_js_1.FastlsError("notifications require a newer Fastls native library");
+        this.notificationMode = notifications !== "poll" && supported ? "async-events" : "poll";
+        if (!this.native.call("features").includes("transport_context_v1"))
+            throw new errors_js_1.FastlsError("SDK-owned sessions require the Fastls 0.1.4 native library or newer");
+        this.handle = (0, native_js_1.asHandle)(this.native.call("transport_create"));
+        this.cookies = new cookies_js_1.Cookies(() => this.ensureOpen(), options.cookies !== false);
+    }
+    ensureOpen() {
+        if (this.closed)
+            throw new errors_js_1.FastlsError("session is closed");
+    }
+    /** Initialize the shared wakeup channel before any HTTP request is allocated. */
+    async ready(signal) {
+        this.ensureOpen();
+        if (signal !== undefined && !(signal instanceof AbortSignal))
+            throw new TypeError("signal must be an AbortSignal");
+        if (signal?.aborted)
+            throw new errors_js_1.AbortError(undefined, { cause: signal.reason });
+        if (this.notificationMode === "poll")
+            return;
+        if (!this.notifier) {
+            const notifier = this.notifier = new notifications_js_1.Notifier(this.native, this.handle);
+            const setup = this.setup = notifier.start().catch(async (error) => {
+                await notifier.closeAsync();
+                if (this.notifier === notifier) {
+                    this.notifier = undefined;
+                    this.setup = undefined;
+                }
+                throw error;
+            });
+            void setup.catch(() => { });
+        }
+        const notifier = this.notifier;
+        notifier.setupWaiters++;
+        try {
+            if (signal)
+                await (0, upload_js_1.abortable)(this.setup, signal);
+            else
+                await this.setup;
+            this.ensureOpen();
+            notifier.check();
+        }
+        catch (error) {
+            if (signal?.aborted)
+                throw new errors_js_1.AbortError(undefined, { cause: signal.reason });
+            throw error;
+        }
+        finally {
+            if (--notifier.setupWaiters === 0 && !notifier.isReady && this.notifier === notifier) {
+                notifier.close();
+                this.notifier = undefined;
+                this.setup = undefined;
+            }
+        }
+    }
+    begin(method, url, options, manual = false, completeHeaders = false) {
+        this.ensureOpen();
+        if (options.signal !== undefined && !(options.signal instanceof AbortSignal)) {
+            throw new TypeError("signal must be an AbortSignal");
+        }
+        if (options.signal?.aborted)
+            throw new errors_js_1.AbortError(undefined, { cause: options.signal.reason });
+        const headers = mergeHeaders(completeHeaders ? undefined : this.headers, options.headers);
+        for (const name of ["proxy-authorization", "proxy-connection"]) {
+            if (name in headers)
+                throw new errors_js_1.FastlsError("proxy headers must not be sent as target headers; configure proxy URL credentials");
+        }
+        const proxy = proxyValue(options.proxy === undefined ? this.proxy : options.proxy);
+        if (proxy && !this.native.call("features").includes("proxy_tunnels")) {
+            throw new errors_js_1.FastlsError("proxy support requires a newer Fastls native library");
+        }
+        const httpsProxy = proxy?.toLowerCase().startsWith("https://") ?? false;
+        if (httpsProxy && !this.native.call("features").includes("https_proxy_tls")) {
+            throw new errors_js_1.FastlsError("HTTPS proxy support requires a newer Fastls native library");
+        }
+        const proxyCaPem = !httpsProxy ? undefined : options.proxyCaFile === undefined
+            ? this.proxyCaPem : proxyTrust(options.proxyCaFile);
+        if (options.duplex !== undefined && typeof options.duplex !== "boolean")
+            throw new TypeError("duplex must be a boolean");
+        const duplex = options.duplex ?? false;
+        if (duplex && !this.native.call("features").includes("duplex_h2")) {
+            throw new errors_js_1.FastlsError("HTTP/2 duplex requires a newer Fastls native library");
+        }
+        const prepared = (0, request_options_js_1.prepare)(url, options, headers);
+        url = prepared.url;
+        if (!("cookie" in headers)) {
+            const cookie = this.cookies.header(url);
+            if (cookie)
+                headers.cookie = cookie;
+        }
+        const body = prepared.body === undefined && duplex && !manual ? Buffer.alloc(0) : prepared.body;
+        const streaming = (0, upload_js_1.isStreamingBody)(body) || duplex;
+        const bodyBytes = streaming || body === undefined ? undefined : Buffer.from(body);
+        const timeouts = options.timeoutMs === undefined ? this.timeouts : (0, timeout_js_1.timeoutFields)(options.timeoutMs);
+        const decodeContent = options.decodeContent ?? this.decodeContent;
+        const maxDecodedBytes = options.maxDecodedBytes ?? this.maxDecodedBytes;
+        decoding(decodeContent, maxDecodedBytes);
+        if (options.allowRedirects !== undefined && typeof options.allowRedirects !== "boolean") {
+            throw new TypeError("allowRedirects must be a boolean");
+        }
+        const started = performance.now();
+        let trailers;
+        if (options.trailers !== undefined) {
+            if (!this.native.call("features").includes("request_trailers"))
+                throw new errors_js_1.FastlsError("request trailers require a newer Fastls native library");
+            if (!options.trailers || typeof options.trailers !== "object" || Array.isArray(options.trailers))
+                throw new TypeError("trailers must be a mapping");
+            trailers = {};
+            for (const [name, value] of Object.entries(options.trailers)) {
+                const values = typeof value === "string" ? [value] : value;
+                if (!Array.isArray(values) || values.some(item => typeof item !== "string"))
+                    throw new TypeError("trailer values must be strings");
+                trailers[name] = [...values];
+            }
+        }
+        const handle = this.native.start({
+            session: this.handle, url, method, headers, trailers, proxy: proxy || undefined, proxy_ca_pem: proxyCaPem,
+            profile: options.profile ?? this.profile,
+            ...timeouts, decode_content: decodeContent, max_decoded_bytes: maxDecodedBytes,
+            disable_redirect: true,
+            ca_pem: this.caPem,
+            body_base64: bodyBytes?.toString("base64"),
+            stream_body: streaming || undefined,
+            duplex: duplex || undefined,
+        });
+        const transfer = new response_js_1.Transfer(this.native, handle, () => { this.active.delete(transfer); this.notifier?.forget(handle); }, options.signal, duplex, this.notifier, info => this.cookies.extract(info.final_url ?? url, new headers_js_1.Headers(info.header_values, info.headers).getAll("set-cookie")));
+        this.active.add(transfer);
+        try {
+            this.notifier?.track(handle);
+            transfer.attachSignal(timeouts.timeout_ms, started);
+            return { transfer, body, streaming };
+        }
+        catch (error) {
+            transfer.close();
+            throw error;
+        }
+    }
+    async streamHop(method, url, options) {
+        await this.ready(options.signal);
+        const { transfer, body, streaming } = this.begin(method, url, options, false, true);
+        try {
+            const upload = streaming ? (0, upload_js_1.startUpload)(transfer, body) : undefined;
+            if (upload) {
+                this.producers.add(upload);
+                void upload.cleanup.then(() => this.producers.delete(upload), () => this.producers.delete(upload));
+            }
+            let info;
+            try {
+                info = await transfer.headers();
+                if (!transfer.duplex && upload && info.status < 300 && !info.upload_discarded && !upload.complete()) {
+                    throw new errors_js_1.FastlsError("server responded before upload finished; duplex streaming is not supported");
+                }
+            }
+            finally {
+                if (upload && (!transfer.duplex || !info || info.status >= 300)) {
+                    upload.stop();
+                    await upload.done;
+                }
+            }
+            transfer.ensureOpen();
+            const response = new response_js_1.StreamResponse(transfer, info, transfer.duplex ? upload : undefined);
+            return response;
+        }
+        catch (error) {
+            transfer.close();
+            throw error;
+        }
+    }
+    async stream(method, url, options = {}) {
+        const headers = mergeHeaders(this.headers, options.headers);
+        const prepared = (0, request_options_js_1.prepare)(url, options, headers);
+        url = prepared.url;
+        options = { ...options, headers, body: prepared.body };
+        for (const key of ["params", "json", "form", "files"])
+            delete options[key];
+        const maximum = options.maxRedirects ?? 30;
+        if (!Number.isSafeInteger(maximum) || maximum < 0)
+            throw new RangeError("maxRedirects must be a non-negative integer");
+        const policy = options.timeoutMs === undefined ? this.timeouts : (0, timeout_js_1.timeoutFields)(options.timeoutMs);
+        const deadline = performance.now() + policy.timeout_ms;
+        for (let redirects = 0;; redirects++) {
+            const remaining = Math.ceil(deadline - performance.now());
+            if (remaining <= 0)
+                throw new errors_js_1.FastlsTimeoutError("total deadline exceeded", "total");
+            options.timeoutMs = { total: remaining, connect: policy.connect_timeout_ms, write: policy.write_timeout_ms, headers: policy.headers_timeout_ms, read: policy.read_timeout_ms };
+            const response = await this.streamHop(method, url, options);
+            const location = response.headers.get("location");
+            if (options.duplex || options.allowRedirects === false || ![301, 302, 303, 307, 308].includes(response.status) || !location || ([307, 308].includes(response.status) && (0, upload_js_1.isStreamingBody)(options.body)))
+                return response;
+            try {
+                if (redirects >= maximum)
+                    throw new errors_js_1.FastlsError("maximum redirects exceeded");
+                const previous = new URL(url), target = new URL(location, url);
+                if (!["http:", "https:"].includes(target.protocol) || target.username || target.password)
+                    throw new errors_js_1.FastlsError("invalid redirect URL");
+                target.hash = "";
+                if (previous.origin !== target.origin)
+                    for (const name of ["authorization", "cookie", "host"])
+                        delete headers[name];
+                if (([302, 303].includes(response.status) && method.toUpperCase() !== "HEAD") || (response.status === 301 && method.toUpperCase() === "POST")) {
+                    method = "GET";
+                    delete options.body;
+                    delete options.trailers;
+                    for (const name of ["content-type", "content-length", "transfer-encoding"])
+                        delete headers[name];
+                }
+                url = target.href;
+                await response.read();
+            }
+            finally {
+                await response.closeAsync();
+            }
+        }
+    }
+    async sse(method, url, options = {}) {
+        const { maxEventBytes = 1024 * 1024, lastEventId, ...request } = options;
+        (0, sse_js_1.validateSSEOptions)(maxEventBytes, lastEventId);
+        const headers = mergeHeaders({ accept: "text/event-stream", "cache-control": "no-cache" }, request.headers);
+        if (lastEventId !== undefined)
+            headers["last-event-id"] = lastEventId;
+        const response = await this.stream(method, url, { ...request, headers });
+        try {
+            return new sse_js_1.SSEStream(response, maxEventBytes, lastEventId);
+        }
+        catch (error) {
+            await response.closeAsync();
+            throw error;
+        }
+    }
+    async request(method, url, options = {}) {
+        const stream = await this.stream(method, url, options);
+        try {
+            const content = await stream.read();
+            return new response_js_1.Response(stream.status, stream.headers, stream.match, content, stream.wireHeaders, stream.decoded, stream.httpVersion, stream.url, stream.trailers);
+        }
+        finally {
+            await stream.closeAsync();
+        }
+    }
+    /** Open a manual exchange; send() and response reads can run concurrently. */
+    duplex(method, url, options = {}) {
+        if (["body", "duplex", "json", "form", "files"].some(key => key in options))
+            throw new TypeError("manual duplex uses send() and finishUpload(), not body, json, form, files or duplex options");
+        this.ensureOpen();
+        const cancellation = new AbortController();
+        const signal = options.signal === undefined ? cancellation.signal : AbortSignal.any([options.signal, cancellation.signal]);
+        const transfer = this.ready(signal).then(() => {
+            if (cancellation.signal.aborted)
+                throw new errors_js_1.FastlsError("exchange is closed");
+            return this.begin(method, url, { ...options, signal, duplex: true }, true).transfer;
+        }, error => { if (cancellation.signal.aborted)
+            throw new errors_js_1.FastlsError("exchange is closed"); throw error; });
+        return new duplex_js_1.DuplexExchange(transfer, () => cancellation.abort());
+    }
+    get(url, options) { return this.request("GET", url, options); }
+    post(url, options) { return this.request("POST", url, options); }
+    put(url, options) { return this.request("PUT", url, options); }
+    patch(url, options) { return this.request("PATCH", url, options); }
+    delete(url, options) { return this.request("DELETE", url, options); }
+    head(url, options = {}) { return this.request("HEAD", url, { allowRedirects: false, ...options }); }
+    options(url, options) { return this.request("OPTIONS", url, options); }
+    fetch(input, options = {}) {
+        if (options.library !== undefined || options.caFile !== undefined)
+            throw new TypeError("library and caFile must be configured on Session");
+        return (0, fetch_js_1.fetchWithSession)(this, input, options);
+    }
+    async websocket(url, options = {}) {
+        await this.ready(options.signal);
+        this.ensureOpen();
+        if (options.signal?.aborted)
+            throw new errors_js_1.AbortError(undefined, { cause: options.signal.reason });
+        if (!this.native.websocketAvailable)
+            throw new errors_js_1.FastlsError("WebSocket requires a newer Fastls native library");
+        const cookieMode = options.cookieMode === undefined ? "session" : options.cookieMode;
+        if (cookieMode !== "session" && cookieMode !== "manual")
+            throw new TypeError("cookieMode must be session or manual");
+        const features = this.native.call("features");
+        const sessionCookies = features.includes("websocket_cookie_control_v1") || features.includes("websocket_cookies");
+        if (cookieMode === "manual" && !sessionCookies && features.includes("websocket_cookies_v1"))
+            throw new errors_js_1.FastlsError("This native library cannot disable automatic WebSocket cookies; a newer library with websocket_cookie_control_v1 is required");
+        if (cookieMode === "session" && !sessionCookies)
+            throw new errors_js_1.FastlsError("WebSocket session cookies require a newer Fastls native library; use cookieMode manual for legacy behavior");
+        const maximum = (options.maxMessageBytes === undefined ? 1048576 : options.maxMessageBytes);
+        if (!Number.isSafeInteger(maximum) || maximum < 1 || maximum > 16777216)
+            throw new RangeError("maxMessageBytes must be 1..16777216");
+        const close = (0, websocket_js_1.wsBudget)((options.closeTimeoutMs === undefined ? 1000 : options.closeTimeoutMs), "closeTimeoutMs", 60000);
+        const headers = mergeHeaders(this.headers, options.headers), prepared = (0, request_options_js_1.prepare)(url, { params: options.params }, headers);
+        if (cookieMode === "session" && !("cookie" in headers)) {
+            const cookie = this.cookies.header(prepared.url);
+            if (cookie)
+                headers.cookie = cookie;
+        }
+        const proxy = proxyValue(options.proxy === undefined ? this.proxy : options.proxy);
+        const proxyCA = proxy?.toLowerCase().startsWith("https://") ? (options.proxyCaFile === undefined ? this.proxyCaPem : proxyTrust(options.proxyCaFile)) : undefined;
+        if (options.subprotocols !== undefined && (!Array.isArray(options.subprotocols) || options.subprotocols.some(p => typeof p !== "string")))
+            throw new TypeError("subprotocols must be an array of strings");
+        const handle = this.native.wsStart({ url: prepared.url, session: this.handle, disable_cookies: true, headers, profile: options.profile ?? this.profile, proxy: proxy || undefined, ca_pem: this.caPem, proxy_ca_pem: proxyCA, subprotocols: options.subprotocols ?? [], max_message_bytes: maximum,
+            timeout_ms: (0, websocket_js_1.wsBudget)((options.handshakeTimeoutMs === undefined ? 30000 : options.handshakeTimeoutMs), "handshakeTimeoutMs"), read_timeout_ms: options.readTimeoutMs === null || options.readTimeoutMs === undefined ? 0 : (0, websocket_js_1.wsBudget)(options.readTimeoutMs, "readTimeoutMs"), write_timeout_ms: (0, websocket_js_1.wsBudget)((options.writeTimeoutMs === undefined ? 30000 : options.writeTimeoutMs), "writeTimeoutMs") });
+        const ws = new websocket_js_1.WebSocket(this.native, handle, () => { this.websockets.delete(ws); this.notifier?.forget(handle); }, maximum, close, this.notifier, options.signal);
+        this.websockets.add(ws);
+        try {
+            this.notifier?.track(handle);
+            return await ws.opened();
+        }
+        catch (error) {
+            ws.abort();
+            throw error;
+        }
+        finally {
+            if (cookieMode === "session" && !this.closed) {
+                const info = ws.info;
+                if (info.status !== 101 || info.state === "headers" || info.state === "eof")
+                    this.cookies.extract(prepared.url, ws.headers.getAll("set-cookie"));
+            }
+        }
+    }
+    listProfiles() { this.ensureOpen(); return this.native.call("profiles"); }
+    stats() { this.ensureOpen(); return this.native.call("stats"); }
+    closeIdleConnections() { this.ensureOpen(); this.native.call("session_close_idle", this.handle); }
+    close() {
+        if (this.closed)
+            return;
+        this.cookies.clear();
+        this.closed = true;
+        try {
+            for (const transfer of this.active)
+                transfer.close(new errors_js_1.FastlsError("session is closed"));
+            for (const ws of this.websockets)
+                ws.abort(new errors_js_1.FastlsError("session is closed"));
+        }
+        finally {
+            try {
+                this.notifier?.close();
+            }
+            finally {
+                this.native.call("session_close", this.handle);
+            }
+        }
+    }
+    /** Release native resources immediately, then wait for cooperative upload cleanup. */
+    async closeAsync() {
+        const producers = [...this.producers];
+        this.close();
+        await this.notifier?.closeAsync();
+        const results = await Promise.allSettled(producers.map(task => task.cleanup));
+        for (const result of results)
+            if (result.status === "rejected")
+                throw result.reason;
+        for (const task of producers)
+            task.check();
+    }
+}
+exports.Session = Session;

package/dist/sse.d.ts

@@ -0,0 +1,52 @@
+import type { StreamResponse } from "./response.js";
+import type { RequestOptions } from "./session.js";
+export interface SSEOptions extends RequestOptions {
+    /** Separate limits for a raw line and accumulated UTF-8 data; defaults to 1 MiB. */
+    maxEventBytes?: number;
+    /** Sets Last-Event-ID and the parser's initial ID. Reconnection is manual. */
+    lastEventId?: string;
+}
+export declare class ServerSentEvent {
+    readonly data: string;
+    readonly event: string;
+    readonly id: string;
+    readonly retry?: number | undefined;
+    constructor(data: string, event?: string, id?: string, retry?: number | undefined);
+    json<T = unknown>(): T;
+}
+export declare function validateSSEOptions(maximum: number, initialId?: string): void;
+/** Internal pull parser. feed() pauses at each event, including within one chunk. */
+export declare class SSEDecoder {
+    private readonly maximum;
+    lastEventId: string;
+    retry?: number;
+    private id;
+    private blockRetry?;
+    private line;
+    private length;
+    private data;
+    private size;
+    private event;
+    private first;
+    private skipLF;
+    constructor(maximum: number, initialId?: string);
+    private append;
+    private processLine;
+    feed(chunk: Uint8Array): Generator<ServerSentEvent>;
+    finish(): void;
+}
+export declare class SSEStream implements AsyncIterable<ServerSentEvent> {
+    readonly response: StreamResponse;
+    private readonly decoder;
+    private started;
+    private closed;
+    constructor(response: StreamResponse, maximum?: number, initialId?: string);
+    get lastEventId(): string;
+    get retry(): number | undefined;
+    private checkOpen;
+    [Symbol.asyncIterator](): AsyncGenerator<ServerSentEvent>;
+    private events;
+    cancel(): void;
+    close(): void;
+    closeAsync(): Promise<void>;
+}