Skip to main content

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:

ConditionStatus codeResponse behavior
Unsupported content coding415Includes Accept-Encoding: gzip, deflate.
Malformed compressed body or data after the final gzip member400Reports that the request body could not be decompressed.
Encoded body or decompressed result exceeds the configured limit413Reports that the request body is too large.
Signed request bodies

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:

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
}
}
}'

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:

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
}
}
}'

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
}