Skip to main content

ghast_protocol/
frame.rs

1//! Framing: length prefixes, zlib compression and the encryption hook.
2//!
3//! [`FrameDecoder`] turns received bytes into [`RawPacket`]s, [`FrameEncoder`] turns
4//! packets into bytes ready to send. Both are synchronous and transport-agnostic; the
5//! `tokio` feature wraps them in [`crate::io`].
6//!
7//! Wire format (vanilla): `VarInt length | data`, where without compression
8//! `data = VarInt id | body` and with compression
9//! `data = VarInt uncompressed_len | (id | body), zlib-compressed unless uncompressed_len == 0`.
10//! With encryption on, the whole stream is AES-128-CFB8 encrypted.
11//!
12//! Lazy decoding: the decoder applies a [`PacketFilter`]. Unwanted packets are dropped
13//! before anything is decoded; for compressed frames only the first few bytes (enough
14//! for the packet id) are inflated, so ignored packets cost almost nothing.
15
16use std::cell::RefCell;
17
18use bytes::{Buf, BufMut, Bytes, BytesMut};
19#[cfg(not(feature = "libdeflate"))]
20use flate2::{Compress, Compression, FlushCompress, Status};
21use flate2::{Decompress, FlushDecompress};
22
23use crate::codec::{McWrite, Reader, read_varint_prefix, varint_len};
24use crate::crypto::{Cfb8Decryptor, Cfb8Encryptor};
25use crate::error::{DecodeError, EncodeError, FrameError};
26use crate::packet::{Packet, PacketFilter, PacketSet, RawPacket};
27
28/// Largest frame length expressible in the 3-byte length prefix vanilla accepts.
29pub const MAX_FRAME_LEN: usize = (1 << 21) - 1;
30
31/// Size of the receive buffer between bursts. A frame that does not fit grows it; once
32/// [`SHRINK_AFTER`] frames in a row fit again, the buffered bytes move to a buffer of this size,
33/// so a 2 MB chunk packet does not leave a 2 MB buffer behind (and a stream of large frames
34/// does not reallocate for each).
35const READ_BUF: usize = 8 * 1024;
36
37/// Frames of at most [`READ_BUF`] in a row after which a grown receive buffer shrinks.
38const SHRINK_AFTER: u16 = 64;
39
40/// Least free space [`FrameDecoder::reserve_read`] leaves for one read.
41const MIN_READ: usize = 2 * 1024;
42
43// The (de)compressor states are scratch space used within one call and reset before each use,
44// so one per thread serves every connection on it: a streaming inflater alone is ~47 KB, a
45// level-6 compressor several hundred KB, which per connection would dominate a light client's
46// memory when many share a process.
47thread_local! {
48    /// Streaming inflater: packet-id peeks (and whole packets without `libdeflate`).
49    static INFLATER: RefCell<Decompress> = RefCell::new(Decompress::new(true));
50}
51#[cfg(feature = "libdeflate")]
52thread_local! {
53    static LIBDEFLATE_INFLATER: RefCell<libdeflater::Decompressor> =
54        RefCell::new(libdeflater::Decompressor::new());
55    // Level 6 like Java's `Deflater` default.
56    static DEFLATER: RefCell<libdeflater::Compressor> =
57        RefCell::new(libdeflater::Compressor::new(libdeflater::CompressionLvl::default()));
58}
59#[cfg(not(feature = "libdeflate"))]
60thread_local! {
61    // Level 6 like Java's `Deflater` default (also gives the same `78 9c` header).
62    static DEFLATER: RefCell<Compress> = RefCell::new(Compress::new(Compression::default(), true));
63}
64
65/// Limits applied by the decoder.
66#[derive(Debug, Clone, Copy, PartialEq, Eq)]
67pub struct FrameLimits {
68    /// Maximum frame length (at most [`MAX_FRAME_LEN`]).
69    pub max_frame_len: usize,
70    /// Maximum declared uncompressed packet size. Vanilla 1.8 uses 2 MiB, later
71    /// versions 8 MiB; the default is 8 MiB.
72    pub max_uncompressed_len: usize,
73}
74
75impl Default for FrameLimits {
76    fn default() -> Self {
77        FrameLimits {
78            max_frame_len: MAX_FRAME_LEN,
79            max_uncompressed_len: 8 << 20,
80        }
81    }
82}
83
84/// Decoder counters (useful for profiling what a server sends).
85#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
86#[non_exhaustive]
87pub struct DecoderStats {
88    /// Frames split off the stream.
89    pub frames: u64,
90    /// Frames dropped by the filter.
91    pub skipped: u64,
92    /// Compressed frames dropped after inflating only the packet id.
93    pub skipped_compressed: u64,
94    /// Bytes produced by inflation.
95    pub inflated_bytes: u64,
96}
97
98/// Splits a byte stream into packets.
99pub struct FrameDecoder {
100    buf: BytesMut,
101    /// `buf` grew past [`READ_BUF`] for a frame: shrink it once frames fit again.
102    grown: bool,
103    /// Frames that fit [`READ_BUF`] split off since `buf` grew.
104    fitting: u16,
105    /// Copy uncompressed frames out of `buf` instead of sharing it.
106    detach: bool,
107    decryptor: Option<Cfb8Decryptor>,
108    compression: bool,
109    filter: PacketFilter,
110    limits: FrameLimits,
111    stats: DecoderStats,
112}
113
114impl std::fmt::Debug for FrameDecoder {
115    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
116        f.debug_struct("FrameDecoder")
117            .field("buffered", &self.buf.len())
118            .field("encrypted", &self.decryptor.is_some())
119            .field("compression", &self.compression)
120            .field("stats", &self.stats)
121            .finish_non_exhaustive()
122    }
123}
124
125impl Default for FrameDecoder {
126    fn default() -> Self {
127        Self::new()
128    }
129}
130
131impl FrameDecoder {
132    /// A decoder with no compression, no encryption, default limits and no filter.
133    pub fn new() -> Self {
134        FrameDecoder {
135            buf: BytesMut::with_capacity(READ_BUF),
136            grown: false,
137            fitting: 0,
138            detach: false,
139            decryptor: None,
140            compression: false,
141            filter: PacketFilter::all(),
142            limits: FrameLimits::default(),
143            stats: DecoderStats::default(),
144        }
145    }
146
147    /// Sets the limits.
148    pub fn set_limits(&mut self, limits: FrameLimits) {
149        self.limits = FrameLimits {
150            max_frame_len: limits.max_frame_len.min(MAX_FRAME_LEN),
151            ..limits
152        };
153    }
154
155    /// Turns compression on or off (from the server's Set Compression packet; a
156    /// negative threshold means off). Call it right after decoding that packet.
157    pub fn set_compression(&mut self, threshold: i32) {
158        self.compression = threshold >= 0;
159    }
160
161    /// Whether compression is on.
162    pub fn compression(&self) -> bool {
163        self.compression
164    }
165
166    /// Turns on decryption. Bytes already buffered but not yet split into frames are
167    /// decrypted too, since the server encrypts everything after its encryption request
168    /// was answered.
169    pub fn enable_encryption(&mut self, secret: &[u8; 16]) {
170        let mut d = Cfb8Decryptor::new(secret);
171        d.decrypt(&mut self.buf);
172        self.decryptor = Some(d);
173    }
174
175    /// Whether decryption is on.
176    pub fn is_encrypted(&self) -> bool {
177        self.decryptor.is_some()
178    }
179
180    /// Sets the per-id interest filter.
181    pub fn set_filter(&mut self, filter: PacketFilter) {
182        self.filter = filter;
183    }
184
185    /// The current filter.
186    pub fn filter(&self) -> &PacketFilter {
187        &self.filter
188    }
189
190    /// Counters.
191    pub fn stats(&self) -> DecoderStats {
192        self.stats
193    }
194
195    /// Number of buffered, not yet consumed bytes.
196    pub fn buffered(&self) -> usize {
197        self.buf.len()
198    }
199
200    /// Appends received bytes (decrypting them if encryption is on).
201    pub fn push(&mut self, data: &[u8]) {
202        let start = self.buf.len();
203        self.buf.extend_from_slice(data);
204        self.decrypt_from(start);
205    }
206
207    /// The receive buffer, for reading directly into it. After appending `n` bytes call
208    /// [`FrameDecoder::commit`] with the length before the read.
209    ///
210    /// [`FrameDecoder::reserve_read`] also makes room for the read first.
211    pub fn buffer_mut(&mut self) -> &mut BytesMut {
212        &mut self.buf
213    }
214
215    /// The receive buffer with room for the next read: at least the rest of the frame being
216    /// received, at least a couple of KB otherwise. The consumed front is reused in place when
217    /// no packet still shares the buffer. After appending call [`FrameDecoder::commit`] with
218    /// the length before the read, as with [`FrameDecoder::buffer_mut`].
219    pub fn reserve_read(&mut self) -> &mut BytesMut {
220        let need = self.needed().unwrap_or(0);
221        let len = self.buf.len();
222        if self.buf.capacity() - len < need.max(MIN_READ) {
223            self.buf
224                .reserve(need.max(READ_BUF.saturating_sub(len)).max(MIN_READ));
225            self.note_growth();
226        }
227        &mut self.buf
228    }
229
230    /// Decrypts bytes appended to [`FrameDecoder::buffer_mut`] since `old_len`.
231    pub fn commit(&mut self, old_len: usize) {
232        self.decrypt_from(old_len);
233    }
234
235    /// Copies uncompressed frames out of the receive buffer instead of sharing it with the
236    /// packets (off by default). A packet body that something keeps (a registry entry, a
237    /// profile property) then does not keep a whole receive buffer alive. Meant for the short
238    /// login and configuration states: it costs an allocation per frame.
239    pub fn set_detach_frames(&mut self, on: bool) {
240        self.detach = on;
241    }
242
243    /// Moves the buffered bytes to a fresh receive buffer of the standard size. Packets split
244    /// off before keep the old buffer (only) to themselves; call it at a state change (the end
245    /// of the configuration) so that the packets of the new state do not share a buffer with
246    /// data kept from the old one.
247    pub fn rehome(&mut self) {
248        let mut fresh = BytesMut::with_capacity(READ_BUF.max(self.buf.len()));
249        fresh.extend_from_slice(&self.buf);
250        self.buf = fresh;
251        self.grown = false;
252    }
253
254    /// After a reserve: the buffer is larger than the standard size (for a large frame).
255    fn note_growth(&mut self) {
256        if !self.grown && self.buf.capacity() > READ_BUF {
257            self.grown = true;
258            self.fitting = 0;
259        }
260    }
261
262    fn decrypt_from(&mut self, start: usize) {
263        if let Some(d) = &mut self.decryptor
264            && start < self.buf.len()
265        {
266            d.decrypt(&mut self.buf[start..]);
267        }
268    }
269
270    /// How many more bytes are needed to complete the next frame, if known.
271    pub fn needed(&self) -> Option<usize> {
272        match read_varint_prefix(&self.buf[..self.buf.len().min(3)]) {
273            Ok(Some((len, n))) if len >= 0 => (n + len as usize).checked_sub(self.buf.len()),
274            _ => None,
275        }
276    }
277
278    /// Splits off the next packet that passes the filter.
279    ///
280    /// Returns `Ok(None)` when more bytes are needed. Errors are fatal for the
281    /// connection (the stream position is lost).
282    pub fn next_packet(&mut self) -> Result<Option<RawPacket>, FrameError> {
283        loop {
284            let Some(frame) = self.next_frame()? else {
285                return Ok(None);
286            };
287            self.stats.frames += 1;
288            if let Some(p) = self.unpack(frame)? {
289                return Ok(Some(p));
290            }
291            self.stats.skipped += 1;
292        }
293    }
294
295    /// Splits off the next raw frame (length prefix removed).
296    fn next_frame(&mut self) -> Result<Option<Bytes>, FrameError> {
297        let head = &self.buf[..self.buf.len().min(3)];
298        let (len, n) = match read_varint_prefix(head) {
299            Ok(Some(v)) => v,
300            Ok(None) if head.len() < 3 => return Ok(None),
301            _ => return Err(FrameError::BadLength),
302        };
303        if len <= 0 {
304            return Err(FrameError::BadLength);
305        }
306        let len = len as usize;
307        if len > self.limits.max_frame_len {
308            return Err(FrameError::FrameTooLarge {
309                len,
310                max: self.limits.max_frame_len,
311            });
312        }
313        if self.buf.len() < n + len {
314            // Make room for the whole frame up front (one allocation).
315            self.buf.reserve(n + len - self.buf.len());
316            self.note_growth();
317            return Ok(None);
318        }
319        self.buf.advance(n);
320        let frame = if self.detach {
321            let f = Bytes::copy_from_slice(&self.buf[..len]);
322            self.buf.advance(len);
323            f
324        } else {
325            self.buf.split_to(len).freeze()
326        };
327        if self.grown {
328            if n + len > READ_BUF {
329                self.fitting = 0;
330            } else {
331                self.fitting = self.fitting.saturating_add(1);
332                if self.fitting >= SHRINK_AFTER && self.buf.len() <= READ_BUF / 2 {
333                    // Large frames have stopped: the grown allocation goes with the last
334                    // packets that still share it; what follows uses a standard buffer.
335                    self.rehome();
336                }
337            }
338        }
339        Ok(Some(frame))
340    }
341
342    /// Turns a frame into a packet, or `None` if the filter drops it.
343    fn unpack(&mut self, frame: Bytes) -> Result<Option<RawPacket>, FrameError> {
344        if !self.compression {
345            return self.split_id(frame);
346        }
347        let mut r = Reader::new(&frame);
348        let data_len = r.read_varint()?;
349        if data_len < 0 {
350            return Err(FrameError::Decode(DecodeError::NegativeLength(i64::from(
351                data_len,
352            ))));
353        }
354        if data_len == 0 {
355            let rest = frame.slice(r.position()..);
356            return self.split_id(rest);
357        }
358        let data_len = data_len as usize;
359        if data_len > self.limits.max_uncompressed_len {
360            return Err(FrameError::DecompressedTooLarge {
361                len: data_len,
362                max: self.limits.max_uncompressed_len,
363            });
364        }
365        let input = &frame[r.position()..];
366        if !self.filter.is_all() {
367            // Inflate just the packet id (at most 5 bytes) and decide.
368            let mut head = [0u8; 5];
369            let want = data_len.min(5);
370            let got = INFLATER.with_borrow_mut(|inf| {
371                inf.reset(true);
372                inf.decompress(input, &mut head[..want], FlushDecompress::None)
373                    .map_err(|_| FrameError::BadCompression("corrupt zlib stream"))?;
374                Ok::<_, FrameError>(inf.total_out() as usize)
375            })?;
376            let id = match read_varint_prefix(&head[..got])? {
377                Some((id, _)) => id,
378                None if got < want => return Err(FrameError::BadCompression("stream ended early")),
379                None => return Err(FrameError::Decode(DecodeError::VarIntTooLong)),
380            };
381            self.stats.inflated_bytes += got as u64;
382            if !self.filter.contains(id) {
383                self.stats.skipped_compressed += 1;
384                return Ok(None);
385            }
386        }
387        let out = self.inflate(input, data_len)?;
388        self.stats.inflated_bytes += data_len as u64;
389        let data = Bytes::from(out);
390        let mut r = Reader::new(&data);
391        let id = r.read_varint()?;
392        let body = data.slice(r.position()..);
393        Ok(Some(RawPacket::new(id, body)))
394    }
395
396    /// Inflates a whole zlib stream that must produce exactly `data_len` bytes.
397    #[cfg(feature = "libdeflate")]
398    fn inflate(&mut self, input: &[u8], data_len: usize) -> Result<Vec<u8>, FrameError> {
399        let mut out = vec![0u8; data_len];
400        match LIBDEFLATE_INFLATER.with_borrow_mut(|d| d.zlib_decompress(input, &mut out)) {
401            Ok(n) if n == data_len => Ok(out),
402            Ok(_) | Err(libdeflater::DecompressionError::InsufficientSpace) => Err(
403                FrameError::BadCompression("size differs from declared length"),
404            ),
405            Err(_) => Err(FrameError::BadCompression("corrupt zlib stream")),
406        }
407    }
408
409    /// Inflates a whole zlib stream that must produce exactly `data_len` bytes.
410    #[cfg(not(feature = "libdeflate"))]
411    fn inflate(&mut self, input: &[u8], data_len: usize) -> Result<Vec<u8>, FrameError> {
412        INFLATER.with_borrow_mut(|inf| inflate_with(inf, input, data_len))
413    }
414
415    fn split_id(&self, data: Bytes) -> Result<Option<RawPacket>, FrameError> {
416        let mut r = Reader::new(&data);
417        let id = r.read_varint()?;
418        if !self.filter.contains(id) {
419            return Ok(None);
420        }
421        let body = data.slice(r.position()..);
422        Ok(Some(RawPacket::new(id, body)))
423    }
424}
425
426/// [`FrameDecoder::inflate`] with the thread's streaming inflater.
427#[cfg(not(feature = "libdeflate"))]
428fn inflate_with(
429    inflater: &mut Decompress,
430    input: &[u8],
431    data_len: usize,
432) -> Result<Vec<u8>, FrameError> {
433    inflater.reset(true);
434    let mut out: Vec<u8> = Vec::with_capacity(data_len);
435    let status = inflater
436        .decompress_vec(input, &mut out, FlushDecompress::Finish)
437        .map_err(|_| FrameError::BadCompression("corrupt zlib stream"))?;
438    if out.len() != data_len {
439        return Err(FrameError::BadCompression(
440            "size differs from declared length",
441        ));
442    }
443    if status != Status::StreamEnd {
444        // The output is full; the stream must end without producing more.
445        let consumed = inflater.total_in() as usize;
446        let mut extra = [0u8; 1];
447        let st = inflater
448            .decompress(
449                &input[consumed.min(input.len())..],
450                &mut extra,
451                FlushDecompress::Finish,
452            )
453            .map_err(|_| FrameError::BadCompression("corrupt zlib stream"))?;
454        if inflater.total_out() as usize != data_len || st != Status::StreamEnd {
455            return Err(FrameError::BadCompression(
456                "size differs from declared length",
457            ));
458        }
459    }
460    Ok(out)
461}
462
463/// Turns packets into wire bytes. Packets are appended to an internal output buffer;
464/// take it with [`FrameEncoder::take`] (or let [`crate::io::FramedWriter`] flush it), so
465/// several packets of one tick go out in a single write.
466pub struct FrameEncoder {
467    out: BytesMut,
468    scratch: BytesMut,
469    compressed: Vec<u8>,
470    threshold: Option<usize>,
471    encryptor: Option<Cfb8Encryptor>,
472}
473
474impl std::fmt::Debug for FrameEncoder {
475    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
476        f.debug_struct("FrameEncoder")
477            .field("pending", &self.out.len())
478            .field("threshold", &self.threshold)
479            .field("encrypted", &self.encryptor.is_some())
480            .finish_non_exhaustive()
481    }
482}
483
484impl Default for FrameEncoder {
485    fn default() -> Self {
486        Self::new()
487    }
488}
489
490impl FrameEncoder {
491    /// An encoder with no compression and no encryption.
492    pub fn new() -> Self {
493        FrameEncoder {
494            // A tick's packets are a few dozen bytes; both grow when a larger one is written.
495            out: BytesMut::with_capacity(256),
496            scratch: BytesMut::with_capacity(256),
497            compressed: Vec::new(),
498            threshold: None,
499            encryptor: None,
500        }
501    }
502
503    /// Sets the compression threshold (negative = off), as received from the server.
504    pub fn set_compression(&mut self, threshold: i32) {
505        self.threshold = usize::try_from(threshold).ok();
506    }
507
508    /// Turns on encryption for everything written from now on.
509    pub fn enable_encryption(&mut self, secret: &[u8; 16]) {
510        self.encryptor = Some(Cfb8Encryptor::new(secret));
511    }
512
513    /// Encodes and frames a typed packet.
514    pub fn write_packet<P: Packet>(&mut self, p: &P) -> Result<(), EncodeError> {
515        self.scratch.clear();
516        self.scratch.put_varint(P::ID);
517        p.encode(&mut self.scratch)?;
518        self.frame_scratch()
519    }
520
521    /// Encodes and frames a packet-set enum value.
522    pub fn write_set<S: PacketSet>(&mut self, p: &S) -> Result<(), EncodeError> {
523        self.scratch.clear();
524        self.scratch.put_varint(p.id());
525        p.encode_body(&mut self.scratch)?;
526        self.frame_scratch()
527    }
528
529    /// Frames a raw packet.
530    pub fn write_raw(&mut self, p: &RawPacket) -> Result<(), EncodeError> {
531        self.scratch.clear();
532        self.scratch.put_varint(p.id);
533        self.scratch.put_slice(&p.body);
534        self.frame_scratch()
535    }
536
537    fn frame_scratch(&mut self) -> Result<(), EncodeError> {
538        let start = self.out.len();
539        let len = self.scratch.len();
540        let too_big = |len| EncodeError::LengthOverflow {
541            len,
542            max: MAX_FRAME_LEN,
543        };
544        match self.threshold {
545            None => {
546                if len > MAX_FRAME_LEN {
547                    return Err(too_big(len));
548                }
549                self.out.put_varint(len as i32);
550                self.out.put_slice(&self.scratch);
551            }
552            Some(t) if len < t => {
553                if len + 1 > MAX_FRAME_LEN {
554                    return Err(too_big(len + 1));
555                }
556                self.out.put_varint(len as i32 + 1);
557                self.out.put_u8(0);
558                self.out.put_slice(&self.scratch);
559            }
560            Some(_) => {
561                let len_i = i32::try_from(len).map_err(|_| too_big(len))?;
562                self.deflate()?;
563                let frame_len = varint_len(len_i) + self.compressed.len();
564                if frame_len > MAX_FRAME_LEN {
565                    return Err(too_big(frame_len));
566                }
567                self.out.put_varint(frame_len as i32);
568                self.out.put_varint(len_i);
569                self.out.put_slice(&self.compressed);
570            }
571        }
572        if let Some(e) = &mut self.encryptor {
573            e.encrypt(&mut self.out[start..]);
574        }
575        Ok(())
576    }
577
578    /// Compresses `scratch` into `compressed`.
579    #[cfg(feature = "libdeflate")]
580    fn deflate(&mut self) -> Result<(), EncodeError> {
581        DEFLATER.with_borrow_mut(|deflater| {
582            let bound = deflater.zlib_compress_bound(self.scratch.len());
583            self.compressed.clear();
584            self.compressed.resize(bound, 0);
585            let n = deflater
586                .zlib_compress(&self.scratch, &mut self.compressed)
587                .map_err(|_| EncodeError::Invalid("deflate failed"))?;
588            self.compressed.truncate(n);
589            Ok(())
590        })
591    }
592
593    /// Compresses `scratch` into `compressed`.
594    #[cfg(not(feature = "libdeflate"))]
595    fn deflate(&mut self) -> Result<(), EncodeError> {
596        DEFLATER.with_borrow_mut(|deflater| self.deflate_with(deflater))
597    }
598
599    #[cfg(not(feature = "libdeflate"))]
600    fn deflate_with(&mut self, deflater: &mut Compress) -> Result<(), EncodeError> {
601        deflater.reset();
602        self.compressed.clear();
603        self.compressed
604            .reserve(self.scratch.len() + self.scratch.len() / 1000 + 64);
605        loop {
606            let consumed = deflater.total_in() as usize;
607            let st = deflater
608                .compress_vec(
609                    &self.scratch[consumed..],
610                    &mut self.compressed,
611                    FlushCompress::Finish,
612                )
613                .map_err(|_| EncodeError::Invalid("deflate failed"))?;
614            if st == Status::StreamEnd {
615                return Ok(());
616            }
617            self.compressed.reserve(self.compressed.capacity().max(64));
618        }
619    }
620
621    /// Bytes waiting to be sent.
622    pub fn pending(&self) -> &[u8] {
623        &self.out
624    }
625
626    /// Takes the bytes waiting to be sent.
627    pub fn take(&mut self) -> BytesMut {
628        self.out.split()
629    }
630
631    /// The output buffer (for transports that consume it in place).
632    pub fn out_mut(&mut self) -> &mut BytesMut {
633        &mut self.out
634    }
635}
636
637#[cfg(test)]
638mod tests {
639    use super::*;
640    use flate2::{Compress, Compression, FlushCompress};
641
642    fn roundtrip(threshold: Option<i32>, secret: Option<[u8; 16]>, filter: PacketFilter) {
643        let mut enc = FrameEncoder::new();
644        let mut dec = FrameDecoder::new();
645        if let Some(t) = threshold {
646            enc.set_compression(t);
647            dec.set_compression(t);
648        }
649        if let Some(s) = secret {
650            enc.enable_encryption(&s);
651            dec.enable_encryption(&s);
652        }
653        dec.set_filter(filter);
654        let packets: Vec<RawPacket> = (0..50)
655            .map(|i| {
656                let body: Vec<u8> = (0..(i * 37) % 700).map(|j| (j * 7 + i) as u8).collect();
657                RawPacket::new(i % 9, Bytes::from(body))
658            })
659            .collect();
660        for p in &packets {
661            enc.write_raw(p).unwrap();
662        }
663        let wire = enc.take();
664        // Feed in odd-sized pieces.
665        let mut got = Vec::new();
666        for chunk in wire.chunks(13) {
667            dec.push(chunk);
668            while let Some(p) = dec.next_packet().unwrap() {
669                got.push(p);
670            }
671        }
672        let want: Vec<RawPacket> = packets
673            .into_iter()
674            .filter(|p| filter.contains(p.id))
675            .collect();
676        assert_eq!(got, want);
677        assert_eq!(dec.buffered(), 0);
678    }
679
680    #[test]
681    fn roundtrips() {
682        let key = [3u8; 16];
683        let f = PacketFilter::none().with(1).with(4);
684        for (t, s, filt) in [
685            (None, None, PacketFilter::all()),
686            (Some(256), None, PacketFilter::all()),
687            (Some(0), None, PacketFilter::all()),
688            (Some(64), Some(key), PacketFilter::all()),
689            (None, Some(key), f),
690            (Some(256), None, f),
691            (Some(1), Some(key), f),
692        ] {
693            roundtrip(t, s, filt);
694        }
695    }
696
697    #[test]
698    fn known_answer_frames() {
699        // Uncompressed: length 3, id 0x00, body [0x01, 0x02].
700        let mut enc = FrameEncoder::new();
701        enc.write_raw(&RawPacket::new(0, Bytes::from_static(&[1, 2])))
702            .unwrap();
703        assert_eq!(&enc.take()[..], &[0x03, 0x00, 0x01, 0x02]);
704        // Below the threshold: data length 0 marker.
705        enc.set_compression(256);
706        enc.write_raw(&RawPacket::new(0x21, Bytes::from_static(&[9])))
707            .unwrap();
708        assert_eq!(&enc.take()[..], &[0x03, 0x00, 0x21, 0x09]);
709        // A zlib frame produced by Java's Deflater (level 6) for id 0x26 + 300 zero bytes
710        // decodes back to that packet.
711        let mut body = vec![0x26];
712        body.extend_from_slice(&[0u8; 300]);
713        let mut z = Compress::new(Compression::default(), true);
714        let mut c = Vec::with_capacity(400);
715        z.compress_vec(&body, &mut c, FlushCompress::Finish)
716            .unwrap();
717        assert_eq!(&c[..2], &[0x78, 0x9c], "zlib header for the default level");
718        let mut frame = BytesMut::new();
719        frame.put_varint((varint_len(301) + c.len()) as i32);
720        frame.put_varint(301);
721        frame.put_slice(&c);
722        let mut dec = FrameDecoder::new();
723        dec.set_compression(256);
724        dec.push(&frame);
725        let p = dec.next_packet().unwrap().unwrap();
726        assert_eq!(p.id, 0x26);
727        assert_eq!(&p.body[..], &[0u8; 300][..]);
728    }
729
730    #[test]
731    fn rejects_malformed() {
732        let mut dec = FrameDecoder::new();
733        dec.push(&[0xff, 0xff, 0xff, 0x01]);
734        assert!(matches!(dec.next_packet(), Err(FrameError::BadLength)));
735        let mut dec = FrameDecoder::new();
736        dec.push(&[0x00]);
737        assert!(matches!(dec.next_packet(), Err(FrameError::BadLength)));
738        // Declared uncompressed size too large.
739        let mut dec = FrameDecoder::new();
740        dec.set_compression(0);
741        dec.push(&[0x05, 0x80, 0x80, 0x80, 0x10, 0x00]);
742        assert!(matches!(
743            dec.next_packet(),
744            Err(FrameError::DecompressedTooLarge { .. })
745        ));
746        // Garbage instead of zlib.
747        let mut dec = FrameDecoder::new();
748        dec.set_compression(0);
749        dec.push(&[0x04, 0x05, 0x01, 0x02, 0x03]);
750        assert!(matches!(
751            dec.next_packet(),
752            Err(FrameError::BadCompression(_))
753        ));
754        // Declared size larger than the actual inflated size.
755        let mut z = Compress::new(Compression::default(), true);
756        let mut c = Vec::with_capacity(64);
757        z.compress_vec(&[1, 2, 3], &mut c, FlushCompress::Finish)
758            .unwrap();
759        let mut frame = BytesMut::new();
760        frame.put_varint(1 + c.len() as i32);
761        frame.put_varint(4);
762        frame.put_slice(&c);
763        let mut dec = FrameDecoder::new();
764        dec.set_compression(0);
765        dec.push(&frame);
766        assert!(matches!(
767            dec.next_packet(),
768            Err(FrameError::BadCompression(_))
769        ));
770        // ... and smaller.
771        let mut frame = BytesMut::new();
772        frame.put_varint(1 + c.len() as i32);
773        frame.put_varint(2);
774        frame.put_slice(&c);
775        let mut dec = FrameDecoder::new();
776        dec.set_compression(0);
777        dec.push(&frame);
778        assert!(matches!(
779            dec.next_packet(),
780            Err(FrameError::BadCompression(_))
781        ));
782    }
783
784    #[test]
785    fn partial_inflation_skips_unwanted() {
786        let mut enc = FrameEncoder::new();
787        enc.set_compression(16);
788        let big = RawPacket::new(0x38, Bytes::from(vec![7u8; 100_000]));
789        enc.write_raw(&big).unwrap();
790        enc.write_raw(&RawPacket::new(0x00, Bytes::from(vec![1u8; 64])))
791            .unwrap();
792        let mut dec = FrameDecoder::new();
793        dec.set_compression(16);
794        dec.set_filter(PacketFilter::all().without(0x38));
795        dec.push(&enc.take());
796        let p = dec.next_packet().unwrap().unwrap();
797        assert_eq!(p.id, 0);
798        let s = dec.stats();
799        assert_eq!((s.frames, s.skipped, s.skipped_compressed), (2, 1, 1));
800        assert!(
801            s.inflated_bytes < 100,
802            "inflated {} bytes",
803            s.inflated_bytes
804        );
805    }
806
807    #[test]
808    fn encryption_enabled_mid_buffer() {
809        // Bytes that arrive before `enable_encryption` but belong after the switch are
810        // decrypted when it is enabled.
811        let key = [9u8; 16];
812        let mut plain = FrameEncoder::new();
813        plain
814            .write_raw(&RawPacket::new(1, Bytes::from_static(b"plain")))
815            .unwrap();
816        let mut crypt = FrameEncoder::new();
817        crypt.enable_encryption(&key);
818        crypt
819            .write_raw(&RawPacket::new(2, Bytes::from_static(b"secret")))
820            .unwrap();
821        let mut dec = FrameDecoder::new();
822        dec.push(&plain.take());
823        dec.push(&crypt.take());
824        assert_eq!(dec.next_packet().unwrap().unwrap().id, 1);
825        dec.enable_encryption(&key);
826        let p = dec.next_packet().unwrap().unwrap();
827        assert_eq!((p.id, &p.body[..]), (2, &b"secret"[..]));
828    }
829
830    /// Feeds `wire` through `reserve_read` / `commit` in reads of at most `chunk` bytes (like
831    /// a socket would) and returns the packets and the largest buffer capacity seen after a
832    /// packet was split off.
833    fn read_all(dec: &mut FrameDecoder, wire: &[u8], chunk: usize) -> (Vec<RawPacket>, usize) {
834        let mut got = Vec::new();
835        let mut pos = 0;
836        let mut max_after = 0;
837        loop {
838            while let Some(p) = dec.next_packet().unwrap() {
839                max_after = max_after.max(dec.buf.capacity());
840                got.push(p);
841            }
842            if pos == wire.len() {
843                return (got, max_after);
844            }
845            let buf = dec.reserve_read();
846            let old = buf.len();
847            let free = buf.capacity() - old;
848            assert!(free > 0);
849            let n = free.min(chunk).min(wire.len() - pos);
850            buf.extend_from_slice(&wire[pos..pos + n]);
851            pos += n;
852            dec.commit(old);
853        }
854    }
855
856    #[test]
857    fn a_large_frame_does_not_leave_a_large_buffer() {
858        let mut enc = FrameEncoder::new();
859        let small = RawPacket::new(1, Bytes::from_static(b"keep alive"));
860        let big = RawPacket::new(
861            2,
862            Bytes::from((0..300_000).map(|i| i as u8).collect::<Vec<_>>()),
863        );
864        let mut sent = vec![small.clone(), big.clone(), big.clone()];
865        sent.extend(std::iter::repeat_n(
866            small.clone(),
867            SHRINK_AFTER as usize + 2,
868        ));
869        for p in &sent {
870            enc.write_raw(p).unwrap();
871        }
872        let wire = enc.take();
873        for chunk in [7, 1000, 64 * 1024, usize::MAX] {
874            let mut dec = FrameDecoder::new();
875            let (got, _) = read_all(&mut dec, &wire, chunk);
876            assert_eq!(got, sent);
877            assert!(!dec.grown, "chunk {chunk}");
878            drop(got);
879            // The big frames' allocation went with them; the decoder is back to the standard
880            // size.
881            assert!(
882                dec.buf.capacity() <= READ_BUF,
883                "chunk {chunk}: {}",
884                dec.buf.capacity()
885            );
886        }
887        // Large frames in a row keep the grown buffer (no reallocation per frame).
888        let mut enc = FrameEncoder::new();
889        for _ in 0..5 {
890            enc.write_raw(&big).unwrap();
891        }
892        let wire = enc.take();
893        let mut dec = FrameDecoder::new();
894        let (got, _) = read_all(&mut dec, &wire, 64 * 1024);
895        assert_eq!(got.len(), 5);
896        assert!(dec.grown);
897    }
898
899    #[test]
900    fn steady_reads_keep_the_standard_buffer() {
901        let mut enc = FrameEncoder::new();
902        enc.set_compression(256);
903        let packets: Vec<RawPacket> = (0..3000)
904            .map(|i| {
905                RawPacket::new(
906                    i % 50,
907                    Bytes::from(vec![i as u8; (i as usize * 131) % 3000]),
908                )
909            })
910            .collect();
911        for p in &packets {
912            enc.write_raw(p).unwrap();
913        }
914        let wire = enc.take();
915        for chunk in [100, 1500, 9000] {
916            let mut dec = FrameDecoder::new();
917            dec.set_compression(256);
918            let (got, max_after) = read_all(&mut dec, &wire, chunk);
919            assert_eq!(got, packets);
920            // Packets dropped as they are handled: one standard buffer throughout.
921            let mut dec = FrameDecoder::new();
922            dec.set_compression(256);
923            let mut n = 0;
924            let mut pos = 0;
925            let mut max_cap = 0;
926            while n < packets.len() {
927                while let Some(p) = dec.next_packet().unwrap() {
928                    assert_eq!(p, packets[n]);
929                    n += 1;
930                }
931                let buf = dec.reserve_read();
932                let old = buf.len();
933                let k = (buf.capacity() - old).min(chunk).min(wire.len() - pos);
934                buf.extend_from_slice(&wire[pos..pos + k]);
935                pos += k;
936                dec.commit(old);
937                max_cap = max_cap.max(dec.buf.capacity() + dec.buf.len());
938            }
939            assert!(max_cap <= 2 * READ_BUF, "chunk {chunk}: {max_cap}");
940            assert!(max_after <= 2 * READ_BUF, "chunk {chunk}: {max_after}");
941        }
942    }
943
944    #[test]
945    fn detached_frames_do_not_share_the_buffer() {
946        let mut enc = FrameEncoder::new();
947        for i in 0..4 {
948            enc.write_raw(&RawPacket::new(i, Bytes::from_static(b"registry entry")))
949                .unwrap();
950        }
951        let wire = enc.take();
952        let mut dec = FrameDecoder::new();
953        dec.set_detach_frames(true);
954        dec.push(&wire[..wire.len() / 2]);
955        let a = dec.next_packet().unwrap().unwrap();
956        assert!(a.body.is_unique());
957        dec.set_detach_frames(false);
958        let b = dec.next_packet().unwrap().unwrap();
959        assert!(!b.body.is_unique());
960        dec.rehome();
961        assert!(b.body.is_unique());
962        dec.push(&wire[wire.len() / 2..]);
963        let rest: Vec<_> = std::iter::from_fn(|| dec.next_packet().unwrap()).collect();
964        assert_eq!(rest.len(), 2);
965        assert_eq!(a.body, b"registry entry"[..]);
966    }
967}