48 lines
4.3 KiB
Markdown
48 lines
4.3 KiB
Markdown
# Compression, transformations and response headers
|
||
|
||
RustProxy can compress eligible responses and optionally transform supported static content before caching or delivery. These controls are **separate**: compression changes transfer encoding; transformation changes representation bytes. Always verify content and response headers with a real client after enabling either feature.
|
||
|
||
## Response compression
|
||
|
||
Open **Settings → Response / Compression** to configure the global codec ceiling. Vhosts and Web Services may further restrict enabled codecs; a local override cannot enable a codec forbidden globally.
|
||
|
||
| Setting | Current default / behavior |
|
||
|---|---|
|
||
| `gzip` | Enabled globally |
|
||
| `br` (Brotli) | Enabled globally |
|
||
| `zstd` | Enabled globally; used only when the client accepts it |
|
||
| `deflate` | Disabled globally |
|
||
| `min_bytes` | 1,024 bytes by default, configurable from 32 to 1,048,576 |
|
||
|
||
RustProxy negotiates encoding against the request's `Accept-Encoding` values and quality weights. An eligible reply with a preexisting `Content-Encoding` is **not compressed again**. Compression is skipped for range responses, HEAD/204/304, upgrades, event streams, `Cache-Control: no-transform` and other ineligible cases. Unknown-length streams are handled without buffering the whole body merely to compress it.
|
||
|
||
The Web Server can additionally use precompressed `.br`/`.gz` file sidecars when eligible. Sidecar delivery is distinct from live response compression. Do not manually force a `Content-Encoding` header that does not match the actual body.
|
||
|
||
## Static response transformations
|
||
|
||
Under **Settings → Transform**, the engine is disabled by default. Even when enabled globally, **each Vhost must opt in**. The default globally enabled transform types, once the engine is turned on, are JavaScript and CSS. HTML, SVG and JSON transformations are individually optional. A Vhost may override the allowed types and extensions within global restrictions. In **Vhosts → Transform**, the optional custom extension list sits immediately below its override checkbox rather than next to the transform-format selectors. The list remains read-only until its override is enabled.
|
||
|
||
The available resource controls include:
|
||
|
||
- `max_body_bytes` — 2 MiB default per eligible response (1 KiB–32 MiB accepted).
|
||
- `memory_budget_bytes` — 128 MiB default process-wide budget (1 MiB–2 GiB accepted).
|
||
- `max_inflight` — 32 default concurrent transformation slots (1–1024 accepted).
|
||
- Presets in the panel can set suggested limits; the stored numeric settings determine actual limits.
|
||
|
||
Transformation is a bounded operation for eligible, supported representations, **not a general rewrite engine**. Unsupported MIME types, larger or unknown-size bodies, non-transformable responses and resource-saturated periods are skipped or handled without changing the original body. Transforming JS/CSS/HTML can break applications that rely on specific syntax or content, so test before enabling site-wide.
|
||
|
||
Transformations can run on eligible reverse-proxy and Web Server responses. When a transformed response is safely cacheable, the cache stores a representation compatible with its validators and later per-client encoding. Changing transform rules may invalidate affected cached content. See [Cache](CACHE.md).
|
||
|
||
## Custom and security headers
|
||
|
||
Configure global response headers, Vhost-specific policies and Web Server/location headers at the appropriate scope. Header rules can set, append or remove allowed names. Certain routing, forwarding, framing, cache diagnostics and security-sensitive fields are protected or subject to extra validation. Review especially HSTS, CSP, CORS and application-specific cookies before using a broad rule.
|
||
|
||
For controlled rollout:
|
||
|
||
1. Enable only the codec/types required, then test with and without `Accept-Encoding` and with ordinary browsers.
|
||
2. Compare response size, actual decoding, `Vary`, cache status and content hash for sensitive assets.
|
||
3. Check the **Transform** and **Cache** dashboards, response logs and browser console for errors.
|
||
4. Disable the particular Vhost or transform type if output changes unexpectedly; investigate before re-enabling.
|
||
|
||
The Transform dashboard provides examined/transformed/skipped/failed counts, saved bytes and resource-limit observations. These are runtime diagnostics, not a guarantee that every asset was transformed or that end-user page loads improved.
|