js-rpc2 2.4.0 → 2.4.2

package/doc/websocket.md

@@ -0,0 +1,223 @@
+# WebSocket 使用文档
+
+## 概述
+
+js-rpc 支持通过 WebSocket 协议进行 RPC 调用，提供了比 HTTP 更高效的双向通信能力。WebSocket 传输适用于需要实时通信、频繁交互或长时间连接的应用场景。
+
+## 核心组件
+
+### 服务器端
+
+1. [createRpcServerWebSocket](../src/server.js#L37) - 创建 WebSocket RPC 服务器
+2. [createRpcServerHelper](../src/lib.js#L467) - 创建 RPC 服务器助手（内部使用）
+
+### 客户端
+
+1. [createRpcClientWebSocket](../src/lib.js#L656) - 创建 WebSocket RPC 客户端
+
+## 完整示例
+
+### 1. 服务器端代码 (server.js)
+
+```js
+import { createServer } from 'http'
+import { WebSocketServer } from 'ws'
+import { createRpcServerWebSocket } from 'js-rpc2/src/server.js'
+
+// 创建 HTTP 服务器
+const server = createServer()
+
+// 创建 WebSocket 服务器
+const wss = new WebSocketServer({ server })
+
+// 定义可远程调用的函数
+class RpcApi {
+    /**
+     * 示例方法：带回调的异步函数
+     * @param {string} name - 名称参数
+     * @param {(data: string) => void} update - 回调函数，用于报告进度
+     */
+    async hello(name, update) {
+        for (let i = 0; i < 5; i++) {
+            // 调用回调函数报告进度
+            update(`progress ${i}`)
+            await new Promise((resolve) => setTimeout(resolve, 500))
+        }
+        return `Hello, ${name}!`
+    }
+
+    /**
+     * 示例方法：处理二进制数据
+     * @param {Uint8Array} buffer - 二进制数据
+     */
+    async processBuffer(buffer) {
+        // 模拟处理过程
+        await new Promise((resolve) => setTimeout(resolve, 1000))
+        // 返回处理后的数据
+        return new Uint8Array(buffer.map(b => b * 2))
+    }
+
+    /**
+     * 示例方法：实时数据推送
+     * @param {(data: object) => void} callback - 数据推送回调
+     */
+    async subscribeToData(callback) {
+        // 模拟实时数据推送
+        for (let i = 0; i < 10; i++) {
+            await new Promise((resolve) => setTimeout(resolve, 1000))
+            callback({
+                timestamp: Date.now(),
+                value: Math.random(),
+                index: i
+            })
+        }
+        return 'Subscription ended'
+    }
+}
+
+// 创建 API 实例
+const extension = new RpcApi()
+
+// 创建 RPC 服务器
+createRpcServerWebSocket({
+    path: '/rpc',           // RPC 服务路径
+    wss: wss,               // WebSocket 服务器实例
+    extension: extension,   // 可调用的函数集合
+    rpcKey: 'optional-secret-key' // 可选的安全密钥
+})
+
+// 启动服务器
+server.listen(9000, () => {
+    console.log('WebSocket RPC server listening on port 9000')
+})
+```
+
+### 2. 客户端代码 (client.js)
+
+```js
+import { createRpcClientWebSocket } from 'js-rpc2/src/client.js'
+
+// 创建 AbortController 用于控制连接
+const ac = new AbortController()
+
+// 创建 RPC 客户端
+/** @type{RpcApi} */
+const rpc = createRpcClientWebSocket({
+    url: 'ws://127.0.0.1:9000/rpc',    // WebSocket RPC 服务地址
+    rpcKey: 'optional-secret-key',     // 可选的安全密钥（需与服务端一致）
+    signal: ac.signal                  // 用于控制连接的信号
+})
+
+// 使用示例
+async function example() {
+    try {
+        // 调用带回调的异步函数
+        console.log('Calling hello with progress updates...')
+        const result = await rpc.hello('WebSocket User', (progress) => {
+            console.log('Progress update:', progress)
+        })
+        console.log('Hello result:', result)
+
+        // 调用处理二进制数据的函数
+        console.log('Processing binary data...')
+        const buffer = new Uint8Array([1, 2, 3, 4, 5])
+        const processedBuffer = await rpc.processBuffer(buffer)
+        console.log('Processed buffer:', processedBuffer)
+
+        // 订阅实时数据
+        console.log('Subscribing to real-time data...')
+        const subscriptionResult = await rpc.subscribeToData((data) => {
+            console.log('Real-time data:', data)
+        })
+        console.log('Subscription result:', subscriptionResult)
+
+    } catch (error) {
+        console.error('RPC call failed:', error)
+    }
+}
+
+// 执行示例
+example()
+
+// 在需要时断开连接
+// ac.abort()
+```
+
+## API 说明
+
+### 服务器端 API
+
+#### createRpcServerWebSocket
+
+创建 WebSocket RPC 服务器。
+
+```js
+/**
+ * @param {{
+ * path: string; 
+ * wss: WebSocketServer; 
+ * rpcKey:string;
+ * extension: {asyncLocalStorage:AsyncLocalStorage<IncomingMessage>;}; 
+ * logger?:(msg:string)=>void;
+ * }} param
+ */
+export function createRpcServerWebSocket(param)
+```
+
+参数说明：
+- `path`: RPC 服务的路径，用于区分不同的服务
+- `wss`: WebSocketServer 实例
+- `rpcKey`: 可选的安全密钥，用于验证客户端连接
+- `extension`: 包含可远程调用函数的对象
+- `logger`: 可选的日志函数
+
+### 客户端 API
+
+#### createRpcClientWebSocket
+
+创建 WebSocket RPC 客户端。
+
+```js
+/**
+ * @param {{
+ * url:string;
+ * rpcKey:string;
+ * signal:AbortSignal;
+ * intercept?:(e:Event)=>void;
+ * }} param
+ */
+export function createRpcClientWebSocket(param)
+```
+
+参数说明：
+- `url`: WebSocket RPC 服务的完整 URL
+- `rpcKey`: 可选的安全密钥，需与服务端一致
+- `signal`: AbortSignal，用于控制连接的生命周期
+- `intercept`: 可选的事件拦截函数
+
+## 特性
+
+1. **双向通信**: WebSocket 提供全双工通信，服务器也可以主动向客户端推送数据
+2. **实时性**: 低延迟通信，适用于实时应用
+3. **连接保持**: 长连接减少重复握手开销
+4. **类型安全**: 通过 JSDoc 注解提供完整的类型支持
+5. **异步回调**: 支持在远程调用过程中传递回调函数
+6. **二进制数据**: 原生支持 Uint8Array 等二进制数据类型
+7. **自动重连**: 客户端具备自动重连机制
+8. **错误处理**: 完善的错误处理和传播机制
+
+## 使用场景
+
+1. **实时应用**: 聊天应用、实时游戏、协作编辑等
+2. **数据推送**: 实时数据监控、股票价格更新等
+3. **频繁交互**: 需要频繁通信的应用，避免 HTTP 请求的开销
+4. **长时间连接**: 需要保持连接状态的应用
+
+## 注意事项
+
+1. WebSocket 连接需要正确处理断开和重连逻辑
+2. 服务器需要合理管理并发连接数
+3. 注意处理网络异常和超时情况
+4. 对于大规模部署，考虑使用负载均衡器
+5. 安全方面，确保使用 WSS（WebSocket Secure）进行加密传输
+6. 在防火墙环境中，确保 WebSocket 端口未被阻止

package/doc/worker_threads.md

@@ -1,187 +1,187 @@
-# 在 Node.js Worker Threads 中使用 js-rpc
-
-Node.js Worker Threads 是一种在 Node.js 中实现并行处理的机制，js-rpc 提供了在主线程和 Worker 线程之间进行 RPC 调用的能力。
-
-## 概述
-
-js-rpc 在 Node.js Worker Threads 中的使用主要包括两个部分：
-1. 在 Worker 线程中创建 RPC 服务器：使用 [createRpcServerNodeJSWorker](../src/lib.js#L993)
-2. 在主线程中创建 RPC 客户端：使用 [createRpcClientNodeJSWorker](../src/lib.js#L1013)
-
-## 完整示例
-
-### 1. Worker 线程代码 (worker.js)
-
-```js
-// 导入必要的模块
-import { parentPort } from 'worker_threads'
-import { createRpcServerNodeJSWorker } from 'js-rpc2/src/lib.js'
-
-// 定义可被远程调用的函数
-async function readClipboard() {
-    // 实现读取剪贴板的逻辑
-    // 这里只是示例，实际实现取决于你的需求
-    return 'clipboard content'
-}
-
-async function writeClipboard(data) {
-    // 实现写入剪贴板的逻辑
-    console.log('Writing to clipboard:', data)
-    return true
-}
-
-async function writeClipboardText(text) {
-    // 实现写入文本到剪贴板的逻辑
-    console.log('Writing text to clipboard:', text)
-    return true
-}
-
-async function readClipboardText() {
-    // 实现读取剪贴板文本的逻辑
-    return 'clipboard text'
-}
-
-async function readClipboardHtml() {
-    // 实现读取剪贴板 HTML 内容的逻辑
-    return '<p>clipboard html</p>'
-}
-
-async function readClipboardImage() {
-    // 实现读取剪贴板图片的逻辑
-    return new Uint8Array([1, 2, 3, 4]) // 示例二进制数据
-}
-
-// 将所有函数导出为一个 API 对象
-export const ExtensionApi = {
-    readClipboard,
-    writeClipboard,
-    writeClipboardText,
-    readClipboardText,
-    readClipboardHtml,
-    readClipboardImage,
-}
-
-// 创建 RPC 服务器
-createRpcServerNodeJSWorker({ 
-    parentPort, 
-    extension: ExtensionApi,
-    logger: (msg) => console.log('[Worker]', msg) // 可选的日志记录器
-})
-```
-
-### 2. 主线程代码 (main.js)
-
-```js
-// 导入必要的模块
-import { createRpcClientNodeJSWorker } from 'js-rpc2/src/lib.js'
-import { Worker } from 'worker_threads'
-
-// 创建 Worker 实例
-export const worker = new Worker(new URL('./worker.js', import.meta.url))
-
-// 创建 RPC 客户端
-/** @type{ExtensionApi} */
-const rpc = createRpcClientNodeJSWorker({ worker: worker })
-
-// 取消 Worker 的引用，允许程序在没有其他任务时退出
-worker.unref()
-
-// 包装远程调用函数
-export async function readClipboard() {
-    return await rpc.readClipboard()
-}
-
-/**
- * 写入剪贴板内容
- * @param {'text'|'richtext'|'image'} type - 数据类型
- * @param {string|Buffer} data - 要写入的数据
- */
-export async function writeClipboard(type, data) {
-    return await rpc.writeClipboard(type, data)
-}
-
-/**
- * 写入文本到剪贴板
- * @param {string} text - 要写入的文本
- */
-export async function writeClipboardText(text) {
-    return rpc.writeClipboardText(text)
-}
-
-export async function readClipboardText() {
-    return rpc.readClipboardText()
-}
-
-export async function readClipboardHtml() {
-    return rpc.readClipboardHtml()
-}
-
-export async function readClipboardImage() {
-    return rpc.readClipboardImage()
-}
-
-// 使用示例
-async function example() {
-    // 调用远程函数
-    const text = await readClipboardText()
-    console.log('Clipboard text:', text)
-    
-    await writeClipboardText('Hello from main thread!')
-    
-    const image = await readClipboardImage()
-    console.log('Clipboard image size:', image.length)
-}
-```
-
-## API 说明
-
-### createRpcServerNodeJSWorker
-
-在 Worker 线程中创建 RPC 服务器。
-
-```js
-/**
- * @param {{
- * parentPort: NodeJSMessagePort;
- * extension: Object;
- * logger?:(msg:string)=>void;
- * }} param 
- */
-export function createRpcServerNodeJSWorker(param)
-```
-
-参数说明：
-- `parentPort`: Worker 线程的 parentPort 对象，用于与主线程通信
-- `extension`: 包含可被远程调用函数的对象
-- `logger`: 可选的日志记录函数
-
-### createRpcClientNodeJSWorker
-
-在主线程中创建 RPC 客户端。
-
-```js
-/**
- * @param {{
- * worker:NodeJSWorker;
- * }} param
- */
-export function createRpcClientNodeJSWorker(param)
-```
-
-参数说明：
-- `worker`: Worker 实例
-
-## 特性
-
-1. **透明的远程调用**：在主线程中调用 Worker 中的函数就像调用本地函数一样简单
-2. **支持异步函数**：所有远程函数都可以是异步的
-3. **参数和返回值序列化**：自动处理参数和返回值的序列化/反序列化
-4. **类型安全**：通过 JSDoc 注解提供完整的类型支持
-5. **错误处理**：远程函数抛出的错误会正确传播到调用方
-
-## 注意事项
-
-1. 确保 Worker 线程中的函数是可序列化的
-2. 大数据传输可能影响性能，考虑使用流式传输
-3. 避免在远程函数中使用闭包引用 Worker 外部的变量
+# 在 Node.js Worker Threads 中使用 js-rpc
+
+Node.js Worker Threads 是一种在 Node.js 中实现并行处理的机制，js-rpc 提供了在主线程和 Worker 线程之间进行 RPC 调用的能力。
+
+## 概述
+
+js-rpc 在 Node.js Worker Threads 中的使用主要包括两个部分：
+1. 在 Worker 线程中创建 RPC 服务器：使用 [createRpcServerNodeJSWorker](../src/lib.js#L993)
+2. 在主线程中创建 RPC 客户端：使用 [createRpcClientNodeJSWorker](../src/lib.js#L1013)
+
+## 完整示例
+
+### 1. Worker 线程代码 (worker.js)
+
+```js
+// 导入必要的模块
+import { parentPort } from 'worker_threads'
+import { createRpcServerNodeJSWorker } from 'js-rpc2/src/lib.js'
+
+// 定义可被远程调用的函数
+async function readClipboard() {
+    // 实现读取剪贴板的逻辑
+    // 这里只是示例，实际实现取决于你的需求
+    return 'clipboard content'
+}
+
+async function writeClipboard(data) {
+    // 实现写入剪贴板的逻辑
+    console.log('Writing to clipboard:', data)
+    return true
+}
+
+async function writeClipboardText(text) {
+    // 实现写入文本到剪贴板的逻辑
+    console.log('Writing text to clipboard:', text)
+    return true
+}
+
+async function readClipboardText() {
+    // 实现读取剪贴板文本的逻辑
+    return 'clipboard text'
+}
+
+async function readClipboardHtml() {
+    // 实现读取剪贴板 HTML 内容的逻辑
+    return '<p>clipboard html</p>'
+}
+
+async function readClipboardImage() {
+    // 实现读取剪贴板图片的逻辑
+    return new Uint8Array([1, 2, 3, 4]) // 示例二进制数据
+}
+
+// 将所有函数导出为一个 API 对象
+export const ExtensionApi = {
+    readClipboard,
+    writeClipboard,
+    writeClipboardText,
+    readClipboardText,
+    readClipboardHtml,
+    readClipboardImage,
+}
+
+// 创建 RPC 服务器
+createRpcServerNodeJSWorker({ 
+    parentPort, 
+    extension: ExtensionApi,
+    logger: (msg) => console.log('[Worker]', msg) // 可选的日志记录器
+})
+```
+
+### 2. 主线程代码 (main.js)
+
+```js
+// 导入必要的模块
+import { createRpcClientNodeJSWorker } from 'js-rpc2/src/lib.js'
+import { Worker } from 'worker_threads'
+
+// 创建 Worker 实例
+export const worker = new Worker(new URL('./worker.js', import.meta.url))
+
+// 创建 RPC 客户端
+/** @type{ExtensionApi} */
+const rpc = createRpcClientNodeJSWorker({ worker: worker })
+
+// 取消 Worker 的引用，允许程序在没有其他任务时退出
+worker.unref()
+
+// 包装远程调用函数
+export async function readClipboard() {
+    return await rpc.readClipboard()
+}
+
+/**
+ * 写入剪贴板内容
+ * @param {'text'|'richtext'|'image'} type - 数据类型
+ * @param {string|Buffer} data - 要写入的数据
+ */
+export async function writeClipboard(type, data) {
+    return await rpc.writeClipboard(type, data)
+}
+
+/**
+ * 写入文本到剪贴板
+ * @param {string} text - 要写入的文本
+ */
+export async function writeClipboardText(text) {
+    return rpc.writeClipboardText(text)
+}
+
+export async function readClipboardText() {
+    return rpc.readClipboardText()
+}
+
+export async function readClipboardHtml() {
+    return rpc.readClipboardHtml()
+}
+
+export async function readClipboardImage() {
+    return rpc.readClipboardImage()
+}
+
+// 使用示例
+async function example() {
+    // 调用远程函数
+    const text = await readClipboardText()
+    console.log('Clipboard text:', text)
+    
+    await writeClipboardText('Hello from main thread!')
+    
+    const image = await readClipboardImage()
+    console.log('Clipboard image size:', image.length)
+}
+```
+
+## API 说明
+
+### createRpcServerNodeJSWorker
+
+在 Worker 线程中创建 RPC 服务器。
+
+```js
+/**
+ * @param {{
+ * parentPort: NodeJSMessagePort;
+ * extension: Object;
+ * logger?:(msg:string)=>void;
+ * }} param 
+ */
+export function createRpcServerNodeJSWorker(param)
+```
+
+参数说明：
+- `parentPort`: Worker 线程的 parentPort 对象，用于与主线程通信
+- `extension`: 包含可被远程调用函数的对象
+- `logger`: 可选的日志记录函数
+
+### createRpcClientNodeJSWorker
+
+在主线程中创建 RPC 客户端。
+
+```js
+/**
+ * @param {{
+ * worker:NodeJSWorker;
+ * }} param
+ */
+export function createRpcClientNodeJSWorker(param)
+```
+
+参数说明：
+- `worker`: Worker 实例
+
+## 特性
+
+1. **透明的远程调用**：在主线程中调用 Worker 中的函数就像调用本地函数一样简单
+2. **支持异步函数**：所有远程函数都可以是异步的
+3. **参数和返回值序列化**：自动处理参数和返回值的序列化/反序列化
+4. **类型安全**：通过 JSDoc 注解提供完整的类型支持
+5. **错误处理**：远程函数抛出的错误会正确传播到调用方
+
+## 注意事项
+
+1. 确保 Worker 线程中的函数是可序列化的
+2. 大数据传输可能影响性能，考虑使用流式传输
+3. 避免在远程函数中使用闭包引用 Worker 外部的变量
 4. Worker 线程在没有任务时会自动退出，如需保持运行请适当管理引用

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "js-rpc2",
-  "version": "2.4.0",
+  "version": "2.4.2",
   "description": "js web websocket http rpc",
   "main": "index.js",
   "type": "module",

package/src/lib.js

@@ -696,13 +696,13 @@ export function createRpcClientWebSocket(param) {
             signal.resolve()
         })
         ws.addEventListener('error', (e) => {
-            if (param.intercept) {
-                param.intercept(e)
-            }
             console.error('createRpcClientWebSocket createWebSocket ws error', e)
             promise.resolve()
         })
-        ws.addEventListener('close', () => {
+        ws.addEventListener('close', (e) => {
+            if (param.intercept) {
+                param.intercept(e)
+            }
             console.error('createRpcClientWebSocket createWebSocket ws close')
             promise.resolve()
         })