RustProxy/docs/RESPONSE_DELIVERY.md

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.

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.

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.