@fastls/fastls 0.10.2 → 0.11.0

package/README.md

@@ -1,5 +1,21 @@
 # Fastls Node.js SDK
 
+开发候选新增 Session `addressPolicy`、`profileSpec: new ProfileSpec(...)` 和
+`httpVersion: "h3"`；Session/fetch 可选择完整 Spec 或显式协议。
+`addressPolicy` 只能创建可信 owner，不能由 `session.fetch()` 或请求替换。
+现有发布库不具备新能力，旧库或缺符号会明确报错，见[能力契约](../CAPABILITIES.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.10.1**。
 
 支持 HTTP/1.1、HTTP/2、流式上传下载、双工、SSE、WebSocket、会话 Cookie 和 HTTP/HTTPS/SOCKS 代理。网络请求由 Go 执行，通过 Koffi 在当前 Node 进程中调用；使用者无需 Python 或 RPC 服务。

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,10 @@
 import { Session, type RequestOptions } from "./session.js";
+import type { ProfileSpec, AddressPolicy } from "./profiles.js";
 export interface FetchOptions extends RequestInit {
+    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,7 +11,9 @@ 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"]);
+        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}`);
@@ -29,7 +31,7 @@ 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, body, 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 +110,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,6 @@
 export { Session } from "./session.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,10 @@
 "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.Session = void 0;
 var session_js_1 = require("./session.js");
 Object.defineProperty(exports, "Session", { enumerable: true, get: function () { return session_js_1.Session; } });
+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, 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/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/session.d.ts

@@ -7,7 +7,10 @@ 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";
 export interface RequestOptions {
+    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 +35,9 @@ export interface RequestOptions {
 }
 export type DuplexOptions = Omit<RequestOptions, "body" | "duplex" | "json" | "form" | "files">;
 export interface SessionOptions {
+    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. */

package/dist/session.js

@@ -15,6 +15,7 @@ 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");
 function decoding(decode, maximum) {
     if (typeof decode !== "boolean")
         throw new TypeError("decodeContent must be a boolean");
@@ -86,7 +87,15 @@ class Session {
         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 +113,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 +195,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 +255,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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastls/fastls",
-  "version": "0.10.2",
+  "version": "0.11.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.11.0",
+    "@fastls/fastls-linux-x64-glibc": "0.11.0",
+    "@fastls/fastls-linux-arm64-glibc": "0.11.0",
+    "@fastls/fastls-darwin-x64": "0.11.0",
+    "@fastls/fastls-darwin-arm64": "0.11.0"
   }
 }