higress/plugins/wasm-go/extensions/response-cache

title, keywords, description

title	keywords	description
Response Cache	higress response cache	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; 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

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

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

# 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:

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:

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 for more usage examples, and test the syntax using the GJSON Playground.

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