Skip to main content

ghast_protocol/
codec.rs

1//! Low-level reading and writing of protocol primitives.
2//!
3//! [`Reader`] is a bounds-checked cursor over a [`Bytes`] buffer: every read returns
4//! `Result`, and variable-length data ([`Reader::read_bytes`], strings) is returned as
5//! zero-copy slices of the underlying buffer. [`McWrite`] adds the protocol's primitive
6//! encodings to [`BytesMut`].
7//!
8//! The [`Decode`] / [`Encode`] traits are implemented by every packet and shared type.
9
10use bytes::{BufMut, Bytes, BytesMut};
11use bytestring::ByteString;
12use uuid::Uuid;
13
14use crate::error::{DecodeError, EncodeError};
15
16/// Result alias for decoding.
17pub type DecodeResult<T> = Result<T, DecodeError>;
18/// Result alias for encoding.
19pub type EncodeResult = Result<(), EncodeError>;
20
21/// A value that can be decoded from protocol bytes.
22pub trait Decode: Sized {
23    /// Decodes one value, advancing the reader past it.
24    fn decode(r: &mut Reader<'_>) -> DecodeResult<Self>;
25}
26
27/// A value that can be encoded to protocol bytes.
28pub trait Encode {
29    /// Appends the encoding of `self` to `w`.
30    fn encode(&self, w: &mut BytesMut) -> EncodeResult;
31}
32
33/// Decodes a complete value from `buf`, failing if any bytes are left over.
34pub fn decode_exact<T: Decode>(buf: &Bytes) -> DecodeResult<T> {
35    let mut r = Reader::new(buf);
36    let v = T::decode(&mut r)?;
37    r.finish()?;
38    Ok(v)
39}
40
41/// Encodes a value into a fresh buffer.
42pub fn encode_to_bytes<T: Encode + ?Sized>(v: &T) -> Result<BytesMut, EncodeError> {
43    let mut w = BytesMut::new();
44    v.encode(&mut w)?;
45    Ok(w)
46}
47
48/// Bounds-checked read cursor over a [`Bytes`] buffer.
49#[derive(Debug, Clone)]
50pub struct Reader<'a> {
51    buf: &'a Bytes,
52    pos: usize,
53}
54
55impl<'a> Reader<'a> {
56    /// Creates a reader at the start of `buf`.
57    #[inline]
58    pub fn new(buf: &'a Bytes) -> Self {
59        Reader { buf, pos: 0 }
60    }
61
62    /// Number of unread bytes.
63    #[inline]
64    pub fn remaining(&self) -> usize {
65        self.buf.len() - self.pos
66    }
67
68    /// Current offset from the start of the buffer.
69    #[inline]
70    pub fn position(&self) -> usize {
71        self.pos
72    }
73
74    /// The unread bytes, without consuming them.
75    #[inline]
76    pub fn rest_slice(&self) -> &'a [u8] {
77        &self.buf[self.pos..]
78    }
79
80    /// Fails with [`DecodeError::TrailingBytes`] unless the input is fully consumed.
81    #[inline]
82    pub fn finish(&self) -> DecodeResult<()> {
83        match self.remaining() {
84            0 => Ok(()),
85            n => Err(DecodeError::TrailingBytes(n)),
86        }
87    }
88
89    #[inline]
90    fn eof(&self, n: usize) -> DecodeError {
91        DecodeError::UnexpectedEof {
92            needed: n - self.remaining(),
93        }
94    }
95
96    /// Consumes `n` bytes and returns them as a borrowed slice.
97    #[inline]
98    pub fn take(&mut self, n: usize) -> DecodeResult<&'a [u8]> {
99        if n > self.remaining() {
100            return Err(self.eof(n));
101        }
102        let buf: &'a Bytes = self.buf;
103        let s = &buf[self.pos..self.pos + n];
104        self.pos += n;
105        Ok(s)
106    }
107
108    /// Advances past `n` bytes.
109    #[inline]
110    pub fn skip(&mut self, n: usize) -> DecodeResult<()> {
111        if n > self.remaining() {
112            return Err(self.eof(n));
113        }
114        self.pos += n;
115        Ok(())
116    }
117
118    #[inline]
119    fn take_array<const N: usize>(&mut self) -> DecodeResult<[u8; N]> {
120        let s = self.take(N)?;
121        let mut a = [0u8; N];
122        a.copy_from_slice(s);
123        Ok(a)
124    }
125
126    /// Consumes `n` bytes and returns them as a zero-copy [`Bytes`] slice.
127    #[inline]
128    pub fn read_bytes(&mut self, n: usize) -> DecodeResult<Bytes> {
129        if n > self.remaining() {
130            return Err(self.eof(n));
131        }
132        let b = self.buf.slice(self.pos..self.pos + n);
133        self.pos += n;
134        Ok(b)
135    }
136
137    /// Zero-copy slice of everything read since offset `start` (from [`Reader::position`]).
138    #[inline]
139    pub fn bytes_since(&self, start: usize) -> Bytes {
140        self.buf.slice(start.min(self.pos)..self.pos)
141    }
142
143    /// Consumes and returns everything that is left (protodef `restBuffer`).
144    #[inline]
145    pub fn read_rest(&mut self) -> Bytes {
146        let b = self.buf.slice(self.pos..);
147        self.pos = self.buf.len();
148        b
149    }
150
151    /// Returns the next byte without consuming it.
152    #[inline]
153    pub fn peek_u8(&self) -> DecodeResult<u8> {
154        self.buf
155            .get(self.pos)
156            .copied()
157            .ok_or(DecodeError::UnexpectedEof { needed: 1 })
158    }
159
160    /// Reads an unsigned byte.
161    #[inline]
162    pub fn read_u8(&mut self) -> DecodeResult<u8> {
163        let b = self.peek_u8()?;
164        self.pos += 1;
165        Ok(b)
166    }
167
168    /// Reads a signed byte.
169    #[inline]
170    pub fn read_i8(&mut self) -> DecodeResult<i8> {
171        Ok(self.read_u8()? as i8)
172    }
173
174    /// Reads a boolean. Like vanilla, any non-zero byte is `true`.
175    #[inline]
176    pub fn read_bool(&mut self) -> DecodeResult<bool> {
177        Ok(self.read_u8()? != 0)
178    }
179
180    /// Reads a big-endian `u16`.
181    #[inline]
182    pub fn read_u16(&mut self) -> DecodeResult<u16> {
183        Ok(u16::from_be_bytes(self.take_array()?))
184    }
185
186    /// Reads a big-endian `i16`.
187    #[inline]
188    pub fn read_i16(&mut self) -> DecodeResult<i16> {
189        Ok(i16::from_be_bytes(self.take_array()?))
190    }
191
192    /// Reads a big-endian `i32`.
193    #[inline]
194    pub fn read_i32(&mut self) -> DecodeResult<i32> {
195        Ok(i32::from_be_bytes(self.take_array()?))
196    }
197
198    /// Reads a big-endian `i64`.
199    #[inline]
200    pub fn read_i64(&mut self) -> DecodeResult<i64> {
201        Ok(i64::from_be_bytes(self.take_array()?))
202    }
203
204    /// Reads a big-endian `u32`.
205    #[inline]
206    pub fn read_u32(&mut self) -> DecodeResult<u32> {
207        Ok(u32::from_be_bytes(self.take_array()?))
208    }
209
210    /// Reads a big-endian `u64`.
211    #[inline]
212    pub fn read_u64(&mut self) -> DecodeResult<u64> {
213        Ok(u64::from_be_bytes(self.take_array()?))
214    }
215
216    /// Reads a big-endian IEEE-754 `f32`.
217    #[inline]
218    pub fn read_f32(&mut self) -> DecodeResult<f32> {
219        Ok(f32::from_be_bytes(self.take_array()?))
220    }
221
222    /// Reads a big-endian IEEE-754 `f64`.
223    #[inline]
224    pub fn read_f64(&mut self) -> DecodeResult<f64> {
225        Ok(f64::from_be_bytes(self.take_array()?))
226    }
227
228    /// Reads a UUID (two big-endian 64-bit halves).
229    #[inline]
230    pub fn read_uuid(&mut self) -> DecodeResult<Uuid> {
231        Ok(Uuid::from_u128(u128::from_be_bytes(self.take_array()?)))
232    }
233
234    /// Reads a VarInt (at most 5 bytes).
235    ///
236    /// Like vanilla, the unused high bits of a 5th byte are ignored; a 6th byte is an
237    /// error ([`DecodeError::VarIntTooLong`]).
238    #[inline]
239    pub fn read_varint(&mut self) -> DecodeResult<i32> {
240        let rest = &self.buf[self.pos..];
241        if let Some(&b) = rest.first()
242            && b < 0x80
243        {
244            self.pos += 1;
245            return Ok(i32::from(b));
246        }
247        let (v, n) = varint_slow(rest)?;
248        self.pos += n;
249        Ok(v)
250    }
251
252    /// Reads a VarLong (at most 10 bytes).
253    #[inline]
254    pub fn read_varlong(&mut self) -> DecodeResult<i64> {
255        let rest = &self.buf[self.pos..];
256        let mut result: u64 = 0;
257        for i in 0..10 {
258            let Some(&b) = rest.get(i) else {
259                return Err(DecodeError::UnexpectedEof { needed: 1 });
260            };
261            result |= u64::from(b & 0x7f) << (7 * i);
262            if b & 0x80 == 0 {
263                self.pos += i + 1;
264                return Ok(result as i64);
265            }
266        }
267        Err(DecodeError::VarIntTooLong)
268    }
269
270    /// Reads a non-negative length of type `i32` and checks it against `limit`.
271    #[inline]
272    fn check_len(len: i64, limit: usize) -> DecodeResult<usize> {
273        if len < 0 {
274            return Err(DecodeError::NegativeLength(len));
275        }
276        let len = len as usize;
277        if len > limit {
278            return Err(DecodeError::LengthTooLarge { len, limit });
279        }
280        Ok(len)
281    }
282
283    /// Reads a VarInt length prefix and checks it is non-negative and at most `limit`.
284    #[inline]
285    pub fn read_len_varint(&mut self, limit: usize) -> DecodeResult<usize> {
286        let n = self.read_varint()?;
287        Self::check_len(i64::from(n), limit)
288    }
289
290    /// Reads an array count of the given prefix width and validates it.
291    ///
292    /// `min_elem_size` is the smallest number of bytes one element can occupy; when it is
293    /// non-zero the count is bounded by the remaining input, so a hostile count can never
294    /// cause a large allocation or a long loop.
295    #[inline]
296    pub fn check_count(&self, count: i64, min_elem_size: usize) -> DecodeResult<usize> {
297        let limit = self
298            .remaining()
299            .checked_div(min_elem_size)
300            .unwrap_or(ZERO_SIZE_ELEMENT_LIMIT);
301        Self::check_len(count, limit)
302    }
303
304    /// Reads a VarInt-prefixed byte array as a zero-copy slice.
305    #[inline]
306    pub fn read_byte_array(&mut self) -> DecodeResult<Bytes> {
307        let n = self.read_len_varint(self.remaining())?;
308        self.read_bytes(n)
309    }
310
311    /// Reads a VarInt-prefixed UTF-8 string as a zero-copy [`ByteString`].
312    #[inline]
313    pub fn read_string(&mut self) -> DecodeResult<ByteString> {
314        let n = self.read_len_varint(self.remaining())?;
315        let b = self.read_bytes(n)?;
316        ByteString::try_from(b).map_err(|_| DecodeError::InvalidUtf8)
317    }
318}
319
320/// Largest count accepted for arrays whose elements can be zero bytes long.
321pub const ZERO_SIZE_ELEMENT_LIMIT: usize = 1 << 16;
322
323#[inline(never)]
324fn varint_slow(rest: &[u8]) -> DecodeResult<(i32, usize)> {
325    let mut result: u32 = 0;
326    for i in 0..5 {
327        let Some(&b) = rest.get(i) else {
328            return Err(DecodeError::UnexpectedEof { needed: 1 });
329        };
330        result |= u32::from(b & 0x7f) << (7 * i);
331        if b & 0x80 == 0 {
332            return Ok((result as i32, i + 1));
333        }
334    }
335    Err(DecodeError::VarIntTooLong)
336}
337
338/// Decodes a VarInt from the start of a plain slice. Returns the value and its length.
339///
340/// Returns `Ok(None)` when the slice ends before the VarInt does.
341#[inline]
342pub fn read_varint_prefix(buf: &[u8]) -> DecodeResult<Option<(i32, usize)>> {
343    match varint_slow(buf) {
344        Ok(v) => Ok(Some(v)),
345        Err(DecodeError::UnexpectedEof { .. }) => Ok(None),
346        Err(e) => Err(e),
347    }
348}
349
350/// Number of bytes the VarInt encoding of `v` takes (1..=5).
351#[inline]
352pub const fn varint_len(v: i32) -> usize {
353    let v = v as u32;
354    match v {
355        0..=0x7f => 1,
356        0x80..=0x3fff => 2,
357        0x4000..=0x1f_ffff => 3,
358        0x20_0000..=0x0fff_ffff => 4,
359        _ => 5,
360    }
361}
362
363/// Encodes `v` as a VarInt into a fixed buffer; returns the buffer and the used length.
364#[inline]
365pub const fn varint_bytes(v: i32) -> ([u8; 5], usize) {
366    let mut v = v as u32;
367    let mut out = [0u8; 5];
368    let mut i = 0;
369    loop {
370        if v < 0x80 {
371            out[i] = v as u8;
372            return (out, i + 1);
373        }
374        out[i] = (v as u8 & 0x7f) | 0x80;
375        v >>= 7;
376        i += 1;
377    }
378}
379
380/// Protocol primitive encodings on top of [`BytesMut`].
381pub trait McWrite {
382    /// Writes a VarInt.
383    fn put_varint(&mut self, v: i32);
384    /// Writes a VarLong.
385    fn put_varlong(&mut self, v: i64);
386    /// Writes a boolean as one byte (0 or 1).
387    fn put_bool(&mut self, v: bool);
388    /// Writes a UUID as 16 big-endian bytes.
389    fn put_uuid(&mut self, v: &Uuid);
390    /// Writes a VarInt length prefix.
391    fn put_len_varint(&mut self, len: usize) -> EncodeResult;
392    /// Writes a VarInt-prefixed byte array.
393    fn put_byte_array(&mut self, b: &[u8]) -> EncodeResult;
394    /// Writes a VarInt-prefixed UTF-8 string.
395    fn put_string(&mut self, s: &str) -> EncodeResult;
396}
397
398impl McWrite for BytesMut {
399    #[inline]
400    fn put_varint(&mut self, v: i32) {
401        if (0..0x80).contains(&v) {
402            self.put_u8(v as u8);
403        } else {
404            let (b, n) = varint_bytes(v);
405            self.put_slice(&b[..n]);
406        }
407    }
408
409    #[inline]
410    fn put_varlong(&mut self, v: i64) {
411        let mut v = v as u64;
412        loop {
413            if v < 0x80 {
414                self.put_u8(v as u8);
415                return;
416            }
417            self.put_u8((v as u8 & 0x7f) | 0x80);
418            v >>= 7;
419        }
420    }
421
422    #[inline]
423    fn put_bool(&mut self, v: bool) {
424        self.put_u8(u8::from(v));
425    }
426
427    #[inline]
428    fn put_uuid(&mut self, v: &Uuid) {
429        self.put_u128(v.as_u128());
430    }
431
432    #[inline]
433    fn put_len_varint(&mut self, len: usize) -> EncodeResult {
434        let v = i32::try_from(len).map_err(|_| EncodeError::LengthOverflow {
435            len,
436            max: i32::MAX as usize,
437        })?;
438        self.put_varint(v);
439        Ok(())
440    }
441
442    #[inline]
443    fn put_byte_array(&mut self, b: &[u8]) -> EncodeResult {
444        self.put_len_varint(b.len())?;
445        self.put_slice(b);
446        Ok(())
447    }
448
449    #[inline]
450    fn put_string(&mut self, s: &str) -> EncodeResult {
451        self.put_byte_array(s.as_bytes())
452    }
453}
454
455/// Upper bound on the capacity reserved up front for a decoded array; larger arrays
456/// grow as elements are actually decoded, so a hostile count cannot force a big
457/// allocation.
458pub const PREALLOC_LIMIT: usize = 4096;
459
460fn overflow(len: usize, max: usize) -> EncodeError {
461    EncodeError::LengthOverflow { len, max }
462}
463
464/// Converts a collection length into an `i16` count prefix.
465#[inline]
466pub fn count_i16(len: usize) -> Result<i16, EncodeError> {
467    i16::try_from(len).map_err(|_| overflow(len, i16::MAX as usize))
468}
469
470/// Converts a collection length into an `i32` count prefix.
471#[inline]
472pub fn count_i32(len: usize) -> Result<i32, EncodeError> {
473    i32::try_from(len).map_err(|_| overflow(len, i32::MAX as usize))
474}
475
476/// Converts a collection length into a `u8` count prefix.
477#[inline]
478pub fn count_u8(len: usize) -> Result<u8, EncodeError> {
479    u8::try_from(len).map_err(|_| overflow(len, u8::MAX as usize))
480}
481
482#[cfg(test)]
483mod tests {
484    use super::*;
485
486    fn rd(bytes: &[u8]) -> DecodeResult<i32> {
487        let b = Bytes::copy_from_slice(bytes);
488        let mut r = Reader::new(&b);
489        let v = r.read_varint()?;
490        r.finish()?;
491        Ok(v)
492    }
493
494    #[test]
495    fn varint_known_answers() {
496        let cases: &[(i32, &[u8])] = &[
497            (0, &[0x00]),
498            (1, &[0x01]),
499            (2, &[0x02]),
500            (127, &[0x7f]),
501            (128, &[0x80, 0x01]),
502            (255, &[0xff, 0x01]),
503            (25565, &[0xdd, 0xc7, 0x01]),
504            (2097151, &[0xff, 0xff, 0x7f]),
505            (2147483647, &[0xff, 0xff, 0xff, 0xff, 0x07]),
506            (-1, &[0xff, 0xff, 0xff, 0xff, 0x0f]),
507            (-2147483648, &[0x80, 0x80, 0x80, 0x80, 0x08]),
508        ];
509        for &(v, bytes) in cases {
510            let mut w = BytesMut::new();
511            w.put_varint(v);
512            assert_eq!(&w[..], bytes, "encode {v}");
513            assert_eq!(varint_len(v), bytes.len());
514            assert_eq!(rd(bytes), Ok(v), "decode {bytes:02x?}");
515        }
516    }
517
518    #[test]
519    fn varint_rejects_too_long_and_eof() {
520        assert_eq!(
521            rd(&[0x80, 0x80, 0x80, 0x80, 0x80, 0x01]),
522            Err(DecodeError::VarIntTooLong)
523        );
524        assert!(matches!(
525            rd(&[0x80]),
526            Err(DecodeError::UnexpectedEof { .. })
527        ));
528        assert!(matches!(rd(&[]), Err(DecodeError::UnexpectedEof { .. })));
529        // Non-canonical (padded) encodings are accepted, like vanilla.
530        assert_eq!(rd(&[0x80, 0x00]), Ok(0));
531        assert_eq!(read_varint_prefix(&[0xff, 0xff]), Ok(None));
532    }
533
534    #[test]
535    fn varlong_known_answers() {
536        let cases: &[(i64, &[u8])] = &[
537            (0, &[0x00]),
538            (127, &[0x7f]),
539            (128, &[0x80, 0x01]),
540            (2147483647, &[0xff, 0xff, 0xff, 0xff, 0x07]),
541            (
542                9223372036854775807,
543                &[0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0x7f],
544            ),
545            (
546                -1,
547                &[0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0x01],
548            ),
549            (
550                -9223372036854775808,
551                &[0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x01],
552            ),
553        ];
554        for &(v, bytes) in cases {
555            let mut w = BytesMut::new();
556            w.put_varlong(v);
557            assert_eq!(&w[..], bytes, "encode {v}");
558            let b = Bytes::copy_from_slice(bytes);
559            let mut r = Reader::new(&b);
560            assert_eq!(r.read_varlong(), Ok(v));
561            assert_eq!(r.remaining(), 0);
562        }
563        let b = Bytes::from_static(&[0x80; 11]);
564        assert_eq!(
565            Reader::new(&b).read_varlong(),
566            Err(DecodeError::VarIntTooLong)
567        );
568    }
569
570    #[test]
571    fn strings_are_bounded_and_validated() {
572        let b = Bytes::from_static(&[0x05, b'h', b'i']);
573        assert!(matches!(
574            Reader::new(&b).read_string(),
575            Err(DecodeError::LengthTooLarge { .. })
576        ));
577        let b = Bytes::from_static(&[0x02, 0xc3, 0x28]);
578        assert_eq!(Reader::new(&b).read_string(), Err(DecodeError::InvalidUtf8));
579        let b = Bytes::from_static(&[0xff, 0xff, 0xff, 0xff, 0x0f]);
580        assert_eq!(
581            Reader::new(&b).read_string(),
582            Err(DecodeError::NegativeLength(-1))
583        );
584        let b = Bytes::from_static(&[0x03, b'a', b'b', b'c', 0x00]);
585        let mut r = Reader::new(&b);
586        assert_eq!(&*r.read_string().unwrap(), "abc");
587        assert_eq!(r.finish(), Err(DecodeError::TrailingBytes(1)));
588    }
589
590    #[test]
591    fn fixed_width_known_answers() {
592        let b = Bytes::from_static(&[
593            0x12, 0x34, 0xff, 0xfe, 0x3f, 0x80, 0x00, 0x00, 0x00, 0x11, 0x22, 0x33, 0x44, 0x55,
594            0x66, 0x77, 0x88, 0x99, 0xaa, 0xbb, 0xcc, 0xdd, 0xee, 0xff,
595        ]);
596        let mut r = Reader::new(&b);
597        assert_eq!(r.read_u16(), Ok(0x1234));
598        assert_eq!(r.read_i16(), Ok(-2));
599        assert_eq!(r.read_f32(), Ok(1.0));
600        assert_eq!(
601            r.read_uuid().unwrap().to_string(),
602            "00112233-4455-6677-8899-aabbccddeeff"
603        );
604        assert_eq!(r.remaining(), 0);
605    }
606}