You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by sp...@apache.org on 2022/04/12 09:35:36 UTC
[apisix] branch master updated: docs: update "Transformation" Plugins (#6775)
This is an automated email from the ASF dual-hosted git repository.
spacewander pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new 3250b9881 docs: update "Transformation" Plugins (#6775)
3250b9881 is described below
commit 3250b9881eb5284f7db04c0fd055a097b9cbfe8f
Author: Navendu Pottekkat <na...@gmail.com>
AuthorDate: Tue Apr 12 15:05:31 2022 +0530
docs: update "Transformation" Plugins (#6775)
---
docs/en/latest/plugins/fault-injection.md | 351 +++++++----------------------
docs/en/latest/plugins/grpc-transcode.md | 139 ++++++------
docs/en/latest/plugins/grpc-web.md | 46 ++--
docs/en/latest/plugins/mocking.md | 62 +++--
docs/en/latest/plugins/proxy-rewrite.md | 42 ++--
docs/en/latest/plugins/response-rewrite.md | 89 +++++---
6 files changed, 294 insertions(+), 435 deletions(-)
diff --git a/docs/en/latest/plugins/fault-injection.md b/docs/en/latest/plugins/fault-injection.md
index f02674f89..296786a28 100644
--- a/docs/en/latest/plugins/fault-injection.md
+++ b/docs/en/latest/plugins/fault-injection.md
@@ -1,5 +1,11 @@
---
title: fault-injection
+keywords:
+ - APISIX
+ - Plugin
+ - Fault Injection
+ - fault-injection
+description: This document contains information about the Apache APISIX fault-injection Plugin.
---
<!--
@@ -23,23 +29,33 @@ title: fault-injection
## Description
-Fault injection plugin, this plugin can be used with other plugins and will be executed before other plugins. The `abort` attribute will directly return the user-specified http code to the client and terminate the subsequent plugins. The `delay` attribute will delay a request and execute subsequent plugins.
+The `fault-injection` Plugin can be used to test the resiliency of your application. This Plugin will be executed before the other configured Plugins.
+
+The `abort` attribute will directly return the specified HTTP code to the client and skips executing the subsequent Plugins.
+
+The `delay` attribute delays a request and executes of the subsequent Plugins.
## Attributes
-| Name | Type | Requirement | Default | Valid | Description |
-| ----------------- | ------- | ----------- | ------- | ---------- | ------------------------------------------------ |
-| abort.http_status | integer | required | | [200, ...] | user-specified http code returned to the client. |
-| abort.body | string | optional | | | response data returned to the client. Nginx variable can be used inside, like `client addr: $remote_addr\n` |
-| abort.percentage | integer | optional | | [0, 100] | percentage of requests to be aborted. |
-| abort.vars | array[] | optional | | | The rules for executing fault injection will only be executed when the rules are matched. `vars` is a list of expressions, which is from the [lua-resty-expr](https://github.com/api7/lua-resty-expr). |
-| delay.duration | number | required | | | delay time (can be decimal). |
-| delay.percentage | integer | optional | | [0, 100] | percentage of requests to be delayed. |
-| delay.vars | array[] | optional | | | Execute the request delay rule, and the request will be delayed only after the rule matches. `vars` is a list of expressions, which is from the [lua-resty-expr](https://github.com/api7/lua-resty-expr). |
+| Name | Type | Requirement | Default | Valid | Description |
+|-------------------|---------|-------------|---------|------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| abort.http_status | integer | required | | [200, ...] | HTTP status code of the response to return to the client. |
+| abort.body | string | optional | | | Body of the response returned to the client. Nginx variables like `client addr: $remote_addr\n` can be used in the body. |
+| abort.percentage | integer | optional | | [0, 100] | Percentage of requests to be aborted. |
+| abort.vars | array[] | optional | | | Rules which are matched before executing fault injection. See [lua-resty-expr](https://github.com/api7/lua-resty-expr) for a list of available expressions. |
+| delay.duration | number | required | | | Duration of the delay. Can be decimal. |
+| delay.percentage | integer | optional | | [0, 100] | Percentage of requests to be delayed. |
+| delay.vars | array[] | optional | | | Rules which are matched before executing fault injection. See [lua-resty-expr](https://github.com/api7/lua-resty-expr) for a list of available expressions. |
+
+:::info IMPORTANT
+
+To use the `fault-injection` Plugin one of `abort` or `delay` must be specified.
-Note: One of `abort` and `delay` must be specified.
+:::
-The `vars` is a list of expression which is from the `lua-resty-expr`, which can flexibly implement the `and/or` relationship between rules. Example:
+:::tip
+
+`vars` can have expressions from [lua-resty-expr](https://github.com/api7/lua-resty-expr) and can flexibly implement AND/OR relationship between rules. For example:
```json
[
@@ -53,13 +69,13 @@ The `vars` is a list of expression which is from the `lua-resty-expr`, which can
]
```
-This means that the relationship between the first two expressions is `and`, and the relationship between the first two expressions and the third expression is `or`.
+This means that the relationship between the first two expressions is AND, and the relationship between them and the third expression is OR.
-## How To Enable
+:::
-### Enable the plugin
+## Enabling the Plugin
-1: enable the fault-injection plugin for a specific route and specify the abort attribute：
+You can enable the `fault-injection` Plugin on a specific Route as shown below:
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -82,23 +98,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```
-Test plugin：
-
-```shell
-$ curl http://127.0.0.1:9080/hello -i
-HTTP/1.1 200 OK
-Date: Mon, 13 Jan 2020 13:50:04 GMT
-Content-Type: text/plain
-Transfer-Encoding: chunked
-Connection: keep-alive
-Server: APISIX web server
-
-Fault Injection!
-```
-
-> http status is 200 and the response body is "Fault Injection! " indicate that the plugin is enabled.
-
-2: Enable the `fault-injection` plugin for a specific route and specify the `delay` attribute:
+Similarly, to enable a `delay` fault:
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -120,149 +120,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```
-Test plugin：
-
-```shell
-$ time curl http://127.0.0.1:9080/hello -i
-HTTP/1.1 200 OK
-Content-Type: application/octet-stream
-Content-Length: 6
-Connection: keep-alive
-Server: APISIX web server
-Date: Tue, 14 Jan 2020 14:30:54 GMT
-Last-Modified: Sat, 11 Jan 2020 12:46:21 GMT
-
-hello
-
-real 0m3.034s
-user 0m0.007s
-sys 0m0.010s
-```
-
-Example 3: Enable the `fault-injection` plugin for a specific route and specify the vars rule of the abort parameter.
-
-```shell
-curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
-{
- "plugins": {
- "fault-injection": {
- "abort": {
- "http_status": 403,
- "body": "Fault Injection!\n",
- "vars": [
- [
- [ "arg_name","==","jack" ]
- ]
- ]
- }
- }
- },
- "upstream": {
- "nodes": {
- "127.0.0.1:1980": 1
- },
- "type": "roundrobin"
- },
- "uri": "/hello"
-}'
-```
-
-Test plugin：
-
-1. The vars rule fails to match, and the request returns upstream response data:
-
-```shell
-$ curl "http://127.0.0.1:9080/hello?name=allen" -i
-HTTP/1.1 200 OK
-Content-Type: application/octet-stream
-Transfer-Encoding: chunked
-Connection: keep-alive
-Date: Wed, 20 Jan 2021 07:21:57 GMT
-Server: APISIX/2.2
-
-hello
-```
-
-2. The vars rule is successfully matched and fault injection is performed:
-
-```shell
-$ curl "http://127.0.0.1:9080/hello?name=jack" -i
-HTTP/1.1 403 Forbidden
-Date: Wed, 20 Jan 2021 07:23:37 GMT
-Content-Type: text/plain; charset=utf-8
-Transfer-Encoding: chunked
-Connection: keep-alive
-Server: APISIX/2.2
-
-Fault Injection!
-```
-
-Example 4: Enable the `fault-injection` plugin for a specific route and specify the vars rule for the delay parameter.
-
-```shell
-curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
-{
- "plugins": {
- "fault-injection": {
- "delay": {
- "duration": 2,
- "vars": [
- [
- [ "arg_name","==","jack" ]
- ]
- ]
- }
- }
- },
- "upstream": {
- "nodes": {
- "127.0.0.1:1980": 1
- },
- "type": "roundrobin"
- },
- "uri": "/hello"
-}'
-```
-
-Test plugin：
-
-1. The vars rule fails to match and the request is not delayed:
-
-```shell
-$ time curl "http://127.0.0.1:9080/hello?name=allen" -i
-HTTP/1.1 200 OK
-Content-Type: application/octet-stream
-Transfer-Encoding: chunked
-Connection: keep-alive
-Date: Wed, 20 Jan 2021 07:26:17 GMT
-Server: APISIX/2.2
-
-hello
-
-real 0m0.007s
-user 0m0.003s
-sys 0m0.003s
-```
-
-2. The vars rule is successfully matched, and the request is delayed for two seconds:
-
-```shell
-$ time curl "http://127.0.0.1:9080/hello?name=jack" -i
-HTTP/1.1 200 OK
-Content-Type: application/octet-stream
-Transfer-Encoding: chunked
-Connection: keep-alive
-Date: Wed, 20 Jan 2021 07:57:50 GMT
-Server: APISIX/2.2
-
-hello
-
-real 0m2.009s
-user 0m0.004s
-sys 0m0.004s
-```
-
-Example 5: Enable the `fault-injection` plugin for a specific route, and specify the vars rules for the abort and delay parameters.
+You can also enable the Plugin with both `abort` and `delay` which can have `vars` for matching:
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -298,81 +156,50 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f1
}'
```
-Test plugin：
+## Example usage
-1. The vars rules of abort and delay fail to match:
+Once you have enabled the Plugin as shown above, you can make a request to the configured Route:
```shell
-$ time curl "http://127.0.0.1:9080/hello?name=allen" -H 'age: 20' -i
-HTTP/1.1 200 OK
-Content-Type: application/octet-stream
-Transfer-Encoding: chunked
-Connection: keep-alive
-Date: Wed, 20 Jan 2021 08:01:43 GMT
-Server: APISIX/2.2
-
-hello
-
-real 0m0.007s
-user 0m0.003s
-sys 0m0.003s
+curl http://127.0.0.1:9080/hello -i
```
-2. The abort vars rule fails to match, no fault injection is performed, but the request is delayed:
-
-```shell
-$ time curl "http://127.0.0.1:9080/hello?name=allen" -H 'age: 18' -i
+```
HTTP/1.1 200 OK
-Content-Type: application/octet-stream
+Date: Mon, 13 Jan 2020 13:50:04 GMT
+Content-Type: text/plain
Transfer-Encoding: chunked
Connection: keep-alive
-Date: Wed, 20 Jan 2021 08:19:03 GMT
-Server: APISIX/2.2
-
-hello
+Server: APISIX web server
-real 0m2.009s
-user 0m0.001s
-sys 0m0.006s
+Fault Injection!
```
-3. The vars rule of delay fails to match, the request is not delayed, but fault injection is performed:
+And if we configure the `delay` fault:
```shell
-$ time curl "http://127.0.0.1:9080/hello?name=jack" -H 'age: 20' -i
-HTTP/1.1 403 Forbidden
-Date: Wed, 20 Jan 2021 08:20:18 GMT
-Content-Type: text/plain; charset=utf-8
-Transfer-Encoding: chunked
-Connection: keep-alive
-Server: APISIX/2.2
-
-Fault Injection!
-
-real 0m0.007s
-user 0m0.002s
-sys 0m0.004s
+time curl http://127.0.0.1:9080/hello -i
```
-4. The vars rules of abort and delay parameters match successfully, perform fault injection, and delay the request:
-
-```shell
-$ time curl "http://127.0.0.1:9080/hello?name=jack" -H 'age: 18' -i
-HTTP/1.1 403 Forbidden
-Date: Wed, 20 Jan 2021 08:21:17 GMT
-Content-Type: text/plain; charset=utf-8
-Transfer-Encoding: chunked
+```
+HTTP/1.1 200 OK
+Content-Type: application/octet-stream
+Content-Length: 6
Connection: keep-alive
-Server: APISIX/2.2
+Server: APISIX web server
+Date: Tue, 14 Jan 2020 14:30:54 GMT
+Last-Modified: Sat, 11 Jan 2020 12:46:21 GMT
-Fault Injection!
+hello
-real 0m2.006s
-user 0m0.001s
-sys 0m0.005s
+real 0m3.034s
+user 0m0.007s
+sys 0m0.010s
```
-Example 6: Enable the `fault-injection` plugin for a specific route, and specify the vars rule of the abort parameter (the relationship of `or`).
+### Fault injection with criteria matching
+
+You can enable the `fault-injection` Plugin with the `vars` attribute to set specific rules:
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -380,17 +207,13 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f1
"plugins": {
"fault-injection": {
"abort": {
- "http_status": 403,
- "body": "Fault Injection!\n",
- "vars": [
- [
- ["arg_name","==","jack"],
- ["arg_age","!","<",18]
- ],
- [
- ["http_apikey","==","apisix-key"]
+ "http_status": 403,
+ "body": "Fault Injection!\n",
+ "vars": [
+ [
+ [ "arg_name","==","jack" ]
+ ]
]
- ]
}
}
},
@@ -404,30 +227,34 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f1
}'
```
-Indicates that when the request parameters name and age satisfy both `name == "jack"` and `age >= 18`, fault injection is performed. Or when the request header apikey satisfies `apikey == "apisix-key"`, fault injection is performed.
+Now, we can test the Route. First, we test with a different `name` argument:
-Test plugin：
+```shell
+curl "http://127.0.0.1:9080/hello?name=allen" -i
+```
-1. The request parameter name and age match successfully, and the request header `apikey` is missing, and fault injection is performed:
+You will get the expected response without the fault injected:
-```shell
-$ curl "http://127.0.0.1:9080/hello?name=jack&age=19" -i
-HTTP/1.1 403 Forbidden
-Date: Fri, 22 Jan 2021 11:05:46 GMT
-Content-Type: text/plain; charset=utf-8
+```
+HTTP/1.1 200 OK
+Content-Type: application/octet-stream
Transfer-Encoding: chunked
Connection: keep-alive
+Date: Wed, 20 Jan 2021 07:21:57 GMT
Server: APISIX/2.2
-Fault Injection!
+hello
```
-2. The request header `apikey` is successfully matched, and the request parameters are missing, and fault injection is performed:
+Now if we set the `name` to match our configuration, the `fault-injection` Plugin is executed:
```shell
-$ curl http://127.0.0.1:9080/hello -H "apikey: apisix-key" -i
+curl "http://127.0.0.1:9080/hello?name=jack" -i
+```
+
+```
HTTP/1.1 403 Forbidden
-Date: Fri, 22 Jan 2021 11:08:34 GMT
+Date: Wed, 20 Jan 2021 07:23:37 GMT
Content-Type: text/plain; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
@@ -436,23 +263,9 @@ Server: APISIX/2.2
Fault Injection!
```
-3. Both request parameters and request headers fail to match, and fault injection is not performed:
-
-```shell
-$ curl http://127.0.0.1:9080/hello -i
-HTTP/1.1 200 OK
-Content-Type: application/octet-stream
-Transfer-Encoding: chunked
-Connection: keep-alive
-Date: Fri, 22 Jan 2021 11:11:17 GMT
-Server: APISIX/2.2
-
-hello
-```
-
## Disable Plugin
-Remove the corresponding JSON in the plugin configuration to disable the plugin immediately without restarting the service:
+To disable the `fault-injection` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect.
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -467,5 +280,3 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}
}'
```
-
-The plugin has been disabled now.
diff --git a/docs/en/latest/plugins/grpc-transcode.md b/docs/en/latest/plugins/grpc-transcode.md
index fc0a6af86..0ef065586 100644
--- a/docs/en/latest/plugins/grpc-transcode.md
+++ b/docs/en/latest/plugins/grpc-transcode.md
@@ -1,5 +1,11 @@
---
title: grpc-transcode
+keywords:
+ - APISIX
+ - Plugin
+ - gRPC Transcode
+ - grpc-transcode
+description: This document contains information about the Apache APISIX grpc-transcode Plugin.
---
<!--
@@ -23,17 +29,36 @@ title: grpc-transcode
## Description
-HTTP(s) -> APISIX -> gRPC server
+The `grpc-transcode` Plugin converts between HTTP and gRPC requests.
-### Proto
+APISIX takes in an HTTP request, transcodes it and forwards it to a gRPC service, gets the response and returns it back to the client in HTTP format.
-#### Attributes
+<!-- TODO: use an image here to explain the concept better -->
-* `content`: `.proto` or `.pb` file's content.
+## Attributes
-#### Add a proto
+| Name | Type | Required | Default | Description |
+| --------- | ------------------------------------------------------ | -------- | ------- | ------------------------------------ |
+| proto_id | string/integer | True | | id of the the proto content. |
+| service | string | True | | Name of the gRPC service. |
+| method | string | True | | Method name of the gRPC service. |
+| deadline | number | False | 0 | Deadline for the gRPC service in ms. |
+| pb_option | array[string([pb_option_def](#options-for-pb_option))] | False | | protobuf options. |
-Here's an example, adding a proto which `id` is `1`:
+### Options for pb_option
+
+| Type | Valid values |
+|-----------------|-------------------------------------------------------------------------------------------|
+| enum as result | `enum_as_name`, `enum_as_value` |
+| int64 as result | `int64_as_number`, `int64_as_string`, `int64_as_hexstring` |
+| default values | `auto_default_values`, `no_default_values`, `use_default_values`, `use_default_metatable` |
+| hooks | `enable_hooks`, `disable_hooks` |
+
+## Enabling the Plugin
+
+Before enabling the Plugin, you have to add the content of your `.proto` or `.pb` files to APISIX.
+
+You can use the `/admin/proto/id` endpoint and add the contents of the file to the `content` field:
```shell
curl http://127.0.0.1:9080/apisix/admin/proto/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -52,10 +77,9 @@ curl http://127.0.0.1:9080/apisix/admin/proto/1 -H 'X-API-KEY: edd1c9f034335f136
}'
```
-If your `.proto` file contains imports, or you want to combine multiple `.proto` files into a proto,
-you can use `.pb` file to create the proto.
+If your proto file contains imports, or if you want to combine multiple proto files, you can generate a `.pb` file and use it in APISIX.
-Assumed we have a `.proto` called `proto/helloworld.proto`, which imports another proto file:
+For example, if we have a file called `proto/helloworld.proto` which imports another proto file:
```proto
syntax = "proto3";
@@ -65,24 +89,25 @@ import "proto/import.proto";
...
```
-First of all, let's create a `.pb` file from `.proto` files:
+We first generate a `.pb` file from the proto files:
```shell
protoc --include_imports --descriptor_set_out=proto.pb proto/helloworld.proto
```
-The output binary file `proto.pb` will contain both `helloworld.proto` and `import.proto`.
+The output binary file, `proto.pb` will contain both `helloworld.proto` and `import.proto`.
-Then we can submit the content of `proto.pb` as the `content` field of the proto.
+We can now use the content of `proto.pb` in the `content` field of the API request.
-As the content is binary, we need to encode it in base64 first. Here we use a Python script to do it:
+As the content of the proto is binary, we encode it in `base64` using this Python script:
-```python
+```python title="upload_pb.py"
#!/usr/bin/env python
# coding: utf-8
-# save this file as upload_pb.py
+
import base64
import sys
+
# sudo pip install requests
import requests
@@ -92,7 +117,7 @@ if len(sys.argv) <= 1:
with open(sys.argv[1], 'rb') as f:
content = base64.b64encode(f.read())
id = sys.argv[2]
-api_key = "edd1c9f034335f136f87ad84b625c8f1" # Change it
+api_key = "edd1c9f034335f136f87ad84b625c8f1" # use a different API key
reqParam = {
"content": content,
@@ -104,31 +129,26 @@ print(resp.status_code)
print(resp.text)
```
-Create proto:
+This script will take in a `.pb` file and the `id` to create, encodes the content of the proto to `base64`, and calls the Admin API with this encoded content.
+
+To run the script:
```bash
chmod +x ./upload_pb.pb
-./upload_pb.py proto.pb 1
-# 200
-# {"node":{"value":{"create_time":1643879753,"update_time":1643883085,"content":"CmgKEnByb3RvL2ltcG9ydC5wcm90bxIDcGtnIhoKBFVzZXISEgoEbmFtZRgBIAEoCVIEbmFtZSIeCghSZXNwb25zZRISCgRib2R5GAEgASgJUgRib2R5QglaBy4vcHJvdG9iBnByb3RvMwq9AQoPcHJvdG8vc3JjLnByb3RvEgpoZWxsb3dvcmxkGhJwcm90by9pbXBvcnQucHJvdG8iPAoHUmVxdWVzdBIdCgR1c2VyGAEgASgLMgkucGtnLlVzZXJSBHVzZXISEgoEYm9keRgCIAEoCVIEYm9keTI5CgpUZXN0SW1wb3J0EisKA1J1bhITLmhlbGxvd29ybGQuUmVxdWVzdBoNLnBrZy5SZXNwb25zZSIAQglaBy4vcHJvdG9iBnByb3RvMw=="},"key":"\ [...]
```
-## Attribute List
-
-| Name | Type | Requirement | Default | Valid | Description |
-| --------- | ------------------------------------------------------------------------------ | ----------- | ------- | ----- | -------------------------------- |
-| proto_id | string/integer | required | | | `.proto` content id. |
-| service | string | required | | | the grpc service name. |
-| method | string | required | | | the method name of grpc service. |
-| deadline | number | optional | 0 | | deadline for grpc, ms |
-| pb_option | array[string([pb_option_def](#use-pb_option-option-of-grpc-transcode-plugin))] | optional | | | protobuf options |
+```
+./upload_pb.py proto.pb 1
+```
-## How To Enable
+Response:
-Here's an example, to enable the grpc-transcode plugin to specified route:
+```
+# 200
+# {"node":{"value":{"create_time":1643879753,"update_time":1643883085,"content":"CmgKEnByb3RvL2ltcG9ydC5wcm90bxIDcGtnIhoKBFVzZXISEgoEbmFtZRgBIAEoCVIEbmFtZSIeCghSZXNwb25zZRISCgRib2R5GAEgASgJUgRib2R5QglaBy4vcHJvdG9iBnByb3RvMwq9AQoPcHJvdG8vc3JjLnByb3RvEgpoZWxsb3dvcmxkGhJwcm90by9pbXBvcnQucHJvdG8iPAoHUmVxdWVzdBIdCgR1c2VyGAEgASgLMgkucGtnLlVzZXJSBHVzZXISEgoEYm9keRgCIAEoCVIEYm9keTI5CgpUZXN0SW1wb3J0EisKA1J1bhITLmhlbGxvd29ybGQuUmVxdWVzdBoNLnBrZy5SZXNwb25zZSIAQglaBy4vcHJvdG9iBnByb3RvMw=="},"key":"\ [...]
+```
-* attention: the `scheme` in the route's upstream must be `grpc`
-* the grpc server example：[grpc_server_example](https://github.com/api7/grpc_server_example)
+Now, we can enable the `grpc-transcode` Plugin to a specific Route:
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/111 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -152,15 +172,23 @@ curl http://127.0.0.1:9080/apisix/admin/routes/111 -H 'X-API-KEY: edd1c9f034335f
}'
```
-## Test Plugin
+:::note
+
+The Upstream service used here should be a gRPC service. Note that the `scheme` is set to `grpc`.
+
+You can use the [grpc_server_example](https://github.com/api7/grpc_server_example) for testing.
+
+:::
-The above configuration proxy:
+## Example usage
+
+Once you configured the Plugin as mentioned above, you can make a request to APISIX to get a response back from the gRPC service (through APISIX):
```shell
curl -i http://127.0.0.1:9080/grpctest?name=world
```
-response:
+Response:
```shell
HTTP/1.1 200 OK
@@ -174,30 +202,7 @@ Proxy-Connection: keep-alive
{"message":"Hello world"}
```
-This means that the proxying is working.
-
-## Use pb_option option of grpc-transcode plugin
-
-### option list
-
-* enum as result
- * enum_as_name
- * enum_as_value
-
-* int64 as result
- * int64_as_number
- * int64_as_string
- * int64_as_hexstring
-
-* default values option
- * auto_default_values
- * no_default_values
- * use_default_values
- * use_default_metatable
-
-* hooks option
- * enable_hooks
- * disable_hooks
+You can also configure the `pb_option` as shown below:
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/23 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -222,12 +227,13 @@ curl http://127.0.0.1:9080/apisix/admin/routes/23 -H 'X-API-KEY: edd1c9f034335f1
}'
```
-### Test pb_option
-
-Visit configured route：
+Now if you check the configured Route:
```shell
-$ curl -i "http://127.0.0.1:9080/zeebe/WorkflowInstanceCreate?bpmnProcessId=order-process&version=1&variables=\{\"orderId\":\"7\",\"ordervalue\":99\}"
+curl -i "http://127.0.0.1:9080/zeebe/WorkflowInstanceCreate?bpmnProcessId=order-process&version=1&variables=\{\"orderId\":\"7\",\"ordervalue\":99\}"
+```
+
+```
HTTP/1.1 200 OK
Date: Wed, 13 Nov 2019 03:38:27 GMT
Content-Type: application/json
@@ -242,12 +248,9 @@ Trailer: grpc-message
{"workflowKey":"#2251799813685260","workflowInstanceKey":"#2251799813688013","bpmnProcessId":"order-process","version":1}
```
-`"workflowKey":"#2251799813685260"` suggests pb_option configuration success.
-
## Disable Plugin
-Remove the corresponding json configuration in the plugin configuration to disable `grpc-transcode`.
-APISIX plugins are hot-reloaded, therefore no need to restart APISIX.
+To disable the `grpc-transcode` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect.
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/111 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
diff --git a/docs/en/latest/plugins/grpc-web.md b/docs/en/latest/plugins/grpc-web.md
index 417b36d22..b820c623d 100644
--- a/docs/en/latest/plugins/grpc-web.md
+++ b/docs/en/latest/plugins/grpc-web.md
@@ -1,5 +1,11 @@
---
title: grpc-web
+keywords:
+ - APISIX
+ - Plugin
+ - gRPC Web
+ - grpc-web
+description: This document contains information about the Apache APISIX grpc-web Plugin.
---
<!--
@@ -23,17 +29,13 @@ title: grpc-web
## Description
-The `grpc-web` plugin is a proxy plugin used to process [gRPC Web](https://github.com/grpc/grpc-web) client requests to `gRPC Server`.
+The `grpc-web` Plugin is a proxy Plugin that can process [gRPC Web](https://github.com/grpc/grpc-web) requests from JavaScript clients to a gRPC service.
-gRPC Web Client -> APISIX -> gRPC server
+## Enabling the Plugin
-## How To Enable
+You can enable the `grpc-web` Plugin on a specific Route as shown below:
-To enable the `gRPC Web` proxy plugin, routing must use the `Prefix matching` pattern (for example: `/*` or `/grpc/example/*`),
-Because the `gRPC Web` client will pass the `package name`, `service interface name`, `method name` and other information declared in the `proto` in the URI (for example: `/path/a6.RouteService/Insert`) ,
-When using `Absolute Match`, it will not be able to hit the plugin and extract the `proto` information.
-
-```bash
+```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri":"/grpc/web/*",
@@ -50,17 +52,31 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```
-## Test Plugin
+:::info IMPORTANT
+
+While using the `grpc-web` Plugin, always using a prefix matching pattern (`/*`, `/grpc/example/*`) for matching Routes. This is because the gRPC Web client passes the package name, the service interface name, the method name and other information in the proto in the URI. For example, `/path/a6.RouteService/Insert`.
+
+So, when absolute matching is used, the Plugin would not be hit and the information from the proto would not be extracted.
+
+:::
+
+## Example usage
+
+Refer to [gRPC-Web Client Runtime Library](https://www.npmjs.com/package/grpc-web) or [Apache APISIX gRPC Web Test Framework](https://github.com/apache/apisix/tree/master/t/plugin/grpc-web) to learn how to setup your web client.
+
+Once you have your gRPC Web client running, you can make a request to APISIX from the browser or through Node.js.
+
+:::note
+
+The supported request methods are `POST` and `OPTIONS`. See [CORS support](https://github.com/grpc/grpc-web/blob/master/doc/browser-features.md#cors-support).
+
+The supported `Content-Type` includes `application/grpc-web`, `application/grpc-web-text`, `application/grpc-web+proto`, and `application/grpc-web-text+proto`. See [Protocol differences vs gRPC over HTTP2](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-WEB.md#protocol-differences-vs-grpc-over-http2).
-- The request method only supports `POST` and `OPTIONS`, refer to: [CORS support](https://github.com/grpc/grpc-web/blob/master/doc/browser-features.md#cors-support).
-- The `Content-Type` supports `application/grpc-web`, `application/grpc-web-text`, `application/grpc-web+proto`, `application/grpc-web-text+proto`, refer to: [Protocol differences vs gRPC over HTTP2](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-WEB.md#protocol-differences-vs-grpc-over-http2).
-- Client deployment, refer to: [gRPC-Web Client Runtime Library](https://www.npmjs.com/package/grpc-web) or [Apache APISIX gRPC Web Test Framework](https://github.com/apache/apisix/tree/master/t/plugin/grpc-web).
-- After the `gRPC Web` client is deployed, you can initiate a `gRPC Web` proxy request to `APISIX` through `browser` or `node`.
+:::
## Disable Plugin
-Just delete the JSON configuration of `grpc-web` in the plugin configuration.
-The APISIX plug-in is hot-reloaded, so there is no need to restart APISIX.
+To disable the `grpc-web` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect.
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
diff --git a/docs/en/latest/plugins/mocking.md b/docs/en/latest/plugins/mocking.md
index e23f04715..3fcb2e2ad 100644
--- a/docs/en/latest/plugins/mocking.md
+++ b/docs/en/latest/plugins/mocking.md
@@ -1,5 +1,11 @@
---
title: mocking
+keywords:
+ - APISIX
+ - Plugin
+ - Mocking
+ - mocking
+description: This document contains information about the Apache APISIX mocking Plugin.
---
<!--
@@ -23,22 +29,29 @@ title: mocking
## Description
-Mock API plugin, When the plugin is bound, it returns random mock data in the specified format and is no longer forwarded to the upstreams.
+The `mocking` Plugin is used for mocking an API. When executed, it returns random mock data in the format specified and the request is not forwarded to the Upstream.
## Attributes
-| Name | Type | Requirement | Default | Valid | Description |
-| ------------- | -------| ----- | ----- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| delay | integer | optional | | | Delay return time, in seconds |
-| response_status | integer| optional | 200 | | response http status code |
-| content_type | string | optional | application/json | | response header Content-Type。 |
-| response_example| string | optional | | | response body |
-| response_schema | object | optional | | | The jsonschema object for the response is specified. This property takes effect if the `response_example` is not specified |
-| with_mock_header | boolean | optional | true | | Whether to return the response header: "x-mock-by: APISIX/{version}", returned by default, false does not return |
+| Name | Type | Required | Default | Description |
+|------------------|---------|----------|------------------|----------------------------------------------------------------------------------------|
+| delay | integer | False | | Response delay in seconds. |
+| response_status | integer | False | 200 | HTTP status code of the response. |
+| content_type | string | False | application/json | Header `Content-Type` of the response. |
+| response_example | string | False | | Body of the response. |
+| response_schema | object | False | | The JSON schema object for the response. Works when `response_example` is unspecified. |
+| with_mock_header | boolean | False | true | When set to `true`, adds a response header `x-mock-by: APISIX/{version}`. |
-Supported field types: `string`, `number`, `integer`, `boolean`, `object`, `array`
-Base data types (`string`, `number`, `integer`, `Boolean`) through configuration example attribute to specify the generated response value, random return not configured.
-Here is a `jsonschema` example:
+The JSON schema supports the following types in their fields:
+
+- `string`
+- `number`
+- `integer`
+- `boolean`
+- `object`
+- `array`
+
+Here is a JSON schema example:
```json
{
@@ -86,7 +99,7 @@ Here is a `jsonschema` example:
}
```
-Here are the return objects that might be generated by this `jsonschema`:
+This is the response generated by the Plugin from this JSON schema:
```json
{
@@ -108,9 +121,9 @@ Here are the return objects that might be generated by this `jsonschema`:
}
```
-## How To Enable
+## Enabling the Plugin
-Here, use `route` as an example (`service` is used in the same way) to enable the `mocking` plugin on the specified `route`.
+The example below configures the `mocking` Plugin for a specific Route:
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -176,9 +189,11 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```
-## Test Plugin
+## Example usage
-the `mocking` plugin is configured as follows:
+Once you have configured the Plugin as mentioned above, you can test the Route.
+
+The example used here uses this mocked response:
```json
{
@@ -190,10 +205,13 @@ the `mocking` plugin is configured as follows:
}
```
-Use curl to access:
+Now to test the Route:
```shell
-$ curl http://127.0.0.1:9080/test-mock -i
+curl http://127.0.0.1:9080/test-mock -i
+```
+
+```
HTTP/1.1 201 Created
...
Content-Type: application/json;charset=utf8
@@ -205,9 +223,7 @@ x-mock-by: APISIX/2.10.0
## Disable Plugin
-When you want to disable this plugin, it is very simple,
-you can delete the corresponding JSON configuration in the plugin configuration,
-no need to restart the service, it will take effect immediately:
+To disable the `mocking` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect.
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -222,5 +238,3 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}
}'
```
-
-This plugin has been disabled now. It works for other plugins.
diff --git a/docs/en/latest/plugins/proxy-rewrite.md b/docs/en/latest/plugins/proxy-rewrite.md
index aae0aff11..1d1a87a17 100644
--- a/docs/en/latest/plugins/proxy-rewrite.md
+++ b/docs/en/latest/plugins/proxy-rewrite.md
@@ -1,5 +1,11 @@
---
title: proxy-rewrite
+keywords:
+ - APISIX
+ - Plugin
+ - Proxy Rewrite
+ - proxy-rewrite
+description: This document contains information about the Apache APISIX proxy-rewrite Plugin.
---
<!--
@@ -23,22 +29,22 @@ title: proxy-rewrite
## Description
-The `proxy-rewrite` is an upstream proxy information rewriting plugin, which supports the rewriting of information such as `scheme`, `uri`, and `host`.
+The `proxy-rewrite` Plugin rewrites Upstream proxy information such as `scheme`, `uri` and `host`.
## Attributes
-| Name | Type | Requirement | Default | Valid | Description |
-| --------- | ------------- | ----------- | ------- | ----------------- | ------------------------------------------------------------ |
-| scheme | string | optional | "http" | ["http", "https"] | Upstream new `schema` forwarding protocol. This option is deprecated. It's recommended to set the proxy `scheme` in the Upstream object's `scheme` field instead.|
-| uri | string | optional | | | Upstream new `uri` forwarding address. Supports the use of [Nginx variables](https://nginx.org/en/docs/http/ngx_http_core_module.html). Variables must start with `$`, such as `$arg_name`. |
-| method | string | optional | | ["GET", "POST", "PUT", "HEAD", "DELETE", "OPTIONS","MKCOL", "COPY", "MOVE", "PROPFIND", "PROPFIND","LOCK", "UNLOCK", "PATCH", "TRACE"] | rewrite the HTTP method.|
-| regex_uri | array[string] | optional | | | Upstream new `uri` forwarding address. Use regular expression to match URL from client, when the match is successful, the URL template will be forwarded upstream. If the match is not successful, the URL from the client will be forwarded to the upstream. When `uri` and `regex_uri` are both exist, `uri` is used first. For example: [" ^/iresty/(.*)/(.*)/(.*)", "/$1-$2-$3"], the first element represents the matching re [...]
-| host | string | optional | | | Upstream new `host` forwarding address, example `iresty.com`. |
-| headers | object | optional | | | Forward to the new `headers` of the upstream, can set up multiple. If it exists, will rewrite the header, otherwise will add the header. You can set the corresponding value to an empty string to remove a header. Support the use of Nginx variables. Need to start with `$`, such as `client_addr: $remote_addr`: it means that the request header `client_addr` is the client IP. |
+| Name | Type | Required | Default | Valid values | Description [...]
+|-----------|---------------|----------|---------|----------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- [...]
+| scheme | string | False | "http" | ["http", "https"] | New upstream protocol scheme. This option is deprecated. Instead, it is recommended to set the `scheme` field in the Upstream. [...]
+| uri | string | False | | | New Upstream forwarding address. Value supports [Nginx variables](https://nginx.org/en/docs/http/ngx_http_core_module.html). For example, `$arg_name`. [...]
+| method | string | False | | ["GET", "POST", "PUT", "HEAD", "DELETE", "OPTIONS","MKCOL", "COPY", "MOVE", "PROPFIND", "PROPFIND","LOCK", "UNLOCK", "PATCH", "TRACE"] | Rewrites the HTTP method. [...]
+| regex_uri | array[string] | False | | | New upstream forwarding address. Regular expressions can be used to match the URL from client. If it matches, the URL template is forwarded to the Upstream otherwise, the URL from the client is forwarded. When both `uri` and `regex_uri` are configured, `uri` is used first. For example, `[" ^/iresty/(.*) [...]
+| host | string | False | | | New Upstream host address. [...]
+| headers | object | False | | | New Upstream headers. Headers are overwritten if they are already present otherwise, they are added to the present headers. To remove a header, set the header value to an empty string. The values in the header can contain Nginx variables like `$remote_addr` and `$client_addr`. [...]
-## How To Enable
+## Enabling the Plugin
-Here's an example, enable the `proxy-rewrite` plugin on the specified route:
+The example below enables the `proxy-rewrite` Plugin on a specific Route:
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -66,27 +72,23 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f1
}'
```
-## Test Plugin
+## Example usage
-Testing based on the above examples :
+Once you have enabled the Plugin as mentioned below, you can test the Route:
```shell
curl -X GET http://127.0.0.1:9080/test/index.html
```
-Send the request and see upstream `access.log', if the output information is consistent with the configuration :
+Once you send the request, you can check the Upstream `access.log` for its output:
```
127.0.0.1 - [26/Sep/2019:10:52:20 +0800] iresty.com GET /test/home.html HTTP/1.1 200 38 - curl/7.29.0 - 0.000 199 107
```
-This means that the `proxy-rewrite` plugin is in effect.
-
## Disable Plugin
-When you want to disable the `proxy-rewrite` plugin, it is very simple,
- you can delete the corresponding json configuration in the plugin configuration,
- no need to restart the service, it will take effect immediately :
+To disable the `proxy-rewrite` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect.
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -102,5 +104,3 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f1
}
}'
```
-
-The `proxy-rewrite` plugin has been disabled now. It works for other plugins.
diff --git a/docs/en/latest/plugins/response-rewrite.md b/docs/en/latest/plugins/response-rewrite.md
index a32ccfed3..80ce66e6e 100644
--- a/docs/en/latest/plugins/response-rewrite.md
+++ b/docs/en/latest/plugins/response-rewrite.md
@@ -1,5 +1,11 @@
---
title: response-rewrite
+keywords:
+ - APISIX
+ - Plugin
+ - Response Rewrite
+ - response-rewrite
+description: This document contains information about the Apache APISIX response-rewrite Plugin.
---
<!--
@@ -23,33 +29,43 @@ title: response-rewrite
## Description
-response rewrite plugin, rewrite the content returned by the upstream as well as Apache APISIX itself.
+The `response-rewrite` Plugin rewrites the content returned by the [Upstream](../terminology/upstream.md) and APISIX.
-**scenario**:
+This Plugin can be useful in these scenarios:
-1. can set `Access-Control-Allow-*` series field to support CORS(Cross-origin Resource Sharing).
-2. we can set customized `status_code` and `Location` field in header to achieve redirect, you can also use [redirect](redirect.md) plugin if you just want a redirection.
+- To set `Access-Control-Allow-*` field for supporting [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS).
+- To set custom `status_code` and `Location` fields in the header to redirect.
+
+:::tip
+
+You can also use the [redirect](./redirect.md) Plugin to setup redirects.
+
+:::
## Attributes
-| Name | Type | Requirement | Default | Valid | Description |
-|-----------------|---------|-------------|---------|-----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| status_code | integer | optional | | [200, 598] | New `status code` to client, keep the original response code by default. |
-| body | string | optional | | | New `body` to client, and the content-length will be reset too. |
-| body_base64 | boolean | optional | false | | Identify if `body` in configuration need base64 decoded before rewrite to client. |
-| headers | object | optional | | | Set the new `headers` for client, can set up multiple. If it exists already from upstream, will rewrite the header, otherwise will add the header. You can set the corresponding value to an empty string to remove a header. The value can contain Nginx variables in `$var` format, like `$remote_addr $balancer_ip`. |
-| vars | array[] | optional | | | A DSL to evaluate with the given ngx.var. See `vars` [lua-resty-expr](https://github.com/api7/lua-resty-expr#operator-list). if the `vars` is empty, then all rewrite operations will be executed unconditionally. |
-| filters | array[] | optional | | | A group of filters that modify response body by replacing one specified string by another. |
-| filters.regex | string | required | | | match pattern on response body. |
-| filters.scope | string | optional | "once" | "once","global" | substitution range, "once" substitutes the first match of `filters.regex` on response body, "global" does global substitution. |
-| filters.replace | string | required | | | substitution content. |
-| filters.options | string | optional | "jo" | | regex options, See [ngx.re.match](https://github.com/openresty/lua-nginx-module#ngxrematch). |
+| Name | Type | Required | Default | Valid values | Description |
+|-------------|---------|----------|---------|---------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| status_code | integer | False | | [200, 598] | New HTTP status code in the response. If unset, falls back to the original status code. |
+| body | string | False | | | New body of the response. The content-length would also be reset. |
+| body_base64 | boolean | False | false | | When set, the body of the request will be decoded before writing to the client. |
+| headers | object | False | | | New headers for the response. Headers are overwritten if they are present in the Upstream response otherwise, they are added to the Upstream headers. To remove a header, set the header value to an empty string. The values in the header can contain Nginx variables like `$remote_addr` and `$balancer_ip`. |
+| vars | array[] | False | | See [lua-resty-expr](https://github.com/api7/lua-resty-expr#operator-list) for a list of available operators. | Nginx variable expressions to conditionally execute the rewrite. The Plugin will be executed unconditionally if this value is empty. |
+| filters | array[] | False | | | List of filters that modify the response body by replacing one specified string with another. |
+| filters.regex | string | True | | | Regex pattern to match on the response body. |
+| filters.scope | string | False | "once" | "once","global" | Range to substitute. `once` substitutes the first match of `filters.regex` and `global` does global substitution. |
+| filters.replace | string | True | | | Content to substitute with. |
+| filters.options | string | False | "jo" | | Regex options. See [ngx.re.match](https://github.com/openresty/lua-nginx-module#ngxrematch). |
+
+:::note
+
+Only one of `body` or `filters` can be configured.
-Only one of `body`, `filters` can be specified.
+:::
-## How To Enable
+## Enabling the Plugin
-Here's an example, enable the `response-rewrite` plugin on the specified route:
+The example below enables the `response-rewrite` Plugin on a specific Route:
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -78,18 +94,19 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f1
}'
```
-## Test Plugin
+Here, `vars` is configured to run the Plugin only on responses with a 200 status code.
-Testing based on the above examples :
+## Example usage
+
+Once you have enabled the Plugin as shown above, you can make a request:
```shell
curl -X GET -i http://127.0.0.1:9080/test/index.html
```
-It will output like below,no matter what kind of content from upstream, the `vars` will make sure that only rewrite response that http status is `200`.
+The response will be as shown below no matter what the response is from the Upstream:
```
-
HTTP/1.1 200 OK
Date: Sat, 16 Nov 2019 09:15:12 GMT
Transfer-Encoding: chunked
@@ -101,13 +118,21 @@ X-Server-balancer_addr: 127.0.0.1:80
{"code":"ok","message":"new json body"}
```
-This means that the `response-rewrite` plugin is in effect.
+:::info IMPORTANT
+
+[ngx.exit](https://openresty-reference.readthedocs.io/en/latest/Lua_Nginx_API/#ngxexit) will interrupt the execution of a request and returns its status code to Nginx.
+
+However, if `ngx.exit` is executed during an access phase, it will only interrupt the request processing phase and the response phase will still continue to run.
+
+So, if you have configured the `response-rewrite` Plugin, it do a force overwrite of the response.
+
+
+
+:::
## Disable Plugin
-When you want to disable the `response-rewrite` plugin, it is very simple,
- you can delete the corresponding json configuration in the plugin configuration,
- no need to restart the service, it will take effect immediately:
+To disable the `response-rewrite` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect.
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -122,13 +147,3 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f1
}
}'
```
-
-The `response-rewrite` plugin has been disabled now. It works for other plugins.
-
-## Attention
-
-`ngx.exit` will interrupt the execution of the current request and return status code to Nginx.
-
-
-
-However, if you execute `ngx.exit` during the access phase, it only interrupts the request processing phase, and the response phase will still process it, i.e. if you configure the `response-rewrite` plugin, it will force overwriting of your response information (e.g. response status code).