higress

The custom-response plugin supports the configuration of custom responses, including custom HTTP response status codes, HTTP response headers, and HTTP response bodies. It can be used for Mock responses or for providing custom responses based on specific status codes, such as implementing custom responses when triggering the gateway rate-limiting policy.

Running Attributes

Plugin Execution Phase: Authentication Phase

Plugin Execution Priority: 910

Configuration Fields

New version - Supports multiple returns

Name	Data Type	Requirements	Default Value	Description
rules	array of object	Required	-	rule array

The configuration field description of rules is as follows：

Name	Data Type	Requirements	Default Value	Description
`status_code`	number	Optional	200	Custom HTTP response status code
`headers`	array of string	Optional	-	Custom HTTP response headers, keys and values separated by `=`
`body`	string	Optional	-	Custom HTTP response body
`enable_on_status`	array of string or number	Optional	-	Match the original status code to generate a custom response. You can fill in the exact value such as :`200`,`404`, etc., you can also fuzzy match such as: `2xx` to match the status code between 200-299, `20x` to match the status code between 200-209, x represents any digit. If enable_on_status is not specified, the original status code is not determined and the first rule with ENABLE_ON_status left blank is used as the default rule

Fuzzy matching rule

Length is 3
At least one digit
At least one x(case insensitive)

rule	Matching content
40x	400-409; If the first two digits are 40
1x4	104,114,124,134,144,154,164,174,184,194；The first and third positions are 1 and 4 respectively
x23	023,123,223,323,423,523,623,723,823,923；The second and third positions are 23
4xx	400-499；The first digit is 4
x4x	040-049,140-149,240-249,340-349,440-449,540-549,640-649,740-749,840-849,940-949；The second digit is 4
xx4	When the mantissa is 4

Matching priority: Exact Match > Fuzzy Match > Default configuration (the first enable_on_status parameter is null)

Old version - Only one return is supported

Name	Data Type	Requirements	Default Value	Description
`status_code`	number	Optional	200	Custom HTTP response status code
`headers`	array of string	Optional	-	Custom HTTP response headers, keys and values separated by `=`
`body`	string	Optional	-	Custom HTTP response body
`enable_on_status`	array of number	Optional	-	Match original status codes to generate custom responses; if not specified, the original status code is not checked

Configuration Example

Different status codes for different response scenarios

rules:
  - body: '{"hello":"world 200"}'
    enable_on_status:
      - '200'
      - '201'
    headers:
      - key1=value1
      - key2=value2
    status_code: 200
  - body: '{"hello":"world 404"}'
    enable_on_status:
      - '404'
    headers:
      - key1=value1
      - key2=value2
    status_code: 200

According to this configuration 200 201 requests will return a custom response as follows：

HTTP/1.1 200 OK
Content-Type: application/json
key1: value1
key2: value2
Content-Length: 21

{"hello":"world 200"}

According to this configuration 404 requests will return a custom response as follows：

HTTP/1.1 200 OK
Content-Type: application/json
key1: value1
key2: value2
Content-Length: 21

{"hello":"world 400"}

With this configuration, 404 response will return the following custom response:

HTTP/1.1 200 OK
Content-Type: application/json
key1: value1
key2: value2
Content-Length: 21

{"hello":"world 404"}

Fuzzy matching scene

rules:
  - body: '{"hello":"world 200"}'
    enable_on_status:
      - 200
    headers:
      - key1=value1
      - key2=value2
    status_code: 200
  - body: '{"hello":"world 40x"}'
    enable_on_status:
      - '40x'
    headers:
      - key1=value1
      - key2=value2
    status_code: 200

According to this configuration, the status 200 will return a custom reply as follows：

HTTP/1.1 200 OK
Content-Type: application/json
key1: value1
key2: value2
Content-Length: 21

{"hello":"world 200"}

According to this configuration, the status code between 401-409 will return a custom reply as follows：

HTTP/1.1 200 OK
Content-Type: application/json
key1: value1
key2: value2
Content-Length: 21

{"hello":"world 40x"}

Mock Response Scenario

enable_on_status:
  - 200
status_code: 200
headers:
  - Content-Type=application/json
  - Hello=World
body: "{\"hello\":\"world\"}"

With this configuration, 200/201 response will return the following custom response:

HTTP/1.1 200 OK
Content-Type: application/json
key1: value1
key2: value2
Content-Length: 21

{"hello":"world"}

Custom Response on Rate Limiting

enable_on_status:
- 429
status_code: 302
headers:
- Location=https://example.com

When the gateway rate limiting is triggered, it generally returns the 429 status code, and the request will return the following custom response:

HTTP/1.1 302 Found
Location: https://example.com

This achieves the goal of redirecting users who have been rate-limited to another page based on the browser's 302 redirect mechanism, which could be a static page on a CDN.

If you wish to return other responses normally when rate limiting is triggered, just refer to the Mock response scenario to configure the relevant fields accordingly.

README_EN.md Unescape Escape

Function Description