
# Response compression

With `server.compression.enabled=true`, the server gzips text responses (HTML, JSON, CSS, JavaScript, ...) for clients that accept gzip.

## Why

JSON and HTML shrink a lot with gzip, often to a fifth of their size. Smaller answers reach slow networks and phones sooner and cost less bandwidth.

Compression costs CPU on every answer, and small answers gain little. So it is off by default, and even when it is on, small answers and media types that are already compressed (images, video, archives) are sent as they are.

Leave it off when a proxy in front (nginx, a CDN) already compresses, or when you serve precompressed files (`spring.web.resources.chain.compressed`).

## Example

```yaml
# lib/resources/application.yml
server:
  compression:
    enabled: true
    mime-types:
      - text/html
      - text/css
      - text/javascript
      - application/javascript
      - application/json
      - application/problem+json
      - image/svg+xml
    min-response-size: 1KB
```

```properties
server.compression.enabled=true
server.compression.mime-types=text/html,text/css,text/javascript,application/javascript,application/json,application/problem+json,image/svg+xml
server.compression.min-response-size=1KB
```

A request and its answer:

```text
GET /api/books HTTP/1.1
Accept-Encoding: gzip, br

HTTP/1.1 200 OK
Content-Type: application/json
Content-Encoding: gzip
Vary: Accept-Encoding
Transfer-Encoding: chunked
```

## Properties

| Key | Type | Default | Meaning |
|---|---|---|---|
| `server.compression.enabled` | `bool` | `false` | Gzip the responses that qualify. |
| `server.compression.mime-types` | `List<String>` | Spring Boot's list (below) | The media types compressed. |
| `server.compression.min-response-size` | `DataSize` | `2KB` | The smallest `Content-Length` compressed. |

### `server.compression.enabled`

- **Type:** `bool`. **Default:** `false`.
- **What it does:** turns gzip on for the answers that qualify (see the rules below), for clients whose `Accept-Encoding` lists `gzip` with a quality above 0 (`gzip`, `gzip;q=0.5`; not `gzip;q=0`).
- **Why change it:** an API or site that clients reach directly, without a compressing proxy.
- **Example:** `server.compression.enabled=true`.

### `server.compression.mime-types`

- **Type:** a list of media types (a comma list or a YAML list). **Default:** Spring Boot's list:

```text
text/html, text/xml, text/plain, text/css, text/javascript,
application/javascript, application/json, application/xml
```

- **What it does:** only answers whose `Content-Type` is one of these are compressed. Parameters are ignored on both sides (`application/json; charset=utf-8` matches `application/json`). Matching ignores case.
- **Wildcards:** `text/*` matches every `text/` type. No other pattern is supported.
- **Setting it replaces the list.** It does not add to the defaults. Write all the types you want.
- **An empty list** (all entries blank) falls back to the defaults.
- **Why change it:** add `application/problem+json` (error answers), `image/svg+xml`, `application/manifest+json`, `text/event-stream`, or remove types.
- **Example:** `server.compression.mime-types=text/*,application/json,application/javascript`.

### `server.compression.min-response-size`

- **Type:** `DataSize` (`2KB`, `512B`; a plain number is bytes). **Default:** `2KB`.
- **What it does:** an answer whose `Content-Length` is smaller is not compressed. An answer whose length is not known yet (a stream, a chunked body) is compressed whatever its size.
- **Why change it:** lower it when most of your answers are small JSON documents; raise it to save CPU.
- **Example:** `server.compression.min-response-size=1KB`.

## Which answers are compressed

An answer is compressed when all of these are true:

1. `server.compression.enabled` is `true`;
2. the client accepts gzip;
3. the status allows a body: not 1xx, `204`, `205` or `304`;
4. it is not partial content: not `206`, no `Content-Range`;
5. it has no `Content-Encoding` yet (a precompressed file is sent as it is);
6. it has no strong `ETag`. A strong tag promises these exact bytes, so, as Tomcat does, such an answer is never compressed. A weak tag (`W/"..."`, as the static resources send) is fine;
7. its `Content-Type` is in `mime-types`;
8. its `Content-Length` is at least `min-response-size`, or not known.

When the answer is compressed, `Content-Encoding: gzip` is added and `Content-Length` is dropped: the body is sent chunked.

### `Vary: Accept-Encoding`

Every answer that rules 1 and 3 to 8 allow gets `Vary: Accept-Encoding`, even for a client that does not accept gzip. So a cache between the client and the server keeps the compressed and the plain answer apart. It is added once. When `Vary` already holds `*`, it stays `*`.

### Streams

- **Server-sent events** (`text/event-stream`) are not in the default list, as in Spring Boot. Add `text/event-stream` to compress them. Each flush sends what was compressed so far, so events still arrive one by one.
- **Byte streams** and **NDJSON** follow the same rules by their media type.

### Only gzip

The server compresses with gzip only. No Brotli, no `deflate`. To serve Brotli, ship precompressed `.br` files next to the static files and set `spring.web.resources.chain.compressed=true`. See [Static resources](../static-resources.md).

### WebSocket

Compression does not apply to WebSocket messages, and the server does not negotiate permessage-deflate. See [WebSocket](websocket.md).

## In Spring (Java)

```properties
server.compression.enabled=true
server.compression.mime-types=text/html,application/json
server.compression.min-response-size=2KB
```

Differences that matter:

- The same keys, defaults and rules (strong `ETag`, partial content, `Vary`) as Spring Boot on Tomcat.
- `server.compression.excluded-user-agents` is not supported.
- Only gzip is produced.

## See also

- [The embedded server](index.md)
- [Static resources](../static-resources.md)
- [Server-sent events](../streaming/sse.md)
- [All properties](../properties.md)
- [Data sizes](../../spring-core-dart/conversion/data-size.md)
