fix(ws): cancel native lifecycle when closed during handshake

.github/workflows/ci.yml

@@ -102,3 +102,32 @@ jobs:
         run: |
           cd packages/catcher_core
           flutter test test/ffi_roundtrip_test.dart
+
+  napi-ws-close-lifecycle:
+    name: napi-ws close (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'pnpm'
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: "packages -> target"
+      - run: pnpm install
+      - run: pnpm --filter @eric8810/catcher-napi-ws build
+        if: runner.os != 'Windows'
+      - name: Build native addon with controlled Sink test feature
+        if: runner.os == 'Windows'
+        run: |
+          pnpm --filter @eric8810/catcher-napi-ws exec napi build --platform --release --features lifecycle-test-hooks
+          pnpm --filter @eric8810/catcher-napi-ws build:ts
+          pnpm --filter @eric8810/catcher-napi-ws exec napi artifacts
+      - run: node --expose-gc --test-concurrency=1 --test packages/catcher-napi-ws/tests/close-lifecycle.cjs

packages/catcher-napi-ws/Cargo.toml

@@ -8,6 +8,9 @@ license = "MIT"
 [lib]
 crate-type = ["cdylib"]
 
+[features]
+lifecycle-test-hooks = ["catcher-ws/lifecycle-test-hooks"]
+
 [dependencies]
 catcher-ws = { path = "../catcher-ws", version = "1.0.0", features = ["rustls-tls", "system-proxy"] }
 napi = { version = "2", default-features = false, features = ["napi4", "tokio_rt", "serde-json"] }

packages/catcher-napi-ws/README.md

@@ -183,3 +183,17 @@ npm run build:ts    # tsup only (no Rust rebuild)
 ## License
 
 MIT
+
+### 关闭与任务生命周期
+
+`close(code?, reason?)` 同步保存终止请求，可在首次握手、重连、退避或发送期间调用，且可重复调用。请求关闭后不接受新的发送，未发送的缓存被丢弃。正在进行的握手和发送会被取消，关闭不等待缓存排空或对端确认；已经交给网络的数据无法撤回。关闭参数保留兼容性，空闲连接上的 Close 帧仅尽力发送；在途发送被中断时直接释放连接，不再 flush 该 sink，以免继续发出用户态缓存。
+
+需要确认该 WS 实例停止时，使用 `await client.closeAndWait()`：方法调用时同步保存关闭意图并拒绝新发送，Promise 完成时该实例的握手/连接管理器和事件转发任务均已退出，不会继续重连或提交新回调。该完成范围不包括共享 DNS 后台刷新、对端关闭确认或已排入 Node.js 队列的回调；已排队回调仍可能执行。该方法要求使用包含本修复的新原生插件。
+
+原生包装对象释放时也会请求取消。但 JavaScript GC 的时机不确定，请显式调用 `close()` 或 `closeAndWait()` 管理资源。
+
+### 原生取消回归
+
+默认构建不启用 `lifecycle-test-hooks`。Windows 原生 CI 使用该测试特性，在真实 Native/Reqwest 连接的 Sink `poll_flush` 上暂停，明确观察 Pending 后再通过原生/TS API 关闭，严格检查关闭后无再次 Sink 调用、无用户帧到达服务端。测试特性只提供观测和闸门，不属于发行 API。
+
+其他平台保留默认构建的真实网络背压测试。可在本机以 `napi build --platform --release --features lifecycle-test-hooks` 构建后设置 `CATCHER_CONTROLLED_SINK_TEST=1` 运行同一组受控测试；关闭 Pending 未建立、取消后再次驱动 Sink 或用户数据到达服务端都会失败，不会跳过。