Skip to content

Commit

Permalink
docs(plugin): refactor proxy-cache.md (apache#7858)
Browse files Browse the repository at this point in the history 
* docs: update proxy-cache.md

* update ref reviews
  • Loading branch information
@lunarwhite @Liu-Junlin
lunarwhite authored and Liu-Junlin committed Nov 4, 2022
1 parent d298fba commit ff8a7b1
Show file tree
Hide file tree
Showing 2 changed files with 77 additions and 223 deletions.
59 changes: 21 additions & 38 deletions docs/en/latest/plugins/proxy-cache.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,9 @@
title: proxy-cache
keywords:
- APISIX
- Plugin
- API Gateway
- Proxy Cache
- proxy-cache
description: This document contains information about the Apache APISIX proxy-cache Plugin.
description: This document contains information about the Apache APISIX proxy-cache Plugin, you can use it to cache the response from the Upstream.
---
<!--
#
Expand All @@ -28,7 +27,7 @@ description: This document contains information about the Apache APISIX proxy-ca

## Description

The `proxy-cache` Plugin can be used to cache the response from the Upstream. It can be used with other Plugins and currently supports disk-based caching.
The `proxy-cache` Plugin can be used to cache the response from the Upstream. It can be used with other Plugins and currently supports disk-based and memory-based caching.

The data to be cached can be filtered with response codes, request modes, or more complex methods using the `no_cache` and `cache_bypass` attributes.

Expand All @@ -37,25 +36,22 @@ The data to be cached can be filtered with response codes, request modes, or mor
| Name | Type | Required | Default | Valid values | Description |
|--------------------|----------------|----------|---------------------------|-------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| cache_strategy | string | False | disk | ["disk","memory"] | Specifies where the cached data should be stored. |
| cache_zone | string | False | disk_cache_one | | Specifies which cache area to use. Each cache area can be configured with different paths. Cache areas can be predefined in your configuration file (conf/config.yaml). If the specified cache area is inconsistent with the pre-defined cache area in your configuration file, the cache is invalid. |
| cache_zone | string | False | disk_cache_one | | Specifies which cache area to use. Each cache area can be configured with different paths. Cache areas can be predefined in your configuration file (`conf/config.yaml`). If the specified cache area is inconsistent with the pre-defined cache area in your configuration file, the cache is invalid. |
| cache_key | array[string] | False | ["$host", "$request_uri"] | | Key to use for caching. For example, `["$host", "$uri", "-cache-id"]`. |
| cache_bypass | array[string] | False | | | Conditions in which response from cache is bypassed. Whether to skip cache retrieval. If at least one value of the string parameters is not empty and is not equal to “0” then the response will not be taken from the cache. For example, `["$arg_bypass"]`. |
| cache_bypass | array[string] | False | | | Conditions in which response from cache is bypassed. Whether to skip cache retrieval. If at least one value of the string parameters is not empty and is not equal to `0` then the response will not be taken from the cache. For example, `["$arg_bypass"]`. |
| cache_method | array[string] | False | ["GET", "HEAD"] | ["GET", "POST", "HEAD"] | Request methods for which the response will be cached. |
| cache_http_status | array[integer] | False | [200, 301, 404] | [200, 599] | HTTP status codes of the Upstream response for which the response will be cached. |
| hide_cache_headers | boolean | False | false | | When set to true adds the `Expires` and `Cache-Control` headers to the client response. |
| cache_control | boolean | False | false | | When set to true, complies with Cache-Control behavior in the HTTP specification. Used only for memory strategy. |
| no_cache | array[string] | False | | | Conditions in which the response will not be cached. If at least one value of the string parameters is not empty and is not equal to “0” then the response will not be saved. |
| hide_cache_headers | boolean | False | false | | When set to `true` adds the `Expires` and `Cache-Control` headers to the client response. |
| cache_control | boolean | False | false | | When set to `true`, complies with Cache-Control behavior in the HTTP specification. Used only for memory strategy. |
| no_cache | array[string] | False | | | Conditions in which the response will not be cached. If at least one value of the string parameters is not empty and is not equal to `0` then the response will not be saved. |
| cache_ttl | integer | False | 300 seconds | | Time that a response is cached until it is deleted or refreshed. Comes in to effect when the `cache_control` attribute is not enabled or the proxied server does not return cache header. Used only for memory strategy. |

:::note

The cache expiration time cannot be configured dynamically. It can only be set by the Upstream response header `Expires` or `Cache-Control`. The default expiration time is 10s if there is no `Expires` or `Cache-Control` in the Upstream response header.

If the Upstream service is not available and APISIX returns a 502 or 504 status code, it will be cached for 10s.

Variables (start with `$`) can be specified in `cache_key`, `cache_bypass` and `no_cache`. It's worth mentioning that the variable value will be an empty string if it doesn't exist.

You can also combine a number of variables and strings (constants), by writing them into an array, eventually, variables will be parsed and stitched together with strings.
- The cache expiration time cannot be configured dynamically. It can only be set by the Upstream response header `Expires` or `Cache-Control`. The default expiration time is 10s if there is no `Expires` or `Cache-Control` in the Upstream response header.
- If the Upstream service is not available and APISIX returns a `502` or `504` status code, it will be cached for 10s.
- Variables (start with `$`) can be specified in `cache_key`, `cache_bypass` and `no_cache`. It's worth mentioning that the variable value will be an empty string if it doesn't exist.
- You can also combine a number of variables and strings (constants), by writing them into an array, eventually, variables will be parsed and stitched together with strings.

:::

Expand All @@ -77,7 +73,8 @@ proxy_cache:
You can enable the Plugin on a specific Route as shown below:
```shell
curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"plugins": {
"proxy-cache": {
Expand Down Expand Up @@ -111,12 +108,7 @@ curl http://127.0.0.1:9080/hello -i

```shell
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
Expand All @@ -130,37 +122,27 @@ curl http://127.0.0.1:9080/hello -i

```shell
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
```

If you set `"cache_zone": "invalid_disk_cache"` attribute to an invalid value (cache not configured in the your configuration file), then it will return a 404 response.
If you set `"cache_zone": "invalid_disk_cache"` attribute to an invalid value (cache not configured in the your configuration file), then it will return a `404` response.

:::tip

To clear the cached data, you can send a request with PURGE method:
To clear the cached data, you can send a request with `PURGE` method:

```shell
curl -i http://127.0.0.1:9080/hello -X PURGE
```

```shell
HTTP/1.1 200 OK
Date: Tue, 03 Mar 2020 11:17:35 GMT
Content-Type: text/plain
Transfer-Encoding: chunked
Connection: keep-alive
Server: APISIX web server
```

If the response code is 200, the deletion is successful. If the cached data is not found, a 404 response code will be returned.
If the response code is `200`, the deletion is successful. If the cached data is not found, a `404` response code will be returned.

:::

Expand All @@ -169,7 +151,8 @@ If the response code is 200, the deletion is successful. If the cached data is n
To disable the `proxy-cache` 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:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/hello",
"plugins": {},
Expand Down
Loading

0 comments on commit ff8a7b1

Please sign in to comment.