mirror of
https://github.com/alibaba/higress.git
synced 2026-03-03 08:00:49 +08:00
121 lines
6.1 KiB
Markdown
121 lines
6.1 KiB
Markdown
---
|
|
title: Response Cache
|
|
keywords: [higress,response cache]
|
|
description: Response Cache Plugin Configuration Reference
|
|
---
|
|
## Function Description
|
|
Response caching plugin supports extracting keys from request headers/request bodies and caching values extracted from response bodies. On subsequent requests, if the request headers/request bodies contain the same key, it directly returns the cached value without forwarding the request to the backend service.
|
|
|
|
**Hint**
|
|
|
|
When carrying the request header `x-higress-skip-response-cache: on`, the current request will not use content from the cache but will be directly forwarded to the backend service. Additionally, the response content from this request will not be cached.
|
|
|
|
## Runtime Properties
|
|
Plugin Execution Phase: `Authentication Phase`
|
|
Plugin Execution Priority: `10`
|
|
|
|
## Configuration Description
|
|
|
|
### Cache Service (cache)
|
|
| Property | Type | Requirement | Default | Description |
|
|
| --- | --- | --- | --- | --- |
|
|
| cache.type | string | required | "" | Cache service type, e.g., redis |
|
|
| cache.serviceName | string | required | "" | Cache service name |
|
|
| cache.serviceHost | string | required | "" | Cache service domain |
|
|
| cache.servicePort | int64 | optional | 6379 | Cache service port |
|
|
| cache.username | string | optional | "" | Cache service username |
|
|
| cache.password | string | optional | "" | Cache service password |
|
|
| cache.timeout | uint32 | optional | 10000 | Timeout for cache service in milliseconds. Default is 10000, i.e., 10 seconds |
|
|
| cache.cacheTTL | int | optional | 0 | Cache expiration time in seconds. Default is 0, meaning never expires |
|
|
| cacheKeyPrefix | string | optional | "higress-response-cache:" | Prefix for cache keys, default is "higress-response-cache:" | |
|
|
|
|
### Other Configurations
|
|
| Name | Type | Requirement | Default | Description |
|
|
| --- | --- | --- | --- | --- |
|
|
| cacheResponseCode | array of number | optional | 200 | Indicates the list of response status codes that support caching; the default is 200.|
|
|
| cacheKeyFromHeader | string | optional | "" | Extracts a fixed field's value from headers as the cache key; when configured, extracts key from request headers without reading the request body; **only one of cacheKeyFromHeader and cacheKeyFromBody can be configured when both are non-empty**|
|
|
| cacheKeyFromBody | string | optional | "" | If empty, extracts all body as the cache key; otherwise, extracts a string from the request body in JSON format based on [GJSON PATH](https://github.com/tidwall/gjson/blob/master/SYNTAX.md); only takes effect when cacheKeyFromHeader is empty or not configured |
|
|
| cacheValueFromBodyType | string | optional | "application/json" | Indicates the type of cached body; the content-type returned on cache hit will be this value; default is "application/json" |
|
|
| cacheValueFromBody | string | optional | "" | If empty, caches all body; when cacheValueFromBodyType is "application/json", supports extracting a string from the response body based on [GJSON PATH](https://github.com/tidwall/gjson/blob/master/SYNTAX.md) |
|
|
|
|
|
|
The logic for concatenating the cache key is one of the following:
|
|
|
|
1. `cacheKeyPrefix` + content extracted from the field corresponding to `cacheKeyFromHeader` in the request header
|
|
2. `cacheKeyPrefix` + content extracted from the field corresponding to `cacheKeyFromBody` in the request body
|
|
|
|
**Note**: `cacheKeyFromHeader` and `cacheKeyFromBody` cannot be configured at the same time (only one of them can be configured when both are non-empty). If both are configured, the plugin will return an error during the configuration parsing phase.
|
|
|
|
In the case of hitting the cache plugin, there are three statuses in the returned response headers:
|
|
|
|
- `x-cache-status: hit` , indicating a cache hit and cached content is returned directly
|
|
- `x-cache-status: miss` , indicating a cache miss and backend response results are returned
|
|
- `x-cache-status: skip` , indicating skipping the cache check
|
|
|
|
## Configuration Example
|
|
### Basic Configuration
|
|
```yaml
|
|
cache:
|
|
type: redis
|
|
serviceName: my-redis.dns
|
|
servicePort: 6379
|
|
timeout: 2000
|
|
|
|
cacheKeyFromHeader: "x-http-cache-key"
|
|
|
|
cacheValueFromBodyType: "application/json"
|
|
cacheValueFromBody: "messages.@reverse.0.content"
|
|
```
|
|
|
|
Assumed Request
|
|
|
|
```bash
|
|
# Request
|
|
curl -H "x-http-cache-key: abcd" <url>
|
|
|
|
# Response
|
|
{"messages":[{"content":"1"}, {"content":"2"}, {"content":"3"}]}
|
|
```
|
|
|
|
In this case, the cache key would be `higress-response-cache:abcd`, and the cached value would be `3`.
|
|
|
|
For subsequent requests that hit the cache, the response Content-Type returned is `application/json`.
|
|
|
|
### Response Body as Cache Value
|
|
To cache all response bodies, configure as follows:
|
|
|
|
```yaml
|
|
cacheValueFromBodyType: "text/html"
|
|
cacheValueFromBody: ""
|
|
```
|
|
For subsequent requests that hit the cache, the response Content-Type returned is `text/html`.
|
|
|
|
|
|
### Request Body as Cache Key
|
|
To use the request body as the key, configure as follows:
|
|
|
|
```yaml
|
|
|
|
cacheKeyFromBody: ""
|
|
```
|
|
|
|
The configuration supports GJSON PATH syntax.
|
|
|
|
|
|
## Advanced Usage
|
|
When the body is `application/json`, GJSON PATH syntax is supported:
|
|
|
|
For example, the expression `messages.@reverse.0.content` means taking the content of the first item after reversing the messages array.
|
|
|
|
GJSON PATH also supports conditional syntax. For instance, to take the content of the last message where role is "user", you can write: `messages.@reverse.#(role=="user").content`.
|
|
|
|
To concatenate all contents where role is "user" into an array, you can write: `messages.@reverse.#(role=="user")#.content`.
|
|
|
|
Pipeline syntax is also supported. For example, to take the second content where role is "user", you can write: `messages.@reverse.#(role=="user")#.content|1`.
|
|
|
|
Refer to the [official documentation](https://github.com/tidwall/gjson/blob/master/SYNTAX.md) for more usage examples, and test the syntax using the [GJSON Playground](https://gjson.dev/).
|
|
|
|
## Common Issues
|
|
If the error `error status returned by host: bad argument` occurs, check:
|
|
- Whether `serviceName` correctly includes the service type suffix (.dns, etc.)
|
|
- Whether `servicePort` is configured correctly, especially that `static` type services now use a fixed port of 80 |