# Response compression

> Compress HTTP responses with gzip, brotli, or zstd — enabled by default, customizable via HTTPRouteFilter.

Apoxy compresses HTTP responses by default. All three algorithms (gzip, brotli, zstd) are enabled on every route, with a 128-byte minimum response size and a standard set of compressible MIME types.

No configuration is needed to get compression — it works out of the box. The `HTTPRouteFilter` extension lets you customize compression behavior on specific routes: change the minimum size, restrict algorithms, override content types, or disable compression entirely.

## Verify default compression

```bash title="terminal"
curl -H 'Accept-Encoding: gzip' -I https://app.example.com/
```

You should see:

```
HTTP/1.1 200 OK
Content-Encoding: gzip
```

## Choosing algorithms

By default, all three algorithms are enabled and Envoy picks the best one based on the client's `Accept-Encoding` header. To restrict to specific algorithms on a route, create an `HTTPRouteFilter`:

```yaml title="compress-filter.yaml"
apiVersion: extensions.apoxy.dev/v1alpha2
kind: HTTPRouteFilter
metadata:
  name: compress-gzip-only
spec:
  compressor:
    algorithms:
    - gzip
```

Attach it to an HTTPRoute:

```yaml title="app-route.yaml"
apiVersion: gateway.apoxy.dev/v1
kind: HTTPRoute
metadata:
  name: app-route
spec:
  parentRefs:
  - name: default
  hostnames:
  - app.example.com
  rules:
  - filters:
    - type: ExtensionRef
      extensionRef:
        group: extensions.apoxy.dev
        kind: HTTPRouteFilter
        name: compress-gzip-only
    backendRefs:
    - group: core.apoxy.dev
      kind: Backend
      name: app-backend
      port: 8080
```

Supported values: `gzip`, `brotli`, `zstd`.

## Tuning the minimum size

Responses smaller than `minContentLength` bytes are not compressed. The default is 128 bytes. Compressing very small responses can actually increase their size due to compression overhead.

```yaml
spec:
  compressor:
    minContentLength: 1024
```

The minimum allowed value is 50 bytes.

## Custom content types

By default, compression applies to common text and structured formats. To override the list on a specific route:

```yaml
spec:
  compressor:
    contentType:
    - application/json
    - text/html
    - text/plain
    - application/xml
```

### Default content types

When `contentType` is not specified, the following MIME types are compressed:

- `application/javascript`
- `application/json`
- `application/xhtml+xml`
- `image/svg+xml`
- `text/css`
- `text/html`
- `text/plain`
- `text/xml`

## Disabling compression on a route

Since compression is enabled by default, you may want to explicitly disable it on specific routes — for example, if the upstream already compresses responses. Use the `disabled` flag:

```yaml title="no-compress-filter.yaml"
apiVersion: extensions.apoxy.dev/v1alpha2
kind: HTTPRouteFilter
metadata:
  name: no-compress
spec:
  compressor:
    disabled: true
```

When `disabled` is set to `true`, no other compressor fields may be specified.

## Full spec reference

```yaml title="compression-spec.yaml"
apiVersion: extensions.apoxy.dev/v1alpha2
kind: HTTPRouteFilter
metadata:
  name: compress-custom
spec:
  compressor:
    # Disable compression entirely. When true, all other fields are forbidden.
    # disabled: true

    # Algorithms to enable. Defaults to all three.
    algorithms:
    - gzip
    - brotli
    - zstd

    # Minimum response body size in bytes to trigger compression.
    # Must be >= 50. Defaults to 128.
    minContentLength: 128

    # MIME types that trigger compression.
    # Defaults to the list above when omitted.
    contentType:
    - application/json
    - text/html
    - text/plain
```

## Key points

- Compression is enabled by default on all routes with a 128-byte minimum size.
- Use `HTTPRouteFilter` only when you need to customize or disable compression on specific routes.
- One `HTTPRouteFilter` can be shared across multiple HTTPRoutes — create it once and reference it from any route.
- The client's `Accept-Encoding` header determines which algorithm is used. If the client doesn't support any of the configured algorithms, the response is sent uncompressed.
- Compression runs after the backend responds, so it does not affect request bodies.
- Binary formats like images and video are typically not compressible. Avoid adding types like `image/png` or `video/mp4` to the content-type list.