-
Notifications
You must be signed in to change notification settings - Fork 58
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
86 additions
and
0 deletions.
There are no files selected for viewing
86 changes: 86 additions & 0 deletions
86
i18n/en-us/docusaurus-plugin-content-docs/current/plugins/custom-response.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,86 @@ | ||
--- | ||
title: Custom response | ||
keywords: [higress, custom response] | ||
description: Custom response plugin configuration reference | ||
--- | ||
|
||
## Description | ||
`custom-response` plugin implements a function of sending 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 Enabled 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. |