Merge pull request #1208 from xuleiming/develop

docs of mod_wasmplugin
bfenetworks · Dec 31, 2024 · ea2c62e · ea2c62e
2 parents 67c85e4 + 84df246
commit ea2c62e
Show file tree

Hide file tree

Showing 4 changed files with 179 additions and 0 deletions.
diff --git a/docs/en_us/SUMMARY.md b/docs/en_us/SUMMARY.md
@@ -64,6 +64,7 @@
   * [mod_trust_clientip](modules/mod_trust_clientip/mod_trust_clientip.md)
   * [mod_userid](modules/mod_userid/mod_userid.md)
   * [mod_secure_link](modules/mod_secure_link/mod_secure_link.md)
+  * [mod_wasmplugin](modules/mod_wasmplugin/mod_wasmplugin.md)
 * Operations
   * [Command line options](operation/command.md)
   * [Environment variables](operation/env_var.md)

diff --git a/docs/en_us/modules/mod_wasmplugin/mod_wasmplugin.md b/docs/en_us/modules/mod_wasmplugin/mod_wasmplugin.md
@@ -0,0 +1,89 @@
+# mod_wasmplugin
+
+## Introduction
+
+Bfe supports calling user-defined wasm plugins (following the proxy-wasm specification, https://github.com/proxy-wasm/spec) in the processing flow of http request/response.
+The mod_wasmplugin module is responsible for running wasm plugins and invoking them according to user-defined rules.。
+
+## Module Configuration
+
+### Description
+
+conf/mod_wasm/mod_wasm.conf
+
+| Config Item                | Description                                        |
+| ---------------------| ------------------------------------------- |
+| Basic.DataPath            | String<br>Path of rule configuration |
+| Basic.WasmPluginPath      | String<br>Folder path for storing wasm plugin files |
+| Log.OpenDebug           | Boolean<br>Debug flag of module<br>Default value: `False` |
+
+### Example
+
+```ini
+[Basic]
+DataPath = mod_wasm/mod_wasm.data
+WasmPluginPath=wasm_plugin/
+```
+
+## Rule Configuration
+
+### Description
+
+| Config Item                | Description                                        |
+| ------- | -------------------------------------------------------------- |
+| Version | String<br>Version of config file |
+| BeforeLocationRules | Object<br>List of wasm plugin rules for the HandleBeforeLocation callback point |
+| BeforeLocationRules[] | Object<br>A rule |
+| BeforeLocationRules[].Cond | String<br>Condition expression, See [Condition](../../condition/condition_grammar.md) |
+| BeforeLocationRules[].PluginList | Object<br>List of wasm plugins to invoke when the condition is matched |
+| BeforeLocationRules[].PluginList[] | String<br>Name of the wasm plugin |
+| ProductRules | Object<br>Wasm plugin rules for each product |
+| ProductRules{k} | String<br>Product name |
+| ProductRules{v} | Object<br>List of wasm plugin rules |
+| ProductRules{v}[] | Object<br>A rule |
+| ProductRules{v}[].Cond | String<br>Condition expression, See [Condition](../../condition/condition_grammar.md) |
+| ProductRules{v}[].PluginList | Object<br>List of wasm plugins to invoke when the condition is matched |
+| ProductRules{v}[].PluginList[] | String<br>Name of the wasm plugin |
+| PluginMap | Object<br>Dictionary of wasm plugins |
+| PluginMap{k} | String<br>Name of the wasm plugin |
+| PluginMap{v} | Object<br>A wasm plugin |
+| PluginMap{v}.Name | String<br>Name of the wasm plugin |
+| PluginMap{v}.WasmVersion | String<br>Version of the wasm file |
+| PluginMap{v}.ConfVersion | String<br>Version of the configuration file |
+| PluginMap{v}.InstanceNum | Integer<br>Number of running instances of the wasm plugin |
+
+### Example
+
+```json
+{
+    "Version": "20240101000000",
+    "BeforeLocationRules": [{
+        "Cond": "req_path_prefix_in(\"/headers\", false)",
+        "PluginList": [ "headers" ]
+    }],
+    "ProductRules": {
+        "local_product": [{
+            "Cond": "default_t()",
+            "PluginList": []
+        }]
+    },
+    "PluginMap": {
+        "headers": {
+            "Name": "headers",
+            "WasmVersion": "20240101000000",
+            "ConfVersion": "20240101000000",
+            "InstanceNum": 20
+        }
+    }
+}
+```
+
+## Wasm Plugin Files
+
+For any wasm plugin (with name `PlugName` for example) in the PluginMap, the following files need to be prepared in advance and stored in the path: `<WasmPluginPath>`/`PlugName`/
+
+| File Name  | Description |
+| ------- | -------------------------------------------------------------- |
+| PlugName.wasm | wasm file |
+| PlugName.md5 | md5 file of PlugName.wasm |
+| PlugName.conf | Custom configuration file for the plugin |
diff --git a/docs/zh_cn/SUMMARY.md b/docs/zh_cn/SUMMARY.md
@@ -64,6 +64,7 @@
   * [mod_trust_clientip](modules/mod_trust_clientip/mod_trust_clientip.md)
   * [mod_userid](modules/mod_userid/mod_userid.md)
   * [mod_secure_link](modules/mod_secure_link/mod_secure_link.md)
+  * [mod_wasmplugin](modules/mod_wasmplugin/mod_wasmplugin.md)
 * 运维管理
   * [命令行工具及参数](operation/command.md)
   * [环境变量说明](operation/env_var.md)

diff --git a/docs/zh_cn/modules/mod_wasmplugin/mod_wasmplugin.md b/docs/zh_cn/modules/mod_wasmplugin/mod_wasmplugin.md
@@ -0,0 +1,88 @@
+# mod_wasmplugin
+
+## 模块简介
+
+Bfe 支持在 http request/response 的处理流程中引入用户自定义的 wasm插件 （遵循 proxy-wasm 规范， https://github.com/proxy-wasm/spec）。
+mod_wasmplugin 负责运行 wasm插件，并根据自定义规则调用 wasm插件。
+
+## 基础配置
+
+### 配置描述
+
+模块配置文件: conf/mod_wasm/mod_wasm.conf
+
+| 配置项                | 描述                                        |
+| ---------------------| ------------------------------------------- |
+| Basic.DataPath            | String<br>wasm插件规则配置的文件路径 |
+| Basic.WasmPluginPath      | String<br>存放wasm插件文件的文件夹路径 |
+| Log.OpenDebug           | Boolean<br>是否开启 debug 日志<br>默认值False |
+
+### 配置示例
+
+```ini
+[Basic]
+DataPath = mod_wasm/mod_wasm.data
+WasmPluginPath=wasm_plugin/
+```
+
+## wasm插件规则配置
+
+### 配置描述
+
+| 配置项  | 描述                                                           |
+| ------- | -------------------------------------------------------------- |
+| Version | String<br>配置文件版本 |
+| BeforeLocationRules | Object<br>HandleBeforeLocation 回调点的 wasm插件规则列表 |
+| BeforeLocationRules[] | Object<br>wasm插件规则详细信息 |
+| BeforeLocationRules[].Cond | String<br>描述匹配请求或连接的条件, 语法详见[Condition](../../condition/condition_grammar.md) |
+| BeforeLocationRules[].PluginList | Object<br>条件匹配时执行的wasm插件列表 |
+| BeforeLocationRules[].PluginList[] | String<br>wasm插件名 |
+| ProductRules | Object<br>各产品线的 wasm插件规则列表 |
+| ProductRules{k} | String<br>产品线名称 |
+| ProductRules{v} | Object<br>产品线下的 wasm插件规则列表 |
+| ProductRules{v}[] | Object<br>wasm插件规则详细信息 |
+| ProductRules{v}[].Cond | String<br>描述匹配请求或连接的条件, 语法详见[Condition](../../condition/condition_grammar.md) |
+| ProductRules{v}[].PluginList | Object<br>条件匹配时执行的wasm插件列表 |
+| ProductRules{v}[].PluginList[] | String<br>wasm插件名 |
+| PluginMap | Object<br>wasm插件字典 |
+| PluginMap{k} | String<br>wasm插件名 |
+| PluginMap{v} | Object<br>wasm插件详细信息 |
+| PluginMap{v}.Name | String<br>wasm插件名 |
+| PluginMap{v}.WasmVersion | String<br>wasm插件文件版本 |
+| PluginMap{v}.ConfVersion | String<br>wasm插件配置文件版本 |
+| PluginMap{v}.InstanceNum | Integer<br>wasm插件运行实例数 |
+
+### 配置示例
+
+```json
+{
+    "Version": "20240101000000",
+    "BeforeLocationRules": [{
+        "Cond": "req_path_prefix_in(\"/headers\", false)",
+        "PluginList": [ "headers" ]
+    }],
+    "ProductRules": {
+        "local_product": [{
+            "Cond": "default_t()",
+            "PluginList": []
+        }]
+    },
+    "PluginMap": {
+        "headers": {
+            "Name": "headers",
+            "WasmVersion": "20240101000000",
+            "ConfVersion": "20240101000000",
+            "InstanceNum": 20
+        }
+    }
+}
+```
+
+## wasm插件文件
+
+对于 PluginMap 中的任意一个 wasm插件（名为`PlugName`），需要预先准备好以下文件，存放于路径： `<WasmPluginPath>`/`PlugName`/
+| 文件名  | 描述                                                           |
+| ------- | -------------------------------------------------------------- |
+| PlugName.wasm | wasm 文件 |
+| PlugName.md5 | PlugName.wasm 的 md5 文件 |
+| PlugName.conf | 插件自定义配置文件 |