diff --git a/docs/en_us/SUMMARY.md b/docs/en_us/SUMMARY.md index 73d90358..559086f4 100644 --- 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 new file mode 100644 index 00000000..1ffaf717 --- /dev/null +++ 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
Path of rule configuration | +| Basic.WasmPluginPath | String
Folder path for storing wasm plugin files | +| Log.OpenDebug | Boolean
Debug flag of module
Default value: `False` | + +### Example + +```ini +[Basic] +DataPath = mod_wasm/mod_wasm.data +WasmPluginPath=wasm_plugin/ +``` + +## Rule Configuration + +### Description + +| Config Item | Description | +| ------- | -------------------------------------------------------------- | +| Version | String
Version of config file | +| BeforeLocationRules | Object
List of wasm plugin rules for the HandleBeforeLocation callback point | +| BeforeLocationRules[] | Object
A rule | +| BeforeLocationRules[].Cond | String
Condition expression, See [Condition](../../condition/condition_grammar.md) | +| BeforeLocationRules[].PluginList | Object
List of wasm plugins to invoke when the condition is matched | +| BeforeLocationRules[].PluginList[] | String
Name of the wasm plugin | +| ProductRules | Object
Wasm plugin rules for each product | +| ProductRules{k} | String
Product name | +| ProductRules{v} | Object
List of wasm plugin rules | +| ProductRules{v}[] | Object
A rule | +| ProductRules{v}[].Cond | String
Condition expression, See [Condition](../../condition/condition_grammar.md) | +| ProductRules{v}[].PluginList | Object
List of wasm plugins to invoke when the condition is matched | +| ProductRules{v}[].PluginList[] | String
Name of the wasm plugin | +| PluginMap | Object
Dictionary of wasm plugins | +| PluginMap{k} | String
Name of the wasm plugin | +| PluginMap{v} | Object
A wasm plugin | +| PluginMap{v}.Name | String
Name of the wasm plugin | +| PluginMap{v}.WasmVersion | String
Version of the wasm file | +| PluginMap{v}.ConfVersion | String
Version of the configuration file | +| PluginMap{v}.InstanceNum | Integer
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: ``/`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 index b80e52c0..792126ae 100644 --- 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 new file mode 100644 index 00000000..11fb41f3 --- /dev/null +++ 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
wasm插件规则配置的文件路径 | +| Basic.WasmPluginPath | String
存放wasm插件文件的文件夹路径 | +| Log.OpenDebug | Boolean
是否开启 debug 日志
默认值False | + +### 配置示例 + +```ini +[Basic] +DataPath = mod_wasm/mod_wasm.data +WasmPluginPath=wasm_plugin/ +``` + +## wasm插件规则配置 + +### 配置描述 + +| 配置项 | 描述 | +| ------- | -------------------------------------------------------------- | +| Version | String
配置文件版本 | +| BeforeLocationRules | Object
HandleBeforeLocation 回调点的 wasm插件规则列表 | +| BeforeLocationRules[] | Object
wasm插件规则详细信息 | +| BeforeLocationRules[].Cond | String
描述匹配请求或连接的条件, 语法详见[Condition](../../condition/condition_grammar.md) | +| BeforeLocationRules[].PluginList | Object
条件匹配时执行的wasm插件列表 | +| BeforeLocationRules[].PluginList[] | String
wasm插件名 | +| ProductRules | Object
各产品线的 wasm插件规则列表 | +| ProductRules{k} | String
产品线名称 | +| ProductRules{v} | Object
产品线下的 wasm插件规则列表 | +| ProductRules{v}[] | Object
wasm插件规则详细信息 | +| ProductRules{v}[].Cond | String
描述匹配请求或连接的条件, 语法详见[Condition](../../condition/condition_grammar.md) | +| ProductRules{v}[].PluginList | Object
条件匹配时执行的wasm插件列表 | +| ProductRules{v}[].PluginList[] | String
wasm插件名 | +| PluginMap | Object
wasm插件字典 | +| PluginMap{k} | String
wasm插件名 | +| PluginMap{v} | Object
wasm插件详细信息 | +| PluginMap{v}.Name | String
wasm插件名 | +| PluginMap{v}.WasmVersion | String
wasm插件文件版本 | +| PluginMap{v}.ConfVersion | String
wasm插件配置文件版本 | +| PluginMap{v}.InstanceNum | Integer
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`),需要预先准备好以下文件,存放于路径: ``/`PlugName`/ +| 文件名 | 描述 | +| ------- | -------------------------------------------------------------- | +| PlugName.wasm | wasm 文件 | +| PlugName.md5 | PlugName.wasm 的 md5 文件 | +| PlugName.conf | 插件自定义配置文件 |