Request Decompress
The request-decompress plugin makes gzip- and deflate-compressed request bodies available to the other plugins on a route. Validation, transformation, security, and logging plugins can work with the plain content without requiring clients to send an uncompressed request.
Introduced in API7 Enterprise 3.10.9 and APISIX 3.20.0. See Configuration for request-size and forwarding options.
Request Handling
The plugin supports gzip, deflate, and identity content encodings. It decompresses multiple encodings in reverse order and processes every member in a concatenated gzip stream. Requests without a Content-Encoding header continue through the same route unchanged.
By default, the upstream service receives the plain body with an updated Content-Length and no Content-Encoding header. Enable compressed forwarding when the upstream expects encoded data; other plugins can still process the plain content before the body is restored or recompressed.
The gateway rejects requests with Content-Encoding that it cannot process:
| Condition | Status code | Response behavior |
|---|---|---|
| Unsupported content coding | 415 | Includes Accept-Encoding: gzip, deflate. |
| Malformed compressed body or data after the final gzip member | 400 | Reports that the request body could not be decompressed. |
| Encoded body or decompressed result exceeds the configured limit | 413 | Reports that the request body is too large. |
By default, request-decompress runs before hmac-auth and other authentication plugins. If hmac-auth validates the request body, it hashes the plain content. Set its priority above 2850 when clients sign the compressed bytes. Configure an appropriate request-body limit to bound decompression work from unauthenticated requests.
Examples
The examples first configure one route and verify that its upstream receives plain JSON. The second example updates the same route so that the upstream receives compressed data instead.
If Admin API authentication is enabled, export an admin-role key as ADMIN_API_KEY.
Decompress a Request Body
Create a route that decompresses request bodies before forwarding them to httpbin.org:
- Admin API
- ADC
- Ingress Controller
curl "http://127.0.0.1:9180/apisix/admin/routes/request-decompress-route" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"uri": "/anything",
"plugins": {
"request-decompress": {}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"httpbin.org:80": 1
}
}
}'
services:
- name: request-decompress-service
labels:
docs-example: request-decompress
routes:
- name: request-decompress-route
uris:
- /anything
plugins:
request-decompress: {}
upstream:
type: roundrobin
nodes:
- host: httpbin.org
port: 80
weight: 1
Preview the changes and confirm that they only affect resources for this example:
adc diff -f adc.yaml \
--include-resource-type service \
--label-selector docs-example=request-decompress
Synchronize the configuration to the gateway:
adc sync -f adc.yaml \
--include-resource-type service \
--label-selector docs-example=request-decompress
- Gateway API
- APISIX CRD
apiVersion: v1
kind: Service
metadata:
namespace: aic
name: httpbin-external-domain
spec:
type: ExternalName
externalName: httpbin.org
---
apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
namespace: aic
name: request-decompress-plugin-config
spec:
plugins:
- name: request-decompress
config: {}
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
namespace: aic
name: request-decompress-route
spec:
parentRefs:
- name: apisix
rules:
- matches:
- path:
type: Exact
value: /anything
filters:
- type: ExtensionRef
extensionRef:
group: apisix.apache.org
kind: PluginConfig
name: request-decompress-plugin-config
backendRefs:
- name: httpbin-external-domain
port: 80
apiVersion: apisix.apache.org/v2
kind: ApisixUpstream
metadata:
namespace: aic
name: httpbin-external-domain
spec:
ingressClassName: apisix
externalNodes:
- type: Domain
name: httpbin.org
---
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
namespace: aic
name: request-decompress-route
spec:
ingressClassName: apisix
http:
- name: request-decompress-route
match:
paths:
- /anything
upstreams:
- name: httpbin-external-domain
plugins:
- name: request-decompress
enable: true
config: {}
Apply the configuration to your cluster:
kubectl apply -f request-decompress-ic.yaml
Send a gzip-compressed JSON body to the route and select the response fields that show what the upstream received:
echo -n '{"name":"world"}' | gzip | \
curl "http://127.0.0.1:9080/anything" -X POST \
-H "Content-Type: application/json" \
-H "Content-Encoding: gzip" \
--data-binary @- | \
jq '{
data,
content_encoding: .headers["Content-Encoding"]
}'
The upstream receives the plain JSON body without a content encoding:
{
"data": "{\"name\":\"world\"}",
"content_encoding": null
}
Keep the Upstream Request Compressed
Update the plugin configuration from the previous example so that other route plugins still receive plain content, but the upstream receives a compressed body:
- Admin API
- ADC
- Ingress Controller
curl "http://127.0.0.1:9180/apisix/admin/routes/request-decompress-route" -X PATCH \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"plugins": {
"request-decompress": {
"forward_compressed": true
}
}
}'
In adc.yaml, enable compressed forwarding on the existing route:
plugins:
request-decompress:
forward_compressed: true
Preview and synchronize the updated file:
adc diff -f adc.yaml \
--include-resource-type service \
--label-selector docs-example=request-decompress
adc sync -f adc.yaml \
--include-resource-type service \
--label-selector docs-example=request-decompress
- Gateway API
- APISIX CRD
Update the plugin in the existing PluginConfig:
spec:
plugins:
- name: request-decompress
config:
forward_compressed: true
Update the plugin in the existing ApisixRoute:
plugins:
- name: request-decompress
enable: true
config:
forward_compressed: true
Apply the updated configuration:
kubectl apply -f request-decompress-ic.yaml
Send another gzip-compressed request. This time, check that the upstream received the encoding header and a binary body:
echo -n '{"name":"world"}' | gzip | \
curl "http://127.0.0.1:9080/anything" -X POST \
-H "Content-Type: application/json" \
-H "Content-Encoding: gzip" \
--data-binary @- | \
jq '{
content_encoding: .headers["Content-Encoding"],
body_is_binary: (.data | startswith("data:application/octet-stream;base64,"))
}'
The response confirms that the upstream received gzip-compressed data:
{
"content_encoding": "gzip",
"body_is_binary": true
}