httlib_protos/decoder/
mod.rs

1//! Provides an implementation of the `proto3` decoder.
2//! 
3//! The decoder performs the task of translating encoded binary data into actual
4//! data fields.
5//! 
6//! ```txt
7//! +-------------------+------------------+-------------------+
8//! +      1. JSON      +   2. Transform   +     3. Encode     + ENCODER
9//! +-------------------+------------------+-------------------+
10//! + {                 +                  +                   +
11//! +   "name": "John", + 1, John          + 0a 04 4a 6f 68 6e +
12//! +   "age": 35       + 2, 35            + 10 23             +
13//! + }                 +                  +                   +
14//! +-------------------+------------------+-------------------+
15//! +      6. JSON      +    5. Rebuild    +     4. Decode     + DECODER
16//! +-------------------+------------------+-------------------+
17//! ```
18//! 
19//! The decoder decodes a binary stream back to the original message.
20
21mod error;
22mod lit;
23mod primitives;
24
25use crate::Typ;
26pub use error::*;
27pub use lit::*;
28use primitives::*;
29
30/// Provides the decoding engine for Protocol Buffers.
31pub struct Decoder {
32    /// A key with tag number and wire type of the currently decoding field.
33    key: (u32, Typ),
34
35    /// The number of bytes that need to be read for the currently decoding
36    /// length-delimited field.
37    ld_len: Option<u64>,
38}
39
40impl Decoder {
41    /// Decodes `proto3` encoded fields from the provided `buf` and writes the
42    /// result into `dst`.
43    /// 
44    /// The returned fields are tuples of format `(tag, type, bytes)` where the
45    /// returned `bytes` represent the encoded value. The developer should wrap
46    /// each value into the desired `DecoderLit` and call `parse` on it. 
47    /// 
48    /// ```rust
49    /// use httlib_protos::{Decoder, DecoderLit};
50    /// 
51    /// let mut decoder = Decoder::default();
52    /// 
53    /// let mut buf = vec![0x85, 0x35, 0x85];
54    /// 
55    /// let mut dst = vec![];
56    /// let size = decoder.decode(&mut buf, &mut dst).unwrap();
57    /// 
58    /// for (tag, typ, byt) in dst {
59    ///     if tag == 1 {
60    ///         i32::from(DecoderLit::Int32(byt));
61    ///     }
62    /// }
63    /// ```
64    /// 
65    /// This function consumes the buffer only if the decoding succeeds. The
66    /// provided vector will stay untouched in case of an error or insufficient
67    /// data.
68    /// 
69    /// On success, the number of written bytes is returned otherwise an error
70    /// is thrown.
71    pub fn decode(
72        &mut self,
73        buf: &mut Vec<u8>,
74        dst: &mut Vec<(u32, Typ, Vec<u8>)>,
75    ) -> Result<usize, DecoderError> {
76        let mut total = 0;
77        loop {
78            let mut _size = 0;
79            match self.key.1 {
80                Typ::Unknown => {
81                    _size = self.decode_key(buf)?;
82                },
83                Typ::Varint => {
84                    _size = self.extract_varint(buf, dst)?;
85                },
86                Typ::Bit32 => {
87                    _size = self.extract_bit32(buf, dst)?;
88                },
89                Typ::Bit64 => {
90                    _size = self.extract_bit64(buf, dst)?;
91                },
92                Typ::LengthDelimited => {
93                    _size = self.extract_ld(buf, dst)?;
94                },
95            }
96            if _size == 0 {
97                break;
98            }
99            total += _size;
100        }
101        Ok(total)
102    }
103
104    /// Decodes an encoded field key from the provided `buf`.
105    /// 
106    /// This function consumes the buffer only if the decoding succeeds. The
107    /// provided vector will stay untouched in case of an error or insufficient
108    /// data.
109    /// 
110    /// On success, the number of written bytes is returned otherwise an error
111    /// is thrown.
112    fn decode_key(&mut self, buf: &mut Vec<u8>) -> Result<usize, DecoderError> {
113        let size = match decode_key(&buf, &mut self.key) {
114            Ok(size) => size,
115            Err(DecoderError::InputUnderflow) => return Ok(0),
116            Err(e) => return Err(e),
117        };
118        buf.drain(..size);
119        Ok(size)
120    }
121
122    /// Reads bytes for value with wire type `0` from the provided `buf` and
123    /// writes the resulting bytes into `dst`.
124    /// 
125    /// This function consumes the buffer only if the decoding succeeds. The
126    /// provided vector will stay untouched in case of an error or insufficient
127    /// data.
128    /// 
129    /// On success, the number of written bytes is returned otherwise an error
130    /// is thrown.
131    fn extract_varint(
132        &mut self,
133        buf: &mut Vec<u8>,
134        dst: &mut Vec<(u32, Typ, Vec<u8>)>,
135    ) -> Result<usize, DecoderError> {
136        let mut bytes = vec![];
137        let size = match extract_varint(&buf, &mut bytes) {
138            Ok(size) => size,
139            Err(DecoderError::InputUnderflow) => return Ok(0),
140            Err(e) => return Err(e),
141        };
142        dst.push((self.key.0, self.key.1, bytes));
143        buf.drain(..size);
144        self.reset();
145        Ok(size)
146    }
147
148    /// Reads bytes for value with wire type `5` from the provided `buf` and
149    /// writes the resulting bytes into `dst`.
150    /// 
151    /// This function consumes the buffer only if the decoding succeeds. The
152    /// provided vector will stay untouched in case of an error or insufficient
153    /// data.
154    /// 
155    /// On success, the number of written bytes is returned otherwise an error
156    /// is thrown.
157    fn extract_bit32(
158        &mut self,
159        buf: &mut Vec<u8>,
160        dst: &mut Vec<(u32, Typ, Vec<u8>)>,
161    ) -> Result<usize, DecoderError> {
162        let mut bytes = vec![];
163        let size = match extract_bit32(&buf, &mut bytes) {
164            Ok(size) => size,
165            Err(DecoderError::InputUnderflow) => return Ok(0),
166            Err(e) => return Err(e),
167        };
168        dst.push((self.key.0, self.key.1, bytes));
169        buf.drain(..size);
170        self.reset();
171        Ok(size)
172    }
173
174    /// Reads bytes for value with wire type `1` from the provided `buf` and
175    /// writes the resulting bytes into `dst`.
176    /// 
177    /// This function consumes the buffer only if the decoding succeeds. The
178    /// provided vector will stay untouched in case of an error or insufficient
179    /// data.
180    /// 
181    /// On success, the number of written bytes is returned otherwise an error
182    /// is thrown.
183    fn extract_bit64(
184        &mut self,
185        buf: &mut Vec<u8>,
186        dst: &mut Vec<(u32, Typ, Vec<u8>)>,
187    ) -> Result<usize, DecoderError> {
188        let mut bytes = vec![];
189        let size = match extract_bit64(&buf, &mut bytes) {
190            Ok(size) => size,
191            Err(DecoderError::InputUnderflow) => return Ok(0),
192            Err(e) => return Err(e),
193        };
194        dst.push((self.key.0, self.key.1, bytes));
195        buf.drain(..size);
196        self.reset();
197        Ok(size)
198    }
199
200    /// Reads bytes for value with wire type `2` from the provided `buf` and
201    /// writes the resulting bytes into `dst`.
202    /// 
203    /// This function consumes the buffer only if the decoding succeeds. The
204    /// provided vector will stay untouched in case of an error or insufficient
205    /// data.
206    /// 
207    /// On success, the number of written bytes is returned otherwise an error
208    /// is thrown.
209    fn extract_ld(
210        &mut self,
211        buf: &mut Vec<u8>,
212        dst: &mut Vec<(u32, Typ, Vec<u8>)>,
213    ) -> Result<usize, DecoderError> {
214        if self.ld_len.is_some() {
215            self.extract_ld_bytes(buf, dst)
216        } else {
217            self.decode_ld_len(buf)
218        }
219    }
220
221    /// Decodes an encoded length of the currently handled length-delimited
222    /// field from the provided `buf`.
223    /// 
224    /// This function consumes the buffer only if the decoding succeeds. The
225    /// provided vector will stay untouched in case of an error or insufficient
226    /// data.
227    /// 
228    /// On success, the number of written bytes is returned otherwise an error
229    /// is thrown.
230    fn decode_ld_len(
231        &mut self,
232        buf: &mut Vec<u8>,
233    ) -> Result<usize, DecoderError> {
234        let mut val = 0;
235        let size = match decode_varint(&buf, &mut val) {
236            Ok(size) => size,
237            Err(DecoderError::InputUnderflow) => return Ok(0),
238            Err(e) => return Err(e),
239        };
240        self.ld_len = Some(val);
241        buf.drain(..size);
242        Ok(size)
243    }
244
245    /// Reads bytes of the currently handled length-delimited field from the
246    /// provided `buf` and writes the resulting bytes into `dst`.
247    /// 
248    /// This function consumes the buffer only if the decoding succeeds. The
249    /// provided vector will stay untouched in case of an error or insufficient
250    /// data.
251    /// 
252    /// On success, the number of written bytes is returned otherwise an error
253    /// is thrown.
254    fn extract_ld_bytes(
255        &mut self,
256        buf: &mut Vec<u8>,
257        dst: &mut Vec<(u32, Typ, Vec<u8>)>,
258    ) -> Result<usize, DecoderError> {
259        let len = self.ld_len.unwrap();
260        let mut bytes = vec![];
261        let size = match extract_ld(&buf, len, &mut bytes) {
262            Ok(size) => size,
263            Err(DecoderError::InputUnderflow) => return Ok(0),
264            Err(e) => return Err(e),
265        };
266        dst.push((self.key.0, self.key.1, bytes));
267        buf.drain(..size);
268        self.reset();
269        Ok(size)
270    }
271
272    /// Resets the decoder and flushes all memoried data.
273    fn reset(&mut self) {
274        self.key = (0, Typ::Unknown);
275        self.ld_len = None;
276    }
277}
278
279impl<'a> Default for Decoder {
280    fn default() -> Self {
281        Self {
282            key: (0, Typ::Unknown),
283            ld_len: None,
284        }
285    }
286}
287
288#[cfg(test)]
289mod test {
290    use super::*;
291
292    /// Should decode supported formats from Protocol Buffers bytes.
293    #[test]
294    fn decodes_supported() {
295        let mut decoder = Decoder::default();
296        let mut dst = vec![];
297        let mut src = vec![
298            10, 3, 102, 111, 111,
299            16, 1,
300            26, 2, 0, 1,
301            32, 1,
302            42, 11, 156, 255, 255, 255, 255, 255, 255, 255, 255, 1, 100,
303            48, 1,
304            58, 11, 156, 255, 255, 255, 255, 255, 255, 255, 255, 1, 100,
305            64, 1,
306            74, 2, 1, 2,
307            80, 1,
308            90, 2, 1, 2,
309            101, 0, 0, 128, 63,
310            106, 8, 0, 0, 128, 63, 0, 0, 0, 64,
311            113, 0, 0, 0, 0, 0, 0, 240, 63,
312            122, 16, 0, 0, 0, 0, 0, 0, 240, 63, 0, 0, 0, 0, 0, 0, 0, 64,
313            130, 1, 3, 102, 111, 111,
314            136, 1, 19,
315            146, 1, 2, 19, 20,
316            152, 1, 19,
317            162, 1, 2, 19, 20,
318            173, 1, 10, 0, 0, 0,
319            178, 1, 8, 1, 0, 0, 0, 2, 0, 0, 0,
320            185, 1, 10, 0, 0, 0, 0, 0, 0, 0,
321            194, 1, 16, 1, 0, 0, 0, 0, 0, 0, 0, 2, 0, 0, 0, 0, 0, 0, 0,
322            205, 1, 246, 255, 255, 255,
323            210, 1, 8, 246, 255, 255, 255, 10, 0, 0, 0,
324            217, 1, 246, 255, 255, 255, 255, 255, 255, 255,
325            226, 1, 16, 246, 255, 255, 255, 255, 255, 255, 255, 10, 0, 0, 0, 0, 0, 0, 0,
326        ];
327        let size = decoder.decode(&mut src, &mut dst).unwrap(); // decode supported fields
328        let mut index = 0;
329        for (tag, typ, byt) in dst.drain(..) {
330            index += 1;
331            assert_eq!(tag, index);
332            if index == 1 {
333                assert_eq!(typ, Typ::LengthDelimited);
334                assert_eq!(byt, vec![102, 111, 111]);
335                assert_eq!(Vec::<u8>::from(DecoderLit::Bytes(byt)), vec![102, 111, 111]);
336            } else if index == 2 {
337                assert_eq!(typ, Typ::Varint);
338                assert_eq!(bool::from(DecoderLit::Bool(byt)), true);
339            } else if index == 3 {
340                assert_eq!(typ, Typ::LengthDelimited);
341                assert_eq!(Vec::<bool>::from(DecoderLit::BoolVec(byt)), vec![false, true]);
342            } else if index == 4 {
343                assert_eq!(typ, Typ::Varint);
344                assert_eq!(i32::from(DecoderLit::Int32(byt)), 1);
345            } else if index == 5 {
346                assert_eq!(typ, Typ::LengthDelimited);
347                assert_eq!(Vec::<i32>::from(DecoderLit::Int32Vec(byt)), vec![-100i32, 100i32]);
348            } else if index == 6 {
349                assert_eq!(typ, Typ::Varint);
350                assert_eq!(i64::from(DecoderLit::Int64(byt)), 1i64);
351            } else if index == 7 {
352                assert_eq!(typ, Typ::LengthDelimited);
353                assert_eq!(Vec::<i64>::from(DecoderLit::Int64Vec(byt)), vec![-100i64, 100i64]);
354            } else if index == 8 {
355                assert_eq!(typ, Typ::Varint);
356                assert_eq!(u32::from(DecoderLit::UInt32(byt)), 1u32);
357            } else if index == 9 {
358                assert_eq!(typ, Typ::LengthDelimited);
359                assert_eq!(Vec::<u32>::from(DecoderLit::UInt32Vec(byt)), vec![1u32, 2u32]);
360            } else if index == 10 {
361                assert_eq!(typ, Typ::Varint);
362                assert_eq!(u64::from(DecoderLit::UInt64(byt)), 1u64);
363            } else if index == 11 {
364                assert_eq!(typ, Typ::LengthDelimited);
365                assert_eq!(Vec::<u64>::from(DecoderLit::UInt64Vec(byt)), vec![1u64, 2u64]);
366            } else if index == 12 {
367                assert_eq!(typ, Typ::Bit32);
368                assert_eq!(f32::from(DecoderLit::Float(byt)), 1.0f32);
369            } else if index == 13 {
370                assert_eq!(typ, Typ::LengthDelimited);
371                assert_eq!(Vec::<f32>::from(DecoderLit::FloatVec(byt)), vec![1.0f32, 2.0f32]);
372            } else if index == 14 {
373                assert_eq!(typ, Typ::Bit64);
374                assert_eq!(f64::from(DecoderLit::Double(byt)), 1.0f64);
375            } else if index == 15 {
376                assert_eq!(typ, Typ::LengthDelimited);
377                assert_eq!(Vec::<f64>::from(DecoderLit::DoubleVec(byt)), vec![1.0f64, 2.0f64]);
378            } else if index == 16 {
379                assert_eq!(typ, Typ::LengthDelimited);
380                assert_eq!(String::from(DecoderLit::Bytes(byt)), String::from("foo"));
381            } else if index == 17 {
382                assert_eq!(typ, Typ::Varint);
383                assert_eq!(i32::from(DecoderLit::SInt32(byt)), -10);
384            } else if index == 18 {
385                assert_eq!(typ, Typ::LengthDelimited);
386                assert_eq!(Vec::<i32>::from(DecoderLit::SInt32Vec(byt)), vec![-10i32, 10i32]);
387            } else if index == 19 {
388                assert_eq!(typ, Typ::Varint);
389                assert_eq!(i64::from(DecoderLit::SInt64(byt)), -10);
390            } else if index == 20 {
391                assert_eq!(typ, Typ::LengthDelimited);
392                assert_eq!(Vec::<i64>::from(DecoderLit::SInt64Vec(byt)), vec![-10i64, 10i64]);
393            } else if index == 21 {
394                assert_eq!(typ, Typ::Bit32);
395                assert_eq!(u32::from(DecoderLit::Fixed32(byt)), 10);
396            } else if index == 22 {
397                assert_eq!(typ, Typ::LengthDelimited);
398                assert_eq!(Vec::<u32>::from(DecoderLit::Fixed32Vec(byt)), vec![1u32, 2u32]);
399            } else if index == 23 {
400                assert_eq!(typ, Typ::Bit64);
401                assert_eq!(u64::from(DecoderLit::Fixed64(byt)), 10);
402            } else if index == 24 {
403                assert_eq!(typ, Typ::LengthDelimited);
404                assert_eq!(Vec::<u64>::from(DecoderLit::Fixed64Vec(byt)), vec![1u64, 2u64]);
405            } else if index == 25 {
406                assert_eq!(typ, Typ::Bit32);
407                assert_eq!(i32::from(DecoderLit::SFixed32(byt)), -10);
408            } else if index == 26 {
409                assert_eq!(typ, Typ::LengthDelimited);
410                assert_eq!(Vec::<i32>::from(DecoderLit::SFixed32Vec(byt)), vec![-10i32, 10i32]);
411            } else if index == 27 {
412                assert_eq!(typ, Typ::Bit64);
413                assert_eq!(i64::from(DecoderLit::SFixed64(byt)), -10);
414            } else if index == 28 {
415                assert_eq!(typ, Typ::LengthDelimited);
416                assert_eq!(Vec::<i64>::from(DecoderLit::SFixed64Vec(byt)), vec![-10i64, 10i64]);
417            }
418        }
419        assert_eq!(size, 209); // read bytes
420        let mut dst = vec![];
421        let mut src = vec![0];
422        assert!(decoder.decode(&mut src, &mut dst).is_err()); // handles errors
423    }
424}
httlib_protos/decoder/mod.rs

httlib_protos/decoder/
mod.rs
