alloy_rlp/
header.rs

1use crate::{decode::static_left_pad, Error, Result, EMPTY_LIST_CODE, EMPTY_STRING_CODE};
2use bytes::{Buf, BufMut};
3use core::hint::unreachable_unchecked;
4
5/// The header of an RLP item.
6#[derive(Clone, Debug, Default, PartialEq, Eq)]
7pub struct Header {
8    /// True if list, false otherwise.
9    pub list: bool,
10    /// Length of the payload in bytes.
11    pub payload_length: usize,
12}
13
14impl Header {
15    /// Decodes an RLP header from the given buffer.
16    ///
17    /// # Errors
18    ///
19    /// Returns an error if the buffer is too short or the header is invalid.
20    #[inline]
21    pub fn decode(buf: &mut &[u8]) -> Result<Self> {
22        let payload_length;
23        let mut list = false;
24        match get_next_byte(buf)? {
25            0..=0x7F => payload_length = 1,
26
27            b @ EMPTY_STRING_CODE..=0xB7 => {
28                buf.advance(1);
29                payload_length = (b - EMPTY_STRING_CODE) as usize;
30                if payload_length == 1 && get_next_byte(buf)? < EMPTY_STRING_CODE {
31                    return Err(Error::NonCanonicalSingleByte);
32                }
33            }
34
35            b @ (0xB8..=0xBF | 0xF8..=0xFF) => {
36                buf.advance(1);
37
38                list = b >= 0xF8; // second range
39                let code = if list { 0xF7 } else { 0xB7 };
40
41                // SAFETY: `b - code` is always in the range `1..=8` in the current match arm.
42                // The compiler/LLVM apparently cannot prove this because of the `|` pattern +
43                // the above `if`, since it can do it in the other arms with only 1 range.
44                let len_of_len = unsafe { b.checked_sub(code).unwrap_unchecked() } as usize;
45                if len_of_len == 0 || len_of_len > 8 {
46                    unsafe { unreachable_unchecked() }
47                }
48
49                if buf.len() < len_of_len {
50                    return Err(Error::InputTooShort);
51                }
52                // SAFETY: length checked above
53                let len = unsafe { buf.get_unchecked(..len_of_len) };
54                buf.advance(len_of_len);
55
56                let len = u64::from_be_bytes(static_left_pad(len)?);
57                payload_length =
58                    usize::try_from(len).map_err(|_| Error::Custom("Input too big"))?;
59                if payload_length < 56 {
60                    return Err(Error::NonCanonicalSize);
61                }
62            }
63
64            b @ EMPTY_LIST_CODE..=0xF7 => {
65                buf.advance(1);
66                list = true;
67                payload_length = (b - EMPTY_LIST_CODE) as usize;
68            }
69        }
70
71        if buf.remaining() < payload_length {
72            return Err(Error::InputTooShort);
73        }
74
75        Ok(Self { list, payload_length })
76    }
77
78    /// Decodes the next payload from the given buffer, advancing it.
79    ///
80    /// # Errors
81    ///
82    /// Returns an error if the buffer is too short or the header is invalid.
83    #[inline]
84    pub fn decode_bytes<'a>(buf: &mut &'a [u8], is_list: bool) -> Result<&'a [u8]> {
85        let Self { list, payload_length } = Self::decode(buf)?;
86
87        if list != is_list {
88            return Err(if is_list { Error::UnexpectedString } else { Error::UnexpectedList });
89        }
90
91        // SAFETY: this is already checked in `decode`
92        let bytes = unsafe { advance_unchecked(buf, payload_length) };
93        Ok(bytes)
94    }
95
96    /// Decodes a string slice from the given buffer, advancing it.
97    ///
98    /// # Errors
99    ///
100    /// Returns an error if the buffer is too short or the header is invalid.
101    #[inline]
102    pub fn decode_str<'a>(buf: &mut &'a [u8]) -> Result<&'a str> {
103        let bytes = Self::decode_bytes(buf, false)?;
104        core::str::from_utf8(bytes).map_err(|_| Error::Custom("invalid string"))
105    }
106
107    /// Extracts the next payload from the given buffer, advancing it.
108    ///
109    /// # Errors
110    ///
111    /// Returns an error if the buffer is too short, the header is invalid or one of the headers one
112    /// level deeper is invalid.
113    #[inline]
114    pub fn decode_raw<'a>(buf: &mut &'a [u8]) -> Result<PayloadView<'a>> {
115        let Self { list, payload_length } = Self::decode(buf)?;
116        // SAFETY: this is already checked in `decode`
117        let mut payload = unsafe { advance_unchecked(buf, payload_length) };
118
119        if !list {
120            return Ok(PayloadView::String(payload));
121        }
122
123        let mut items = alloc::vec::Vec::new();
124        while !payload.is_empty() {
125            // decode the next header without advancing in the payload
126            let Self { payload_length, .. } = Self::decode(&mut &payload[..])?;
127            // the length of the RLP encoding is the length of the header plus its payload length
128            // if payload length is 1 and the first byte is in [0x00, 0x7F], then there is no header
129            let rlp_length = if payload_length == 1 && payload[0] <= 0x7F {
130                1
131            } else {
132                payload_length + crate::length_of_length(payload_length)
133            };
134            items.push(&payload[..rlp_length]);
135            payload.advance(rlp_length);
136        }
137
138        return Ok(PayloadView::List(items));
139    }
140
141    /// Encodes the header into the `out` buffer.
142    #[inline]
143    pub fn encode(&self, out: &mut dyn BufMut) {
144        if self.payload_length < 56 {
145            let code = if self.list { EMPTY_LIST_CODE } else { EMPTY_STRING_CODE };
146            out.put_u8(code + self.payload_length as u8);
147        } else {
148            let len_be;
149            let len_be = crate::encode::to_be_bytes_trimmed!(len_be, self.payload_length);
150            let code = if self.list { 0xF7 } else { 0xB7 };
151            out.put_u8(code + len_be.len() as u8);
152            out.put_slice(len_be);
153        }
154    }
155
156    /// Returns the length of the encoded header.
157    #[inline]
158    pub const fn length(&self) -> usize {
159        crate::length_of_length(self.payload_length)
160    }
161}
162
163/// Structured representation of an RLP payload.
164pub enum PayloadView<'a> {
165    /// Payload is a byte string.
166    String(&'a [u8]),
167    /// Payload is a list of RLP encoded data.
168    List(alloc::vec::Vec<&'a [u8]>),
169}
170
171/// Same as `buf.first().ok_or(Error::InputTooShort)`.
172#[inline(always)]
173fn get_next_byte(buf: &[u8]) -> Result<u8> {
174    if buf.is_empty() {
175        return Err(Error::InputTooShort);
176    }
177    // SAFETY: length checked above
178    Ok(*unsafe { buf.get_unchecked(0) })
179}
180
181/// Same as `let (bytes, rest) = buf.split_at(cnt); *buf = rest; bytes`.
182#[inline(always)]
183unsafe fn advance_unchecked<'a>(buf: &mut &'a [u8], cnt: usize) -> &'a [u8] {
184    if buf.remaining() < cnt {
185        unreachable_unchecked()
186    }
187    let bytes = &buf[..cnt];
188    buf.advance(cnt);
189    bytes
190}
191
192#[cfg(test)]
193mod tests {
194    use super::*;
195    use crate::Encodable;
196    use alloc::vec::Vec;
197    use core::fmt::Debug;
198
199    fn check_decode_raw_list<T: Encodable + Debug>(input: Vec<T>) {
200        let encoded = crate::encode(&input);
201        let expected: Vec<_> = input.iter().map(crate::encode).collect();
202        let mut buf = encoded.as_slice();
203        assert!(
204            matches!(Header::decode_raw(&mut buf), Ok(PayloadView::List(v)) if v == expected),
205            "input: {:?}, expected list: {:?}",
206            input,
207            expected
208        );
209        assert!(buf.is_empty(), "buffer was not advanced");
210    }
211
212    fn check_decode_raw_string(input: &str) {
213        let encoded = crate::encode(input);
214        let expected = Header::decode_bytes(&mut &encoded[..], false).unwrap();
215        let mut buf = encoded.as_slice();
216        assert!(
217            matches!(Header::decode_raw(&mut buf), Ok(PayloadView::String(v)) if v == expected),
218            "input: {}, expected string: {:?}",
219            input,
220            expected
221        );
222        assert!(buf.is_empty(), "buffer was not advanced");
223    }
224
225    #[test]
226    fn decode_raw() {
227        // empty list
228        check_decode_raw_list(Vec::<u64>::new());
229        // list of an empty RLP list
230        check_decode_raw_list(vec![Vec::<u64>::new()]);
231        // list of an empty RLP string
232        check_decode_raw_list(vec![""]);
233        // list of two RLP strings
234        check_decode_raw_list(vec![0xBBCCB5_u64, 0xFFC0B5_u64]);
235        // list of three RLP lists of various lengths
236        check_decode_raw_list(vec![vec![0u64], vec![1u64, 2u64], vec![3u64, 4u64, 5u64]]);
237        // list of four empty RLP strings
238        check_decode_raw_list(vec![0u64; 4]);
239        // list of all one-byte strings, some will have an RLP header and some won't
240        check_decode_raw_list((0u64..0xFF).collect());
241
242        // strings of various lengths
243        check_decode_raw_string("");
244        check_decode_raw_string(" ");
245        check_decode_raw_string("test1234");
246    }
247}
alloy_rlp/header.rs

alloy_rlp/
header.rs
