Yilialinn commented on code in PR #11910: URL: https://github.com/apache/apisix/pull/11910#discussion_r1972787242
########## docs/en/latest/plugins/proxy-cache.md: ########## @@ -91,118 +94,286 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"/ ::: +### Cache Data on Disk + +On-disk caching strategy offers the advantages of data persistency when system restarts and having larger storage capacity compared to in-memory cache. It is suitable for applications that prioritize durability and can tolerate slightly larger cache access latency. + +The following example demonstrates how you can use `proxy-cache` Plugin on a Route to cache data on disk. + +When using the on-disk caching strategy, the cache TTL is determined by value from the response header `Expires` or `Cache-Control`. If none of these headers is present or if APISIX returns `502 Bad Gateway` or `504 Gateway Timeout` due to unavailable upstreams, the cache TTL defaults to the value configured in the [configuration files](#static-configuration). + +Create a Route with the `proxy-cache` Plugin to cache data on disk: + ```shell -curl http://127.0.0.1:9180/apisix/admin/routes/1 \ --H "X-API-KEY: $admin_key" -X PUT -d ' -{ - "uri": "/ip", +curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "proxy-cache-route", + "uri": "/anything", "plugins": { - "proxy-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"] - } + "proxy-cache": { + "cache_strategy": "disk" + } }, "upstream": { - "nodes": { - "httpbin.org": 1 - }, - "type": "roundrobin" + "type": "roundrobin", + "nodes": { + "httpbin.org": 1 + } } -}' + }' ``` -### Use memory-based caching +Send a request to the route: Review Comment: ```suggestion Send a request to the Route: ``` ########## docs/en/latest/plugins/proxy-cache.md: ########## @@ -25,64 +26,66 @@ description: This document contains information about the Apache APISIX proxy-ca # --> +<head> + <link rel="canonical" href="https://docs.api7.ai/hub/proxy-cache"; /> +</head> + ## 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 and memory-based caching. +The `proxy-cache` Plugin provides the capability to cache responses based on a cache key. The Plugin supports both disk-based and memory-based caching options to cache for [GET](https://anything.org/learn/serving-over-http/#get-request), [POST](https://anything.org/learn/serving-over-http/#post-request), and [HEAD](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD) requests. -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. +Responses can be conditionally cached based on request HTTP methods, response status codes, request header values, and more. ## Attributes | 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_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_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`, hide the `Expires` and `Cache-Control` response headers. | -| 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. | +| cache_strategy | string | False | disk | ["disk","memory"] | Caching strategy. Cache on disk or in memory. | +| cache_zone | string | False | disk_cache_one | | Cache zone used with the caching strategy. The value should match one of the cache zones defined in the [configuration files](#static-configurations) and should correspond to the caching strategy. For example, when using the in-memory caching strategy, you should use an in-memory cache zone. | +| cache_key | array[string] | False | ["$host", "$request_uri"] | | Key to use for caching. Support [Nginx variables](https://nginx.org/en/docs/varindex.html) and constant strings in values. Variables should be prefixed with a `$` sign. | +| cache_bypass | array[string] | False | | | One or more parameters to parse value from, such that if any of the values is not empty and is not equal to `0`, response will not be retrieved from cache. Support [Nginx variables](https://nginx.org/en/docs/varindex.html) and constant strings in values. Variables should be prefixed with a `$` sign. | +| cache_method | array[string] | False | ["GET", "HEAD"] | ["GET", "POST", "HEAD"] | Request methods of which the response should be cached. | +| cache_http_status | array[integer] | False | [200, 301, 404] | [200, 599] | Response HTTP status codes of which the response should be cached. | +| hide_cache_headers | boolean | False | false | | If true, hide `Expires` and `Cache-Control` response headers. | +| cache_control | boolean | False | false | | If true, comply with `Cache-Control` behavior in the HTTP specification. Only valid for in-memory strategy. | +| no_cache | array[string] | False | | | One or more parameters to parse value from, such that if any of the values is not empty and is not equal to `0`, response will not be cached. Support [Nginx variables](https://nginx.org/en/docs/varindex.html) and constant strings in values. Variables should be prefixed with a `$` sign. | +| cache_ttl | integer | False | 300 | >=1 | Cache time to live (TTL) in seconds when caching in memory. To adjust the TTL when caching on disk, update `cache_ttl` in the [configuration files](#static-configurations). The TTL value is evaluated in conjunction with the values in the response headers [`Cache-Control`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) and [`Expires`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Expires) received from the Upstream service. | Review Comment: Shall we capitalize "s" in "service(s)"? ########## docs/en/latest/plugins/proxy-cache.md: ########## @@ -91,118 +94,286 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"/ ::: +### Cache Data on Disk + +On-disk caching strategy offers the advantages of data persistency when system restarts and having larger storage capacity compared to in-memory cache. It is suitable for applications that prioritize durability and can tolerate slightly larger cache access latency. + +The following example demonstrates how you can use `proxy-cache` Plugin on a Route to cache data on disk. + +When using the on-disk caching strategy, the cache TTL is determined by value from the response header `Expires` or `Cache-Control`. If none of these headers is present or if APISIX returns `502 Bad Gateway` or `504 Gateway Timeout` due to unavailable upstreams, the cache TTL defaults to the value configured in the [configuration files](#static-configuration). + +Create a Route with the `proxy-cache` Plugin to cache data on disk: + ```shell -curl http://127.0.0.1:9180/apisix/admin/routes/1 \ --H "X-API-KEY: $admin_key" -X PUT -d ' -{ - "uri": "/ip", +curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "proxy-cache-route", + "uri": "/anything", "plugins": { - "proxy-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"] - } + "proxy-cache": { + "cache_strategy": "disk" + } }, "upstream": { - "nodes": { - "httpbin.org": 1 - }, - "type": "roundrobin" + "type": "roundrobin", + "nodes": { + "httpbin.org": 1 + } } -}' + }' ``` -### Use memory-based caching +Send a request to the route: -You can enable the Plugin on a Route with in-memory `cache_strategy` and a corresponding in-memory `cache_zone` as shown below: +```shell +curl -i "http://127.0.0.1:9080/anything"; +``` + +You should see an `HTTP/1.1 200 OK` response with the following header, showing the Plugin is successfully enabled: + +```text +Apisix-Cache-Status: MISS +``` + +As there is no cache available before the first response, `Apisix-Cache-Status: MISS` is shown. + +Send the same request again within the cache TTL window. You should see an `HTTP/1.1 200 OK` response with the following headers, showing the cache is hit: + +```text +Apisix-Cache-Status: HIT +``` + +Wait for the cache to expire after the TTL and send the same request again. You should see an `HTTP/1.1 200 OK` response with the following headers, showing the cache has expired: + +```text +Apisix-Cache-Status: EXPIRED +``` + +### Cache Data in Memory + +In-memory caching strategy offers the advantage of low-latency access to the cached data, as retrieving data from RAM is faster than retrieving data from disk storage. It also works well for storing temporary data that does not need to be persisted long-term, allowing for efficient caching of frequently changing data. + +The following example demonstrates how you can use `proxy-cache` Plugin on a Route to cache data in memory. + +Create a Route with `proxy-cache` and configure it to use memory-based caching: ```shell -curl http://127.0.0.1:9180/apisix/admin/routes/1 \ --H "X-API-KEY: $admin_key" -X PUT -d ' -{ - "uri": "/ip", +curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "proxy-cache-route", + "uri": "/anything", "plugins": { - "proxy-cache": { - "cache_strategy": "memory", - "cache_zone": "memory_cache", - "cache_ttl": 10 - } + "proxy-cache": { + "cache_strategy": "memory", + "cache_zone": "memory_cache", + "cache_ttl": 10 + } }, "upstream": { - "nodes": { - "httpbin.org": 1 - }, - "type": "roundrobin" + "type": "roundrobin", + "nodes": { + "httpbin.org": 1 + } } -}' + }' ``` -## Example usage - -Once you have configured the Plugin as shown above, you can make an initial request: +Send a request to the route: Review Comment: ```suggestion Send a request to the Route: ``` ########## docs/zh/latest/plugins/proxy-cache.md: ########## @@ -28,57 +28,57 @@ description: 本文介绍了 Apache APISIX proxy-cache 插件的相关操作， ## 描述 -`proxy-cache` 插件提供缓存后端响应数据的能力，它可以和其他插件一起使用。该插件支持基于磁盘和内存的缓存。目前可以根据响应码和请求模式来指定需要缓存的数据，也可以通过 `no_cache` 和 `cache_bypass`属性配置更复杂的缓存策略。 +`proxy-cache` 插件提供了根据缓存键缓存响应的功能。该插件支持基于磁盘和基于内存的缓存选项，用于缓存 [GET](https://anything.org/learn/serving-over-http/#get-request)、[POST](https://anything.org/learn/serving-over-http/#post-request) 和 [HEAD](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD) 请求。 + +可以根据请求 HTTP 方法、响应状态代码、请求标头值等有条件地缓存响应。 ## 属性 | 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | | ------------------ | -------------- | ------ | ------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -| cache_strategy | string | 否 | disk | ["disk","memory"] | 缓存策略，指定缓存数据存储在磁盘还是内存中。 | -| cache_zone | string | 否 | disk_cache_one | | 指定使用哪个缓存区域，不同的缓存区域可以配置不同的路径，在 `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", "HEAD"] | 根据请求 method 决定是否需要缓存。 | -| cache_http_status | array[integer] | 否 | [200, 301, 404] | [200, 599] | 根据 HTTP 响应码决定是否需要缓存。 | -| hide_cache_headers | boolean | 否 | false | | 当设置为 `true` 时不将 `Expires` 和 `Cache-Control` 响应头返回给客户端。 | -| cache_control | boolean | 否 | false | | 当设置为 `true` 时遵守 HTTP 协议规范中的 `Cache-Control` 的行为。 | -| no_cache | array[string] | 否 | | | 当此参数的值不为空或非 `0` 时将不会缓存数据，可以使用变量。 | -| cache_ttl | integer | 否 | 300 秒 | | 当选项 `cache_control` 未开启或开启以后服务端没有返回缓存控制头时，提供的默认缓存时间。 | - -:::note 注意 - -- 对于基于磁盘的缓存，不能动态配置缓存的过期时间，只能通过后端服务响应头 `Expires` 或 `Cache-Control` 来设置过期时间，当后端响应头中没有 `Expires` 或 `Cache-Control` 时，默认缓存时间为 10 秒钟 -- 当上游服务不可用时，APISIX 将返回 `502` 或 `504` HTTP 状态码，默认缓存时间为 10 秒钟； -- 变量以 `$` 开头，不存在时等价于空字符串。也可以使用变量和字符串的结合，但是需要以数组的形式分开写，最终变量被解析后会和字符串拼接在一起。 +| cache_strategy | string | 否 | disk | ["disk","memory"] | 缓存策略。缓存在磁盘还是内存中。 | +| cache_zone | string | 否 | disk_cache_one | | 与缓存策略一起使用的缓存区域。该值应与[配置文件](#static-configurations)中定义的缓存区域之一匹配，并与缓存策略相对应。例如，当使用内存缓存策略时，应该使用内存缓存区域。 | +| cache_key | array[string] | 否 | ["$host", "$request_uri"] | | 用于缓存的键。支持[Nginx 变量](https://nginx.org/en/docs/varindex.html)和值中的常量字符串。变量应该以 `$` 符号为前缀。 | +| cache_bypass | array[string] | 否 | | |一个或多个用于解析值的参数，如果任何值不为空且不等于 `0`，则不会从缓存中检索响应。支持值中的 [Nginx variables](https://nginx.org/en/docs/varindex.html) 和常量字符串。变量应该以 `$` 符号为前缀。| +| cache_method | array[string] | 否 | ["GET", "HEAD"] | ["GET", "POST", "HEAD"] | 应缓存响应的请求方法。| +| cache_http_status | array[integer] | 否 | [200, 301, 404] | [200, 599] | 应缓存响应的响应 HTTP 状态代码。| +| hide_cache_headers | boolean | 否 | false | | 如果为 true，则隐藏 `Expires` 和 `Cache-Control` 响应标头。| +| cache_control | boolean | 否 | false | | 如果为 true，则遵守 HTTP 规范中的 `Cache-Control` 行为。仅对内存中策略有效。 | +| no_cache | array[string] | 否 | | | 用于解析值的一个或多个参数，如果任何值不为空且不等于 `0`，则不会缓存响应。支持 [Nginx variables](https://nginx.org/en/docs/varindex.html) 和值中的常量字符串。变量应以 `$` 符号为前缀。 | Review Comment: ```suggestion | cache_key | array[string] | 否 | ["$host", "$request_uri"] | | 用于缓存的键。支持[NGINX 变量](https://nginx.org/en/docs/varindex.html)和值中的常量字符串。变量应该以 `$` 符号为前缀。 | | cache_bypass | array[string] | 否 | | |一个或多个用于解析值的参数，如果任何值不为空且不等于 `0`，则不会从缓存中检索响应。支持值中的 [NGINX 变量](https://nginx.org/en/docs/varindex.html) 和常量字符串。变量应该以 `$` 符号为前缀。| | cache_method | array[string] | 否 | ["GET", "HEAD"] | ["GET", "POST", "HEAD"] | 应缓存响应的请求方法。| | cache_http_status | array[integer] | 否 | [200, 301, 404] | [200, 599] | 应缓存响应的响应 HTTP 状态代码。| | hide_cache_headers | boolean | 否 | false | | 如果为 true，则隐藏 `Expires` 和 `Cache-Control` 响应标头。| | cache_control | boolean | 否 | false | | 如果为 true，则遵守 HTTP 规范中的 `Cache-Control` 行为。仅对内存中策略有效。 | | no_cache | array[string] | 否 | | | 用于解析值的一个或多个参数，如果任何值不为空且不等于 `0`，则不会缓存响应。支持 [NGINX 变量](https://nginx.org/en/docs/varindex.html) 和值中的常量字符串。变量应以 `$` 符号为前缀。 | ``` ########## docs/en/latest/plugins/proxy-cache.md: ########## @@ -91,118 +94,286 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"/ ::: +### Cache Data on Disk + +On-disk caching strategy offers the advantages of data persistency when system restarts and having larger storage capacity compared to in-memory cache. It is suitable for applications that prioritize durability and can tolerate slightly larger cache access latency. + +The following example demonstrates how you can use `proxy-cache` Plugin on a Route to cache data on disk. + +When using the on-disk caching strategy, the cache TTL is determined by value from the response header `Expires` or `Cache-Control`. If none of these headers is present or if APISIX returns `502 Bad Gateway` or `504 Gateway Timeout` due to unavailable upstreams, the cache TTL defaults to the value configured in the [configuration files](#static-configuration). Review Comment: ```suggestion When using the on-disk caching strategy, the cache TTL is determined by value from the response header `Expires` or `Cache-Control`. If none of these headers is present or if APISIX returns `502 Bad Gateway` or `504 Gateway Timeout` due to unavailable Upstreams, the cache TTL defaults to the value configured in the [configuration files](#static-configuration). ``` ########## docs/zh/latest/plugins/proxy-cache.md: ########## @@ -28,57 +28,57 @@ description: 本文介绍了 Apache APISIX proxy-cache 插件的相关操作， Review Comment: ```suggestion <head> <link rel="canonical" href="https://docs.api7.ai/hub/proxy-cache"; /> </head> ``` ########## docs/en/latest/plugins/proxy-cache.md: ########## @@ -25,64 +26,66 @@ description: This document contains information about the Apache APISIX proxy-ca # --> +<head> + <link rel="canonical" href="https://docs.api7.ai/hub/proxy-cache"; /> +</head> + ## 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 and memory-based caching. +The `proxy-cache` Plugin provides the capability to cache responses based on a cache key. The Plugin supports both disk-based and memory-based caching options to cache for [GET](https://anything.org/learn/serving-over-http/#get-request), [POST](https://anything.org/learn/serving-over-http/#post-request), and [HEAD](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD) requests. -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. +Responses can be conditionally cached based on request HTTP methods, response status codes, request header values, and more. ## Attributes | 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_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_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`, hide the `Expires` and `Cache-Control` response headers. | -| 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. | +| cache_strategy | string | False | disk | ["disk","memory"] | Caching strategy. Cache on disk or in memory. | +| cache_zone | string | False | disk_cache_one | | Cache zone used with the caching strategy. The value should match one of the cache zones defined in the [configuration files](#static-configurations) and should correspond to the caching strategy. For example, when using the in-memory caching strategy, you should use an in-memory cache zone. | +| cache_key | array[string] | False | ["$host", "$request_uri"] | | Key to use for caching. Support [Nginx variables](https://nginx.org/en/docs/varindex.html) and constant strings in values. Variables should be prefixed with a `$` sign. | +| cache_bypass | array[string] | False | | | One or more parameters to parse value from, such that if any of the values is not empty and is not equal to `0`, response will not be retrieved from cache. Support [Nginx variables](https://nginx.org/en/docs/varindex.html) and constant strings in values. Variables should be prefixed with a `$` sign. | Review Comment: ```suggestion | cache_key | array[string] | False | ["$host", "$request_uri"] | | Key to use for caching. Support [NGINX variables](https://nginx.org/en/docs/varindex.html) and constant strings in values. Variables should be prefixed with a `$` sign. | | cache_bypass | array[string] | False | | | One or more parameters to parse value from, such that if any of the values is not empty and is not equal to `0`, response will not be retrieved from cache. Support [NGINX variables](https://nginx.org/en/docs/varindex.html) and constant strings in values. Variables should be prefixed with a `$` sign. | ``` ########## docs/en/latest/plugins/proxy-cache.md: ########## @@ -91,118 +94,286 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"/ ::: +### Cache Data on Disk + +On-disk caching strategy offers the advantages of data persistency when system restarts and having larger storage capacity compared to in-memory cache. It is suitable for applications that prioritize durability and can tolerate slightly larger cache access latency. + +The following example demonstrates how you can use `proxy-cache` Plugin on a Route to cache data on disk. + +When using the on-disk caching strategy, the cache TTL is determined by value from the response header `Expires` or `Cache-Control`. If none of these headers is present or if APISIX returns `502 Bad Gateway` or `504 Gateway Timeout` due to unavailable upstreams, the cache TTL defaults to the value configured in the [configuration files](#static-configuration). + +Create a Route with the `proxy-cache` Plugin to cache data on disk: + ```shell -curl http://127.0.0.1:9180/apisix/admin/routes/1 \ --H "X-API-KEY: $admin_key" -X PUT -d ' -{ - "uri": "/ip", +curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "proxy-cache-route", + "uri": "/anything", "plugins": { - "proxy-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"] - } + "proxy-cache": { + "cache_strategy": "disk" + } }, "upstream": { - "nodes": { - "httpbin.org": 1 - }, - "type": "roundrobin" + "type": "roundrobin", + "nodes": { + "httpbin.org": 1 + } } -}' + }' ``` -### Use memory-based caching +Send a request to the route: -You can enable the Plugin on a Route with in-memory `cache_strategy` and a corresponding in-memory `cache_zone` as shown below: +```shell +curl -i "http://127.0.0.1:9080/anything"; +``` + +You should see an `HTTP/1.1 200 OK` response with the following header, showing the Plugin is successfully enabled: + +```text +Apisix-Cache-Status: MISS +``` + +As there is no cache available before the first response, `Apisix-Cache-Status: MISS` is shown. + +Send the same request again within the cache TTL window. You should see an `HTTP/1.1 200 OK` response with the following headers, showing the cache is hit: + +```text +Apisix-Cache-Status: HIT +``` + +Wait for the cache to expire after the TTL and send the same request again. You should see an `HTTP/1.1 200 OK` response with the following headers, showing the cache has expired: + +```text +Apisix-Cache-Status: EXPIRED +``` + +### Cache Data in Memory + +In-memory caching strategy offers the advantage of low-latency access to the cached data, as retrieving data from RAM is faster than retrieving data from disk storage. It also works well for storing temporary data that does not need to be persisted long-term, allowing for efficient caching of frequently changing data. + +The following example demonstrates how you can use `proxy-cache` Plugin on a Route to cache data in memory. + +Create a Route with `proxy-cache` and configure it to use memory-based caching: ```shell -curl http://127.0.0.1:9180/apisix/admin/routes/1 \ --H "X-API-KEY: $admin_key" -X PUT -d ' -{ - "uri": "/ip", +curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "proxy-cache-route", + "uri": "/anything", "plugins": { - "proxy-cache": { - "cache_strategy": "memory", - "cache_zone": "memory_cache", - "cache_ttl": 10 - } + "proxy-cache": { + "cache_strategy": "memory", + "cache_zone": "memory_cache", + "cache_ttl": 10 + } }, "upstream": { - "nodes": { - "httpbin.org": 1 - }, - "type": "roundrobin" + "type": "roundrobin", + "nodes": { + "httpbin.org": 1 + } } -}' + }' ``` -## Example usage - -Once you have configured the Plugin as shown above, you can make an initial request: +Send a request to the route: ```shell -curl http://127.0.0.1:9080/ip -i +curl -i "http://127.0.0.1:9080/anything"; ``` -```shell -HTTP/1.1 200 OK -··· +You should see an `HTTP/1.1 200 OK` response with the following header, showing the Plugin is successfully enabled: + +```text Apisix-Cache-Status: MISS +``` + +As there is no cache available before the first response, `Apisix-Cache-Status: MISS` is shown. -hello +Send the same request again within the cache TTL window. You should see an `HTTP/1.1 200 OK` response with the following headers, showing the cache is hit: + +```text +Apisix-Cache-Status: HIT ``` -The `Apisix-Cache-Status` in the response shows `MISS` meaning that the response is not cached, as expected. Now, if you make another request, you will see that you get a cached response: +### Cache Responses Conditionally + +The following example demonstrates how you can configure the `proxy-cache` Plugin to conditionally cache responses. + +Create a Route with the `proxy-cache` Plugin and configure the `no_cache` attribute, such that if at least one of the values of the URL parameter `no_cache` and header `no_cache` is not empty and is not equal to `0`, the response will not be cached: + +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "proxy-cache-route", + "uri": "/anything", + "plugins": { + "proxy-cache": { + "no_cache": ["$arg_no_cache", "$http_no_cache"] + } + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org": 1 + } + } + }' +``` + +Send a few requests to the Route with the URL parameter `no_cache` value indicating cache bypass: ```shell -curl http://127.0.0.1:9080/ip -i +curl -i "http://127.0.0.1:9080/anything?no_cache=1"; +``` + +You should receive `HTTP/1.1 200 OK` responses for all requests and observe the following header every time: + +```text +Apisix-Cache-Status: EXPIRED ``` +Send a few other requests to the Route with the URL parameter `no_cache` value being zero: + ```shell -HTTP/1.1 200 OK -··· +curl -i "http://127.0.0.1:9080/anything?no_cache=0"; +``` + +You should receive `HTTP/1.1 200 OK` responses for all requests and start seeing the cache being hit: + +```text Apisix-Cache-Status: HIT +``` + +You can also specify the value in the `no_cache` header as such: -hello +```shell +curl -i "http://127.0.0.1:9080/anything"; -H "no_cache: 1" ``` -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. +The response should not be cached: -:::tip +```text +Apisix-Cache-Status: EXPIRED +``` + +### Retrieve Responses from Cache Conditionally + +The following example demonstrates how you can configure the `proxy-cache` Plugin to conditionally retrieve responses from cache. -To clear the cached data, you can send a request with `PURGE` method: +Create a Route with the `proxy-cache` Plugin and configure the `cache_bypass` attribute, such that if at least one of the values of the URL parameter `bypass` and header `bypass` is not empty and is not equal to `0`, the response will not be retrieved from the cache: ```shell -curl -i http://127.0.0.1:9080/ip -X PURGE +curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "proxy-cache-route", + "uri": "/anything", + "plugins": { + "proxy-cache": { + "cache_bypass": ["$arg_bypass", "$http_bypass"] + } + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org": 1 + } + } + }' ``` +Send a request to the Route with the URL parameter `bypass` value indicating cache bypass: + ```shell -HTTP/1.1 200 OK +curl -i "http://127.0.0.1:9080/anything?bypass=1"; ``` -If the response code is `200`, the deletion is successful. If the cached data is not found, a `404` response code will be returned. +You should see an `HTTP/1.1 200 OK` response with the following header: -::: +```text +Apisix-Cache-Status: BYPASS +``` -## Delete Plugin +Send another request to the Route with the URL parameter `bypass` value being zero: + +```shell +curl -i "http://127.0.0.1:9080/anything?bypass=0"; +``` -To remove 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. +You should see an `HTTP/1.1 200 OK` response with the following header: + +```text +Apisix-Cache-Status: MISS +``` + +You can also specify the value in the `bypass` header as such: ```shell -curl http://127.0.0.1:9180/apisix/admin/routes/1 \ --H "X-API-KEY: $admin_key" -X PUT -d ' -{ - "uri": "/ip", - "plugins": {}, +curl -i "http://127.0.0.1:9080/anything"; -H "bypass: 1" +``` + +The cache should be bypassed: + +```text +Apisix-Cache-Status: BYPASS +``` + +### Cache for 502 and 504 Error Response Code + +When the Upstream services return server errors in the 500 range, `proxy-cache` Plugin will cache the responses if and only if the returned status is `502 Bad Gateway` or `504 Gateway Timeout`. + +The following example demonstrates the behavior of `proxy-cache` Plugin when the Upstream service returns `504 Gateway Timeout`. + +Create a Route with the `proxy-cache` Plugin and configure a dummy Upstream service: + +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "proxy-cache-route", + "uri": "/timeout", + "plugins": { + "proxy-cache": { } + }, "upstream": { - "type": "roundrobin", - "nodes": { - "httpbin.org": 1 - } + "type": "roundrobin", + "nodes": { + "12.34.56.78": 1 + } } -}' + }' ``` + +Generate a few requests to the route: Review Comment: ```suggestion Generate a few requests to the Route: ``` ########## docs/en/latest/plugins/proxy-cache.md: ########## @@ -25,64 +26,66 @@ description: This document contains information about the Apache APISIX proxy-ca # --> +<head> + <link rel="canonical" href="https://docs.api7.ai/hub/proxy-cache"; /> +</head> + ## 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 and memory-based caching. +The `proxy-cache` Plugin provides the capability to cache responses based on a cache key. The Plugin supports both disk-based and memory-based caching options to cache for [GET](https://anything.org/learn/serving-over-http/#get-request), [POST](https://anything.org/learn/serving-over-http/#post-request), and [HEAD](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD) requests. -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. +Responses can be conditionally cached based on request HTTP methods, response status codes, request header values, and more. ## Attributes | 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_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_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`, hide the `Expires` and `Cache-Control` response headers. | -| 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. | +| cache_strategy | string | False | disk | ["disk","memory"] | Caching strategy. Cache on disk or in memory. | +| cache_zone | string | False | disk_cache_one | | Cache zone used with the caching strategy. The value should match one of the cache zones defined in the [configuration files](#static-configurations) and should correspond to the caching strategy. For example, when using the in-memory caching strategy, you should use an in-memory cache zone. | +| cache_key | array[string] | False | ["$host", "$request_uri"] | | Key to use for caching. Support [Nginx variables](https://nginx.org/en/docs/varindex.html) and constant strings in values. Variables should be prefixed with a `$` sign. | +| cache_bypass | array[string] | False | | | One or more parameters to parse value from, such that if any of the values is not empty and is not equal to `0`, response will not be retrieved from cache. Support [Nginx variables](https://nginx.org/en/docs/varindex.html) and constant strings in values. Variables should be prefixed with a `$` sign. | +| cache_method | array[string] | False | ["GET", "HEAD"] | ["GET", "POST", "HEAD"] | Request methods of which the response should be cached. | +| cache_http_status | array[integer] | False | [200, 301, 404] | [200, 599] | Response HTTP status codes of which the response should be cached. | +| hide_cache_headers | boolean | False | false | | If true, hide `Expires` and `Cache-Control` response headers. | +| cache_control | boolean | False | false | | If true, comply with `Cache-Control` behavior in the HTTP specification. Only valid for in-memory strategy. | +| no_cache | array[string] | False | | | One or more parameters to parse value from, such that if any of the values is not empty and is not equal to `0`, response will not be cached. Support [Nginx variables](https://nginx.org/en/docs/varindex.html) and constant strings in values. Variables should be prefixed with a `$` sign. | Review Comment: ```suggestion | no_cache | array[string] | False | | | One or more parameters to parse value from, such that if any of the values is not empty and is not equal to `0`, response will not be cached. Support [NGINX variables](https://nginx.org/en/docs/varindex.html) and constant strings in values. Variables should be prefixed with a `$` sign. | ``` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
