Skip to main content

nevo_messaging/
compression.rs

1//! Payload compression negotiated through the `content-encoding` header.
2
3use bytes::Bytes;
4
5use crate::error::{Error, Result};
6
7#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
8pub enum Encoding {
9    #[default]
10    Identity,
11    Gzip,
12    Deflate,
13    Zstd,
14}
15
16impl Encoding {
17    pub fn parse(value: &str) -> Option<Self> {
18        match value.trim() {
19            "" | "identity" => Some(Self::Identity),
20            "gzip" => Some(Self::Gzip),
21            "deflate" => Some(Self::Deflate),
22            "zstd" => Some(Self::Zstd),
23            _ => None,
24        }
25    }
26
27    pub fn as_str(self) -> &'static str {
28        match self {
29            Self::Identity => "identity",
30            Self::Gzip => "gzip",
31            Self::Deflate => "deflate",
32            Self::Zstd => "zstd",
33        }
34    }
35
36    pub fn is_identity(self) -> bool {
37        self == Self::Identity
38    }
39}
40
41impl std::fmt::Display for Encoding {
42    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
43        f.write_str(self.as_str())
44    }
45}
46
47impl serde::Serialize for Encoding {
48    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
49        serializer.serialize_str(self.as_str())
50    }
51}
52
53impl<'de> serde::Deserialize<'de> for Encoding {
54    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
55        let raw = <std::borrow::Cow<'de, str>>::deserialize(deserializer)?;
56        Self::parse(&raw).ok_or_else(|| {
57            serde::de::Error::custom(format!("unsupported content encoding {raw:?}"))
58        })
59    }
60}
61
62#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
63pub enum Algorithm {
64    #[default]
65    Gzip,
66    Deflate,
67    Zstd,
68}
69
70impl Algorithm {
71    pub fn encoding(self) -> Encoding {
72        match self {
73            Self::Gzip => Encoding::Gzip,
74            Self::Deflate => Encoding::Deflate,
75            Self::Zstd => Encoding::Zstd,
76        }
77    }
78}
79
80/// Outbound compression policy. Disabled by default.
81#[derive(Debug, Clone, PartialEq, Eq)]
82#[non_exhaustive]
83pub struct Compression {
84    pub enabled: bool,
85    pub algorithm: Algorithm,
86    pub threshold: usize,
87    pub level: u32,
88}
89
90impl Default for Compression {
91    fn default() -> Self {
92        Self {
93            enabled: false,
94            algorithm: Algorithm::Gzip,
95            threshold: 1024,
96            level: 6,
97        }
98    }
99}
100
101impl Compression {
102    pub fn disabled() -> Self {
103        Self::default()
104    }
105
106    pub fn gzip() -> Self {
107        Self::with(Algorithm::Gzip)
108    }
109
110    pub fn deflate() -> Self {
111        Self::with(Algorithm::Deflate)
112    }
113
114    pub fn zstd() -> Self {
115        Self::with(Algorithm::Zstd)
116    }
117
118    pub fn with(algorithm: Algorithm) -> Self {
119        Self {
120            enabled: true,
121            algorithm,
122            ..Self::default()
123        }
124    }
125
126    pub fn threshold(mut self, bytes: usize) -> Self {
127        self.threshold = bytes;
128        self
129    }
130
131    pub fn level(mut self, level: u32) -> Self {
132        self.level = level;
133        self
134    }
135
136    fn applies_to(&self, len: usize) -> bool {
137        self.enabled && len >= self.threshold
138    }
139}
140
141/// Compresses `data` when the policy asks for it; identity otherwise.
142pub fn compress(data: Bytes, policy: &Compression) -> Result<(Bytes, Encoding)> {
143    if !policy.applies_to(data.len()) {
144        return Ok((data, Encoding::Identity));
145    }
146    compress_with(data, policy.algorithm, policy.level)
147}
148
149#[cfg(feature = "compression")]
150fn compress_with(data: Bytes, algorithm: Algorithm, level: u32) -> Result<(Bytes, Encoding)> {
151    use std::io::Write;
152
153    let io_err = |e: std::io::Error| Error::internal(format!("compression failed: {e}"));
154    match algorithm {
155        Algorithm::Gzip => {
156            let mut enc = flate2::write::GzEncoder::new(
157                Vec::with_capacity(data.len() / 2),
158                flate2::Compression::new(level.min(9)),
159            );
160            enc.write_all(&data).map_err(io_err)?;
161            Ok((Bytes::from(enc.finish().map_err(io_err)?), Encoding::Gzip))
162        }
163        Algorithm::Deflate => {
164            let mut enc = flate2::write::ZlibEncoder::new(
165                Vec::with_capacity(data.len() / 2),
166                flate2::Compression::new(level.min(9)),
167            );
168            enc.write_all(&data).map_err(io_err)?;
169            Ok((
170                Bytes::from(enc.finish().map_err(io_err)?),
171                Encoding::Deflate,
172            ))
173        }
174        #[cfg(feature = "zstd")]
175        Algorithm::Zstd => {
176            let out =
177                zstd::stream::encode_all(&data[..], level.clamp(1, 22) as i32).map_err(io_err)?;
178            Ok((Bytes::from(out), Encoding::Zstd))
179        }
180        #[cfg(not(feature = "zstd"))]
181        Algorithm::Zstd => {
182            tracing::warn!(
183                event = "compression.zstd_unavailable",
184                "zstd feature is disabled; falling back to gzip"
185            );
186            compress_with(data, Algorithm::Gzip, level)
187        }
188    }
189}
190
191#[cfg(not(feature = "compression"))]
192fn compress_with(data: Bytes, _algorithm: Algorithm, _level: u32) -> Result<(Bytes, Encoding)> {
193    tracing::warn!(
194        event = "compression.unavailable",
195        "compression feature is disabled; sending identity payload"
196    );
197    Ok((data, Encoding::Identity))
198}
199
200/// Inflates `data`, refusing to allocate more than `max_output` bytes.
201pub fn decompress(data: Bytes, encoding: Encoding, max_output: usize) -> Result<Bytes> {
202    if encoding.is_identity() {
203        return Ok(data);
204    }
205    decompress_with(data, encoding, max_output)
206}
207
208#[cfg(feature = "compression")]
209fn decompress_with(data: Bytes, encoding: Encoding, max_output: usize) -> Result<Bytes> {
210    use std::io::Read;
211
212    fn drain(mut reader: impl Read, max_output: usize) -> Result<Bytes> {
213        let mut out = Vec::new();
214        let limit = max_output as u64 + 1;
215        reader
216            .by_ref()
217            .take(limit)
218            .read_to_end(&mut out)
219            .map_err(|e| Error::parse(format!("decompression failed: {e}")))?;
220        if out.len() > max_output {
221            return Err(Error::payload_too_large(out.len(), max_output));
222        }
223        Ok(Bytes::from(out))
224    }
225
226    match encoding {
227        Encoding::Identity => Ok(data),
228        Encoding::Gzip => drain(flate2::read::GzDecoder::new(&data[..]), max_output),
229        Encoding::Deflate => drain(flate2::read::ZlibDecoder::new(&data[..]), max_output),
230        #[cfg(feature = "zstd")]
231        Encoding::Zstd => {
232            let decoder = zstd::stream::Decoder::new(&data[..])
233                .map_err(|e| Error::parse(format!("decompression failed: {e}")))?;
234            drain(decoder, max_output)
235        }
236        #[cfg(not(feature = "zstd"))]
237        Encoding::Zstd => Err(Error::bad_request(
238            "zstd payload received but the zstd feature is disabled",
239        )),
240    }
241}
242
243#[cfg(not(feature = "compression"))]
244fn decompress_with(_data: Bytes, encoding: Encoding, _max_output: usize) -> Result<Bytes> {
245    Err(Error::bad_request(format!(
246        "{encoding} payload received but the compression feature is disabled"
247    )))
248}
249
250#[cfg(all(test, feature = "compression"))]
251mod tests {
252    use super::*;
253
254    #[test]
255    fn round_trip_gzip_and_deflate() {
256        let original = Bytes::from("hello world ".repeat(200));
257        for policy in [
258            Compression::gzip().threshold(1),
259            Compression::deflate().threshold(1),
260        ] {
261            let (packed, encoding) = compress(original.clone(), &policy).unwrap();
262            assert_eq!(encoding, policy.algorithm.encoding());
263            assert!(packed.len() < original.len());
264            let back = decompress(packed, encoding, 1 << 20).unwrap();
265            assert_eq!(back, original);
266        }
267    }
268
269    #[test]
270    fn below_threshold_is_identity() {
271        let (out, enc) = compress(Bytes::from_static(b"tiny"), &Compression::gzip()).unwrap();
272        assert_eq!(enc, Encoding::Identity);
273        assert_eq!(&out[..], b"tiny");
274    }
275
276    #[test]
277    fn bombs_are_rejected_before_full_allocation() {
278        let zeros = Bytes::from(vec![0u8; 8 * 1024 * 1024]);
279        let (bomb, enc) = compress(zeros, &Compression::gzip().threshold(1)).unwrap();
280        assert!(bomb.len() < 64 * 1024);
281        let err = decompress(bomb, enc, 1024 * 1024).unwrap_err();
282        assert_eq!(err.code(), crate::ErrorCode::PayloadTooLarge);
283    }
284
285    #[test]
286    fn encoding_parsing() {
287        assert_eq!(Encoding::parse("gzip"), Some(Encoding::Gzip));
288        assert_eq!(Encoding::parse(""), Some(Encoding::Identity));
289        assert_eq!(Encoding::parse("br"), None);
290    }
291}