+ English | 中文 +
+ # 功能说明 `custom-response`插件支持配置自定义的响应，包括自定义 HTTP 应答状态码、HTTP 应答头，以及 HTTP 应答 Body。可以用于 Mock 响应，也可以用于判断特定状态码后给出自定义应答，例如在触发网关限流策略时实现自定义响应。 diff --git a/plugins/wasm-cpp/extensions/custom_response/README_EN.md b/plugins/wasm-cpp/extensions/custom_response/README_EN.md new file mode 100644 index 000000000..929c03f14 --- /dev/null +++ b/plugins/wasm-cpp/extensions/custom_response/README_EN.md @@ -0,0 +1,84 @@ ++ English | 中文 +
+ +# Description +`custom-response` plugin supports configure custom responses, including custom HTTP response status codes, HTTP response headers and HTTP response body, which can be used in the scenarios of response mocking and sending a custom response for specific status codes, such as customizing the response for rate-limited requests. + +# Configuration Fields + +| Name | Type | Requirement | Default Value | Description | +| -------- | -------- | -------- | -------- | -------- | +| status_code | number | Optional | 200 | Custom HTTP response status code | +| headers | array of string | Optional | - | Custom HTTP response header. Key and value shall be separated using `=`. | +| body | string | Optional | - | Custom HTTP response body | +| enable_on_status | array of number | Optional | - | The original response status code to match. Generate the custom response only the actual status code matches the configuration. Ignore the status code match if left unconfigured. | + +# Configuration Samples + +## Mock Responses + +```yaml +status_code: 200 +headers: +- Content-Type=application/json +- Hello=World +body: "{\"hello\":\"world\"}" + +``` + +According to the configuration above, all the requests will get the following custom response: + +```text +HTTP/1.1 200 OK +Content-Type: application/json +Hello: World +Content-Length: 17 + +{"hello":"world"} +``` + +## Send a Custom Response when Rate-Limited + +```yaml +enable_on_status: +- 429 +status_code: 302 +headers: +- Location=https://example.com +``` + +When rate-limited, normally gateway will return a status code of `429` . Now, rate-limited requests will get the following custom response: + +```text +HTTP/1.1 302 Found +Location: https://example.com +``` + +So based on the 302 redirecting mechanism provided by browsers, this can redirect rate-limited users to other pages, for example, a static page hosted on CDN. + +If you'd like to send other responses when rate-limited, please add other fields into the configuration, referring to the Mock Responses scenario. + +## Only Enable for Specific Routes or Domains +```yaml +# Use _rules_ field for fine-grained rule configurations +_rules_: +# Rule 1: Match by route name +- _match_route_: + - route-a + - route-b + body: "{\"hello\":\"world\"}" +# Rule 2: Match by domain +- _match_domain_: + - "*.example.com" + - test.com + enable_on_status: + - 429 + status_code: 200 + headers: + - Content-Type=application/json + body: "{\"errmsg\": \"rate limited\"}" +``` +In the rule sample of `_match_route_`, `route-a` and `route-b` are the route names provided when creating a new gateway route. When the current route names matches the configuration, the rule following shall be applied. +In the rule sample of `_match_domain_`, `*.example.com` and `test.com` are the domain names used for request matching. When the current domain name matches the configuration, the rule following shall be applied. +All rules shall be checked following the order of items in the `_rules_` field, The first matched rule will be applied. All remained will be ignored. diff --git a/plugins/wasm-cpp/extensions/key_rate_limit/README_EN.md b/plugins/wasm-cpp/extensions/key_rate_limit/README_EN.md index 35bcafed2..2fe250fb0 100644 --- a/plugins/wasm-cpp/extensions/key_rate_limit/README_EN.md +++ b/plugins/wasm-cpp/extensions/key_rate_limit/README_EN.md @@ -67,4 +67,4 @@ _rules_: ``` In the rule sample of `_match_route_`, `route-a` and `route-b` are the route names provided when creating a new gateway route. When the current route names matches the configuration, the rule following shall be applied. In the rule sample of `_match_domain_`, `*.example.com` and `test.com` are the domain names used for request matching. When the current domain name matches the configuration, the rule following shall be applied. -All rules shall be checked following the order of items in the `_rules_` field，The first matched rule will be applied. All remained will be ignored. \ No newline at end of file +All rules shall be checked following the order of items in the `_rules_` field, The first matched rule will be applied. All remained will be ignored. \ No newline at end of file