@fastls/fastls 0.10.1-dev.0 → 0.10.2

package/README.md

@@ -1,6 +1,6 @@
 # Fastls Node.js SDK
 
-Node.js 22+ 的 Fastls C ABI v1 绑定，提供 Promise API、TypeScript 声明、ESM 和 CommonJS 入口。当前开发包版本为 `0.10.1-dev.0`，npm 预发布渠道使用 `next`。
+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 服务。
 
@@ -13,10 +13,10 @@ Node.js 22+ 的 Fastls C ABI v1 绑定，提供 Promise API、TypeScript 声明
 
 ## 安装与快速开始
 
-npm 的 `next` 版本发布后，在消费项目中安装：
+安装指定版本：
 
 ```sh
-npm install @fastls/fastls@next
+npm install @fastls/fastls@0.10.1
 ```
 
 主包通过同版本的可选依赖自动安装当前平台的 Fastls 原生库。保留 optional dependencies；支持 Windows x64、Linux glibc x64/arm64、macOS x64/arm64。Linux musl 和其它架构没有内置包。具体系统最低版本见原生包的 `native/manifest.json`。
@@ -42,24 +42,57 @@ try {
 
 后续片段假定 `session` 已创建且未关闭；`consume`、`produceBytes` 等是应用自行实现的业务函数。每次实际使用均应关闭会话和未消费完的响应。
 
-从源码开发时，在仓库根目录构建动态库和测试服务，再安装 Node 开发依赖：
+源码构建、测试和发包见 [开发指南](DEVELOPMENT.md)。普通 npm 用户不需要这些步骤。
 
-```sh
-python scripts/build.py
-go build -o build/ffi-fixture ./cmd/ffi-fixture
-npm ci --prefix node
-npm run build --prefix node
+## 设置浏览器请求头
+
+Python 0.1.4 / Node 0.10.1 所用的默认 `chrome/156/windows` 配置没有为 `Accept-Encoding`、`Accept-Language` 和 `Priority` 设置默认值。下面的示例显式补充它们；其它配置的默认值可能不同。
+
+```js
+import { fetch } from '@fastls/fastls';
+
+const response = await fetch('https://tls.peet.ws/api/all', {
+  profile: 'chrome/156/windows',
+  headers: {
+    'Accept-Encoding': 'gzip, deflate, br, zstd',
+    'Accept-Language': 'zh-CN,zh;q=0.9,en;q=0.8,en-GB;q=0.7,en-US;q=0.6',
+    'Priority': 'u=0, i',
+  },
+});
+if (!response.ok) throw new Error(`HTTP ${response.status}`);
+console.log(await response.json());
 ```
 
-Windows 测试服务文件名使用 `build/ffi-fixture.exe`，原生构建需要可用的 C 编译器，可通过 `--cc` 指定。`scripts/build.py --local` 会生成忽略跟踪的 `go.work`，使用同级源码仓库；也可用 `FASTLS_LOCAL_FASTLS`、`FASTLS_LOCAL_FTRANSPORT`、`FASTLS_LOCAL_IMITATE` 指向固定副本。当前脚本没有 `--workspace` 参数。正式发布消费同提交 CI 的固定依赖构建，不能用任意本地构建替代。
+`Accept-Language` 表示语言偏好，请按应用需要调整；`Priority` 的值也与请求场景有关，示例不是所有浏览器请求的固定模板。请求头顺序配置只排列已有字段，不会为其中的字段自动生成值。支持自动解压 gzip/deflate/br/zstd，不等于会自动发送对应的 `Accept-Encoding`。显式传入的头值优先于配置默认值；复用会话时，也可通过 Session 的 `headers` 设置。
 
-源码默认加载仓库 `dist/`；普通 `npm pack ./node` 生成需要外部动态库的 thin 包。thin 包可通过 `FASTLS_LIBRARY` 或 `new Session({ library: '/absolute/path/to/library' })` 指定库。GitHub 内置库候选和 npm 拆分包的区别见下文。
+## 从 Node fetch 迁移
 
+新增 `fetch` 入口沿用 Node 原生 fetch 的主要调用习惯，并增加指纹、代理和证书配置：
+
+```js
+import { fetch } from '@fastls/fastls';
+
+const response = await fetch('https://tls.peet.ws/api/all', {
+  profile: 'chrome/156/windows',
+  headers: new Headers({ Accept: 'application/json' }),
+  signal: AbortSignal.timeout(10_000),
+});
+if (!response.ok) throw new Error(`HTTP ${response.status}`);
+console.log(await response.json());
+```
+
+接受字符串、URL、Request，以及标准 Headers、FormData、URLSearchParams、Blob、字节和可读流正文。流式请求使用 `duplex: 'half'`，一次性正文不会为 307/308 自动重放。返回 Node 标准 `Response`，在响应头到达时返回；`text/json/arrayBuffer()` 为异步方法，`body` 为 Web ReadableStream，`ok` 为 200–299。正文只消费一次；不用时必须 `await response.body?.cancel()`。另附只读 `match` 和 `httpVersion`。
+
+顶层 `fetch` 与 Node 一样不保存 Cookie，每次请求的临时资源会在正文读完或取消后关闭。需要 Cookie 和连接长期复用时，使用 `session.fetch(url, options)`，最后 `await session.closeAsync()`。会话级 `library/caFile` 应在构造 Session 时设置。HTTP 错误状态仍返回响应；`redirect` 支持 `follow/manual/error`。默认最多跟随 30 次，可设置 `maxRedirects`。
+
+这不是浏览器环境：不实现 CORS、缓存、自动认证、referrer、integrity 或 keepalive 策略。显式传入 `cache/credentials/integrity/keepalive/mode/referrer/referrerPolicy` 会报错。默认校验 TLS，不支持关闭验证；不接收 Node http/https Agent、dispatcher 或 Axios 配置。超时以毫秒计，使用 `timeoutMs` 或 AbortSignal。
+
+Fastls 原有 `Session.request/stream/duplex/sse/websocket` 保留，适合需要分阶段超时、原始字节、Trailer 和更精细资源控制的场景。Cookie、重定向和默认参数由 JavaScript SDK 管理；动态库负责网络传输、指纹、证书与连接池。旧 C Cookie 接口仅供旧客户端兼容，新 SDK 不使用原生 Cookie 存储。
 
 ## 请求和响应
 
-- `await session.request(method, url, options)`，以及 `get`、`post`，返回完整缓存的 Response。
-- 请求选项包括 `profile`、`headers`、`trailers`、`params`、`json`、`form`、`files`、`body`、`timeoutMs`、`allowRedirects`、`signal`、`proxy`、`proxyCaFile`、`decodeContent`、`maxDecodedBytes`、`duplex`。会话级选项还包括 `library`、`caFile`、`cookies`、`notifications`；以公开 TypeScript 类型为准。
+- `await session.request(method, url, options)`，以及 `get/post/put/patch/delete/head/options`，返回完整缓存的 Response。
+- 请求选项包括 `profile`、`headers`、`trailers`、`params`、`json`、`form`、`files`、`body`、`timeoutMs`、`allowRedirects`、`maxRedirects`、`signal`、`proxy`、`proxyCaFile`、`decodeContent`、`maxDecodedBytes`、`duplex`。会话级选项还包括 `library`、`caFile`、`cookies`、`notifications`；以公开 TypeScript 类型为准。
 - `body` 为字符串、Buffer、Uint8Array、同步/异步字节迭代器、Node Readable 或接收 AbortSignal 的生产者工厂。超过512 KiB的字符串/字节自动使用上传通道。
 - `timeoutMs` 为毫秒整数或 `{ total, connect?, write?, headers?, read? }`，每项范围1..86400000；默认总时限30000。请求级数字覆盖会清除会话分层限制，结构化覆盖替换整份策略。
 - 会话默认头和请求头按大小写不敏感方式合并，请求值优先，包括空字符串。
@@ -76,7 +109,7 @@ Windows 测试服务文件名使用 `build/ffi-fixture.exe`，原生构建需要
 
 未知 profile 报错；Match 保留生成身份和协议基线信息，不承诺与真实浏览器指纹完全等价。
 
-`request('PUT', url, options)` 等可使用其它合法方法；便捷方法只有 `get` 和 `post`。请求头的值为字符串；`trailers` 的值为字符串或只读字符串数组，名称和值由原生层继续验证，且要求 `request_trailers` 能力。
+`request('PUT', url, options)` 等可使用其它合法方法；便捷方法包括 `get/post/put/patch/delete/head/options`。请求头的值为字符串；`trailers` 的值为字符串或只读字符串数组，名称和值由原生层继续验证，且要求 `request_trailers` 能力。
 
 `url` 是最终响应 URL，`httpVersion` 是实际 HTTP 协议版本。缓存响应已经读到 EOF，包含最终 `trailers`；流式响应先消费正文，再读取最终尾部字段。提前关闭不代表已经收到全部 trailers。
 
@@ -113,7 +146,7 @@ try {
 - JSON/表单在内存中编码；超过512KiB自动转为流式上传，不是大型数据增量编码器。默认Content-Type仅在没有会话/请求自定义头时设置；编码正文拒绝Content-Length/Transfer-Encoding。原始body沿用原有规则。
 - `files`接受对象、Map或重复字段对数组。每个文件是Uint8Array、`MultipartReader`，或`[filename, body, contentType?]`；filename为null省略filename参数。默认从读取器name/字段名取文件名；内置固定MIME推断只覆盖txt/json/html/csv/png/jpg/jpeg/pdf，其它类型请显式指定，缺省application/octet-stream。不支持自定义分部头。
 - multipart可配合form字段，每次read最多64KiB，空Uint8Array表示EOF；支持同步/Promise读取器。无需seek/长度/临时文件，不全量缓存文件；调用方负责close和重新定位，成功、失败、取消均保留读取器所有权。提供给read的AbortSignal可中断自定义等待；不可取消的Promise会延后closeAsync清理。Node Readable及FileHandle不能直接作为此读取器，应适配其读取接口；现有原始body的Readable销毁规则不变。
-- multipart管理随机boundary及Content-Type，拒绝会话或请求中显式Content-Type；元数据拒绝控制字符。正文仅使用一次，307/308不自动重放，301/302/303沿用核心GET转换规则。
+- multipart管理随机boundary及Content-Type，拒绝会话或请求中显式Content-Type；元数据拒绝控制字符。正文仅使用一次，307/308不自动重放，301/302/303按 SDK 规则转换方法和丢弃正文。
 - request/get/post/stream/sse与自动duplex共享参数处理；multipart不支持duplex。手动duplex只接受params，正文继续send()/finishUpload()。自动双工支持JSON/表单且关闭重定向。
 
 ## 流式下载和取消
@@ -150,7 +183,7 @@ try {
 
 Session 复用原生会话的 H1 keep-alive 和 H2 多路复用；不同 Session 隔离。
 `session.closeIdleConnections()` 释放空闲连接，保留 Cookie。
-Cookie 自动管理和重定向处理均由 Go 完成：
+Cookie 自动管理和重定向处理均由 JavaScript SDK 完成；原生上下文只负责传输：
 
 ```js
 session.cookies.set('token', 'value', { url: 'https://example.com', path: '/', secure: true });
@@ -180,22 +213,16 @@ try {
 } finally { await session.closeAsync(); }
 ```
 
-Session和请求的`proxy`接受URL字符串或null。请求省略或undefined继承会话默认值；null或空字符串直连。普通请求、stream、sse、自动/手动duplex遵循相同规则。传入其它类型会报TypeError。显式代理要求原生`proxy_tunnels`能力；旧ABI-v1库仍可直连，代理请求在登记请求句柄前报错。
+Session和请求的`proxy`接受URL字符串或null。请求省略或undefined继承会话默认值；null或空字符串直连。普通请求、stream、sse、自动/手动duplex遵循相同规则。传入其它类型会报TypeError。显式代理要求原生`proxy_tunnels`能力；当前 SDK 始终要求 transport_context_v1；缺少代理能力时，代理请求在登记句柄前报错。
 
 `http://`对HTTP和HTTPS目标均使用HTTP/1.1 CONNECT，默认端口80。`socks5://`本机解析目标域名，`socks5h://`交给代理解析，默认端口1080。支持HTTP Basic和SOCKS用户名/密码认证，凭据按URL规则转义，例如密码中的@写成%40。不读取HTTP_PROXY、HTTPS_PROXY、ALL_PROXY、NO_PROXY及其小写形式。`https://`在代理TLS中运行HTTP/1.1 CONNECT，默认端口443，证书和主机名验证始终开启，不回退到明文。HTTPS代理另要求原生`https_proxy_tls`能力；暂不支持SOCKS4或PAC，详情见上级PROXY.md。
 
 `proxyCaFile`只控制HTTPS代理信任，`caFile`只控制目标信任，两者互不代替。未设置代理CA使用系统根；提供文件则替换系统根。构造Session时读取默认代理CA一次，请求指定路径时重新读取；请求undefined继承默认，null恢复系统根。直连、HTTP和SOCKS忽略代理CA默认值及请求覆盖。代理地址及凭据、profile、代理CA和目标CA共同隔离连接池。目标证书仍需验证；目标请求禁止设置Proxy-Authorization和Proxy-Connection。认证只用于代理握手，错误消息不回显凭据或代理任意响应短语。握手计入connect和total预算，AbortSignal取消会关闭未建立的隧道；取消单条H2流继续复用健康的共享隧道。代理拒绝后不降级或自动重试。
 
-代理测试使用Node测试进程中的独立、仅访问loopback的CONNECT/RFC1928/RFC1929靶场；SDK本身不依赖Python或代理辅助进程。十三组Python行为映射、源码及内置库安装包统一验收；语言适配见PARITY.md。
-
-`npm run test:proxy:soak`默认以32路并发运行60秒，轮换正常请求、共享H2流取消、错误认证和停滞握手取消；四种scheme分别使用真实loopback代理。FASTLS_NODE_PROXY_SOAK_SECONDS可设为1..300。Linux当前Go/Node组合执行该独立测试，沿用现有RSS、Go堆、goroutine及句柄阈值，逐批记录写入build/node-proxy-recovery-*.json，不计入225项主套件。
-
-代理独立长测与SSE长测一样，显式使用`--max-semi-space-size=16`固定测试进程的V8半空间上限。本机Windows Node24默认策略在持续分配时将new_space保留空间从4MiB扩大至128MiB，而Go堆、原生请求和隧道已回收。该参数仅作用于独立测试进程，不修改SDK用户进程的运行配置，也不放宽RSS或句柄阈值。证据保存运行参数、V8空间快照，以及阈值判定之后的完整GC诊断；判定使用GC前的最终采样。
+代理测试和资源长测的运行方式见 [开发说明](https://github.com/FastTLS/fastls-ffi/blob/main/node/DEVELOPMENT.md#代理长测)。
 
 私有HTTPS代理示例：`new Session({ proxy: 'https://proxy.example:443', proxyCaFile: '/path/to/proxy-ca.pem', caFile: '/path/to/target-ca.pem' })`。两类CA分别验证代理与目标；请求可用`{ proxyCaFile: null }`恢复代理系统信任，或指定其它代理CA文件，均不会复用不相符的已有隧道。
 
-代理长测按靶场握手阶段同步取消，避免固定毫秒计时在慢runner上提前中止TLS而未触达待测CONNECT阶段。HTTPS靶场延迟50毫秒处理CONNECT，确保该时序在本地也能覆盖。H2可合并同一代理的在途建连；每批每种scheme至少触发一次真实握手取消，并逐批核对启动/回收计数，不依赖请求数等于物理建连数。资源阈值保持不变。
-
 ## HTTP/2 双工
 
 `duplex: true` 允许响应头到达后继续上传，可同时读取响应。仅支持 HTTP/2，并始终禁止自动重定向；普通上传仍拒绝未完成上传时提前返回的 2xx。
@@ -299,17 +326,17 @@ send/ping/pong等到原生写入完成；同时最多一名读者和一名写入
 
 正常远端关闭抛出WebSocketClosed(code/reason)，连接保留closeCode/closeReason。closeAsync的整个握手受closeTimeoutMs约束（最多60000），超时直接释放；abort立即中断。连接级AbortSignal中断当前及后续操作，Session关闭回收全部所属WS。读/写/握手超时使连接终止，FastlsTimeoutError.phase为read/write/handshake；HTTP会话总超时不限定WS寿命。
 
-复用Session的profile、头、CA、代理与代理CA；params、请求级覆盖/显式直连沿用HTTP规则。wss始终验证证书和主机名，ALPN适配HTTP/1.1；不承诺适配后的Upgrade头序与浏览器完全一致。使用websocket_v1和三个可选ABI符号，旧库的HTTP继续可用。通知默认共享一条会话连接，poll可显式选择，不阻塞主线程或增加网络线程。
+复用Session的profile、头、CA、代理与代理CA；params、请求级覆盖/显式直连沿用HTTP规则。wss始终验证证书和主机名，ALPN适配HTTP/1.1；不承诺适配后的Upgrade头序与浏览器完全一致。使用websocket_v1和三个可选ABI符号，当前 SDK 还要求 transport_context_v1；ABI 号相同不能代替能力检查。通知默认共享一条会话连接，poll可显式选择，不阻塞主线程或增加网络线程。
 
-默认与HTTP共享Cookie罐，要求原生库提供websocket_cookies能力。cookieMode:"manual"可禁用本次握手的自动收发，并兼容旧库。显式Cookie头（包括空值）优先，默认仍接受握手Set-Cookie；Session的cookies:false禁用自动收发。域/路径/Secure/过期规则与HTTP一致。有效101及普通HTTP拒绝/重定向响应可写回；无效101或TLS失败不写回。Authorization/Origin由调用方设置。无压缩、H2/H3 CONNECT、握手重定向、自动心跳/重连或消息重放。ping只证明写入完成，可用info.websocket.pongs/last_pong_base64观察响应。协议细节与原生资源限制见根目录WEBSOCKET.md。
+默认与 HTTP 共享 SDK Cookie 罐；原生库不保存 Cookie。cookieMode:"manual" 可禁用本次握手的自动 Cookie 收发。显式Cookie头（包括空值）优先，默认仍接受握手Set-Cookie；Session的cookies:false禁用自动收发。域/路径/Secure/过期规则与HTTP一致。有效101及普通HTTP拒绝/重定向响应可写回；无效101或TLS失败不写回。Authorization/Origin由调用方设置。无压缩、H2/H3 CONNECT、握手重定向、自动心跳/重连或消息重放。ping只证明写入完成，可用info.websocket.pongs/last_pong_base64观察响应。协议细节与原生资源限制见根目录WEBSOCKET.md。
 
-npm run test:quick先运行类型、清单及WS/原生用例；test:ws针对25项WS和16项共享Cookie；test:ws:soak运行独立60秒/32路资源回收。快速反馈不能替代225项源码/安装包完整回归与六组平台验收。
+npm run test:quick先运行类型、清单及WS/原生用例；test:ws针对25项WS和16项共享Cookie；test:ws:soak运行独立60秒/32路资源回收。快速反馈不能替代231项源码/安装包完整回归与六组平台验收。
 
-原生websocket_cookie_control_v1明确保证按连接禁用自动Cookie，并保留0.10的websocket_cookies契约。仅提供websocket_cookies_v1的历史分发库需要升级：SDK会在建立连接前拒绝manual，防止Cookie被静默发送或保存。无自动Cookie的旧WS库仍支持manual。npm run test:compat用真实原生库验证收发、显式头和失败握手；可通过FASTLS_COOKIE_COMPAT_LIBRARIES传入含library与kind(full/legacy/automatic-only)的JSON数组，逐库在独立进程运行。源码快速检查与隔离安装包都会执行当前库兼容验收。
+0.10.1 SDK 使用不含 Cookie 的原生传输上下文，并在 JavaScript 中完成 Cookie 选择及响应更新。旧原生 Cookie 能力只为历史客户端保留。npm run test:compat 验证当前完整库的收发、显式头和失败握手。
 
 ## 原生就绪通知
 
-默认使用`notifications: 'auto'`：新库带session_notifications能力且符号完整时启用，旧ABI-v1库继续轮询。`required`缺少能力时在创建原生会话前报错；`poll`显式使用原调度器。
+默认使用`notifications: 'auto'`：新库带session_notifications能力且符号完整时启用，缺少通知能力时轮询，但库仍须满足 transport_context_v1 等 SDK 基础能力。`required`缺少能力时在创建原生会话前报错；`poll`显式使用原调度器。
 
 ```js
 const session = await Session.open({ notifications: 'required' });
@@ -332,55 +359,27 @@ try {
 网络由 Go goroutine 执行。新库默认通过每会话一条本机TCP连接接收就绪提示，Node事件循环随后重查非阻塞C接口，不定时查询空闲请求。
 通知是重查提示，不保证读写一定成功；通过代次快照防止漏唤醒，并独立取消双工的读写等待。
 立即调用会让出事件循环；不承诺固定吞吐量或延迟，原生控制调用及JSON/Buffer转换仍在主线程执行。
-显式poll或旧库回退使用共享约10ms定时器，保留每轮处理数量及时间上限。
+显式 poll 或配套库缺少通知能力时使用共享约 10ms 定时器，保留每轮处理数量及时间上限。
 
 句柄使用 bigint，无损解析和序列化 ABI JSON 数字；返回的 C 字符串逐次由 fastls_free 释放。
-外部动态库基础能力要求为 `stream_decode`、`phase_timeouts`、`stream_upload`、`write_timeout`；双工、代理、WebSocket 和请求 trailers 在调用时另检查对应能力。加载时检查 ABI 及所需能力，并使用系统级固定加载（Windows PIN / POSIX NODELETE），避免Node环境清理时卸载仍有Go后台线程的动态库。
+外部动态库基础能力要求为 `transport_context_v1`、`stream_decode`、`phase_timeouts`、`stream_upload`、`write_timeout`；双工、代理、WebSocket 和请求 trailers 在调用时另检查对应能力。加载时检查 ABI 及所需能力，并使用系统级固定加载（Windows PIN / POSIX NODELETE），避免Node环境清理时卸载仍有Go后台线程的动态库。
 原生限制仍适用：最多 64 会话、256 未关闭请求，每会话最多 16 种传输配置。
-代理支持HTTP/HTTPS CONNECT、socks5及socks5h，见下节；WebSocket见对应章节。
-
-## 候选包与原生库加载
-
-构建本平台Go动态库后，运行 `npm run pack:native`，产物位于上级 `dist/`。
-例如Windows x64：`fastls-fastls-0.10.1-dev.0-win32-x64.tgz`；Linux包名另带`-glibc`。
-在目标项目执行 `npm install <候选包绝对路径> --ignore-scripts`，随后即可 `new Session()`，无需Go、Python、编译器或FASTLS_LIBRARY。
-安装时保留npm可选依赖，Koffi使用对应平台的预编译组件。`npm run test:package`在空工具搜索路径、清除FASTLS_LIBRARY且关闭安装脚本的临时项目中重复完整225项测试。靶场是仓库中已构建的独立测试服务，SDK和动态库均从安装目录加载。
-
-当前候选覆盖Windows x64、Linux glibc x64/arm64、macOS x64/arm64，Node22+。每个tarball只含一个系统/架构，不能将同名版本的这些变体当成可直接发布到npm的通用包。npm的os/cpu/libc字段限制安装目标；首次使用还检查平台、ABI声明、库SHA256及Linux的glibc版本。Linux最低glibc从ELF符号版本提取，macOS最低版本从Mach-O提取，具体要求及系统动态依赖见包内`native/manifest.json`，不将CI宿主机上的通过扩大为所有旧系统均已测试。musl不在当前范围。
-
-加载顺序：显式 `SessionOptions.library` → `FASTLS_LIBRARY` → 包内 `native/manifest.json` 对应的库 → 已安装主包的本平台可选依赖；源码目录没有内置 manifest 时使用仓库 `dist/`。已安装的 thin 包没有仓库回退。可选原生包必须与主包同版本；缺包、错误平台、glibc 不兼容或摘要不一致均报错。显式路径覆盖仍检查 ABI 与必需能力。SHA-256 只验证内容完整性，不能替代来源签名。
-
-清单还保存Go构建来源摘要、模块版本/校验和、FastTLS仓库提交和收集到的许可证文本。`native/THIRD_PARTY_NOTICES.txt`仅是可用材料清单。依赖许可证按实际构建输入收集；imitate已补齐Apache-2.0许可证，npm发布要求所有平台的licenseReviewRequired均为空。GitHub内置库候选保持private且没有安装/构建脚本；npm主包与平台包的发布流程见NPM_RELEASE.md。
-
-npm 拆分包通过 `npm run test:package` 后再执行 `npm run test:npm` 生成，主包与本机原生包位于 `dist/npm/`。五个同名同版本的 GitHub 内置库候选不能作为五个 npm 版本发布。首次 registry 发布必须使用同提交 main CI 汇总得到的六包组，详见 NPM_RELEASE.md。
-
-## 验证
-
-所有命令从仓库根目录执行，先完成动态库和测试服务构建。
-
-```sh
-npm run test:quick --prefix node
-npm test --prefix node
-npm run test:package --prefix node
-npm run test:npm --prefix node
-python node/scripts/test-npm-release.py
-```
-
-`test:quick` 提供类型、映射、原生绑定、WebSocket 和 Cookie 兼容的短反馈。`npm test`、`test:package`、`test:npm` 分别运行源码、内置库候选、npm 拆分包的完整 225 项套件：十五组 Python 的 209 项行为映射，加 2 项绑定和 14 项 Node 专有测试。类型、Cookie 真实库兼容、安装元数据和发布边界检查另计；当前发布边界测试为 9 项。
-
-两类安装测试都在独立消费项目运行，关闭安装脚本、清除外部库环境变量并移除编译工具搜索路径。拆分包测试由临时 registry 提供尚未发布的本项目平台包，npm 自行按平台筛选；其它依赖仍使用正常 registry。
-
-主 CI 覆盖五个平台的 Node 24，以及 Linux x64 的 Node 22 组合，复用固定的原生构建输入。源码证据位于 `build/node-*.json`；内置候选和摘要在 `dist/`；拆分包、`npm-package-info.json` 和独立安装证据在 `dist/npm/`。具体映射、资源阈值及长测命令见 PARITY.md。功能检查和资源长测分开执行，不把清单存在或历史绿色结果当作新提交已通过。
+代理支持 HTTP/HTTPS CONNECT、socks5 及 socks5h，见代理章节；WebSocket见对应章节。
 
 ## 与 Python 的语言差异
 
 Node统一使用Promise API，不提供Python同步Session或共享同步会话多线程调用；对应场景采用同步迭代器输入和96路Promise请求验证，不宣称线程安全。Node Readable按自身流的生命周期管理文件句柄，区别于Python保留调用方文件对象。
 JavaScript无法强行中断任意Promise：取消会立即释放原生请求，并请求迭代器return/destroy；生产者正在等待的自定义I/O必须支持取消，才能保证其finally及时执行。推荐使用接收AbortSignal的上传工厂。Python的协程强制取消场景对应为工厂信号取消，报告中明确标记适配。
 
-## 发布与授权
+## 文档、许可证与使用声明
+
+[完整 Node 文档](https://fasttls.github.io/node/) · [Apache-2.0](LICENSE)。原生第三方声明随平台包提供。
+
+## 使用边界与免责声明
+
+仅在拥有权限的系统、数据和网络上使用，并遵守适用法律、服务条款及隐私要求。软件按许可证约定以“现状”提供，不承诺可用性、特定用途适用性、第三方服务放行、匿名性或与真实浏览器完全一致。浏览器名称和版本用于描述配置，不表示获得相应厂商认证或背书。部署方负责访问控制、密钥和个人信息保护、请求限额及数据备份；担保排除与责任限制以随附许可证及适用法律为准。本说明不改变许可证授予的权利或新增许可限制。
 
-维护者在 main 的同提交完整 CI 成功后，运行 `npm-publish.yml` 准备或发布 npm 六包组；首次发布、账号权限、2FA、Trusted Publisher 和重试步骤见 NPM_RELEASE.md。
 
-`node-release.yml` 单独签发 GitHub 内置库候选和 thin 包，生成 SHA256SUMS、Sigstore 来源证明及清单，不会发布 npm。既有 `node-v0.10.1-dev.0` GitHub 预发布使用历史包名 `@fasttls/fastls`；本次 npm 包名为 `@fastls/fastls`，两套归档不能互换。后续 GitHub 签发使用新版本号，不能覆盖既有 tag 的来源记录。
+## 动态库选择与安装排错
 
-每次构建收集原生依赖许可证，npm 发布要求五个平台的 `licenseReviewRequired` 均为空。`imitate` 已固定到补齐 Apache-2.0 的提交；是否满足要求以本次候选清单为准。发布状态以 npm registry 和已完成的工作流为准。
+加载优先级：显式 SessionOptions.library → FASTLS_LIBRARY → 包内 manifest → 同版本平台可选依赖；源码目录可回退仓库 dist，已安装 thin 包不回退仓库。普通 npm 用户应保留 optionalDependencies，不必设置外部库路径。外部旧库可能覆盖新包，ABI 号相同也不保证扩展能力相同。Linux glibc 与 macOS 最低版本、摘要及动态依赖以 native/manifest.json 为准。更多排错见 [在线帮助](https://fasttls.github.io/help/)。

package/dist/cookies.d.ts

@@ -13,11 +13,18 @@ export interface Cookie {
     value: string;
 }
 export declare class Cookies {
-    private readonly command;
-    constructor(command: (input: unknown) => unknown);
+    private readonly ensureOpen;
+    private readonly enabled;
+    private readonly jar;
+    constructor(ensureOpen: () => void, enabled?: boolean);
+    private url;
     getAll(url: string): Cookie[];
     get(name: string, url: string): string | undefined;
     set(name: string, value: string, options: CookieOptions): void;
     delete(name: string, options: Pick<CookieOptions, "url" | "path" | "domain">): void;
     clear(): void;
+    /** @internal */
+    header(url: string): string;
+    /** @internal */
+    extract(url: string, fields: string[]): void;
 }

package/dist/cookies.js

@@ -1,27 +1,70 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Cookies = void 0;
+const tough_cookie_1 = require("tough-cookie");
+const errors_js_1 = require("./errors.js");
 class Cookies {
-    command;
-    constructor(command) {
-        this.command = command;
+    ensureOpen;
+    enabled;
+    jar = new tough_cookie_1.CookieJar();
+    constructor(ensureOpen, enabled = true) {
+        this.ensureOpen = ensureOpen;
+        this.enabled = enabled;
+    }
+    url(value) {
+        try {
+            const url = new URL(value.replace(/^ws:/, "http:").replace(/^wss:/, "https:"));
+            if (!["http:", "https:"].includes(url.protocol) || url.username || url.password)
+                throw new Error();
+            return url.href;
+        }
+        catch {
+            throw new errors_js_1.FastlsError("cookie URL must be absolute HTTP(S) without credentials");
+        }
     }
     getAll(url) {
-        return this.command({ action: "get", url });
+        this.ensureOpen();
+        const target = this.url(url);
+        return this.enabled ? this.jar.getCookiesSync(target).map(cookie => ({ name: cookie.key, value: cookie.value })) : [];
     }
     get(name, url) {
         return this.getAll(url).find(cookie => cookie.name === name)?.value;
     }
     set(name, value, options) {
-        this.command({ action: "set", url: options.url, cookie: {
-                name, value, path: options.path, domain: options.domain,
-                secure: options.secure, http_only: options.httpOnly,
-                max_age: options.maxAge, expires: options.expires,
-            } });
+        this.ensureOpen();
+        if (!this.enabled)
+            throw new errors_js_1.FastlsError("cookie store is disabled");
+        if (!/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(name) || /[^\x20-\x7e]|[;"\\]/.test(value) || Buffer.byteLength(name + value) > 4096)
+            throw new errors_js_1.FastlsError("invalid cookie name or value");
+        if (options.path !== undefined && (!options.path.startsWith("/") || /[\x00-\x1f;]/.test(options.path)))
+            throw new errors_js_1.FastlsError("invalid cookie path");
+        if (options.maxAge !== undefined && (!Number.isInteger(options.maxAge) || options.maxAge < -2147483648 || options.maxAge > 2147483647))
+            throw new errors_js_1.FastlsError("invalid cookie maxAge");
+        const expires = options.expires === undefined ? undefined : new Date(options.expires);
+        if (expires && (!Number.isFinite(expires.getTime()) || !/^\d{4}-\d\d-\d\dT.*(?:Z|[+-]\d\d:\d\d)$/.test(options.expires)))
+            throw new errors_js_1.FastlsError("expires must use RFC3339 format");
+        const cookie = new tough_cookie_1.Cookie({ key: name, value, path: options.path, domain: options.domain?.replace(/^\./, ""), secure: options.secure, httpOnly: options.httpOnly, maxAge: options.maxAge, expires });
+        try {
+            this.jar.setCookieSync(cookie, this.url(options.url));
+        }
+        catch {
+            throw new errors_js_1.FastlsError("invalid cookie domain or attributes");
+        }
     }
     delete(name, options) {
         this.set(name, "", { ...options, maxAge: 0 });
     }
-    clear() { this.command({ action: "clear" }); }
+    clear() { this.ensureOpen(); this.jar.removeAllCookiesSync(); }
+    /** @internal */
+    header(url) { return this.getAll(url).map(cookie => `${cookie.name}=${cookie.value}`).join("; "); }
+    /** @internal */
+    extract(url, fields) {
+        this.ensureOpen();
+        if (!this.enabled)
+            return;
+        const target = this.url(url);
+        for (const field of fields)
+            this.jar.setCookieSync(field, target, { ignoreError: true });
+    }
 }
 exports.Cookies = Cookies;

package/dist/fetch.d.ts

@@ -0,0 +1,20 @@
+import { Session, type RequestOptions } from "./session.js";
+export interface FetchOptions extends RequestInit {
+    duplex?: "half";
+    profile?: string;
+    proxy?: string | null;
+    proxyCaFile?: string | null;
+    caFile?: string;
+    library?: string;
+    timeoutMs?: RequestOptions["timeoutMs"];
+    maxRedirects?: number;
+}
+/** A standard Node Response with Fastls transport metadata. */
+export interface FetchResponse extends globalThis.Response {
+    readonly match: Readonly<Record<string, unknown>>;
+    readonly httpVersion: string;
+}
+/** @internal Used by Session.fetch; ownership is explicit to avoid closing shared pools. */
+export declare function fetchWithSession(session: Session, input: string | URL | Request, init?: FetchOptions, owned?: boolean): Promise<FetchResponse>;
+/** Fetch-compatible entry point. No persistent cookie jar is created. */
+export declare function fetch(input: string | URL | Request, init?: FetchOptions): Promise<FetchResponse>;

package/dist/fetch.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchWithSession = fetchWithSession;
+exports.fetch = fetch;
+const node_stream_1 = require("node:stream");
+const session_js_1 = require("./session.js");
+/** @internal Used by Session.fetch; ownership is explicit to avoid closing shared pools. */
+async function fetchWithSession(session, input, init = {}, owned = false) {
+    try {
+        for (const key of ["cache", "credentials", "integrity", "keepalive", "mode", "referrer", "referrerPolicy"]) {
+            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"]);
+        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);
+        const headers = Object.fromEntries(request.headers);
+        let body;
+        if (request.body) {
+            if (typeof init.body === "string" || init.body instanceof Uint8Array)
+                body = init.body;
+            else if (init.body instanceof URLSearchParams)
+                body = init.body.toString();
+            else
+                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,
+            timeoutMs: init.timeoutMs, maxRedirects: init.maxRedirects,
+            allowRedirects: request.redirect === "follow", signal: request.signal,
+        });
+        let closing;
+        const close = () => closing ??= (async () => {
+            stream.closedSignal.removeEventListener("abort", abort);
+            try {
+                await stream.closeAsync();
+            }
+            finally {
+                if (owned)
+                    await session.closeAsync();
+            }
+        })();
+        const abort = () => { void close().catch(() => { }); };
+        stream.closedSignal.addEventListener("abort", abort, { once: true });
+        if (stream.closedSignal.aborted) {
+            await close();
+            throw stream.closedSignal.reason;
+        }
+        try {
+            if (request.redirect === "error" && [301, 302, 303, 307, 308].includes(stream.status))
+                throw new TypeError("redirect encountered with redirect: error");
+            const responseHeaders = new globalThis.Headers();
+            for (const [name, value] of stream.headers.multiItems())
+                responseHeaders.append(name, value);
+            const empty = request.method === "HEAD" || [204, 205, 304].includes(stream.status);
+            const iterator = stream.body[Symbol.asyncIterator]();
+            const responseBody = empty ? null : new ReadableStream({
+                async pull(controller) {
+                    try {
+                        const item = await iterator.next();
+                        if (item.done) {
+                            await close();
+                            controller.close();
+                        }
+                        else
+                            controller.enqueue(item.value);
+                    }
+                    catch (error) {
+                        try {
+                            await close();
+                        }
+                        finally {
+                            controller.error(error);
+                        }
+                    }
+                },
+                async cancel() { try {
+                    await iterator.return?.();
+                }
+                finally {
+                    await close();
+                } },
+            }, { highWaterMark: 0 });
+            const response = new globalThis.Response(responseBody, { status: stream.status, headers: responseHeaders });
+            Object.defineProperties(response, {
+                url: { value: stream.url }, redirected: { value: stream.url !== request.url },
+                match: { value: stream.match }, httpVersion: { value: stream.httpVersion },
+            });
+            if (empty)
+                await close();
+            return response;
+        }
+        catch (error) {
+            await close();
+            throw error;
+        }
+    }
+    catch (error) {
+        if (owned)
+            await session.closeAsync();
+        throw error;
+    }
+}
+/** 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,
+        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 { fetch } from "./fetch.js";
+export type { FetchOptions, FetchResponse } from "./fetch.js";
 export type { SessionOptions, RequestOptions, DuplexOptions, Stats } from "./session.js";
 export { DuplexExchange } from "./duplex.js";
 export { WebSocket, WebSocketClosed } from "./websocket.js";

package/dist/index.js

@@ -3,6 +3,8 @@ 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;
 var session_js_1 = require("./session.js");
 Object.defineProperty(exports, "Session", { enumerable: true, get: function () { return session_js_1.Session; } });
+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");
 Object.defineProperty(exports, "DuplexExchange", { enumerable: true, get: function () { return duplex_js_1.DuplexExchange; } });
 var websocket_js_1 = require("./websocket.js");

package/dist/index.mjs

@@ -1,2 +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;

package/dist/native.js

@@ -103,6 +103,9 @@ 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_context_v1")) {
+                this.functions.transport_create = lib.func("void *fastls_transport_create(void)");
+            }
             let websocketAvailable = false;
             if (features.has("websocket_v1")) {
                 try {

package/dist/response.d.ts

@@ -16,13 +16,15 @@ export declare class Transfer {
     private readonly external?;
     readonly duplex: boolean;
     private readonly notifier?;
+    private readonly acceptHeaders?;
     private readonly controller;
     private closed;
     private failure?;
     private timer?;
     private deadline?;
+    private acceptedHeaders;
     private readonly externalAbort;
-    constructor(native: Native, handle: bigint, release: () => void, external?: AbortSignal | undefined, duplex?: boolean, notifier?: Notifier | undefined);
+    constructor(native: Native, handle: bigint, release: () => void, external?: AbortSignal | undefined, duplex?: boolean, notifier?: Notifier | undefined, acceptHeaders?: ((info: NativeInfo) => void) | undefined);
     private wait;
     attachSignal(total?: number, started?: number): void;
     get signal(): AbortSignal;
@@ -71,6 +73,8 @@ export declare class StreamResponse {
     raiseForStatus(): void;
     /** @internal Check cancellation even when a parser still holds buffered data. */
     ensureOpen(): void;
+    /** @internal Notification for adapters that own a temporary Session. */
+    get closedSignal(): AbortSignal;
     private iterate;
     read(): Promise<Buffer>;
     text(): Promise<string>;

package/dist/response.js

@@ -17,19 +17,22 @@ class Transfer {
     external;
     duplex;
     notifier;
+    acceptHeaders;
     controller = new AbortController();
     closed = false;
     failure;
     timer;
     deadline;
+    acceptedHeaders = false;
     externalAbort = () => this.close(new errors_js_1.AbortError(undefined, { cause: this.external?.reason }));
-    constructor(native, handle, release, external, duplex = false, notifier) {
+    constructor(native, handle, release, external, duplex = false, notifier, acceptHeaders) {
         this.native = native;
         this.handle = handle;
         this.release = release;
         this.external = external;
         this.duplex = duplex;
         this.notifier = notifier;
+        this.acceptHeaders = acceptHeaders;
     }
     wait(probe, signal) {
         return this.notifier ? this.notifier.probe(this.handle, probe, signal) : scheduler_js_1.scheduler.wait(probe, signal);
@@ -69,7 +72,13 @@ class Transfer {
         return this.wait(() => {
             this.ensureOpen();
             const info = this.info();
-            return info.state === "pending" ? undefined : info;
+            if (info.state === "pending")
+                return undefined;
+            if (!this.acceptedHeaders) {
+                this.acceptHeaders?.(info);
+                this.acceptedHeaders = true;
+            }
+            return info;
         }, this.controller.signal);
     }
     async next() {
@@ -177,6 +186,8 @@ class StreamResponse {
         throw new errors_js_1.FastlsHTTPError(this); }
     /** @internal Check cancellation even when a parser still holds buffered data. */
     ensureOpen() { this.transfer.ensureOpen(); }
+    /** @internal Notification for adapters that own a temporary Session. */
+    get closedSignal() { return this.transfer.signal; }
     async *iterate() {
         if (this.consumed)
             throw new errors_js_1.FastlsError("response body already has a consumer");

package/dist/session.d.ts

@@ -6,6 +6,7 @@ import { DuplexExchange } from "./duplex.js";
 import { SSEStream, type SSEOptions } from "./sse.js";
 import { type QueryParams, type JSONValue, type FormFields, type MultipartFiles } from "./request-options.js";
 import { WebSocket, type WebSocketOptions } from "./websocket.js";
+import { type FetchOptions, type FetchResponse } from "./fetch.js";
 export interface RequestOptions {
     /** Undefined inherits the session proxy; null or an empty string connects directly. */
     proxy?: string | null;
@@ -17,6 +18,7 @@ export interface RequestOptions {
     /** Total deadline including response body consumption, in milliseconds. */
     timeoutMs?: Timeout;
     allowRedirects?: boolean;
+    maxRedirects?: number;
     body?: UploadBody;
     params?: QueryParams;
     json?: JSONValue;
@@ -84,6 +86,7 @@ export declare class Session {
     /** Initialize the shared wakeup channel before any HTTP request is allocated. */
     ready(signal?: AbortSignal): Promise<void>;
     private begin;
+    private streamHop;
     stream(method: string, url: string, options?: RequestOptions): Promise<StreamResponse>;
     sse(method: string, url: string, options?: SSEOptions): Promise<SSEStream>;
     request(method: string, url: string, options?: RequestOptions): Promise<Response>;
@@ -91,6 +94,12 @@ export declare class Session {
     duplex(method: string, url: string, options?: DuplexOptions): DuplexExchange;
     get(url: string, options?: RequestOptions): Promise<Response>;
     post(url: string, options?: RequestOptions): Promise<Response>;
+    put(url: string, options?: RequestOptions): Promise<Response>;
+    patch(url: string, options?: RequestOptions): Promise<Response>;
+    delete(url: string, options?: RequestOptions): Promise<Response>;
+    head(url: string, options?: RequestOptions): Promise<Response>;
+    options(url: string, options?: RequestOptions): Promise<Response>;
+    fetch(input: string | URL | Request, options?: FetchOptions): Promise<FetchResponse>;
     websocket(url: string, options?: WebSocketOptions): Promise<WebSocket>;
     listProfiles(): string[];
     stats(): Stats;

package/dist/session.js

@@ -3,6 +3,7 @@ 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");
@@ -13,6 +14,7 @@ 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");
@@ -100,22 +102,10 @@ class Session {
         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";
-        this.handle = (0, native_js_1.asHandle)(this.native.call("session_create"));
-        this.cookies = new cookies_js_1.Cookies(input => {
-            this.ensureOpen();
-            const raw = (0, native_js_1.encodeNativeJSON)(input, 16384);
-            return this.native.call("session_cookies", this.handle, raw, raw.length);
-        });
-        try {
-            if (options.cookies === false) {
-                const raw = (0, native_js_1.encodeNativeJSON)({ action: "configure", enabled: false });
-                this.native.call("session_cookies", this.handle, raw, raw.length);
-            }
-        }
-        catch (error) {
-            this.close();
-            throw error;
-        }
+        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)
@@ -165,14 +155,14 @@ class Session {
             }
         }
     }
-    begin(method, url, options, manual = false) {
+    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(this.headers, options.headers);
+        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");
@@ -195,6 +185,11 @@ class Session {
         }
         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);
@@ -224,13 +219,13 @@ class Session {
             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: duplex || options.allowRedirects === false,
+            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);
+        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);
@@ -242,9 +237,9 @@ class Session {
             throw error;
         }
     }
-    async stream(method, url, options = {}) {
+    async streamHop(method, url, options) {
         await this.ready(options.signal);
-        const { transfer, body, streaming } = this.begin(method, url, options);
+        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) {
@@ -265,13 +260,60 @@ class Session {
                 }
             }
             transfer.ensureOpen();
-            return new response_js_1.StreamResponse(transfer, info, transfer.duplex ? upload : undefined);
+            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);
@@ -314,6 +356,16 @@ class Session {
     }
     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();
@@ -335,11 +387,16 @@ class Session {
             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: sessionCookies && cookieMode === "manual" ? true : undefined, headers, profile: options.profile ?? this.profile, proxy: proxy || undefined, ca_pem: this.caPem, proxy_ca_pem: proxyCA, subprotocols: options.subprotocols ?? [], max_message_bytes: maximum,
+        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);
@@ -351,6 +408,13 @@ class Session {
             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"); }
@@ -358,6 +422,7 @@ class Session {
     close() {
         if (this.closed)
             return;
+        this.cookies.clear();
         this.closed = true;
         try {
             for (const transfer of this.active)

package/dist/websocket.js

@@ -69,7 +69,8 @@ class WebSocket {
     ensure() { if (this.closed)
         throw this.failure ?? new errors_js_1.FastlsError("WebSocket is closed"); }
     get info() { if (this.closed && this.last)
-        return this.last; this.ensure(); return this.last = this.native.call("info", this.handle); }
+        return this.last; this.ensure(); const info = this.last = this.native.call("info", this.handle); if (info.status)
+        this.headers = new headers_js_1.Headers(info.header_values); return info; }
     get closeCode() { return (this.closed ? this.last : this.info)?.websocket?.close_code ?? 1006; }
     get closeReason() { return (this.closed ? this.last : this.info)?.websocket?.close_reason ?? ""; }
     check(info) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastls/fastls",
-  "version": "0.10.1-dev.0",
+  "version": "0.10.2",
   "description": "Node.js bindings for the Fastls C ABI",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -21,7 +21,8 @@
   },
   "dependencies": {
     "koffi": "3.3.3",
-    "lossless-json": "4.3.3"
+    "lossless-json": "4.3.3",
+    "tough-cookie": "6.0.0"
   },
   "license": "Apache-2.0",
   "repository": {
@@ -34,10 +35,10 @@
     "registry": "https://registry.npmjs.org/"
   },
   "optionalDependencies": {
-    "@fastls/fastls-win32-x64": "0.10.1-dev.0",
-    "@fastls/fastls-linux-x64-glibc": "0.10.1-dev.0",
-    "@fastls/fastls-linux-arm64-glibc": "0.10.1-dev.0",
-    "@fastls/fastls-darwin-x64": "0.10.1-dev.0",
-    "@fastls/fastls-darwin-arm64": "0.10.1-dev.0"
+    "@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"
   }
 }