Skip to main content

zigbee_primitives/
wire.rs

1//! A bounds-checked little-endian reader and writer for frame parsing.
2//!
3//! [`Reader`] never panics: every read returns [`Truncated`] when the input
4//! runs out, so parsers built on it turn malformed input into errors.
5
6use crate::{ExtPanId, Ieee, Key};
7
8/// The input ended before the value being read.
9#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
10#[error("frame truncated: needed {needed} more bytes at offset {offset}")]
11pub struct Truncated {
12    /// Offset of the read that failed.
13    pub offset: usize,
14    /// Bytes that were missing.
15    pub needed: usize,
16}
17
18/// A cursor over a byte slice that reads little-endian values.
19#[derive(Debug, Clone)]
20pub struct Reader<'a> {
21    buf: &'a [u8],
22    pos: usize,
23}
24
25impl<'a> Reader<'a> {
26    /// A reader at the start of `buf`.
27    pub fn new(buf: &'a [u8]) -> Self {
28        Reader { buf, pos: 0 }
29    }
30
31    /// Bytes not yet read.
32    pub fn remaining(&self) -> usize {
33        self.buf.len().saturating_sub(self.pos)
34    }
35
36    /// True when everything has been read.
37    pub fn is_empty(&self) -> bool {
38        self.remaining() == 0
39    }
40
41    /// Current offset from the start.
42    pub fn position(&self) -> usize {
43        self.pos
44    }
45
46    /// The next `n` bytes.
47    pub fn bytes(&mut self, n: usize) -> Result<&'a [u8], Truncated> {
48        let end = self.pos.checked_add(n).filter(|end| *end <= self.buf.len());
49        match end.and_then(|end| self.buf.get(self.pos..end)) {
50            Some(slice) => {
51                self.pos += n;
52                Ok(slice)
53            }
54            None => Err(Truncated {
55                offset: self.pos,
56                needed: n.saturating_sub(self.remaining()),
57            }),
58        }
59    }
60
61    /// Everything not yet read.
62    pub fn rest(&mut self) -> &'a [u8] {
63        let rest = self.buf.get(self.pos..).unwrap_or(&[]);
64        self.pos = self.buf.len();
65        rest
66    }
67
68    /// A fixed-size array.
69    pub fn array<const N: usize>(&mut self) -> Result<[u8; N], Truncated> {
70        let mut out = [0u8; N];
71        out.copy_from_slice(self.bytes(N)?);
72        Ok(out)
73    }
74
75    /// One byte.
76    pub fn u8(&mut self) -> Result<u8, Truncated> {
77        Ok(self.array::<1>()?[0])
78    }
79
80    /// One signed byte.
81    pub fn i8(&mut self) -> Result<i8, Truncated> {
82        Ok(self.u8()? as i8)
83    }
84
85    /// A little-endian `u16`.
86    pub fn u16(&mut self) -> Result<u16, Truncated> {
87        Ok(u16::from_le_bytes(self.array()?))
88    }
89
90    /// A little-endian `u32`.
91    pub fn u32(&mut self) -> Result<u32, Truncated> {
92        Ok(u32::from_le_bytes(self.array()?))
93    }
94
95    /// A little-endian `u64`.
96    pub fn u64(&mut self) -> Result<u64, Truncated> {
97        Ok(u64::from_le_bytes(self.array()?))
98    }
99
100    /// A little-endian unsigned integer of `width` bytes (1 to 8).
101    pub fn uint_n(&mut self, width: usize) -> Result<u64, Truncated> {
102        let bytes = self.bytes(width.min(8))?;
103        Ok(bytes
104            .iter()
105            .rev()
106            .fold(0u64, |acc, b| (acc << 8) | u64::from(*b)))
107    }
108
109    /// A boolean byte (non-zero is true).
110    pub fn bool(&mut self) -> Result<bool, Truncated> {
111        Ok(self.u8()? != 0)
112    }
113
114    /// An IEEE address in wire order.
115    pub fn ieee(&mut self) -> Result<Ieee, Truncated> {
116        Ok(Ieee::from_le_bytes(self.array()?))
117    }
118
119    /// An extended PAN id in wire order.
120    pub fn ext_pan_id(&mut self) -> Result<ExtPanId, Truncated> {
121        Ok(ExtPanId::from_le_bytes(self.array()?))
122    }
123
124    /// A 16-byte key, in byte order.
125    pub fn key(&mut self) -> Result<Key, Truncated> {
126        Ok(Key(self.array()?))
127    }
128
129    /// A byte string prefixed by a one-byte length.
130    pub fn u8_prefixed(&mut self) -> Result<&'a [u8], Truncated> {
131        let len = self.u8()?;
132        self.bytes(usize::from(len))
133    }
134
135    /// `count` little-endian `u16` values.
136    pub fn u16_list(&mut self, count: usize) -> Result<Vec<u16>, Truncated> {
137        // Check the length first so a large count cannot allocate.
138        let raw = self.bytes(count.saturating_mul(2))?;
139        Ok(raw
140            .as_chunks::<2>()
141            .0
142            .iter()
143            .map(|c| u16::from_le_bytes(*c))
144            .collect())
145    }
146}
147
148/// Little-endian writers for `Vec<u8>`.
149pub trait Writer {
150    /// Append one byte.
151    fn put_u8(&mut self, v: u8);
152    /// Append a little-endian `u16`.
153    fn put_u16(&mut self, v: u16);
154    /// Append a little-endian `u32`.
155    fn put_u32(&mut self, v: u32);
156    /// Append a little-endian `u64`.
157    fn put_u64(&mut self, v: u64);
158    /// Append the low `width` bytes of `v`, little-endian.
159    fn put_uint_n(&mut self, v: u64, width: usize);
160    /// Append bytes.
161    fn put_bytes(&mut self, v: &[u8]);
162    /// Append an IEEE address in wire order.
163    fn put_ieee(&mut self, v: Ieee);
164    /// Append an extended PAN id in wire order.
165    fn put_ext_pan_id(&mut self, v: ExtPanId);
166    /// Append a key in byte order.
167    fn put_key(&mut self, v: &Key);
168    /// Append a byte string with a one-byte length prefix, truncated to 255.
169    fn put_u8_prefixed(&mut self, v: &[u8]);
170}
171
172impl Writer for Vec<u8> {
173    fn put_u8(&mut self, v: u8) {
174        self.push(v);
175    }
176    fn put_u16(&mut self, v: u16) {
177        self.extend_from_slice(&v.to_le_bytes());
178    }
179    fn put_u32(&mut self, v: u32) {
180        self.extend_from_slice(&v.to_le_bytes());
181    }
182    fn put_u64(&mut self, v: u64) {
183        self.extend_from_slice(&v.to_le_bytes());
184    }
185    fn put_uint_n(&mut self, v: u64, width: usize) {
186        let bytes = v.to_le_bytes();
187        self.extend_from_slice(bytes.get(..width.min(8)).unwrap_or(&bytes));
188    }
189    fn put_bytes(&mut self, v: &[u8]) {
190        self.extend_from_slice(v);
191    }
192    fn put_ieee(&mut self, v: Ieee) {
193        self.extend_from_slice(&v.to_le_bytes());
194    }
195    fn put_ext_pan_id(&mut self, v: ExtPanId) {
196        self.extend_from_slice(&v.to_le_bytes());
197    }
198    fn put_key(&mut self, v: &Key) {
199        self.extend_from_slice(&v.0);
200    }
201    fn put_u8_prefixed(&mut self, v: &[u8]) {
202        let v = v.get(..v.len().min(255)).unwrap_or(v);
203        self.push(v.len() as u8);
204        self.extend_from_slice(v);
205    }
206}
207
208#[cfg(test)]
209mod tests {
210    use super::*;
211
212    #[test]
213    fn reads_and_reports_truncation() {
214        let mut r = Reader::new(&[1, 2, 3, 4, 5]);
215        assert_eq!(r.u16().unwrap(), 0x0201);
216        assert_eq!(r.uint_n(3).unwrap(), 0x050403);
217        assert_eq!(
218            r.u8(),
219            Err(Truncated {
220                offset: 5,
221                needed: 1
222            })
223        );
224        let mut r = Reader::new(&[3, 1]);
225        assert!(r.u8_prefixed().is_err());
226        let mut r = Reader::new(&[]);
227        assert!(r.u16_list(usize::MAX).is_err());
228    }
229
230    #[test]
231    fn writes_little_endian() {
232        let mut w = Vec::new();
233        w.put_u16(0x1234);
234        w.put_uint_n(0xAABBCC, 3);
235        w.put_u8_prefixed(b"hi");
236        assert_eq!(w, [0x34, 0x12, 0xCC, 0xBB, 0xAA, 2, b'h', b'i']);
237    }
238}