For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Compress responses to clients and decompress encoded request bodies.

Attaches to:

Use the policies.compression policy for response compression and request decompression. You can configure either feature or both on the same route.

About compression

Response compression reduces bandwidth for JSON, HTML, CSS, JavaScript, XML, plain text, and SVG responses. Clients must advertise a configured algorithm in the Accept-Encoding header to receive compressed responses.

The following limits apply:

• Responses must have a known length of at least 32 bytes. Streams without a known length, such as server-sent events, are not compressed.
• Responses that are already encoded, have a Content-Range header, or set Cache-Control: no-transform are not compressed. Responses with a 1xx, 204, or 304 status code are also excluded.
• Request decompression requires a single configured encoding in Content-Encoding. Unsupported or layered encodings, such as Content-Encoding: gzip, br, are forwarded unchanged.

Algorithm selection

The algorithm with the highest quality value (q) in Accept-Encoding wins. Ties follow the configured algorithm order. A * entry applies to algorithms that the client does not list by name. If identity has a higher quality value than every configured algorithm, the response stays uncompressed.

Headers and content types

Compressed responses set Content-Encoding, remove Content-Length and Accept-Ranges, and change strong ETag values to weak values, such as W/"abc". Eligible responses include Vary: accept-encoding even when sent uncompressed, so caches can distinguish responses by the client’s accepted encodings.

Eligible media types are application/javascript, application/json, application/xml, application/xhtml+xml, image/svg+xml, text/css, text/html, text/javascript, text/plain, and text/xml. Types with a +json or +xml suffix also qualify. Responses with other media types or without a Content-Type header are not compressed.

Decompressed requests have their Content-Encoding and Content-Length headers removed.

Policy order

Response compression runs after other response policies and the access log snapshot. Transformations and response body logs see the uncompressed body. The client’s Accept-Encoding is read before request header modifiers run, so removing that header before forwarding does not disable compression.

Request decompression runs after route-level authentication and authorization. These policies see encoded bodies, and denied requests are never decoded. Route-level rate limiting, external processing, and transformations see decoded bodies. Backend authorization also sees decoded bodies.

Gateway-phase policies (phase: gateway) also see encoded request bodies.

Compression settings

The compression policy takes a response block, a request block, or both.

Choose from gzip, brotli, deflate, and zstd. If you omit algorithms, the default is gzip. The HTTP encoding token for Brotli is br.

The following example compresses responses with gzip or brotli and decodes gzip request bodies.

policies:
  compression:
    response:
      compress:
        algorithms: [gzip, brotli]
    request:
      decompress: {}

For the full list of fields, see the configuration reference.

Before you begin

1. Install a nightly agentgateway binary. On the installation page, select Nightly build. Compression is not available in v1.7.0.
2. Make sure that you have docker, such as by installing Docker Desktop.

Compress responses and decompress requests

The following steps start a sample httpbin app as the backend, configure a route with a compression policy, and test response compression and request decompression.

1. Start the httpbin sample app in Docker. The app listens on port 8000 on your machine.

   docker run -d --name httpbin -p 8000:8080 mccutchen/go-httpbin:v2.15.0

2. Create a configuration file with a compression policy. The policy compresses responses with gzip, brotli, or zstd, and decodes request bodies that are encoded with gzip.

   cat > config.yaml <<EOF
   # yaml-language-server: \$schema=https://agentgateway.dev/schema/config
   gateways:
     default:
       port: 3000
   routes:
   - backends:
     - host: localhost:8000
     policies:
       compression:
         response:
           compress:
             algorithms: [gzip, brotli, zstd]
         request:
           decompress:
             algorithms: [gzip]
   EOF

3. Run agentgateway with the configuration file.

   agentgateway -f config.yaml

4. In another terminal, request a JSON response and advertise support for br and gzip in the Accept-Encoding header. The client accepts both algorithms equally, so the first matching algorithm in the policy wins. The policy lists gzip before brotli, so the proxy compresses the response with gzip.

   curl -s -o /dev/null -D - http://localhost:3000/json \
     -H "Accept-Encoding: br, gzip"

   Example output:

   HTTP/1.1 200 OK
   Access-Control-Allow-Credentials: true
   Access-Control-Allow-Origin: *
   Content-Type: application/json; charset=utf-8
   content-encoding: gzip
   vary: accept-encoding
   transfer-encoding: chunked
   

5. Send the request again and accept only br, which is the HTTP token for Brotli. The proxy compresses the response with Brotli.

   curl -s -o /dev/null -D - http://localhost:3000/json \
     -H "Accept-Encoding: br"

   Example output:

   HTTP/1.1 200 OK
   Access-Control-Allow-Credentials: true
   Access-Control-Allow-Origin: *
   Content-Type: application/json; charset=utf-8
   content-encoding: br
   vary: accept-encoding
   transfer-encoding: chunked
   

6. Send the request without an Accept-Encoding header. The proxy does not compress the response, so the response has a Content-Length header and no content-encoding header. The response still includes the vary: accept-encoding header.

   curl -s -o /dev/null -D - http://localhost:3000/json

   Example output:

   HTTP/1.1 200 OK
   Access-Control-Allow-Credentials: true
   Access-Control-Allow-Origin: *
   Content-Type: application/json; charset=utf-8
   Content-Length: 421
   vary: accept-encoding
   

7. Send a request body that is compressed with gzip to the httpbin /anything endpoint, which echoes the request back. The proxy decodes the body, so httpbin receives the decoded JSON body. The data and json fields in the output show the decoded body.

   echo '{"hello":"world"}' | gzip | curl -s http://localhost:3000/anything \
     -H "Content-Type: application/json" \
     -H "Content-Encoding: gzip" \
     --data-binary @-

   Example output:

   {
     ...
     "data": "{\"hello\":\"world\"}\n",
     ...
     "json": {
       "hello": "world"
     }
   }
   

Cleanup

Stop agentgateway and remove the resources that you created.

1. Stop agentgateway by pressing Ctrl+C in the terminal where agentgateway runs.

2. Remove the httpbin container and the configuration file.

   docker rm -f httpbin
   rm config.yaml