js-rpc2 2.2.0 → 2.3.0

package/README.md

@@ -355,4 +355,56 @@ async function postPortMessage() {
     let ret = await rpc.hello('6667');
     console.info("ret from rpc:", ret);
 }
+```
+
+## chrome extensions
+```js
+import {createRpcServerChromeExtensions, createRpcClientChromeExtensions} from 'js-rpc2/src/lib.js'
+
+// background.js
+export class RpcBackgroundApi {
+    /**
+     * @param {(progress: string, date: Date) => Promise<void>} cb
+     */
+    async callback(cb) {
+        console.info('callback in background', 'cb')
+        for (let i = 0; i < 10; i++) {
+            await sleep(1000)
+            await cb(`from background index is ${i}`, new Date())
+        }
+        return 'over!'
+    }
+}
+createRpcServerChromeExtensions({ chrome, key: 'rpc-popup->background', extension: new RpcBackgroundApi(), })
+createRpcServerChromeExtensions({ chrome, key: 'rpc-content-scripts->background', extension: new RpcBackgroundApi(), })
+
+
+// content_scripts.js
+export class RpcContentScriptsApi {
+    async callBackgroundWithCallback(name, callback) {
+        console.info('name', name)
+        return await rpcContentScriptBackground.callback(callback)
+    }
+}
+createRpcServerChromeExtensions({ chrome, key: 'rpc-popup->content-script', extension: new RpcContentScriptsApi() })
+/** @type{RpcBackgroundApi} */
+export const rpcContentScriptBackground = createRpcClientChromeExtensions({ chrome, key: 'rpc-content-scripts->background' })
+
+
+// popup.js
+const [tab] = await chrome.tabs.query({ active: true, currentWindow: true })
+/** @type{RpcContentScriptsApi} */
+export const rpcPopupContentScripts = createRpcClientChromeExtensions({ chrome, key: 'rpc-popup->content-script', tabId: tab.id, })
+/** @type{RpcBackgroundApi} */
+export const rpcPopupBackground = createRpcClientChromeExtensions({ chrome, key: 'rpc-popup->background' })
+
+let resp = await rpcPopupContentScripts.callBackgroundWithCallback("name", async (progress, date) => {
+    console.info('at popup callback ',progress, date)
+})
+console.info("over!", resp)
+
+let resp = await rpcPopupBackground.callback(async (progress, date) => {
+    console.info('at popup callback ',progress, date)
+})
+console.info("over!", resp)
 ```

package/doc/chrome-extensions.md

@@ -0,0 +1,133 @@
+# Chrome Extensions RPC 通信使用说明
+
+## 概述
+
+本项目使用 `js-rpc2` 库实现在 Chrome 扩展各组件间的远程过程调用（RPC）通信，支持在 popup、content scripts 和 background 之间进行双向通信。
+
+## 项目结构
+
+### 组件说明
+
+- **background.js**: 后台脚本，提供核心服务接口
+- **content_scripts.js**: 内容脚本，运行在网页上下文中，可作为通信中继
+- **popup.js**: 扩展弹窗界面，用户交互入口
+
+## 核心实现
+
+### Background 脚本
+
+```javascript
+import {createRpcServerChromeExtensions} from 'js-rpc2/src/lib.js'
+
+export class RpcBackgroundApi {
+    /**
+     * 带回调的示例方法
+     * @param {(progress: string, date: Date) => Promise<void>} cb - 回调函数
+     */
+    async callback(cb) {
+        for (let i = 0; i < 10; i++) {
+            await sleep(1000)
+            await cb(`from background index is ${i}`, new Date())
+        }
+        return 'over!'
+    }
+}
+
+// 创建RPC服务端点
+createRpcServerChromeExtensions({ 
+    chrome, 
+    key: 'rpc-popup->background', 
+    extension: new RpcBackgroundApi()
+})
+
+createRpcServerChromeExtensions({ 
+    chrome, 
+    key: 'rpc-content-scripts->background', 
+    extension: new RpcBackgroundApi()
+})
+```
+
+### Content Scripts 脚本
+
+```javascript
+import {createRpcServerChromeExtensions, createRpcClientChromeExtensions} from 'js-rpc2/src/lib.js'
+
+export class RpcContentScriptsApi {
+    async callBackgroundWithCallback(name, callback) {
+        return await rpcContentScriptBackground.callback(callback)
+    }
+}
+
+// 创建RPC服务端点供popup调用
+createRpcServerChromeExtensions({
+    chrome, 
+    key: 'rpc-popup->content-script', 
+    extension: new RpcContentScriptsApi()
+})
+
+// 创建RPC客户端连接到background
+export const rpcContentScriptBackground = createRpcClientChromeExtensions({
+    chrome, 
+    key: 'rpc-content-scripts->background'
+})
+```
+
+### Popup 脚本
+
+```javascript
+import {createRpcClientChromeExtensions} from 'js-rpc2/src/lib.js'
+
+// 获取当前活动标签页
+const [tab] = await chrome.tabs.query({ active: true, currentWindow: true })
+
+// 创建RPC客户端
+export const rpcPopupContentScripts = createRpcClientChromeExtensions({
+    chrome, 
+    key: 'rpc-popup->content-script', 
+    tabId: tab.id
+})
+
+export const rpcPopupBackground = createRpcClientChromeExtensions({
+    chrome, 
+    key: 'rpc-popup->background'
+})
+
+// 使用示例
+let resp = await rpcPopupContentScripts.callBackgroundWithCallback("name", async (progress, date) => {
+    console.info('at popup callback', progress, date)
+})
+console.info("over!", resp)
+
+let resp2 = await rpcPopupBackground.callback(async (progress, date) => {
+    console.info('at popup callback', progress, date)
+})
+console.info("over!", resp2)
+```
+
+## 通信模式
+
+### 直接通信
+Popup → Background
+```javascript
+rpcPopupBackground.callback(callbackFunction)
+```
+
+### 间接通信
+Popup → Content Script → Background
+```javascript
+rpcPopupContentScripts.callBackgroundWithCallback(name, callbackFunction)
+```
+
+## 使用方法
+
+1. 在各组件中导入相应的 RPC 创建函数
+2. 定义服务接口类
+3. 使用 `createRpcServerChromeExtensions` 创建服务端点
+4. 使用 `createRpcClientChromeExtensions` 创建客户端连接
+5. 通过客户端实例调用远程方法
+
+## 注意事项
+
+- 确保 manifest.json 中正确配置了各组件的权限和通信策略
+- 注意处理异步回调的生命周期管理
+- 建议为所有 RPC 接口添加适当的错误处理机制

package/doc/electron.md

@@ -0,0 +1,138 @@
+# Electron RPC 通信使用说明
+
+## 概述
+
+本文档介绍如何在 Electron 应用中使用 `js-rpc2` 库实现主进程与渲染进程之间的 RPC 通信。通过 MessagePort 机制，实现跨进程的远程方法调用。
+
+## 项目结构
+
+### 组件说明
+
+- **main.js**: Electron 主进程，提供核心服务接口
+- **preload.js**: 预加载脚本，建立主进程与渲染进程的通信桥梁
+- **renderer.js**: 渲染进程，运行在浏览器环境中
+- **usage.js**: 使用示例，展示如何调用 RPC 方法
+
+## 核心实现
+
+### 主进程 (main.js)
+
+```javascript
+import { ipcMain } from 'electron'
+import { createRpcServerElectronMessagePort } from 'js-rpc2/src/lib.js'
+
+class AppApi {
+    asyncLocalStorage = new AsyncLocalStorage()
+
+    async hello(param) {
+        return 'wertyuioiuytre ' + param
+    }
+}
+
+// 监听来自渲染进程的 port 消息
+ipcMain.on('port', (event) => {
+    const port = event.ports[0]
+    // 创建 RPC 服务端点
+    createRpcServerElectronMessagePort({ 
+        port, 
+        rpcKey: '', 
+        extension: new AppApi() 
+    })
+    port.start()
+})
+```
+
+### 预加载脚本 (preload.js)
+
+```javascript
+import { ipcRenderer } from 'electron/renderer'
+
+// 监听来自渲染进程的消息
+window.onmessage = (/** @type {MessageEvent} */ event) => {
+    // 验证消息来源并转发给主进程
+    if (event.origin == location.origin && event.data != 'port') {
+        ipcRenderer.postMessage('port', null, [event.ports[0]])
+    }
+}
+```
+
+### 渲染进程 (renderer.js)
+
+```javascript
+import { createRpcClientMessagePort } from 'js-rpc2/src/lib.js'
+
+// 创建消息通道
+const channel = new MessageChannel();
+
+// 向主进程发送端口
+window.postMessage("port", location.origin, [channel.port1]);
+
+// 创建 RPC 客户端
+let rpc = createRpcClientMessagePort({ 
+    port: channel.port2, 
+    rpcKey: "" 
+});
+```
+
+### 使用示例 (usage.js)
+
+```javascript
+async function postPortMessage() {
+    // 调用远程方法
+    let ret = await rpc.hello('6667');
+    console.info("ret from rpc:", ret);
+}
+```
+
+## 通信流程
+
+1. 渲染进程创建 `MessageChannel` 并通过 `postMessage` 将 `port1` 发送到预加载脚本
+2. 预加载脚本验证消息来源并将端口转发给主进程
+3. 主进程接收端口并创建 RPC 服务端点
+4. 渲染进程使用 `port2` 创建 RPC 客户端
+5. 客户端可以调用主进程中定义的服务方法
+
+## 使用方法
+
+### 1. 主进程设置
+
+在主进程中定义服务类并创建 RPC 服务：
+
+```javascript
+class AppApi {
+    async yourMethod(params) {
+        // 实现业务逻辑
+        return result;
+    }
+}
+
+ipcMain.on('port', (event) => {
+    const port = event.ports[0]
+    createRpcServerElectronMessagePort({ 
+        port, 
+        rpcKey: '', 
+        extension: new AppApi() 
+    })
+    port.start()
+})
+```
+
+### 2. 渲染进程调用
+
+在渲染进程中建立连接并调用远程方法：
+
+```javascript
+const channel = new MessageChannel();
+window.postMessage("port", location.origin, [channel.port1]);
+let rpc = createRpcClientMessagePort({ port: channel.port2, rpcKey: "" });
+
+// 调用远程方法
+let result = await rpc.yourMethod(params);
+```
+
+## 注意事项
+
+- 确保在 Electron 的安全策略下正确配置 `contextIsolation` 和 `sandbox` 选项
+- 预加载脚本中的消息验证是安全通信的关键
+- MessagePort 需要在两端都启动后才能正常通信
+- 异步方法调用需要正确处理 Promise 返回值

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "js-rpc2",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "js web websocket http rpc",
   "main": "index.js",
   "type": "module",
@@ -21,7 +21,10 @@
     "web",
     "http",
     "websocket",
-    "rpc"
+    "rpc",
+    "electron",
+    "chrome",
+    "extensions"
   ],
   "author": "yuanliwei",
   "license": "MIT",

package/src/lib.js

@@ -518,7 +518,7 @@ export function createRpcServerHelper(param) {
     decode.readable.pipeTo(new WritableStream({
         async write(buffer) {
             let asyncLocalStorage = param.extension.asyncLocalStorage
-            asyncLocalStorage.enterWith(param.context)
+            asyncLocalStorage?.enterWith(param.context)
             if (param.async) {
                 rpcRunServerDecodeBuffer(param.extension, writer, buffer, param.logger).catch(console.error)
             } else {
@@ -832,3 +832,119 @@ export function createRpcClientMessagePort(param) {
     }
     return createRPCProxy(helper.apiInvoke)
 }
+
+/**
+ * @param {string} text 
+ * @returns 
+ */
+export function base64decode(text) {
+    const _tidyB64 = (/** @type {string} */ s) => s.replace(/[^A-Za-z0-9\+\/]/g, '')
+    const _unURI = (/** @type {string} */ a) => _tidyB64(a.replace(/[-_]/g, (m0) => m0 == '-' ? '+' : '/'))
+    text = _unURI(text)
+    return new Uint8Array(globalThis.atob(text).split('').map(c => c.charCodeAt(0)))
+}
+
+/**
+ * @param {Uint8Array<ArrayBuffer>} buffer 
+ * @returns 
+ */
+export function base64encode(buffer, urlsafe = false) {
+    let b64 = globalThis.btoa(String.fromCharCode(...new Uint8Array(buffer)))
+    if (urlsafe) {
+        b64 = b64.replace(/=/g, '').replace(/[+\/]/g, (m0) => m0 == '+' ? '-' : '_')
+    }
+    return b64
+}
+
+/**
+ * @import {chrome as Chrome} from './types.js'
+ * @template T
+ * @param {{
+ * chrome:Chrome;
+ * key: string;
+ * extension: ExtensionApi<T>
+ * logger?:(msg:string)=>void;
+ * }} param 
+ */
+export function createRpcServerChromeExtensions(param) {
+    const chrome = param.chrome
+    const actionMap = new Map()
+    chrome.runtime.onMessage.addListener(async (request, sender, sendResponse) => {
+        if (request.action === param.key) {
+            let tabId = sender.tab?.id
+            let { keyServer, keyClient } = request.data
+            let helper = createRpcServerHelper({
+                rpcKey: '', extension: param.extension, async: true, logger: param.logger,
+            })
+            let writer = helper.writable.getWriter()
+            actionMap.set(keyServer, (/** @type {Uint8Array<ArrayBuffer>} */ data) => {
+                writer.write(data)
+            })
+            helper.readable.pipeTo(new WritableStream({
+                async write(chunk) {
+                    let resp = null
+                    if (tabId) {
+                        resp = await chrome.tabs.sendMessage(tabId, { action: keyClient, data: base64encode(chunk), })
+                    } else {
+                        resp = await chrome.runtime.sendMessage({ action: keyClient, data: base64encode(chunk), })
+                    }
+                    if (!resp) {
+                        actionMap.delete(keyServer)
+                    }
+                }
+            }))
+            sendResponse(true)
+        }
+        let write = actionMap.get(request.action)
+        if (write) {
+            write(base64decode(request.data))
+            sendResponse(true)
+        }
+    })
+}
+
+/**
+ * @param {{ 
+ * chrome:Chrome;
+ * key:string;
+ * tabId?: number;
+ * }} param
+ */
+export function createRpcClientChromeExtensions(param) {
+    const chrome = param.chrome
+    let helper = createRpcClientHelper({ rpcKey: '' })
+    let writer = helper.writable.getWriter()
+    !(async () => {
+        let keyServer = guid()
+        let keyClient = guid()
+        chrome.runtime.onMessage.addListener(async (request, sender, sendResponse) => {
+            if (request.action === keyClient) {
+                sendResponse(true)
+                await writer.write(base64decode(request.data))
+            }
+        })
+        helper.readable.pipeTo(new WritableStream({
+            async write(chunk) {
+                if (param.tabId) {
+                    await chrome.tabs.sendMessage(param.tabId, { action: keyServer, data: base64encode(chunk) })
+                } else {
+                    await chrome.runtime.sendMessage({ action: keyServer, data: base64encode(chunk) })
+                }
+            }
+        }))
+        let response = null
+        try {
+            if (param.tabId) {
+                response = await chrome.tabs.sendMessage(param.tabId, { action: param.key, data: { keyServer, keyClient }, })
+            } else {
+                response = await chrome.runtime.sendMessage({ action: param.key, data: { keyServer, keyClient }, })
+            }
+        } catch (error) {
+            throw new Error(`Failed to establish RPC connection: ${error.message}`)
+        }
+        if (!response) {
+            throw new Error('RPC server did not respond - connection failed')
+        }
+    })()
+    return createRPCProxy(helper.apiInvoke)
+}

package/src/types.ts

@@ -1,6 +1,6 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 
-export type ExtensionApi<T> = { asyncLocalStorage: AsyncLocalStorage<T> } & object;
+export type ExtensionApi<T> = { asyncLocalStorage?: AsyncLocalStorage<T> } & object;
 
 
 export type RPC_TYPE_CALL = 0xdf68f4cb
@@ -52,6 +52,11 @@ export declare namespace Electron {
 
     const NodeEventEmitter: typeof import('events').EventEmitter;
 
+    interface MessageEvent {
+        data: any;
+        ports: MessagePortMain[];
+    }
+
     class MessagePortMain extends NodeEventEmitter {
 
         // Docs: https://electronjs.org/docs/api/message-port-main
@@ -88,4 +93,42 @@ export declare namespace Electron {
         start(): void;
     }
 
-}
+}
+
+export declare namespace chrome {
+    namespace events {
+        interface Event<T extends (...args: any) => void> {
+            addListener(callback: T): void;
+        }
+    }
+    namespace tabs {
+        interface Tab {
+            id?: number | undefined;
+        }
+        interface MessageSender {
+            tab?: chrome.tabs.Tab;
+        }
+        export interface MessageSendOptions {
+        }
+        export function sendMessage<M = any, R = any>(
+            tabId: number,
+            message: M,
+            options?: MessageSendOptions,
+        ): Promise<R>;
+        interface MessageOptions {
+            includeTlsChannelId?: boolean | undefined;
+        }
+    }
+    namespace runtime {
+        interface MessageSender {
+            tab?: chrome.tabs.Tab;
+        }
+        const onMessage: events.Event<
+            (message: any, sender: MessageSender, sendResponse: (response?: any) => void) => void
+        >;
+        function sendMessage<M = any, R = any>(message: M, options?: MessageOptions): Promise<R>;
+        interface MessageOptions {
+            includeTlsChannelId?: boolean | undefined;
+        }
+    }
+}