@fastls/fastls 0.10.2 → 0.12.0

package/README.md

@@ -1,6 +1,27 @@
 # Fastls Node.js SDK
 
-Node.js 22+ 的 Fastls C ABI v1 绑定，提供 Promise API、TypeScript 声明、ESM 和 CommonJS 入口。本文对应 **0.10.1**。
+Node 0.11.0 起支持 Session `addressPolicy`、`profileSpec: new ProfileSpec(...)` 和
+`httpVersion: "h3"`；Session/fetch 可选择完整 Spec 或显式协议。
+`addressPolicy` 只能创建可信 owner，不能由 `session.fetch()` 或请求替换。
+较旧原生库缺能力或符号时会明确报错，见[能力契约](../CAPABILITIES.md)。
+
+Node 0.12.0 新增默认关闭的 RetryPolicy、Session/fetch 的 bodyFactory 和
+ProfileBundle/ProfileStore 离线配置工具。重试与跳转共用总超时，不重放一次性正文，
+不重试取消、策略/证书拒绝或响应正文读取错误。见[中文指南](https://github.com/FastTLS/fastls-ffi/blob/main/RELIABILITY.zh-CN.md)
+及 [English contract](https://github.com/FastTLS/fastls-ffi/blob/main/RELIABILITY.md)。
+
+```typescript
+import { Session, ProfileSpec } from '@fastls/fastls';
+import { readFileSync } from 'node:fs';
+const profileSpec = new ProfileSpec(JSON.parse(readFileSync('browser.json', 'utf8')));
+const session = new Session({ profileSpec });
+try { await session.get('https://example.com'); } finally { await session.closeAsync(); }
+// 强制 H3 直连，不支持时不会回退到 TCP；目标须支持 H3。
+const h3 = new Session({ httpVersion: 'h3' });
+try { await h3.get('https://example.com'); } finally { await h3.closeAsync(); }
+```
+
+Node.js 22+ 的 Fastls C ABI v1 绑定，提供 Promise API、TypeScript 声明、ESM 和 CommonJS 入口。本文对应 **0.12.0**。
 
 支持 HTTP/1.1、HTTP/2、流式上传下载、双工、SSE、WebSocket、会话 Cookie 和 HTTP/HTTPS/SOCKS 代理。网络请求由 Go 执行，通过 Koffi 在当前 Node 进程中调用；使用者无需 Python 或 RPC 服务。
 
@@ -16,7 +37,7 @@ Node.js 22+ 的 Fastls C ABI v1 绑定，提供 Promise API、TypeScript 声明
 安装指定版本：
 
 ```sh
-npm install @fastls/fastls@0.10.1
+npm install @fastls/fastls@0.12.0
 ```
 
 主包通过同版本的可选依赖自动安装当前平台的 Fastls 原生库。保留 optional dependencies；支持 Windows x64、Linux glibc x64/arm64、macOS x64/arm64。Linux musl 和其它架构没有内置包。具体系统最低版本见原生包的 `native/manifest.json`。

package/dist/errors.d.ts

@@ -1,5 +1,6 @@
 export declare class FastlsError extends Error {
     name: string;
+    code?: string | number;
 }
 export declare class FastlsHTTPError extends FastlsError {
     readonly response: import("./response.js").Response | import("./response.js").StreamResponse;

package/dist/errors.js

@@ -4,6 +4,7 @@ exports.AbortError = exports.FastlsDecodeError = exports.FastlsTimeoutError = ex
 exports.responseError = responseError;
 class FastlsError extends Error {
     name = "FastlsError";
+    code;
 }
 exports.FastlsError = FastlsError;
 class FastlsHTTPError extends FastlsError {
@@ -36,7 +37,9 @@ function responseError(info) {
         return new FastlsTimeoutError(message, (info.timeout_phase ?? "total"));
     if (info.error_code === "decode_error")
         return new FastlsDecodeError(message);
-    return new FastlsError(message);
+    const error = new FastlsError(message);
+    error.code = info.error_code;
+    return error;
 }
 class AbortError extends FastlsError {
     name = "AbortError";

package/dist/fetch.d.ts

@@ -1,5 +1,12 @@
 import { Session, type RequestOptions } from "./session.js";
+import type { ProfileSpec, AddressPolicy } from "./profiles.js";
 export interface FetchOptions extends RequestInit {
+    retry?: RequestOptions["retry"];
+    bodyFactory?: RequestOptions["bodyFactory"];
+    profileSpec?: ProfileSpec;
+    httpVersion?: "auto" | "h3";
+    /** Only standalone fetch can create a new trusted policy owner. */
+    addressPolicy?: AddressPolicy;
     duplex?: "half";
     profile?: string;
     proxy?: string | null;

package/dist/fetch.js

@@ -11,13 +11,19 @@ async function fetchWithSession(session, input, init = {}, owned = false) {
             if (init[key] !== undefined)
                 throw new TypeError(`Fastls fetch does not support ${key}`);
         }
-        const allowed = new Set(["method", "headers", "body", "redirect", "signal", "duplex", "profile", "proxy", "proxyCaFile", "caFile", "library", "timeoutMs", "maxRedirects"]);
+        const allowed = new Set(["method", "headers", "body", "redirect", "signal", "duplex", "profile", "profileSpec", "httpVersion", "addressPolicy", "proxy", "proxyCaFile", "caFile", "library", "timeoutMs", "maxRedirects", "retry", "bodyFactory"]);
+        if (!owned && init.addressPolicy !== undefined)
+            throw new TypeError("addressPolicy is a Session creation option");
         for (const key of Object.keys(init))
             if (!allowed.has(key))
                 throw new TypeError(`Fastls fetch does not support ${key}`);
         // Request performs the platform's normal URL/method/header validation and
         // serializes URLSearchParams, Blob and FormData without a second encoder.
         const request = new Request(input, init);
+        if (init.bodyFactory !== undefined && request.body !== null)
+            throw new TypeError("bodyFactory cannot be combined with a Request body");
+        if (init.bodyFactory !== undefined && ["GET", "HEAD"].includes(request.method))
+            throw new TypeError("fetch GET/HEAD cannot have a bodyFactory");
         const headers = Object.fromEntries(request.headers);
         let body;
         if (request.body) {
@@ -29,7 +35,8 @@ async function fetchWithSession(session, input, init = {}, owned = false) {
                 body = node_stream_1.Readable.fromWeb(request.body);
         }
         const stream = await session.stream(request.method, request.url, {
-            headers, body, profile: init.profile, proxy: init.proxy, proxyCaFile: init.proxyCaFile,
+            headers, ...(init.bodyFactory === undefined ? { body } : { bodyFactory: init.bodyFactory }), retry: init.retry,
+            profile: init.profile, profileSpec: init.profileSpec, httpVersion: init.httpVersion, proxy: init.proxy, proxyCaFile: init.proxyCaFile,
             timeoutMs: init.timeoutMs, maxRedirects: init.maxRedirects,
             allowRedirects: request.redirect === "follow", signal: request.signal,
         });
@@ -108,6 +115,7 @@ async function fetchWithSession(session, input, init = {}, owned = false) {
 /** Fetch-compatible entry point. No persistent cookie jar is created. */
 async function fetch(input, init = {}) {
     const options = { cookies: false, profile: init.profile, proxy: init.proxy,
+        profileSpec: init.profileSpec, httpVersion: init.httpVersion, addressPolicy: init.addressPolicy,
         proxyCaFile: init.proxyCaFile, caFile: init.caFile, library: init.library, timeoutMs: init.timeoutMs };
     return fetchWithSession(new session_js_1.Session(options), input, init, true);
 }

package/dist/index.d.ts

@@ -1,4 +1,9 @@
 export { Session } from "./session.js";
+export { RetryPolicy } from "./retry.js";
+export { ProfileBundle, ProfileStore } from "./profile-store.js";
+export type { RetryOptions } from "./retry.js";
+export { ProfileSpec } from "./profiles.js";
+export type { AddressPolicy } from "./profiles.js";
 export { fetch } from "./fetch.js";
 export type { FetchOptions, FetchResponse } from "./fetch.js";
 export type { SessionOptions, RequestOptions, DuplexOptions, Stats } from "./session.js";

package/dist/index.js

@@ -1,8 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FastlsTimeoutError = exports.FastlsDecodeError = exports.AbortError = exports.FastlsHTTPError = exports.FastlsError = exports.Cookies = exports.Headers = exports.StreamResponse = exports.Response = exports.SSEStream = exports.ServerSentEvent = exports.WebSocketClosed = exports.WebSocket = exports.DuplexExchange = exports.Session = void 0;
+exports.FastlsTimeoutError = exports.FastlsDecodeError = exports.AbortError = exports.FastlsHTTPError = exports.FastlsError = exports.Cookies = exports.Headers = exports.StreamResponse = exports.Response = exports.SSEStream = exports.ServerSentEvent = exports.WebSocketClosed = exports.WebSocket = exports.DuplexExchange = exports.ProfileSpec = exports.ProfileStore = exports.ProfileBundle = exports.RetryPolicy = exports.Session = void 0;
 var session_js_1 = require("./session.js");
 Object.defineProperty(exports, "Session", { enumerable: true, get: function () { return session_js_1.Session; } });
+var retry_js_1 = require("./retry.js");
+Object.defineProperty(exports, "RetryPolicy", { enumerable: true, get: function () { return retry_js_1.RetryPolicy; } });
+var profile_store_js_1 = require("./profile-store.js");
+Object.defineProperty(exports, "ProfileBundle", { enumerable: true, get: function () { return profile_store_js_1.ProfileBundle; } });
+Object.defineProperty(exports, "ProfileStore", { enumerable: true, get: function () { return profile_store_js_1.ProfileStore; } });
+var profiles_js_1 = require("./profiles.js");
+Object.defineProperty(exports, "ProfileSpec", { enumerable: true, get: function () { return profiles_js_1.ProfileSpec; } });
 var fetch_js_1 = require("./fetch.js");
 Object.defineProperty(exports, "fetch", { enumerable: true, get: function () { return fetch_js_1.fetch; } });
 var duplex_js_1 = require("./duplex.js");

package/dist/index.mjs

@@ -1,3 +1,3 @@
 import sdk from './index.js';
 export const fetch = sdk.fetch;
-export const { Session, Response, StreamResponse, DuplexExchange, WebSocket, WebSocketClosed, ServerSentEvent, SSEStream, Headers, Cookies, FastlsError, FastlsHTTPError, AbortError, FastlsDecodeError, FastlsTimeoutError } = sdk;
+export const { Session, ProfileSpec, RetryPolicy, ProfileBundle, ProfileStore, Response, StreamResponse, DuplexExchange, WebSocket, WebSocketClosed, ServerSentEvent, SSEStream, Headers, Cookies, FastlsError, FastlsHTTPError, AbortError, FastlsDecodeError, FastlsTimeoutError } = sdk;

package/dist/native.d.ts

@@ -31,6 +31,7 @@ export interface NativeInfo {
 }
 export declare class Native {
     private functions;
+    readonly transportOptionsAvailable: boolean;
     readonly notificationsAvailable: boolean;
     readonly websocketAvailable: boolean;
     readonly path: string;
@@ -38,6 +39,7 @@ export declare class Native {
     private constructor();
     call<T = unknown>(name: string, ...args: unknown[]): T;
     start(input: unknown): bigint;
+    requireCapabilities(required: readonly string[]): void;
     wsStart(input: unknown): bigint;
     wsSend(handle: bigint, opcode: number, data: Uint8Array): number;
     wsRead(handle: bigint, buffer: Buffer): {

package/dist/native.js

@@ -62,6 +62,7 @@ function pinLibrary(path) {
 }
 class Native {
     functions = {};
+    transportOptionsAvailable = false;
     notificationsAvailable;
     websocketAvailable;
     path;
@@ -103,6 +104,13 @@ class Native {
             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_options_v1")) {
+                try {
+                    this.functions.transport_create_with_options = lib.func("void *fastls_transport_create_with_options(void *json, size_t length)");
+                    this.transportOptionsAvailable = true;
+                }
+                catch { /* Optional symbol: old default transport stays loadable. */ }
+            }
             if (features.has("transport_context_v1")) {
                 this.functions.transport_create = lib.func("void *fastls_transport_create(void)");
             }
@@ -149,19 +157,30 @@ class Native {
             // 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));
+            envelope = (name === "start" || name === "ws_start" || name === "session_create" || name === "transport_create" || name === "transport_create_with_options" || 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");
+        if (!envelope?.ok) {
+            const error = new errors_js_1.FastlsError(envelope?.error ?? "invalid native result");
+            error.code = envelope?.error_code;
+            throw error;
+        }
         return envelope.result;
     }
     start(input) {
         const raw = encodeNativeJSON(input);
         return asHandle(this.call("start", raw, raw.length));
     }
+    requireCapabilities(required) {
+        const features = new Set(this.call("features"));
+        if (!this.transportOptionsAvailable || required.some(name => !features.has(name))) {
+            const error = new errors_js_1.FastlsError("native transport capability is unavailable");
+            error.code = "unsupported_capability";
+            throw error;
+        }
+    }
     wsStart(input) {
         if (!this.websocketAvailable)
             throw new errors_js_1.FastlsError("WebSocket requires a newer Fastls native library");

package/dist/profile-store.d.ts

@@ -0,0 +1,35 @@
+import { ProfileSpec } from "./profiles.js";
+/** A pinned digest verifies exact Spec bytes, not producer authenticity. */
+export declare class ProfileBundle {
+    readonly sha256: string;
+    readonly profileId: string;
+    readonly source: string;
+    private readonly text;
+    private readonly specText;
+    constructor(text: string, options: {
+        sha256: string;
+        library?: string;
+    });
+    static create(spec: ProfileSpec, options: {
+        source: string;
+        library?: string;
+    }): ProfileBundle;
+    get spec(): ProfileSpec;
+    dumps(): string;
+    export(path: string): void;
+}
+/** Trusted local directories only; callers must serialize concurrent writers. */
+export declare class ProfileStore {
+    readonly directory: string;
+    private readonly options;
+    private readonly objects;
+    private readonly statePath;
+    constructor(directory: string, options?: {
+        library?: string;
+    });
+    private state;
+    load(sha256?: string): ProfileBundle;
+    install(path: string, sha256: string): ProfileBundle;
+    pin(sha256: string): ProfileBundle;
+    rollback(): ProfileBundle;
+}

package/dist/profile-store.js

@@ -0,0 +1,203 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProfileStore = exports.ProfileBundle = void 0;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const lossless_json_1 = require("lossless-json");
+const profiles_js_1 = require("./profiles.js");
+const session_js_1 = require("./session.js");
+const LIMIT = 512 * 1024;
+const HASH = /^[0-9a-f]{64}$/;
+function strict(text) {
+    if (typeof text !== "string" || Buffer.byteLength(text) > LIMIT)
+        throw new RangeError("profile bundle exceeds 512KiB");
+    try {
+        // lossless-json accepts repeated keys when their values are equal. Inspect
+        // all object keys as well, so the bundle schema rejects every duplicate.
+        const stack = [];
+        for (const token of text.matchAll(/"(?:\\.|[^"\\])*"|[{}\[\]]/gs)) {
+            if (token[0] === "{")
+                stack.push(new Set());
+            else if (token[0] === "[")
+                stack.push(null);
+            else if (token[0] === "}" || token[0] === "]")
+                stack.pop();
+            else {
+                let offset = token.index + token[0].length;
+                while (offset < text.length && /\s/.test(text[offset]))
+                    offset++;
+                if (text[offset] === ":") {
+                    const keys = stack.at(-1), key = JSON.parse(token[0]);
+                    if (!keys || keys.has(key))
+                        throw new TypeError("duplicate profile bundle field");
+                    keys.add(key);
+                }
+            }
+            if (stack.length > 64)
+                throw new RangeError("profile bundle exceeds depth 64");
+        }
+        const value = (0, lossless_json_1.parse)(text, null, {
+            parseNumber(token) {
+                const number = Number(token);
+                if (!/^-?\d+$/.test(token) || !Number.isSafeInteger(number))
+                    throw new TypeError("profile bundle requires portable integer fields");
+                return number;
+            },
+            onDuplicateKey() { throw new TypeError("duplicate profile bundle field"); },
+        });
+        function visit(item, depth = 0) {
+            if (depth > 64)
+                throw new RangeError("profile bundle exceeds depth 64");
+            if (typeof item === "string" && /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/.test(item))
+                throw new TypeError("invalid Unicode");
+            if (item && typeof item === "object")
+                for (const [key, entry] of Object.entries(item)) {
+                    visit(key, depth + 1);
+                    visit(entry, depth + 1);
+                }
+        }
+        visit(value);
+        return value;
+    }
+    catch {
+        throw new TypeError("invalid profile bundle JSON");
+    }
+}
+function record(value) { return !!value && typeof value === "object" && !Array.isArray(value); }
+function read(path) {
+    const fd = (0, node_fs_1.openSync)(path, "r");
+    try {
+        const buffer = Buffer.alloc(LIMIT + 1);
+        let length = 0, size;
+        while (length < buffer.length && (size = (0, node_fs_1.readSync)(fd, buffer, length, buffer.length - length, null)) > 0)
+            length += size;
+        if (length > LIMIT)
+            throw new RangeError("profile bundle exceeds 512KiB");
+        return new TextDecoder("utf-8", { fatal: true }).decode(buffer.subarray(0, length));
+    }
+    finally {
+        (0, node_fs_1.closeSync)(fd);
+    }
+}
+function atomic(path, text) {
+    const temporary = (0, node_path_1.join)((0, node_path_1.dirname)(path), ".fastls-" + (0, node_crypto_1.randomBytes)(16).toString("hex"));
+    const fd = (0, node_fs_1.openSync)(temporary, "wx", 0o600);
+    try {
+        try {
+            (0, node_fs_1.writeFileSync)(fd, text, "utf8");
+            (0, node_fs_1.fsyncSync)(fd);
+        }
+        finally {
+            (0, node_fs_1.closeSync)(fd);
+        }
+        (0, node_fs_1.renameSync)(temporary, path);
+    }
+    finally {
+        if ((0, node_fs_1.existsSync)(temporary))
+            (0, node_fs_1.unlinkSync)(temporary);
+    }
+}
+function canonical(value) {
+    if (Array.isArray(value))
+        return value.map(canonical);
+    if (record(value))
+        return Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical(value[key])]));
+    return value;
+}
+/** A pinned digest verifies exact Spec bytes, not producer authenticity. */
+class ProfileBundle {
+    sha256;
+    profileId;
+    source;
+    text;
+    specText;
+    constructor(text, options) {
+        if (typeof options.sha256 !== "string" || !HASH.test(options.sha256))
+            throw new TypeError("an explicit lowercase SHA-256 pin is required");
+        const envelope = strict(text);
+        const keys = ["profile_id", "schema_version", "sha256", "source", "spec_json"];
+        if (!record(envelope) || JSON.stringify(Object.keys(envelope).sort()) !== JSON.stringify(keys) || envelope.schema_version !== 1)
+            throw new TypeError("unsupported profile bundle schema");
+        const raw = envelope.spec_json, source = envelope.source;
+        if (typeof raw !== "string" || typeof source !== "string" || source.length < 1 || Buffer.byteLength(source) > 512 || /[\x00-\x1f\x7f]/.test(source))
+            throw new TypeError("invalid profile bundle fields");
+        const digest = (0, node_crypto_1.createHash)("sha256").update(raw, "utf8").digest("hex");
+        if (digest !== options.sha256 || digest !== envelope.sha256)
+            throw new TypeError("profile bundle digest mismatch");
+        const value = strict(raw);
+        if (!record(value) || typeof value.id !== "string" || value.id !== envelope.profile_id)
+            throw new TypeError("profile bundle ID mismatch");
+        const spec = new profiles_js_1.ProfileSpec(value);
+        const session = new session_js_1.Session({ library: options.library, profileSpec: spec });
+        session.close();
+        this.sha256 = digest;
+        this.profileId = value.id;
+        this.source = source;
+        this.text = JSON.stringify(canonical(envelope)) + "\n";
+        this.specText = JSON.stringify(value);
+        Object.freeze(this);
+    }
+    static create(spec, options) {
+        if (!(spec instanceof profiles_js_1.ProfileSpec))
+            throw new TypeError("spec must be ProfileSpec");
+        const raw = JSON.stringify(canonical(spec.toJSON()));
+        const digest = (0, node_crypto_1.createHash)("sha256").update(raw, "utf8").digest("hex");
+        const text = JSON.stringify({ schema_version: 1, profile_id: spec.toJSON().id, spec_json: raw, sha256: digest, source: options.source });
+        return new ProfileBundle(text, { sha256: digest, library: options.library });
+    }
+    get spec() { return new profiles_js_1.ProfileSpec(JSON.parse(this.specText)); }
+    dumps() { return this.text; }
+    export(path) { atomic(path, this.text); }
+}
+exports.ProfileBundle = ProfileBundle;
+/** Trusted local directories only; callers must serialize concurrent writers. */
+class ProfileStore {
+    directory;
+    options;
+    objects;
+    statePath;
+    constructor(directory, options = {}) {
+        this.directory = directory;
+        this.options = options;
+        this.objects = (0, node_path_1.join)(directory, "objects");
+        this.statePath = (0, node_path_1.join)(directory, "state.json");
+        (0, node_fs_1.mkdirSync)(this.objects, { recursive: true });
+    }
+    state() {
+        if (!(0, node_fs_1.existsSync)(this.statePath))
+            return { current: null, previous: null };
+        const value = strict(read(this.statePath));
+        if (!record(value) || Object.keys(value).sort().join(",") !== "current,previous" || Object.values(value).some(pin => pin !== null && (typeof pin !== "string" || !HASH.test(pin))))
+            throw new TypeError("invalid profile store state");
+        return value;
+    }
+    load(sha256) {
+        const pin = sha256 ?? this.state().current;
+        if (typeof pin !== "string" || !HASH.test(pin))
+            throw new TypeError("no valid profile pin");
+        return new ProfileBundle(read((0, node_path_1.join)(this.objects, pin + ".json")), { ...this.options, sha256: pin });
+    }
+    install(path, sha256) {
+        const bundle = new ProfileBundle(read(path), { ...this.options, sha256 });
+        const target = (0, node_path_1.join)(this.objects, bundle.sha256 + ".json");
+        if ((0, node_fs_1.existsSync)(target))
+            this.load(bundle.sha256);
+        else
+            atomic(target, bundle.dumps());
+        return this.pin(bundle.sha256);
+    }
+    pin(sha256) {
+        const bundle = this.load(sha256), state = this.state();
+        if (state.current !== sha256)
+            atomic(this.statePath, JSON.stringify({ current: sha256, previous: state.current }) + "\n");
+        return bundle;
+    }
+    rollback() {
+        const previous = this.state().previous;
+        if (previous === null)
+            throw new TypeError("no previous profile pin");
+        return this.pin(previous);
+    }
+}
+exports.ProfileStore = ProfileStore;

package/dist/profiles.d.ts

@@ -0,0 +1,14 @@
+/** Trusted immutable session policy. Keys follow the native versioned schema. */
+export interface AddressPolicy {
+    readonly allow_schemes?: readonly ("http" | "https")[];
+    readonly allow_hosts?: readonly string[];
+    readonly allow_ports?: readonly number[];
+    readonly allow_cidrs?: readonly string[];
+    readonly deny_cidrs?: readonly string[];
+}
+/** Explicit snapshot of a complete schema-v1 profile, validated by the core. */
+export declare class ProfileSpec {
+    private readonly snapshot;
+    constructor(value: Readonly<Record<string, unknown>>);
+    toJSON(): Record<string, unknown>;
+}

package/dist/profiles.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProfileSpec = void 0;
+/** Explicit snapshot of a complete schema-v1 profile, validated by the core. */
+class ProfileSpec {
+    snapshot;
+    constructor(value) {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            throw new TypeError("ProfileSpec requires an object");
+        this.snapshot = JSON.stringify(value);
+        if (Buffer.byteLength(this.snapshot) > 256 * 1024)
+            throw new RangeError("profileSpec exceeds 256KiB");
+    }
+    toJSON() { return JSON.parse(this.snapshot); }
+}
+exports.ProfileSpec = ProfileSpec;

package/dist/retry.d.ts

@@ -0,0 +1,28 @@
+import type { UploadBody } from "./upload.js";
+export interface RetryOptions {
+    maxRetries?: number;
+    methods?: readonly string[];
+    statuses?: readonly number[];
+    backoffMs?: number;
+    maxDelayMs?: number;
+    jitter?: boolean;
+    retryAfter?: boolean;
+    retryNetwork?: boolean;
+    allowNonIdempotent?: boolean;
+}
+/** Immutable, opt-in business retries. Durations are milliseconds. */
+export declare class RetryPolicy {
+    readonly maxRetries: number;
+    readonly methods: readonly string[];
+    readonly statuses: readonly number[];
+    readonly backoffMs: number;
+    readonly maxDelayMs: number;
+    readonly jitter: boolean;
+    readonly retryAfter: boolean;
+    readonly retryNetwork: boolean;
+    constructor(options?: RetryOptions);
+    eligible(method: string, used: number, replayable: boolean, error?: unknown, status?: number): boolean;
+    delay(used: number, header?: string | null): number;
+}
+export declare function replayable(body?: UploadBody, factory?: () => UploadBody): boolean;
+export declare function retryWait(delay: number, deadline: number, signal: AbortSignal): Promise<void>;

package/dist/retry.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RetryPolicy = void 0;
+exports.replayable = replayable;
+exports.retryWait = retryWait;
+const promises_1 = require("node:timers/promises");
+const errors_js_1 = require("./errors.js");
+const SAFE = new Set(["GET", "HEAD", "OPTIONS", "PUT", "DELETE"]);
+/** Immutable, opt-in business retries. Durations are milliseconds. */
+class RetryPolicy {
+    maxRetries;
+    methods;
+    statuses;
+    backoffMs;
+    maxDelayMs;
+    jitter;
+    retryAfter;
+    retryNetwork;
+    constructor(options = {}) {
+        if (!options || typeof options !== "object" || Array.isArray(options))
+            throw new TypeError("retry options must be an object");
+        const allowed = new Set(["maxRetries", "methods", "statuses", "backoffMs", "maxDelayMs", "jitter", "retryAfter", "retryNetwork", "allowNonIdempotent"]);
+        if (Object.keys(options).some(key => !allowed.has(key)))
+            throw new TypeError("unknown retry option");
+        for (const key of ["methods", "statuses"])
+            if (options[key] !== undefined && !Array.isArray(options[key]))
+                throw new TypeError(`${key} must be an array`);
+        this.maxRetries = options.maxRetries === undefined ? 2 : options.maxRetries;
+        if (!Number.isInteger(this.maxRetries) || this.maxRetries < 0 || this.maxRetries > 100)
+            throw new RangeError("maxRetries must be 0..100");
+        this.methods = Object.freeze([...(options.methods ?? SAFE)].map(method => {
+            if (typeof method !== "string" || !/^[A-Za-z]+$/.test(method))
+                throw new TypeError("invalid retry method");
+            return method.toUpperCase();
+        }));
+        for (const key of ["jitter", "retryAfter", "retryNetwork", "allowNonIdempotent"]) {
+            if (options[key] !== undefined && typeof options[key] !== "boolean")
+                throw new TypeError(`${key} must be a boolean`);
+        }
+        if (!options.allowNonIdempotent && this.methods.some(method => !SAFE.has(method)))
+            throw new TypeError("non-idempotent methods require explicit authorization");
+        this.statuses = Object.freeze([...(options.statuses ?? [429, 502, 503, 504])]);
+        if (this.statuses.some(status => !Number.isInteger(status) || status < 400 || status > 599 || [401, 403, 407].includes(status)))
+            throw new RangeError("invalid retry status");
+        this.backoffMs = options.backoffMs === undefined ? 100 : options.backoffMs;
+        this.maxDelayMs = options.maxDelayMs === undefined ? 10000 : options.maxDelayMs;
+        for (const value of [this.backoffMs, this.maxDelayMs])
+            if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 86400000)
+                throw new RangeError("retry delays must be within 0..86400000 milliseconds");
+        this.jitter = options.jitter ?? true;
+        this.retryAfter = options.retryAfter ?? true;
+        this.retryNetwork = options.retryNetwork ?? true;
+        Object.freeze(this);
+    }
+    eligible(method, used, replayable, error, status) {
+        if (used >= this.maxRetries || !this.methods.includes(method.toUpperCase()) || !replayable)
+            return false;
+        if (status !== undefined)
+            return this.statuses.includes(status);
+        return this.retryNetwork && error instanceof errors_js_1.FastlsError && (error.code === "network_error" ||
+            (error instanceof errors_js_1.FastlsTimeoutError && ["connect", "headers"].includes(error.phase)));
+    }
+    delay(used, header) {
+        let delay = Math.min(this.maxDelayMs, this.backoffMs * 2 ** used);
+        if (this.jitter)
+            delay *= Math.random();
+        if (this.retryAfter && header) {
+            const seconds = /^[0-9]+$/.test(header) ? Number(header) : undefined;
+            const value = seconds === undefined ? Date.parse(header) - Date.now() : Math.min(seconds, this.maxDelayMs / 1000) * 1000;
+            if (!Number.isNaN(value))
+                delay = Math.max(delay, Math.min(this.maxDelayMs, Math.max(0, value)));
+        }
+        return delay;
+    }
+}
+exports.RetryPolicy = RetryPolicy;
+function replayable(body, factory) {
+    return factory !== undefined || body === undefined || typeof body === "string" || body instanceof Uint8Array;
+}
+async function retryWait(delay, deadline, signal) {
+    if (signal.aborted)
+        throw new errors_js_1.AbortError(undefined, { cause: signal.reason });
+    if (deadline - performance.now() <= delay)
+        throw new errors_js_1.FastlsTimeoutError("total deadline exceeded before retry", "total");
+    try {
+        await (0, promises_1.setTimeout)(delay, undefined, { signal });
+    }
+    catch (error) {
+        if (signal.aborted)
+            throw new errors_js_1.AbortError(undefined, { cause: signal.reason });
+        throw error;
+    }
+}

package/dist/session.d.ts

@@ -7,7 +7,13 @@ 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";
 import { type FetchOptions, type FetchResponse } from "./fetch.js";
+import { ProfileSpec, type AddressPolicy } from "./profiles.js";
+import { RetryPolicy } from "./retry.js";
 export interface RequestOptions {
+    retry?: RetryPolicy | null;
+    bodyFactory?: () => UploadBody;
+    profileSpec?: ProfileSpec;
+    httpVersion?: "auto" | "h3";
     /** 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. */
@@ -32,6 +38,10 @@ export interface RequestOptions {
 }
 export type DuplexOptions = Omit<RequestOptions, "body" | "duplex" | "json" | "form" | "files">;
 export interface SessionOptions {
+    retry?: RetryPolicy;
+    addressPolicy?: AddressPolicy;
+    profileSpec?: ProfileSpec;
+    httpVersion?: "auto" | "h3";
     /** 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. */
@@ -79,6 +89,8 @@ export declare class Session {
     private readonly websockets;
     private readonly producers;
     private closed;
+    private readonly closing;
+    private readonly retry?;
     private notifier?;
     private setup?;
     constructor(options?: SessionOptions);

package/dist/session.js

@@ -15,6 +15,8 @@ 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");
+const profiles_js_1 = require("./profiles.js");
+const retry_js_1 = require("./retry.js");
 function decoding(decode, maximum) {
     if (typeof decode !== "boolean")
         throw new TypeError("decodeContent must be a boolean");
@@ -78,15 +80,28 @@ class Session {
     websockets = new Set();
     producers = new Set();
     closed = false;
+    closing = new AbortController();
+    retry;
     notifier;
     setup;
     constructor(options = {}) {
+        if (options.retry !== undefined && !(options.retry instanceof retry_js_1.RetryPolicy))
+            throw new TypeError("retry must be RetryPolicy");
+        this.retry = options.retry;
         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";
+        if (options.profile !== undefined && typeof options.profile !== "string")
+            throw new TypeError("profile must be a selector string");
+        if (options.profileSpec !== undefined && !(options.profileSpec instanceof profiles_js_1.ProfileSpec))
+            throw new TypeError("profileSpec must be a ProfileSpec");
+        if (options.profile !== undefined && options.profileSpec !== undefined)
+            throw new TypeError("profile and profileSpec are mutually exclusive");
+        if (options.httpVersion !== undefined && !["auto", "h3"].includes(options.httpVersion))
+            throw new TypeError("httpVersion must be auto or h3");
+        this.profile = options.profile ?? (options.profileSpec !== undefined || options.httpVersion === "h3" ? "" : "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;
@@ -104,7 +119,36 @@ class Session {
         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"));
+        const configuration = { schema_version: 1 };
+        const required = [];
+        if (options.addressPolicy !== undefined) {
+            if (!options.addressPolicy || typeof options.addressPolicy !== "object" || Array.isArray(options.addressPolicy))
+                throw new TypeError("addressPolicy must be an object");
+            configuration.address_policy = options.addressPolicy;
+            required.push("transport_address_policy_v1");
+        }
+        if (options.profileSpec !== undefined) {
+            configuration.profile_spec = options.profileSpec.toJSON();
+            required.push("profile_spec_v1");
+        }
+        if (options.httpVersion === "h3") {
+            configuration.http_version = "h3";
+            required.push("http3_v1");
+        }
+        if (required.length) {
+            this.native.requireCapabilities(required);
+            if (options.profile !== undefined)
+                configuration.profile = options.profile;
+            if (this.proxy && (options.addressPolicy !== undefined || options.httpVersion === "h3")) {
+                const error = new errors_js_1.FastlsError("unsupported transport combination");
+                error.code = "unsupported_capability";
+                throw error;
+            }
+            const raw = (0, native_js_1.encodeNativeJSON)(configuration);
+            this.handle = (0, native_js_1.asHandle)(this.native.call("transport_create_with_options", raw, raw.length));
+        }
+        else
+            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() {
@@ -157,6 +201,8 @@ class Session {
     }
     begin(method, url, options, manual = false, completeHeaders = false) {
         this.ensureOpen();
+        if ("addressPolicy" in options)
+            throw new TypeError("addressPolicy is a Session creation option");
         if (options.signal !== undefined && !(options.signal instanceof AbortSignal)) {
             throw new TypeError("signal must be an AbortSignal");
         }
@@ -215,9 +261,24 @@ class Session {
                 trailers[name] = [...values];
             }
         }
+        if (options.profileSpec !== undefined && !(options.profileSpec instanceof profiles_js_1.ProfileSpec))
+            throw new TypeError("profileSpec must be a ProfileSpec");
+        if (options.profileSpec !== undefined && options.profile !== undefined)
+            throw new TypeError("profile and profileSpec are mutually exclusive");
+        const required = [];
+        if (options.profileSpec !== undefined)
+            required.push("profile_spec_v1");
+        if (options.httpVersion !== undefined) {
+            if (!["auto", "h3"].includes(options.httpVersion))
+                throw new TypeError("httpVersion must be auto or h3");
+            required.push("http3_v1");
+        }
+        if (required.length)
+            this.native.requireCapabilities(required);
         const handle = this.native.start({
             session: this.handle, url, method, headers, trailers, proxy: proxy || undefined, proxy_ca_pem: proxyCaPem,
-            profile: options.profile ?? this.profile,
+            profile: options.profile ?? (options.profileSpec !== undefined || options.httpVersion === "h3" ? "" : this.profile),
+            profile_spec: options.profileSpec?.toJSON(), http_version: options.httpVersion,
             ...timeouts, decode_content: decodeContent, max_decoded_bytes: maxDecodedBytes,
             disable_redirect: true,
             ca_pem: this.caPem,
@@ -269,9 +330,24 @@ class Session {
         }
     }
     async stream(method, url, options = {}) {
+        const retry = options.retry === undefined ? this.retry : options.retry ?? undefined;
+        if (retry !== undefined && !(retry instanceof retry_js_1.RetryPolicy))
+            throw new TypeError("retry must be RetryPolicy or null");
+        let factory = options.bodyFactory;
+        if (factory !== undefined && typeof factory !== "function")
+            throw new TypeError("bodyFactory must be a function");
+        if (factory !== undefined && ["body", "json", "form", "files"].some(key => key in options))
+            throw new TypeError("bodyFactory cannot be combined with body, json, form or files");
+        if (options.duplex && (retry !== undefined || factory !== undefined))
+            throw new TypeError("duplex does not support retry or bodyFactory");
+        if (options.signal !== undefined && !(options.signal instanceof AbortSignal))
+            throw new TypeError("signal must be an AbortSignal");
+        const signal = options.signal === undefined ? this.closing.signal : AbortSignal.any([options.signal, this.closing.signal]);
         const headers = mergeHeaders(this.headers, options.headers);
         const prepared = (0, request_options_js_1.prepare)(url, options, headers);
         url = prepared.url;
+        // Session close has its own established transfer error. Its signal only
+        // interrupts retry backoff; forwarding it as a caller abort changes that error.
         options = { ...options, headers, body: prepared.body };
         for (const key of ["params", "json", "form", "files"])
             delete options[key];
@@ -280,14 +356,37 @@ class Session {
             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++) {
+        let used = 0, redirects = 0;
+        for (;;) {
+            this.ensureOpen();
+            if (signal.aborted)
+                throw new errors_js_1.AbortError(undefined, { cause: signal.reason });
+            if (factory !== undefined)
+                options.body = factory();
             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);
+            let response;
+            try {
+                response = await this.streamHop(method, url, options);
+            }
+            catch (error) {
+                if (!retry?.eligible(method, used, (0, retry_js_1.replayable)(options.body, factory), error))
+                    throw error;
+                await (0, retry_js_1.retryWait)(retry.delay(used), deadline, signal);
+                used++;
+                continue;
+            }
+            if (retry?.eligible(method, used, (0, retry_js_1.replayable)(options.body, factory), undefined, response.status)) {
+                const delay = retry.delay(used, response.headers.get("retry-after"));
+                await response.closeAsync();
+                await (0, retry_js_1.retryWait)(delay, deadline, signal);
+                used++;
+                continue;
+            }
             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)))
+            if (options.duplex || options.allowRedirects === false || ![301, 302, 303, 307, 308].includes(response.status) || !location || ([307, 308].includes(response.status) && !(0, retry_js_1.replayable)(options.body, factory)))
                 return response;
             try {
                 if (redirects >= maximum)
@@ -303,10 +402,12 @@ class Session {
                     method = "GET";
                     delete options.body;
                     delete options.trailers;
+                    factory = undefined;
                     for (const name of ["content-type", "content-length", "transfer-encoding"])
                         delete headers[name];
                 }
                 url = target.href;
+                redirects++;
                 await response.read();
             }
             finally {
@@ -341,6 +442,8 @@ class Session {
     }
     /** Open a manual exchange; send() and response reads can run concurrently. */
     duplex(method, url, options = {}) {
+        if (options.retry !== undefined || options.bodyFactory !== undefined)
+            throw new TypeError("manual duplex does not support retry or bodyFactory");
         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();
@@ -424,6 +527,7 @@ class Session {
             return;
         this.cookies.clear();
         this.closed = true;
+        this.closing.abort(new errors_js_1.AbortError("session is closed"));
         try {
             for (const transfer of this.active)
                 transfer.close(new errors_js_1.FastlsError("session is closed"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastls/fastls",
-  "version": "0.10.2",
+  "version": "0.12.0",
   "description": "Node.js bindings for the Fastls C ABI",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -35,10 +35,10 @@
     "registry": "https://registry.npmjs.org/"
   },
   "optionalDependencies": {
-    "@fastls/fastls-win32-x64": "0.10.2",
-    "@fastls/fastls-linux-x64-glibc": "0.10.2",
-    "@fastls/fastls-linux-arm64-glibc": "0.10.2",
-    "@fastls/fastls-darwin-x64": "0.10.2",
-    "@fastls/fastls-darwin-arm64": "0.10.2"
+    "@fastls/fastls-win32-x64": "0.12.0",
+    "@fastls/fastls-linux-x64-glibc": "0.12.0",
+    "@fastls/fastls-linux-arm64-glibc": "0.12.0",
+    "@fastls/fastls-darwin-x64": "0.12.0",
+    "@fastls/fastls-darwin-arm64": "0.12.0"
   }
 }