From 830841b689e6467c12decf75239284cf713e53b1 Mon Sep 17 00:00:00 2001 From: yu_tao <59214333+trickMin@users.noreply.github.com> Date: Tue, 11 Oct 2022 13:35:02 +0800 Subject: [PATCH] Signed-off-by: yutao04 (#36) docs: add response-header-rewrite and static-downgrade plugin docs --- docs/README.md | 7 +-- docs/plugin/percent-limit.md | 9 ++-- docs/plugin/response-header-rewrite.md | 47 ++++++++++++++++++ docs/plugin/static-downgrade.md | 66 ++++++++++++++++++++++++++ docs/plugin/ua-restriction.md | 48 +++++++++++++++++++ 5 files changed, 170 insertions(+), 7 deletions(-) create mode 100644 docs/plugin/response-header-rewrite.md create mode 100644 docs/plugin/static-downgrade.md create mode 100644 docs/plugin/ua-restriction.md diff --git a/docs/README.md b/docs/README.md index fc6e607..275251f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -3,10 +3,11 @@ ## 插件 * [插件界面配置引导](plugin/plugin-configuring-guide.md) - * [percent-limit](plugin/percent-limit.md) +* [static-downgrade](plugin/static-downgrade.md) +* [response-header-rewrite](plugin/response-header-rewrite.md) +* [ua-restriction](plugin/ua-restriction.md) ## 问题定位 -* [问题定位引导](troubleshooting/troubleshooting.md) - +* [问题定位引导](troubleshooting/troubleshooting.md) \ No newline at end of file diff --git a/docs/plugin/percent-limit.md b/docs/plugin/percent-limit.md index 35c9741..073f9f6 100644 --- a/docs/plugin/percent-limit.md +++ b/docs/plugin/percent-limit.md @@ -6,14 +6,15 @@ ## 属性 -| 名称 | 类型 | 必选项 | 默认值 | 描述 | -|-------|--------|-----|-----|------------| -| 限流百分比 | number | 是 | - | 允许通过流量的百分比 | +| 名称 | 类型 | 必选项 | 范围 | 描述 | +|---------------|---------|-----|---------------|------------| +| kind | string | 是 | percent-limit | 插件类型（值固定） | +| limit_percent | integer | 是 | [0, 100] | 允许通过流量的百分比 | ## 前置条件 -以下curl命令中存在变量，使用前需要替换为真实环境数据，变量以`{{}}`符号包裹，例如`{{ 网关ID }}`需要根据网关的实际ID进行替换 +以下curl命令中存在变量，使用前需要替换为真实环境数据，变量以`{{}}`符号包裹，例如`{{ 网关ID }}`需要根据网关的实际ID进行替换；创建插件命令中`PluginConfiguration`（插件配置）需要根据实际需要进行配置 ## 创建 diff --git a/docs/plugin/response-header-rewrite.md b/docs/plugin/response-header-rewrite.md new file mode 100644 index 0000000..3c6d7c8 --- /dev/null +++ b/docs/plugin/response-header-rewrite.md @@ -0,0 +1,47 @@ +# 响应头部重写 + +## 描述 + +`response-header-rewrite`插件对请求的响应头进行变更，包括新增、删除和修改操作 + +## 属性 + +| 名称 | 类型 | 必选项 | 默认值 | 范围 | 描述 | +|----------------------|--------|-----|--------|------------------------------|--------------| +| header[].headerKey | string | 是 | - | length <= 200 | 需要操作的响应头名称 | +| header[].operation | string | 是 | create | create
update
delete | 对响应的的操作类型 | +| header[].headerValue | string | 是 | - | length <= 200 | 对于响应头新增或修改的值 | + + +## 前置条件 + +以下curl命令中存在变量，使用前需要替换为真实环境数据，变量以`{{}}`符号包裹，例如`{{ 网关ID }}`需要根据网关的实际ID进行替换；创建插件命令中`PluginConfiguration`（插件配置）需要根据实际需要进行配置 + +## 创建 + +```shell +curl -XPOST -v -H "Content-Type:application/json" -d '{ + "BindingObjectId": {{ 路由ID }}, + "BindingObjectType": "routeRule", + "GwId": {{ 网关ID }}, + "PluginConfiguration": "{\"header\":[\"headerKey\": \"testHeader\",\"operation\": \"update\",\"headerValue\": \"testHeaderValue\"]}", + "PluginType": "response-header-rewrite" +}' http://{{ hango-portal ip:port }}/gdashboard?Action=BindingPlugin&Version=2019-09-01 +``` + +## 测试 + +```shell +## 基于如下基础curl命令，根据后端服务要求将请求具体化，观察响应中的头变化是否符合插件配置的预期（响应头是否新增、被修改或删除） +curl -v "http://{{ 网关IP }}/{{ 路由path }}" -H "host:{{ 网关关联域名 }}" +``` + +## 删除 + +```shell +curl -v -H "Content-Type:application/json" http://{{ hango-portal ip:port }}/gdashboard?PluginBindingInfoId={{ 插件ID }}&Action=UnbindingPlugin&Version=2019-09-01 +``` + +## 界面配置方法 + +[插件界面配置方法引导](plugin-configuring-guide.md) \ No newline at end of file diff --git a/docs/plugin/static-downgrade.md b/docs/plugin/static-downgrade.md new file mode 100644 index 0000000..12887b4 --- /dev/null +++ b/docs/plugin/static-downgrade.md @@ -0,0 +1,66 @@ +# 静态降级 + +## 描述 + +`static-downgrade`插件可匹配指定的请求进行降级，返回指定的响应内容 + +## 属性 + +| 名称 | 类型 | 必选项 | 范围 | 描述 | +|-----------------------------------------|----------|-----|--------------------------------------------------------------------------------------|--------------| +| kind | string | 是 | static-downgrade | 插件类型（值固定） | +| condition.request.requestSwitch | boolean | 是 | - | 是否使用请求进行匹配 | +| condition.request.method | []string | 否 | GET
POST
PUT
DELETE
OPTIONS
HEAD
TRACE
CONNECT
PATCH | HTTP的请求方法类型 | +| condition.request.path.match_type | string | 否 | exact_match
safe_regex_match | 请求路径匹配方式 | +| condition.request.path.value | string | 否 | - | 请求路径匹配内容 | +| condition.request.host.match_type | string | 否 | exact_match
safe_regex_match | 请求域名匹配方式 | +| condition.request.host.value | string | 否 | - | 请求域名匹配内容 | +| condition.request.headers[].headerKey | string | 否 | - | 请求头匹配名称 | +| condition.request.headers[].match_type | string | 否 | exact_match
safe_regex_match | 请求头匹配匹配方式 | +| condition.request.headers[].value | string | 否 | - | 请求头匹配匹配内容 | +| condition.response.code.match_type | string | 是 | exact_match
safe_regex_match | 响应状态码匹配方式 | +| condition.response.code.value | integer | 是 | [200, 599] | 响应状态码匹配内容 | +| condition.response.headers[].headerKey | string | 否 | - | 响应头匹配名称 | +| condition.response.headers[].match_type | string | 否 | exact_match
safe_regex_match | 响应头匹配方式 | +| condition.response.headers[].value | string | 否 | - | 响应头匹配内容 | +| response.code | integer | 是 | [200, 599] | 降级后返回的状态码 | +| response.headers[key] | string | 是 | - | 降级后返回的响应头 | +| response.headers[value] | string | 是 | - | 降级后返回的响应头对应值 | +| response.body | string | 否 | - | 降级后返回的body内容 | + + +## 前置条件 + +以下curl命令中存在变量，使用前需要替换为真实环境数据，变量以`{{}}`符号包裹，例如`{{ 网关ID }}`需要根据网关的实际ID进行替换；创建插件命令中`PluginConfiguration`（插件配置）需要根据实际需要进行配置 + +## 创建 + +```shell +curl -XPOST -v -H "Content-Type:application/json" -d '{ + "BindingObjectId": {{ 路由ID }}, + "BindingObjectType": "routeRule", + "GwId": {{ 网关ID }}, + "PluginConfiguration": "{\"condition\":{\"request\":{\"requestSwitch\":true,\"method\":[\"GET\",\"POST\"],\"path\":{\"match_type\":\"exact_match\",\"value\":\"/rootpath/subpath\"},\"headers\":[{\"headerKey\":\"reqHeader\",\"match_type\":\"exact_match\",\"value\":\"reqHeaderValue\"}]},\"response\":{\"code\":{\"match_type\":\"safe_regex_match\",\"value\":\"503\"},\"headers\":[{\"headerKey\":\"rspHeader\",\"match_type\":\"exact_match\",\"value\":\"rspHeaderValue\"}]}},\"kind\":\"static-downgrade\",\"response\":{\"headers\":{\"downgradeHeader\":\"downgradeHeaderValue\"},\"code\":\"200\",\"body\":\"Test Response Context\"}}", + "PluginType": "static-downgrade" +}' http://{{ hango-portal ip:port }}/gdashboard?Action=BindingPlugin&Version=2019-09-01 +``` + +## 测试 + +```shell +## 基于如下基本的curl命令，添加插件中配置的请求头、响应头等降级条件，测试是否返回配置的响应内容（响应码、响应头和响应体） +curl -v "http://{{ 网关IP }}/{{ 路由path }}" -H "host:{{ 网关关联域名 }}" + +## 例如，插件中配置了降级条件配置了一个响应头为"reqHeader: reqHeaderValue"，则需要构造如下请求进行测试 +curl -v "http://{{ 网关IP }}/{{ 路由path }}" -H "host:{{ 网关关联域名 }}" -H "reqHeader:reqHeaderValue" +``` + +## 删除 + +```shell +curl -v -H "Content-Type:application/json" http://{{ hango-portal ip:port }}/gdashboard?PluginBindingInfoId={{ 插件ID }}&Action=UnbindingPlugin&Version=2019-09-01 +``` + +## 界面配置方法 + +[插件界面配置方法引导](plugin-configuring-guide.md) \ No newline at end of file diff --git a/docs/plugin/ua-restriction.md b/docs/plugin/ua-restriction.md new file mode 100644 index 0000000..26eabbd --- /dev/null +++ b/docs/plugin/ua-restriction.md @@ -0,0 +1,48 @@ +# UA黑白名单 + +## 描述 + +`ua-restriction`插件可以针对来源于不同User-Agent（用户代理）的请求进行黑名单或白名单限制 + +## 属性 + +| 名称 | 类型 | 必选项 | 范围 | 描述 | +|-------------------|---------|-----|---------------------------------------------------|--------------------------| +| kind | string | 是 | ua-restriction | 插件类型（值固定） | +| type | integer | 是 | [0, 1] | UA黑白名单策略
0:黑名单；1:白名单 | +| list[].match_type | string | 是 | exact_match
prefix_match
safe_regex_match | UA黑白名单策略 | +| list[].value | string | 是 | length <= 200 | User-Agent值 | + + +## 前置条件 + +以下curl命令中存在变量，使用前需要替换为真实环境数据，变量以`{{}}`符号包裹，例如`{{ 网关ID }}`需要根据网关的实际ID进行替换；创建插件命令中`PluginConfiguration`（插件配置）需要根据实际需要进行配置 + +## 创建 + +```shell +curl -XPOST -v -H "Content-Type:application/json" -d '{ + "BindingObjectId": {{ 路由ID }}, + "BindingObjectType": "routeRule", + "GwId": {{ 网关ID }}, + "PluginConfiguration": "{\"type\":\"0\",\"list\":[{\"match_type\":\"exact_match\",\"value\":[\"testUA\"]}],\"kind\":\"ua-restriction\"}", + "PluginType": "ua-restriction" +}' http://{{ hango-portal ip:port }}/gdashboard?Action=BindingPlugin&Version=2019-09-01 +``` + +## 测试 + +```shell +## 修改如下请求的User-Agent参数，与插件配置的UA值一致，测试黑白名单效果 +curl -v "http://{{ 网关IP }}/{{ 路由path }}" -H "host:{{ 网关关联域名 }}" -H "User-Agent:xxx" +``` + +## 删除 + +```shell +curl -v -H "Content-Type:application/json" http://{{ hango-portal ip:port }}/gdashboard?PluginBindingInfoId={{ 插件ID }}&Action=UnbindingPlugin&Version=2019-09-01 +``` + +## 界面配置方法 + +[插件界面配置方法引导](plugin-configuring-guide.md) \ No newline at end of file