rust_web_server/compression/
mod.rs

1#[cfg(test)]
2mod tests;
3
4pub mod dictionary;
5
6use flate2::Compression;
7use flate2::write::GzEncoder;
8use std::io::Write;
9use crate::header::Header;
10use crate::request::Request;
11use crate::response::Response;
12
13/// MIME types whose responses are worth compressing.
14const COMPRESSIBLE: &[&str] = &[
15    "text/html",
16    "text/css",
17    "text/javascript",
18    "text/plain",
19    "text/xml",
20    "application/json",
21    "application/javascript",
22    "application/xml",
23    "application/xhtml+xml",
24    "image/svg+xml",
25];
26
27/// Bodies smaller than this are sent uncompressed: gzip's framing overhead
28/// and the CPU time outweigh what it saves (Caddy's `encode` uses the same
29/// minimum).
30pub const MIN_COMPRESS_SIZE: usize = 512;
31
32/// If the client accepts gzip and the response body is compressible text of
33/// at least [`MIN_COMPRESS_SIZE`] bytes, compress every content range
34/// in-place and add `Content-Encoding: gzip`; also appends `Accept-Encoding`
35/// to the `Vary` header. A body that gzip doesn't make smaller (already
36/// compressed or random data) is left as it was, and so is a response that
37/// already has a `Content-Encoding` (e.g. a backend that compressed it).
38pub fn apply_gzip(request: &Request, response: &mut Response) {
39    compress_with(request, response, &[Encoding::Gzip]);
40}
41
42/// Like [`apply_gzip`], with the content coding negotiated from the request's
43/// `Accept-Encoding` among those compiled in ([`DYNAMIC_PREFERENCE`]): `zstd`,
44/// `br` or `gzip`. What the HTTP/1.1, HTTP/2 and HTTP/3 writers call (18.1.0).
45pub fn apply_compression(request: &Request, response: &mut Response) {
46    compress_with(request, response, DYNAMIC_PREFERENCE);
47}
48
49fn compress_with(request: &Request, response: &mut Response, preference: &[Encoding]) {
50    if response.content_range_list.is_empty() {
51        return;
52    }
53    // A partial body (206, one range or several) is a slice of the
54    // representation: gzipping the slice and rewriting Content-Range to the
55    // compressed size describes bytes that don't exist (#52, RFC 9110 §14.4).
56    if response.status_code == 206 || response.content_range_list.len() > 1 {
57        return;
58    }
59    if response.headers.iter().any(|h| h.name.eq_ignore_ascii_case(Header::_CONTENT_ENCODING)) {
60        return;
61    }
62    let original_size: usize = response.content_range_list.iter().map(|cr| cr.body.len()).sum();
63    if original_size < MIN_COMPRESS_SIZE {
64        return;
65    }
66    let Some(encoding) = negotiate(request, preference) else { return };
67    let content_type = response
68        .content_range_list
69        .first()
70        .map(|cr| cr.content_type.as_str())
71        .unwrap_or_default();
72    if !is_compressible(content_type) {
73        return;
74    }
75
76    let mut compressed_bodies = Vec::with_capacity(response.content_range_list.len());
77    for cr in &response.content_range_list {
78        match encode(encoding, &cr.body, Level::Dynamic) {
79            Some(compressed) => compressed_bodies.push(compressed),
80            None => return,
81        }
82    }
83    let compressed_size: usize = compressed_bodies.iter().map(Vec::len).sum();
84    if compressed_size >= original_size {
85        return;
86    }
87    for (cr, compressed) in response.content_range_list.iter_mut().zip(compressed_bodies) {
88        let new_len = compressed.len() as u64;
89        cr.body = compressed;
90        cr.range.end = new_len;
91        cr.size = new_len.to_string();
92    }
93    mark_encoded(response, encoding);
94    tag_etag(response, encoding);
95}
96
97/// A compressed body is a different representation, so it needs its own
98/// ETag: `"x"` becomes `"x-br"` (weak tags too), as nginx and Caddy do.
99fn tag_etag(response: &mut Response, encoding: Encoding) {
100    for header in response.headers.iter_mut().filter(|h| h.name.eq_ignore_ascii_case(Header::_ETAG)) {
101        let value = header.value.trim();
102        if let Some(quoted) = value.strip_suffix('"') {
103            let mut tagged = String::with_capacity(value.len() + 6);
104            tagged.push_str(quoted);
105            tagged.push('-');
106            tagged.push_str(encoding.token());
107            tagged.push('"');
108            header.value = tagged.into();
109        }
110    }
111}
112
113/// A content coding rws can produce. `Brotli` and `Zstd` need the `brotli`
114/// and `zstd` features (both default); without them they are never chosen.
115#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
116pub enum Encoding {
117    Gzip,
118    Brotli,
119    Zstd,
120}
121
122impl Encoding {
123    /// The `Content-Encoding` / `Accept-Encoding` token.
124    pub fn token(self) -> &'static str {
125        match self {
126            Encoding::Gzip => "gzip",
127            Encoding::Brotli => "br",
128            Encoding::Zstd => "zstd",
129        }
130    }
131
132    /// Whether this build can produce it.
133    pub fn available(self) -> bool {
134        match self {
135            Encoding::Gzip => true,
136            Encoding::Brotli => cfg!(feature = "brotli"),
137            Encoding::Zstd => cfg!(feature = "zstd"),
138        }
139    }
140}
141
142/// Order of preference for responses compressed per request, when the client
143/// accepts several equally: zstd costs the least CPU at a ratio close to
144/// brotli's at the levels used here.
145pub const DYNAMIC_PREFERENCE: &[Encoding] = &[Encoding::Zstd, Encoding::Brotli, Encoding::Gzip];
146
147/// Order of preference for static files, compressed once per file version:
148/// brotli's smaller output wins.
149pub const STATIC_PREFERENCE: &[Encoding] = &[Encoding::Brotli, Encoding::Zstd, Encoding::Gzip];
150
151/// How hard to compress.
152#[derive(Clone, Copy, Debug, PartialEq, Eq)]
153pub enum Level {
154    /// For a body compressed on every request: fast levels (brotli 4, zstd 3,
155    /// gzip 6 — what Caddy and nginx use). Brotli's default quality, 11, is
156    /// about a hundred times slower than gzip.
157    Dynamic,
158    /// For a static file compressed once per version and cached: a notch
159    /// higher (brotli 6, zstd 6, gzip 6).
160    Static,
161}
162
163/// Brotli quality per [`Level`].
164pub const BROTLI_QUALITY: [u32; 2] = [4, 6];
165/// zstd level per [`Level`].
166pub const ZSTD_LEVEL: [i32; 2] = [3, 6];
167
168impl Level {
169    fn index(self) -> usize {
170        match self {
171            Level::Dynamic => 0,
172            Level::Static => 1,
173        }
174    }
175}
176
177/// The coding to use for this request among `preference` (in that order of
178/// preference on equal weight): the one with the highest `q` in its
179/// `Accept-Encoding`, counting `*` for codings not listed; `None` without the
180/// header, or when nothing in `preference` is acceptable or compiled in.
181pub fn negotiate(request: &Request, preference: &[Encoding]) -> Option<Encoding> {
182    let header = request.header(Header::_ACCEPT_ENCODING)?;
183    let mut best: Option<(Encoding, f32)> = None;
184    for &encoding in preference.iter().filter(|e| e.available()) {
185        let q = accepted_weight(&header.value, encoding.token());
186        if q > 0.0 && best.is_none_or(|(_, best_q)| q > best_q) {
187            best = Some((encoding, q));
188        }
189    }
190    best.map(|(encoding, _)| encoding)
191}
192
193/// `token`'s weight in an `Accept-Encoding` value: its own entry's `q`
194/// (1 when absent or unparsable), else the `*` entry's, else 0.
195fn accepted_weight(value: &str, token: &str) -> f32 {
196    let mut wildcard = None;
197    for coding in value.split(',') {
198        let mut parts = coding.split(';');
199        let name = parts.next().unwrap_or("").trim();
200        let q = parts
201            .find_map(|p| {
202                let p = p.trim();
203                // Bytes, not a str slice: `p` may start with a multi-byte
204                // character, and `p[..2]` would panic (found by fuzzing).
205                p.as_bytes().get(..2).is_some_and(|b| b.eq_ignore_ascii_case(b"q=")).then(|| p[2..].trim().parse::<f32>().ok())
206            })
207            .flatten()
208            .filter(|q| (0.0..=1.0).contains(q))
209            .unwrap_or(1.0);
210        if name.eq_ignore_ascii_case(token) {
211            return q;
212        }
213        if name == "*" {
214            wildcard = Some(q);
215        }
216    }
217    wildcard.unwrap_or(0.0)
218}
219
220/// `body` in `encoding` at `level`; `None` if this build can't produce it or
221/// the encoder fails.
222pub fn encode(encoding: Encoding, body: &[u8], level: Level) -> Option<Vec<u8>> {
223    match encoding {
224        Encoding::Gzip => gzip(body),
225        #[cfg(feature = "brotli")]
226        Encoding::Brotli => {
227            let mut out = Vec::with_capacity(body.len() / 3 + 64);
228            {
229                let mut writer = brotli::CompressorWriter::new(&mut out, 4096, BROTLI_QUALITY[level.index()], 22);
230                writer.write_all(body).ok()?;
231                writer.flush().ok()?;
232            }
233            Some(out)
234        }
235        #[cfg(feature = "zstd")]
236        Encoding::Zstd => zstd::bulk::compress(body, ZSTD_LEVEL[level.index()]).ok(),
237        #[allow(unreachable_patterns)]
238        _ => {
239            let _ = level;
240            None
241        }
242    }
243}
244
245/// The headers of a body in `encoding`: `Content-Encoding`, and
246/// `Accept-Encoding` appended to `Vary` (or a new `Vary`).
247pub fn mark_encoded(response: &mut Response, encoding: Encoding) {
248    response.headers.push(Header {
249        name: Header::_CONTENT_ENCODING.into(),
250        value: encoding.token().into(),
251    });
252    add_vary_accept_encoding(response);
253}
254
255/// Whether a body of this `Content-Type` is worth compressing ([`COMPRESSIBLE`]
256/// prefixes, case-insensitive).
257pub(crate) fn is_compressible(content_type: &str) -> bool {
258    COMPRESSIBLE.iter().any(|mime| {
259        content_type.len() >= mime.len() && content_type.as_bytes()[..mime.len()].eq_ignore_ascii_case(mime.as_bytes())
260    })
261}
262
263/// `body` gzip-compressed at the default level, as [`apply_gzip`] sends it.
264pub(crate) fn gzip(body: &[u8]) -> Option<Vec<u8>> {
265    let mut encoder = GzEncoder::new(Vec::new(), Compression::default());
266    encoder.write_all(body).ok()?;
267    encoder.finish().ok()
268}
269
270fn add_vary_accept_encoding(response: &mut Response) {
271    let vary_pos = response.headers.iter().position(|h| h.name == Header::_VARY);
272    if let Some(i) = vary_pos {
273        let current = response.headers[i].value.clone();
274        if !current.to_lowercase().contains("accept-encoding") {
275            response.headers[i].value = format!("{}, Accept-Encoding", current).into();
276        }
277    } else {
278        response.headers.push(Header {
279            name: Header::_VARY.into(),
280            value: "Accept-Encoding".into(),
281        });
282    }
283}
rust_web_server/compression/mod.rs

rust_web_server/compression/
mod.rs
