test/apisix
1
0
Fork 0
mirror of https://gitee.com/iresty/apisix.git synced 2024-12-08 06:58:20 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

feat(proxy-cache): the cache_zone field in the schema should be optional (#2776)

Browse Source
This commit is contained in:
Yuelin Zheng 2020-11-18 16:07:13 +08:00 committed by GitHub
parent 53e2d5387f
commit e4de3d5b9b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 349 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
apisix/plugins/proxy-cache.lua
View File

@ -34,7 +34,9 @@ local schema = {
properties = {
cache_zone = {
type = "string",
minLength = 1
minLength = 1,
maxLength = 100,
default = "disk_cache_one",
},
cache_key = {
type = "array",
@ -91,7 +93,6 @@ local schema = {
},
},
},
required = {"cache_zone"},
}
local _M = {

172
doc/plugins/proxy-cache.md
View File

@ -31,7 +31,7 @@ The proxy-cache plugin, which provides the ability to cache upstream response da
| Name | Type | Requirement | Default | Valid | Description |
| ------------------ | -------------- | ----------- | ------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| cache_zone | string | required | | | Specify which cache area to use, each cache area can be configured with different paths. In addition, cache areas can be predefined in conf/config.yaml file |
| cache_zone | string | optional | disk_cache_one | | Specify which cache area to use, each cache area can be configured with different paths. In addition, cache areas can be predefined in conf/config.yaml file. When the default value is not used, the specified cache area is inconsistent with the pre-defined cache area in the conf/config.yaml file, and the cache is invalid. |
| cache_key | array[string] | optional | ["$host", "$request_uri"] | | key of a cache, can use variables. For example: ["$host", "$uri", "-cache-id"] |
| cache_bypass | array[string] | optional | | | Whether to skip cache retrieval. That is, do not look for data in the cache. It can use variables, and note that cache data retrieval will be skipped when the value of this attribute is not empty or not '0'. For example: ["$arg_bypass"] |
| cache_method | array[string] | optional | ["GET", "HEAD"] | ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD","OPTIONS", "CONNECT", "TRACE"] | Decide whether to be cached according to the request method |
@ -43,10 +43,26 @@ Note:
1. The variable starts with $.
2. The attribute can use a combination of the variable and the string, but it needs to be written separately as an array, and the final values are stitched together after the variable is parsed.
Example configuration in the `conf/config.yaml` file:
```yaml
proxy_cache: # Proxy Caching configuration
cache_ttl: 10s # The default caching time if the upstream does not specify the cache time
zones: # The parameters of a cache
- name: disk_cache_one # The name of the cache, administrator can be specify
# which cache to use by name in the admin api
memory_size: 50m # The size of shared memory, it's used to store the cache index
disk_size: 1G # The size of disk, it's used to store the cache data
disk_path: "/tmp/disk_cache_one" # The path to store the cache data
cache_levels: "1:2" # The hierarchy levels of a cache
```
### Examples
#### Enable the plugin
Example 1: The cache_zone parameter defaults to `disk_cache_one`
1: enable the proxy-cache plugin for a specific route :
```shell
@ -54,13 +70,12 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f1
{
"plugins": {
"proxy-cache": {
"cache_zone": "disk_cache_one",
"cache_key": ["$uri", "-cache-id"],
"cache_bypass": ["$arg_bypass"],
"cache_method": ["GET"],
"cache_http_status": [200],
"hide_cache_headers": true,
"no_cache": ["$arg_test"]
"cache_key": ["$uri", "-cache-id"],
"cache_bypass": ["$arg_bypass"],
"cache_method": ["GET"],
"cache_http_status": [200],
"hide_cache_headers": true,
"no_cache": ["$arg_test"]
}
},
"upstream": {
@ -88,10 +103,10 @@ Apisix-Cache-Status: MISS
hello
```
> http status is '200' and the response header contains 'Apisix-Cache-Status' to indicate that the plug-in is enabled.
2: Verify that the file is cached, request the address above again:
> http status is '200' and the response header contains 'Apisix-Cache-Status' to indicate that the plugin is enabled.
2: Verify that the data is cached, request the address above again:
```shell
$ curl http://127.0.0.1:9080/hello -i
@ -107,10 +122,120 @@ Apisix-Cache-Status: HIT
hello
```
> Response header Apisix-Cache-Status has changed to HIT, indicating that the file has been cached.
Example 2: Customize the cache_zone parameter to `disk_cache_two`
3: How to clean up the cached file, simply specify the request method as PURGE:
1. Specify the cache area and other information in the `conf/config.yaml` file:
```yaml
proxy_cache:
cache_ttl: 10s
zones:
- name: disk_cache_two
memory_size: 50m
disk_size: 1G
disk_path: "/tmp/disk_cache_one"
cache_levels: "1:2"
```
2. Enable the `proxy-cache` 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 '
{
"plugins": {
"proxy-cache": {
"cache_zone": "disk_cache_two",
"cache_key": ["$uri", "-cache-id"],
"cache_bypass": ["$arg_bypass"],
"cache_method": ["GET"],
"cache_http_status": [200],
"hide_cache_headers": true,
"no_cache": ["$arg_test"]
}
},
"upstream": {
"nodes": {
"127.0.0.1:1999": 1
},
"type": "roundrobin"
},
"uri": "/hello"
}'
```
Test Plugin:
```shell
$ 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, 03 Mar 2020 10:45:36 GMT
Last-Modified: Tue, 03 Mar 2020 10:36:38 GMT
Apisix-Cache-Status: MISS
hello
```
> http status is '200' and the response header contains 'Apisix-Cache-Status' to indicate that the plug-in is enabled.
3. Verify that the data is cached and request the above address again:
```shell
$ 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, 03 Mar 2020 11:14:46 GMT
Last-Modified: Thu, 20 Feb 2020 14:21:41 GMT
Apisix-Cache-Status: HIT
hello
```
> The response header `Apisix-Cache-Status` value has changed to HIT, indicating that the data has been cached
Example 3: Specifying cache_zone as `invalid_disk_cache` is inconsistent with the cache area `disk_cache_one` specified in the `conf/config.yaml` file.
```shell
$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"plugins": {
"proxy-cache": {
"cache_zone": "invalid_disk_cache",
"cache_key": ["$uri", "-cache-id"],
"cache_bypass": ["$arg_bypass"],
"cache_method": ["GET"],
"cache_http_status": [200],
"hide_cache_headers": true,
"no_cache": ["$arg_test"]
}
},
"upstream": {
"nodes": {
"127.0.0.1:1999": 1
},
"type": "roundrobin"
},
"uri": "/hello"
}'
```
```json
{"error_msg":"failed to check the configuration of plugin proxy-cache err: cache_zone invalid_disk_cache not found"}
```
In response to an error message, the plug-in configuration is invalid.
#### Clear cached data
How to clean the cached data only needs to specify the requested method as PURGE.
Test Plugin:
```shell
$ curl -i http://127.0.0.1:9080/hello -X PURGE
@ -122,13 +247,32 @@ Connection: keep-alive
Server: APISIX web server
```
> The response status is 200, indicating that the file was deleted successfully. And return 404 if the file is not found.
> If the response code is 200, it means the deletion is successful. If the cached data is not found, 404 will be returned.
Request again, the cached data is not found and return 404:
```shell
$ curl -i http://127.0.0.1:9080/hello -X PURGE
HTTP/1.1 404 Not Found
Date: Wed, 18 Nov 2020 05:46:34 GMT
Content-Type: text/plain
Transfer-Encoding: chunked
Connection: keep-alive
Server: APISIX web server
<html>
<head><title>404 Not Found</title></head>
<body>
<center><h1>404 Not Found</h1></center>
<hr><center>openresty</center>
</body>
</html>
```
## Disable Plugin
Remove the corresponding JSON in the plugin configuration to disable the plugin immediately without restarting the service:
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{

176
doc/zh-cn/plugins/proxy-cache.md
View File

@ -31,7 +31,7 @@
| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
| ------------------ | -------------- | ------ | ------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| cache_zone | string | 必须 | | | 指定使用哪个缓存区域，不同的缓存区域可以配置不同的路径，在conf/config.yaml文件中可以预定义使用的缓存区域 |
| cache_zone | string | 可选 | disk_cache_one | | 指定使用哪个缓存区域，不同的缓存区域可以配置不同的路径，在 conf/config.yaml 文件中可以预定义使用的缓存区域。当不使用默认值时，指定的缓存区域与 conf/config.yaml 文件中预定义的缓存区域不一致，缓存无效。 |
| cache_key | array[string] | 可选 | ["$host", "$request_uri"] | | 缓存key，可以使用变量。例如：["$host", "$uri", "-cache-id"] |
| cache_bypass | array[string] | 可选 | | | 是否跳过缓存检索，即不在缓存中查找数据，可以使用变量，需要注意当此参数的值不为空或非'0'时将会跳过缓存的检索。例如：["$arg_bypass"] |
| cache_method | array[string] | 可选 | ["GET", "HEAD"] | ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD","OPTIONS", "CONNECT", "TRACE"] | 根据请求method决定是否需要缓存 |
@ -39,27 +39,40 @@
| hide_cache_headers | boolean | 可选 | false | | 是否将 Expires 和 Cache-Control 响应头返回给客户端 |
| no_cache | array[string] | 可选 | | | 是否缓存数据，可以使用变量，需要注意当此参数的值不为空或非'0'时将不会缓存数据 |
注：变量以$开头，也可以使用变量和字符串的结合，但是需要以数组的形式分开写，最终变量被解析后会和字符串拼接在一起。
在 `conf/config.yaml` 文件中的配置示例:
```yaml
proxy_cache: # 代理缓存配置
cache_ttl: 10s # 如果上游未指定缓存时间，则为默认缓存时间
zones: # 缓存的参数
- name: disk_cache_one # 缓存名称(缓存区域)，管理员可以通过admin api中的 cache_zone 字段指定要使用的缓存区域
memory_size: 50m # 共享内存的大小，用于存储缓存索引
disk_size: 1G # 磁盘大小，用于存储缓存数据
disk_path: "/tmp/disk_cache_one" # 存储缓存数据的路径
cache_levels: "1:2" # 缓存的层次结构级别
```
### 示例
#### 启用插件
示例1：为特定路由启用 `proxy-cache` 插件：
示例一：cache_zone 参数默认为 `disk_cache_one`
1、为特定路由启用 `proxy-cache` 插件：
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"plugins": {
"proxy-cache": {
"cache_zone": "disk_cache_one",
"cache_key": ["$uri", "-cache-id"],
"cache_bypass": ["$arg_bypass"],
"cache_method": ["GET"],
"cache_http_status": [200],
"hide_cache_headers": true,
"no_cache": ["$arg_test"]
"cache_key": ["$uri", "-cache-id"],
"cache_bypass": ["$arg_bypass"],
"cache_method": ["GET"],
"cache_http_status": [200],
"hide_cache_headers": true,
"no_cache": ["$arg_test"]
}
},
"upstream": {
@ -88,11 +101,9 @@ Apisix-Cache-Status: MISS
hello
```
> http status 返回`200`并且响应头中包含`Apisix-Cache-Status`，表示该插件已启用。
> http status 返回`200`并且响应头中包含 `Apisix-Cache-Status`，表示该插件已启用。
示例2：验证文件是否被缓存，再次请求上边的地址：
测试：
2、验证数据是否被缓存，再次请求上边的地址：
```shell
$ curl http://127.0.0.1:9080/hello -i
@ -108,9 +119,120 @@ Apisix-Cache-Status: HIT
hello
```
> 响应头 Apisix-Cache-Status 值变为了 HIT，说明文件已经被缓存
> 响应头 Apisix-Cache-Status 值变为了 HIT，说明数据已经被缓存
示例3：如何清理缓存的文件，只需要指定请求的 method 为 PURGE：
示例二：自定义 cache_zone 参数为 `disk_cache_two`
1、在 `conf/config.yaml` 文件中的指定缓存区域等信息:
```yaml
proxy_cache:
cache_ttl: 10s
zones:
- name: disk_cache_two
memory_size: 50m
disk_size: 1G
disk_path: "/tmp/disk_cache_one"
cache_levels: "1:2"
```
2、为特定路由启用 `proxy-cache` 插件：
```shell
$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"plugins": {
"proxy-cache": {
"cache_zone": "disk_cache_two",
"cache_key": ["$uri", "-cache-id"],
"cache_bypass": ["$arg_bypass"],
"cache_method": ["GET"],
"cache_http_status": [200],
"hide_cache_headers": true,
"no_cache": ["$arg_test"]
}
},
"upstream": {
"nodes": {
"127.0.0.1:1999": 1
},
"type": "roundrobin"
},
"uri": "/hello"
}'
```
测试：
```shell
$ 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, 03 Mar 2020 10:45:36 GMT
Last-Modified: Tue, 03 Mar 2020 10:36:38 GMT
Apisix-Cache-Status: MISS
hello
```
> http status 返回`200`并且响应头中包含 `Apisix-Cache-Status`，表示该插件已启用。
3、验证数据是否被缓存，再次请求上面的地址：
```shell
$ 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, 03 Mar 2020 11:14:46 GMT
Last-Modified: Thu, 20 Feb 2020 14:21:41 GMT
Apisix-Cache-Status: HIT
hello
```
> 响应头 `Apisix-Cache-Status` 值变为了 HIT，说明数据已经被缓存
示例3：指定 cache_zone 为 `invalid_disk_cache` 与 `conf/config.yaml` 文件中指定的缓存区域 `disk_cache_one` 不一致。
```shell
$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"plugins": {
"proxy-cache": {
"cache_zone": "invalid_disk_cache",
"cache_key": ["$uri", "-cache-id"],
"cache_bypass": ["$arg_bypass"],
"cache_method": ["GET"],
"cache_http_status": [200],
"hide_cache_headers": true,
"no_cache": ["$arg_test"]
}
},
"upstream": {
"nodes": {
"127.0.0.1:1999": 1
},
"type": "roundrobin"
},
"uri": "/hello"
}'
```
```json
{"error_msg":"failed to check the configuration of plugin proxy-cache err: cache_zone invalid_disk_cache not found"}
```
响应错误信息，表示插件配置无效。
#### 清除缓存数据
如何清理缓存的数据，只需要指定请求的 method 为 PURGE。
测试：
@ -124,7 +246,27 @@ Connection: keep-alive
Server: APISIX web server
```
> 响应码为200即表示删除成功，如果文件未找到将返回404
> 响应码为200即表示删除成功，如果缓存的数据未找到将返回404。
再次请求，缓存数据未找到返回404：
```shell
$ curl -i http://127.0.0.1:9080/hello -X PURGE
HTTP/1.1 404 Not Found
Date: Wed, 18 Nov 2020 05:46:34 GMT
Content-Type: text/plain
Transfer-Encoding: chunked
Connection: keep-alive
Server: APISIX web server
<html>
<head><title>404 Not Found</title></head>
<body>
<center><h1>404 Not Found</h1></center>
<hr><center>openresty</center>
</body>
</html>
```
#### 禁用插件

33
t/plugin/proxy-cache.t
View File

@ -59,7 +59,7 @@ run_tests;
__DATA__
=== TEST 1: sanity check (missing required field)
=== TEST 1: sanity check (missing cache_zone field, the default value is disk_cache_one)
--- config
location /t {
content_by_lua_block {
@ -83,6 +83,32 @@ __DATA__
"type": "roundrobin"
},
"uri": "/hello"
}]],
[[{
"node": {
"value": {
"uri": "/hello",
"upstream": {
"nodes": {
"127.0.0.1:1980": 1
},
"type": "roundrobin"
},
"plugins": {
"proxy-cache":{
"cache_zone":"disk_cache_one",
"hide_cache_headers":true,
"cache_bypass":["$arg_bypass"],
"cache_key":["$host","$request_uri"],
"no_cache":["$arg_no_cache"],
"cache_http_status":[200],
"cache_method":["GET"]
}
}
},
"key": "/apisix/routes/1"
},
"action": "set"
}]]
)
@ -94,9 +120,8 @@ __DATA__
}
--- request
GET /t
--- error_code: 400
--- response_body eval
qr/failed to check the configuration of plugin proxy-cache/
--- response_body
passed
--- no_error_log
[error]