Module compress 

Content negotiation for the web surfaces (WEBUI-PLAN.md W1/W2).

Design law: the wire contract is the freeze’s — a client that sends neither Accept-Encoding nor If-None-Match must receive byte-identical responses to what ocserve served before this module existed (WEBUI-PLAN target 3, asserted by replay/pair/k6 and by tests here). Compression and validators are strictly additive, gated on the client asking.

• negotiate picks an encoding from Accept-Encoding by q-value.
• compress produces gzip (flate2, fast level) or brotli (q5). Brotli wins on bytes for JSON/JS/CSS and is precomputed off the request path for the F5 wire routes.
• etag_for is a strong validator over the identity body, so the same ETag tags both the identity and compressed representations (RFC 9110 §8.8.3 — a strong ETag must not change with encoding; the encoding is conveyed by Content-Encoding + Vary, so the representation is still distinct). 304 is answered before any body work.

Enums

Encoding

Encodings we can produce, best-bytes first.

Functions

compress

Compress data. gzip uses the fast level (request-path friendly); brotli uses quality 5 (best bytes/second tradeoff — WEBUI-PLAN measured br-q11 at 20 s for 6.2 MB, rejected; q5 at 0.18 s). Precomputed callers use this on the write-epoch path, not per request.

encode_response

Apply negotiation + validators to an identity body, returning a full response. identity_etag is the caller-computed ETag (over identity bytes) or None to skip validator handling.

etag_for

Strong ETag over the identity body: "<hex-sha256[..16]>" quoted per RFC 9110. Stable across encodings (see module docs).

if_none_match_matches

Whether an If-None-Match header matches this ETag (weak/strong comparison per RFC 9110 §13.1.2 — compare opaque tags, W/ ignored on the request side is not needed because we never emit weak tags).

is_compressible

Whether a route’s content type is compressible (SSE is NOT: byte-golden stream, and compressing it would break framing/latency). Images/fonts already-compressed are skipped.

negotiate

Pick the client’s preferred supported encoding from Accept-Encoding. Honours q-values; identity/*;q=0 suppress compression. Returns None when the client did not offer anything (→ identity, the pre-existing behavior).