whistle.script 1.2.9 → 1.3.0

package/README.md

@@ -1,264 +1,249 @@
-# whistle.script
-whistle.script为[whistle](https://github.com/avwo/whistle)的一个扩展脚本插件，可以直接在界面上引用全局安装的Node模块及Node的内容模块编写脚本操作请求及其响应，所有正常Node程序可以实现的功能，都可以通过该插件实现，包括：
-
-1. HTTP[s]:
-   - 动态设置[whistle规则](https://avwo.github.io/whistle/rules/)
-   - 拦截请求响应
-   - 控制请求响应速度
-   - 修改请求url、请求方法、请求头、请求内容
-   - 修改响应状态码、响应头、响应内容
-   - 在插件界面的Console上显示脚本程序 `console.xxx` 的内容，如果可以打印响应的内容或调试信息等
-2. WebSocket:
-   - 动态设置[whistle规则](https://avwo.github.io/whistle/rules/)
-   - 拦截请求响应
-   - 修改发送或收到的数据
-   - 直接向WebSocket客户端或服务端发送数据
-   - 在插件界面的Console上显示脚本程序 `console.xxx` 的内容，如果可以打印发送和接收到的数据或调试信息等，从而通过该插件可以直接查看WebSocket的数据
-3. Tunnel: 基本功能同WebSocket，可以用来直接操作Socket请求，如Protobuf协议的请求等
-
-# 安装
-
-1. 安装Node: [官网下载安装最新版本(LTS和Stable都可以)](https://nodejs.org/)
-2. 安装最新版的[whistle](https://github.com/avwo/whistle)。
-
-		npm install -g whistle
-		
-		# Mac、Linux用户可能需要加sudo
-		sudo npm install -g whistle
-
-3. 安装script插件:
-
-		w2 i whistle.script
-
-# 使用
-
-打开script插件的界面，创建一个名字为 `test` 的脚本:
-
-1. 可以通过 `Plugins->Home->script`打开或右键并选择 `在新标签页中打开` 
-2. 直接访问 [http://local.whistlejs.com/plugin.script](http://local.whistlejs.com/plugin.script/)
-
- ![whistle.script界面](https://user-images.githubusercontent.com/11450939/126302159-0c533ea7-3bc0-484a-bd30-698d5a7881df.gif)
-
-#### 设置规则
-
-1. 设置HTTP或HTTPs请求的[whistle规则](https://avwo.github.io/whistle/rules/)(操作HTTPs需要[开启HTTPs拦截](https://avwo.github.io/whistle/webui/https.html))
-
-	在界面中的`test` 脚本输入(也可以在其它编辑器编辑后再copy进来):
-	
-		exports.handleRequestRules = (ctx) => {
-			// ctx.fullUrl 可以获取请求url
-			// ctx.headers 可以获取请求头
-			// ctx.options 里面包含一些特殊的请求头字段，分别可以获取一些额外信息，如请求方法、设置的规则等
-			ctx.rules = ['www.qq.com file://{test.html}'];
-		 	ctx.values = { 'test.html': 'Hello world.' };
-		};
-	
-	Note: 如果里面包含一些异步方法可以采用 async 函数，即：`exports.handleRequestRules = async () => {}`
-	
-	在whistle的Rules配置界面上输入规则:
-	
-		whistle.script://test www.ifeng.com www.qq.com www.baidu.com echo.websocket.org
-	
-	分别访问[http://www.ifeng.com](http://www.ifeng.com)和[http://www.qq.com](http://www.qq.com)，前者可以正常访问，后者输出 `Hello world.`。
-	
-	具体效果见图：[demo1](https://user-images.githubusercontent.com/11450939/126302225-2598772c-d6a3-45e3-97d6-685fbed1ba37.gif)
-	
-	如果需要通过配置给脚本传递一些额外参数，可以如下配置(注意中间不能有空格):
-	
-		whistle.script://test(a,b,c) www.ifeng.com www.qq.com www.baidu.com echo.websocket.org
-	
-	可以在脚本中通过 `process.args` 获取:
-	
-		exports.handleRequestRules = (ctx) => {
-		  console.log(process.args); // output: ["a", "b", "c"]
-		  ctx.rules = ['www.qq.com file://{test.html}'];
-		  ctx.values = { 'test.html': 'Hello world.' };
-		};
-
-2. 设置WebSocket请求的规则(需要[开启HTTPs拦截](https://avwo.github.io/whistle/webui/https.html)):
-
-		exports.handleWebSocketRules = (ctx) => {
-		  // ctx.fullUrl 可以获取请求url
-		  // ctx.headers 可以获取请求头
-		  // ctx.options 里面包含一些特殊的请求头字段，分别可以获取一些额外信息，如请求方法、设置的规则等
-		  this.rules = '127.0.0.1 echo.websocket.org';
-		};
-
-	接下来的操作同上。
-
-3. 设置Tunnel请求的规则(要测试可以暂时[关闭HTTPs拦截](https://avwo.github.io/whistle/webui/https.html)):
-
-		exports.handleTunnel = (ctx) => {
-		  // ctx.fullUrl 可以获取请求url
-		  // ctx.headers 可以获取请求头
-		  // ctx.options 里面包含一些特殊的请求头字段，分别可以获取一些额外信息，如请求方法、设置的规则等
-		  this.rules = '127.0.0.1 www.baidu.com';
-		};
-
-
-	接下来的操作同上。
-
-#### 操作请求
-
-1. 操作HTTP或HTTPs请求(操作HTTPs需要[开启HTTPs拦截](https://avwo.github.io/whistle/webui/https.html))
-	``` js
-	exports.handleRequest = async (ctx, request) => {
-		// ctx.fullUrl 可以获取请求url
-		// ctx.headers 可以获取请求头
-		// ctx.options 里面包含一些特殊的请求头字段，分别可以获取一些额外信息，如请设置的规则等
-		// ctx.method 获取和设置请求方法
-		// ctx.req
-		// ctx.res
-		const { req, res } = ctx;
-		const client = request((svrRes) => {
-			res.writeHead(svrRes.statusCode, svrRes.headers);
-			svrRes.pipe(res);
-			// try {
-				// const body = await ctx.getStreamBuffer(svrRes);
-				// delete svrRes.headers['content-encoding'];
-				// res.writeHead(svrRes.statusCode, svrRes.headers);
-				// res.end(body);
-			// } catch (err) {}
-		});
-		req.pipe(client);
-	};
-	```
-	在whistle的Rules配置界面上输入规则:
-	``` txt
-	# 这里不能用whistle.script，否则请求不会转发到handleRequest
-	# whistle.script只会执行handleXxxRules
-	# 你也可以通过在handleXxxRules里面设置 script://test(a,b,c)，实现转发
-	script://test www.ifeng.com www.qq.com www.baidu.com echo.websocket.org
-	```
-	分别访问[http://www.ifeng.com](http://www.ifeng.com)和[http://www.qq.com](http://www.qq.com)，可以在script的界面中的Consle看到打印出来的请求的url、响应状态吗和头部。
-
-	具体效果见图：[demo2](https://user-images.githubusercontent.com/11450939/126302210-e3aa0b56-9001-4e03-83c8-8986d8f544ff.gif)
-
-	需要在配置中带上参数，可以参考上面的规则设置
-2. 操作WebSocket请求(需要[开启HTTPs拦截](https://avwo.github.io/whistle/webui/https.html))
-	``` js
-	exports.handleWebSocket = async (socket, connect) => {
-		// 与服务器建立连接
-		const svrSocket = await connect();
-		// 客户端 pong 服务端
-		socket.on('pong', (data) => {
-			svrSocket.pong(data);
-		});
-		// 客户端 ping 服务pong 端
-		socket.on('ping', (data) => {
-			svrSocket.ping(data);
-		});
-		// 服务端 ping 客户端
-		svrSocket.on('ping', (data) => {
-			socket.ping(data);
-		});
-		// 服务端 pong 客户端
-		svrSocket.on('pong', (data) => {
-			socket.pong(data);
-		});
-		// 正常断开 WebSocket 连接
-		socket.on('disconnect', (code, message, opts) => {
-			console.log(code, 'client disconnect');
-			svrSocket.disconnect(code, opts);
-		});
-		// 正常断开 WebSocket 连接
-		svrSocket.on('disconnect', (code, message, opts) => {
-			console.log(code, 'server disconnect');
-			socket.disconnect(code, opts);
-		});
-		// 获取客户端解析后的帧数据
-		socket.on('message', (data, opts) => {
-			console.log(data, 'client data');
-			svrSocket.send(data, opts);
-		});
-		// 获取服务端解析后的帧数据
-		svrSocket.on('message', (data, opts) => {
-			console.log(data, 'server data');
-			socket.send(data, opts);
-		});
-	};
-
-	```
-
-		whistle规则配置同上，访问[https://www.websocket.org/echo.html](https://www.websocket.org/echo.html)，点击下面的connect按钮及send按钮，可以如下效果：[demo3](https://user-images.githubusercontent.com/11450939/126302243-26c8b4af-851c-4b00-87b9-3286e9e67251.gif)
-3. 操作Tunnel请求
-	``` js
-	exports.handleTunnel = async (socket, connect) => {
-		const svrSocket = await connect();
-		socket.pipe(svrSocket).pipe(socket);
-	};
-	```
-	whistle规则配置同上
-
-4. 鉴权
-插件 `v1.2.0` 版本开始支持自定义鉴权方法（要求 Whistle 版本 >= `v2.7.16`）：
-``` js
-exports.auth = async (req, options) => {
-	// 给请求添加自定义头，必须与 `x-whistle-` 开头
-	// 这样可以在插件的其他 hook 里面获取到该请求头（除了 http 请求的 reqRead 钩子）
-	req.setHeader('x-whistle-test', '1111111111');
-	// return false; // 直接返回 403
-};
-```
+# 🧩 whistle.script - 脚本扩展插件
 
-5. pipe
-插件 `v1.2.1` 版本开始支持自定义 pipe 方法：
-``` js
+中文 · [English](./README-en_US.md)
 
-exports.handleReqRead = (req, res, options) => {
-  req.pipe(res);
-};
+> 环境要求：Whistle 版本需为 2.10.0 或更高。
 
-exports.handleReqWrite = (req, res, options) => {
-  req.pipe(res);
-};
+whistle.script 是 [Whistle](https://github.com/avwo/whistle) 的脚本扩展插件。通过在 Web 界面编写 Node.js 脚本，您可以为 Whistle 注入动态逻辑，实现对网络请求、响应及 WebSocket 等协议的**编程式深度控制**。
 
-exports.handleResRead = (req, res, options) => {
-  req.pipe(res);
-};
+## 🎯 核心功能
 
-exports.handleResWrite = (req, res, options) => {
-  req.pipe(res);
-};
+### HTTP/HTTPS 处理
+- **动态规则生成** - 根据请求URL、头部等信息，实时生成并注入 Whistle 匹配规则。
+- **请求/响应拦截与修改** - 完整拦截 HTTP(S) 请求流与响应流，支持修改 URL、方法、头部、状态码及响应体。
+- **调试与日志** - 脚本内的 `console.log` 等输出会实时显示在插件控制台中，便于调试。
 
-exports.handleWsReqRead = (req, res, options) => {
-  req.pipe(res);
-};
+### WebSocket 处理
+- **双向通信拦截** - 拦截客户端与服务器之间的 WebSocket 握手及数据帧。
+- **消息动态处理** - 实时查看、修改或转发 `ping`、`pong`、`message` 及控制帧。
+- **直接数据发送** - 可主动向任一端发送数据或断开连接。
 
-exports.handleWsReqWrite = (req, res, options) => {
-  req.pipe(res);
-};
+### Tunnel / 原始 Socket 处理
+- **透明管道操作** - 处理如 HTTPS 隧道等原始 TCP 连接，实现底层数据流转发或修改。
+- **灵活性高** - 提供与 WebSocket 类似的 API，用于处理非 HTTP 协议。
+
+## 📦 安装指南
+
+### 1. 安装 Whistle 运行时
+**推荐方式（桌面用户）**：下载并安装可视化客户端，管理更便捷。  
+👉 [Whistle 客户端下载](https://github.com/avwo/whistle-client)
 
-exports.handleWsResRead = (req, res, options) => {
-  req.pipe(res);
+**命令行方式**：
+1.  **安装 Node.js (>= 8.8)**  
+    请从 [Node.js 官网](https://nodejs.org/) 下载并安装最新的 LTS 版本。
+2.  **全局安装 Whistle**
+    ```bash
+    npm install -g whistle
+    ```
+    > **提示**：若安装过程提示权限不足，可尝试使用 `sudo`（不推荐）或参考官方文档配置 npm 全局安装路径。
+
+### 2. 安装 whistle.script 插件
+在 Whistle 运行后，执行以下命令：
+```bash
+w2 i whistle.script
+```
+**或通过管理界面安装**：
+1.  启动 Whistle 并打开管理界面（默认为 `http://127.0.0.1:8899`）。
+2.  进入 **Plugins** 页面。
+3.  点击顶部的 `Install` 按钮。
+4.  输入 `whistle.script` 并确认安装。
+
+## 🚀 快速开始
+
+### 1. 打开插件界面
+-   在 Whistle 管理界面，通过菜单 `Plugins -> script` 进入。
+-   或直接访问地址：[http://local.whistlejs.com/plugin.script/](http://local.whistlejs.com/plugin.script/)。
+
+### 2. 创建并关联你的第一个脚本
+1.  在插件界面点击 **Create**，创建一个名为 `test` 的脚本。
+2.  在右侧编辑器中，输入以下示例代码：
+    ```javascript
+    exports.handleRequestRules = (ctx) => {
+        console.log('收到请求：', ctx.fullUrl);
+        ctx.rules = ['www.example.com 127.0.0.1:8080']; // 将请求转发到本地8080端口
+    };
+    ```
+3.  在 Whistle 的 **Rules** 配置页面，添加规则：
+    ```txt
+    www.example.com whistle.script://test
+    ```
+4.  现在，访问 `http://www.example.com` 的请求将被脚本处理，并可在插件 **Console** 标签页查看日志。
+
+![插件界面操作演示](https://user-images.githubusercontent.com/11450939/126302159-0c533ea7-3bc0-484a-bd30-698d5a7881df.gif)
+
+## 📖 功能详解
+
+### 1. 规则动态设置
+此模式允许脚本根据请求信息，动态返回需要执行的 Whistle 规则（字符串或数组），规则会与 `whistle.script://` 配置的原始规则合并执行。
+
+#### HTTP/HTTPS 规则
+> **重要**：如需拦截 HTTPS 请求，须先[开启并安装 Whistle 的 HTTPS 根证书](https://wproxy.org/docs/gui/https.html)。
+
+**脚本示例 (`test`)**：
+```javascript
+exports.handleRequestRules = (ctx) => {
+    // 根据请求路径动态返回本地文件
+    if (ctx.fullUrl.includes('/api/test')) {
+        ctx.rules = ['api.example.com/api/test file://{mockData.json}'];
+        ctx.values = {
+            'mockData.json': JSON.stringify({ code: 200, data: 'mocked' })
+        };
+    }
 };
+```
+**Whistle 规则配置**：
+```txt
+# 将多个域名的请求交给 `test` 脚本处理
+whistle.script://test www.test.com api.example.com
+```
 
-exports.handleWsResWrite = (req, res, options) => {
-  req.pipe(res);
+#### 向脚本传递参数
+可以在规则中向脚本传递参数（参数内请避免使用空格）。
+```txt
+whistle.script://test(prod,env1) www.example.com
+```
+脚本内通过以下方式获取：
+```javascript
+exports.handleRequestRules = (ctx) => {
+    console.log(process.args); // 输出：["prod", "env1"]
+    console.log(ctx.scriptValue); // 输出 (v1.3.0+)："prod,env1"
+    // 可根据参数执行不同逻辑
+    ctx.rules = 'www.test.com 127.0.0.1:8080';
 };
+```
 
-exports.handleTunnelReqRead = (req, res, options) => {
-  req.pipe(res);
+#### WebSocket 规则设置
+```javascript
+exports.handleWebSocketRules = (ctx) => {
+    // 动态决定哪些 WebSocket 连接需要被本插件处理
+    this.rules = 'echo.websocket.org statusCode://101';
 };
+```
 
-exports.handleTunnelReqWrite = (req, res, options) => {
-  req.pipe(res);
+### 2. 请求与响应的直接操作
+此模式赋予脚本对网络流量的完全控制权，可以手动发起请求、读取和修改数据。
+
+#### HTTP/HTTPS 请求处理
+使用 `script://` 协议触发此模式。
+
+```javascript
+exports.handleRequest = (ctx, request) => {
+    const { req, res } = ctx;
+    
+    req.passThrough({
+        // 可选
+        transformReq: function(req, next) {
+          // getBuffer, getText, getJson 都可以用来获取请求体，参数和回调函数的用法也完全一样
+          req.getJson(function(err, data) {
+            if (err) {
+              return next();
+            }
+            // data.a.b.c = 'test';
+            next(JSON.stringify(data));
+          });
+        },
+        // 可选
+        transformRes: function(svrRes, next) {
+          // getBuffer, getText, getJson 都可以用来获取请求体，参数和回调函数的用法也完全一样
+          svrRes.getText(function(err, text) {
+            if (err) {
+              return next();
+            }
+            next('[' + text + ', 123' + ']');
+          });
+        }
+      });
 };
+```
+**关联规则**：
+```txt
+# 注意：此处使用 script:// 触发 handleRequest 方法
+www.example.com/api script://test
+```
 
-exports.handleTunnelResRead = (req, res, options) => {
-  req.pipe(res);
+#### WebSocket 连接处理
+```javascript
+exports.handleWebSocket = async (socket, connect) => {
+    console.log('WebSocket 连接已建立');
+    
+    // 连接到原始后端服务器
+    const serverSocket = await connect();
+    
+    // 监听客户端消息，转发至服务器
+    socket.on('message', (data, opts) => {
+        console.log('<< 来自客户端:', data);
+        // 可在此处修改 data
+        serverSocket.send(`[中转] ${data}`, opts);
+    });
+    
+    // 监听服务器消息，转发至客户端
+    serverSocket.on('message', (data, opts) => {
+        console.log('>> 来自服务器:', data);
+        socket.send(data, opts);
+    });
+    
+    // 处理连接关闭
+    socket.on('disconnect', (code, reason) => {
+        console.log(`客户端断开连接 [${code}]: ${reason}`);
+        serverSocket.disconnect(code, reason);
+    });
 };
+```
 
-exports.handleTunnelResWrite = (req, res, options) => {
-  req.pipe(res);
+#### Tunnel (原始TCP) 处理
+
+用于处理 `CONNECT` 方法建立的隧道（如 HTTPS）。
+```javascript
+exports.handleTunnel = async (clientSocket, connect) => {
+    const targetSocket = await connect();
+    // 建立双向透明管道
+    clientSocket.pipe(targetSocket).pipe(clientSocket);
+    
+    // 可监听 data 事件进行更底层的二进制数据操作
 };
+```
 
+### 3. 高级功能
+
+#### 请求鉴权 (`auth`)
+在请求进入其他处理阶段前，进行身份验证。
+```javascript
+exports.auth = async (req, options) => {
+    const token = req.headers['x-auth-token'];
+    // 1. 添加内部透传头 (以 x-whistle- 开头)
+    req.setHeader('x-whistle-req-id', Date.now());
+    
+    // 2. 进行异步验证
+    // const isValid = await verifyToken(token);
+    // return isValid; // 返回 false 将直接响应 403 Forbidden
+    
+    // 3. 默认允许通过
+    return true;
+};
 ```
 
-# 如何引入第三方模块
-使用绝对路径引入，如假设你的模块安装路径为 `/Users/test/node_modules/xxx`，则可以在脚本里面通过 `require('/Users/test/node_modules/xxx')` 引入。
+#### 管道钩子 (Pipe Hooks)
+在请求/响应的不同生命周期阶段进行轻量拦截。
+```javascript
+// 在请求体被 Whistle 规则引擎读取前处理
+exports.handleReqRead = (req, res, options) => {
+    // 可用于记录原始请求体或进行早期修改
+    req.pipe(res); // 通常直接管道传输
+};
 
-# License
+// 在请求体被 Whistle 规则引擎处理后、发送到目标服务器前处理
+exports.handleReqWrite = (req, res, options) => {
+    // 可用于基于规则结果进行最终修改
+    req.pipe(res);
+};
+// 类似钩子：handleResRead, handleResWrite, handleWsReqRead 等
+```
 
-[MIT](https://github.com/whistle-plugins/whistle.script/blob/master/LICENSE)
+## 🔗 更多资源
+- [Whistle 核心文档](https://wproxy.org/)
+- [Whistle 规则配置语法](https://wproxy.org/docs/rules/rule.html)
+- [Whistle GitHub 仓库](https://github.com/avwo/whistle)
+- [插件开发类型定义参考](https://github.com/avwo/lack/blob/master/assets/ts/src/types/global.d.ts)
 
+## 📄 许可证
+本项目基于 [MIT License](./LICENSE) 开源。

package/lib/scripts.js

@@ -77,11 +77,14 @@ const execScript = (script, value) => {
 const parseRuleValue = (ctx) => {
   const { ruleValue } = ctx.req.originalReq;
   if (!RULE_VALUE_RE.test(ruleValue)) {
+    ctx.scriptValue = '';
     return '';
   }
+  const value = RegExp.$2;
+  ctx.scriptValue = value;
   return {
     name: RegExp.$1,
-    value: RegExp.$2,
+    value,
   };
 };
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "whistle.script",
   "description": "The plugin for the extension script for whistle",
-  "version": "1.2.9",
+  "version": "1.3.0",
   "author": "avenwu <avenwu@vip.qq.com>",
   "contributors": [],
   "license": "MIT",
@@ -53,7 +53,7 @@
     "koa": "^2.13.1",
     "koa-bodyparser": "^4.3.0",
     "koa-onerror": "^4.1.0",
-    "koa-router": "^10.0.0",
+    "koa-router": "^12.0.1",
     "koa-static": "^5.0.0"
   }
 }

package/public/index.html

@@ -7,6 +7,6 @@
 </head>
 <body>
 <div id="main" class="main"></div>
-<script src="index.js?v=0.4.0"></script>
+<script src="index.js?v=1.3.0"></script>
 </body>
 </html>