yzx_core/

frame.rs

/*
 * Description: Encoding of Zstandard frame types.
 *
 * Copyright (C) 2025 d@nny mc² <dmc2@hypnicjerk.ai>
 * SPDX-License-Identifier: AGPL-3.0-or-later
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License as published
 * by the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Affero General Public License for more details.
 *
 * You should have received a copy of the GNU Affero General Public License
 * along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */

//! Encoding of Zstandard frame types.
//!
//! A Zstandard data stream is composed of one or more *frames*, concatenated together
//! without interruption. Frames may refer to data or contain metadata.
//!
//! Supported frame types are specified in section 3.1 of IETF RFC 8878[^sec-3.1]. They are similar to the
//! format used for frames in LZ4[^lz4].
//!
//! [^sec-3.1]: <https://datatracker.ietf.org/doc/html/rfc8878#section-3.1>
//! [^lz4]: <https://github.com/lz4/lz4/blob/a018abc07a3018371625a265f195c4fafbf1f99d/doc/lz4_Frame_format.md>

#[derive(Debug, Copy, Clone)]
pub enum ParseResult<Success, Error> {
  Success {
    result: Success,
    consumed_bytes: usize,
  },
  NeedsMoreInput {
    at_least_this_many_more_bytes: usize,
  },
  Error(Error),
}

pub trait SliceParse {
  type Success<'data>;
  type Error;

  type Arg;
  fn parse<'data>(
    arg: Self::Arg,
    data: &'data [u8],
  ) -> ParseResult<Self::Success<'data>, Self::Error>
  where
    Self: Sized;
}

/// Encoding of a Zstandard frame.
///
/// A "Zstandard frame" (somewhat confusingly) refers to a single specific type of frame which may
/// appear in a Zstandard data stream. This frame type is also currently the only kind which is
/// specified to produce decoded output data. Therefore, this codebase uses the term "data frame".
///
/// This frame type's encoding is specified in section 3.1.1 of IETF RFC 8878[^sec-3.1.1]:
/// ```custom,{class=language-md}
///                     +--------------------+------------+
///                     | Magic_Number       | 4 bytes    |
///                     +--------------------+------------+
///                     | Frame_Header       | 2-14 bytes |
///                     +--------------------+------------+
///                     | Data_Block         | n bytes    |
///                     +--------------------+------------+
///                     | [More Data_Blocks] |            |
///                     +--------------------+------------+
///                     | [Content_Checksum] | 4 bytes    |
///                     +--------------------+------------+
/// ```
///
/// [^sec-3.1.1]: <https://datatracker.ietf.org/doc/html/rfc8878#section-3.1.1>
pub mod data {
  /// The "magic number" identifying the start of a data frame.
  ///
  /// As per the RFC:
  /// > The magic number was selected to be less probable to find at the beginning of an arbitrary
  /// > file. It avoids trivial patterns (0x00, 0xFF, repeated bytes, increasing bytes, etc.),
  /// > contains byte values outside of the ASCII range, and doesn't map into UTF-8 space, all of
  /// > which reduce the likelihood of its appearance at the top of a text file.
  pub const MAGIC: u32 = 0xFD2FB528;
  /* This will represent the data we write to or read off the wire. */
  const MAGIC_BYTES: [u8; 4] = MAGIC.to_le_bytes();

  pub mod header {
    use core::{error, fmt, num};

    use crate::frame::{ParseResult, SliceParse};

    #[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
    pub struct FrameHeader {
      pub window: WindowBounds,
      pub dictionary: Option<DictionaryID>,
      pub checksum: ChecksumBehavior,
    }

    #[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
    pub enum WindowBounds {
      SingleSegment {
        frame_content_size: u64,
      },
      Windowed {
        window_size: num::NonZero<u64>,
        frame_content_size: Option<u64>,
      },
    }

    impl WindowBounds {
      #[inline(always)]
      pub const fn window_size(&self) -> u64 {
        match self {
          Self::SingleSegment { frame_content_size } => *frame_content_size,
          Self::Windowed { window_size, .. } => window_size.get(),
        }
      }

      #[inline(always)]
      const fn clamp_block_size(window_size: u64) -> u32 {
        if window_size > (super::block::BLOCK_SIZE_MAX as u64) {
          super::block::BLOCK_SIZE_MAX
        } else {
          window_size as u32
        }
      }

      #[inline(always)]
      pub const fn block_maximum_size(&self) -> u32 { Self::clamp_block_size(self.window_size()) }
    }

    #[repr(transparent)]
    #[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
    pub struct DictionaryID(u32);

    impl DictionaryID {
      #[inline(always)]
      pub const fn new(x: u32) -> Self { Self(x) }

      #[inline(always)]
      pub const fn within_iana_reserved_ranges(&self) -> bool {
        (self.0 <= 32767) || (self.0 >= 1 << 31)
      }
    }

    #[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
    pub enum ChecksumBehavior {
      HasContentChecksum,
      None,
    }

    /// The first byte of each frame header.
    ///
    /// As per the RFC:
    /// > The first header's byte is called the `Frame_Header_Descriptor`. It describes which other
    /// > fields are present. Decoding this byte is enough to tell the size of `Frame_Header`.
    #[repr(transparent)]
    struct FrameHeaderDescriptor(u8);

    impl FrameHeaderDescriptor {
      #[inline(always)]
      const fn from_le(x: &u8) -> Self { Self(u8::from_le(*x)) }

      #[inline]
      const fn fcs_field_size(&self) -> Option<num::NonZero<u8>> {
        let frame_content_size_flag: u8 = (self.0 & 0b1100_0000) >> 6;
        let ret: u8 = if frame_content_size_flag == 0 && !self.single_segment_flag() {
          0
        } else {
          0b1u8 << frame_content_size_flag
        };
        num::NonZero::new(ret)
      }

      #[inline(always)]
      const fn single_segment_flag(&self) -> bool { (self.0 & 0b0010_0000) != 0 }

      #[inline(always)]
      const fn unused_bit_is_set(&self) -> bool { (self.0 & 0b0001_0000) != 0 }

      #[inline(always)]
      const fn reserved_bit_is_set(&self) -> bool { (self.0 & 0b0000_1000) != 0 }

      #[inline(always)]
      const fn content_checksum_flag(&self) -> bool { (self.0 & 0b0000_0100) != 0 }

      #[inline(always)]
      const fn did_field_size(&self) -> Option<num::NonZero<u8>> {
        num::NonZero::new(match self.0 & 0b11 {
          3 => 4,
          x => x,
        })
      }
    }

    #[repr(transparent)]
    struct WindowDescriptor(u8);

    impl WindowDescriptor {
      #[inline(always)]
      const fn from_le(x: &u8) -> Self { Self(u8::from_le(*x)) }

      #[inline(always)]
      #[allow(non_snake_case)]
      #[rustfmt::skip] /* This is the only way to retain the range bounds, sigh... */
      const fn compute_window_size(&self) -> num::NonZero<u64> {
        let Exponent: u64 = ((self.0 & 0b1111_1000) >> 3) as u64; /* [0, 31] */
        let Mantissa: u64 = (self.0 & 0b0000_0111) as u64;        /* [0, 7] */
        let windowLog: u64 = 10 + Exponent;                       /* [10, 41] */
        let windowBase: u64 = 1 << windowLog;                     /* [1<<10, 1<<41] */
        let windowAdd: u64 = (windowBase / 8) * Mantissa;         /* [0, 7x(1<<38)] */
        /* LLVM optimizes out the panic branch on --release! */
        num::NonZero::new(windowBase + windowAdd).unwrap() /* [1<<10, (1<<41)+7x(1<<38)] */
      }
    }

    #[derive(Debug, Copy, Clone)]
    pub enum HeaderParseError {
      ReservedBitSet,
      InvalidWindowBounds {
        window_size: num::NonZero<u64>,
        frame_content_size: u64,
      },
    }

    impl fmt::Display for HeaderParseError {
      fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        match self {
          Self::ReservedBitSet => write!(f, "reserved bit set in frame header descriptor"),
          Self::InvalidWindowBounds {
            window_size,
            frame_content_size,
          } => {
            let window_size = window_size.get();
            assert!(window_size > *frame_content_size);
            write!(
              f,
              "invalid window bounds: Window_Size ({window_size}) \
             was greater than Frame_Content_Size ({frame_content_size})"
            )
          },
        }
      }
    }

    impl error::Error for HeaderParseError {}

    impl SliceParse for FrameHeader {
      type Success<'data> = FrameHeader;
      type Error = HeaderParseError;

      type Arg = ();
      fn parse<'data>(
        _arg: Self::Arg,
        data: &'data [u8],
      ) -> ParseResult<Self::Success<'data>, Self::Error>
      where
        Self: Sized,
      {
        let original_length = data.len();
        let (descriptor, data) = match data.split_first() {
          None => {
            return ParseResult::NeedsMoreInput {
              at_least_this_many_more_bytes: 1,
            };
          },
          Some((x, rest)) => (FrameHeaderDescriptor::from_le(x), rest),
        };
        if descriptor.reserved_bit_is_set() {
          return ParseResult::Error(HeaderParseError::ReservedBitSet);
        }

        let (window_descriptor, data): (Option<WindowDescriptor>, &[u8]) =
          if descriptor.single_segment_flag() {
            (None, data)
          } else {
            match data.split_first() {
              None => {
                return ParseResult::NeedsMoreInput {
                  at_least_this_many_more_bytes: 1,
                };
              },
              Some((x, rest)) => (Some(WindowDescriptor::from_le(x)), rest),
            }
          };

        let (dictionary, data): (Option<DictionaryID>, &[u8]) = match descriptor.did_field_size() {
          None => (None, data),
          Some(n) => match data.split_at_checked(n.get() as usize) {
            None => {
              return ParseResult::NeedsMoreInput {
                at_least_this_many_more_bytes: (n.get() as usize) - data.len(),
              };
            },
            Some((dict_data, rest)) => {
              let id: u32 = match dict_data.len() {
                1 => u8::from_le(dict_data[0]) as u32,
                2 => u16::from_le_bytes(dict_data.try_into().unwrap()) as u32,
                4 => u32::from_le_bytes(dict_data.try_into().unwrap()),
                _ => unreachable!("1, 2, and 4 are the only viable did_field_size results"),
              };
              (Some(DictionaryID::new(id)), rest)
            },
          },
        };

        let (frame_content_size, data): (Option<u64>, &[u8]) = match descriptor.fcs_field_size() {
          None => (None, data),
          Some(n) => match data.split_at_checked(n.get() as usize) {
            None => {
              return ParseResult::NeedsMoreInput {
                at_least_this_many_more_bytes: (n.get() as usize) - data.len(),
              };
            },
            Some((frame_data, rest)) => {
              let size: u64 = match frame_data.len() {
                1 => u8::from_le(frame_data[0]) as u64,
                /* NB: the specific case of 2-byte width adds an additional offset.
                 *     This is not explained in the specification for some reason. */
                2 => (u16::from_le_bytes(frame_data.try_into().unwrap()) as u64) + 256,
                4 => u32::from_le_bytes(frame_data.try_into().unwrap()) as u64,
                8 => u64::from_le_bytes(frame_data.try_into().unwrap()),
                _ => unreachable!("1, 2, 4, and 8 are the only viable fcs_field_size results"),
              };
              (Some(size), rest)
            },
          },
        };

        let window = match (window_descriptor, frame_content_size) {
          (None, None) => {
            unreachable!(
              "Single_Segment_Flag modulates Window_Size and Frame_Content_Size, \
             making this case impossible"
            )
          },
          /* Single_Segment_Flag */
          (None, Some(frame_content_size)) => WindowBounds::SingleSegment { frame_content_size },
          (Some(window_descriptor), None) => WindowBounds::Windowed {
            window_size: window_descriptor.compute_window_size(),
            frame_content_size: None,
          },
          (Some(window_descriptor), Some(frame_content_size)) => {
            let window_size: num::NonZero<u64> = window_descriptor.compute_window_size();
            if window_size.get() > frame_content_size {
              return ParseResult::Error(HeaderParseError::InvalidWindowBounds {
                window_size,
                frame_content_size,
              });
            }
            WindowBounds::Windowed {
              window_size,
              frame_content_size: Some(frame_content_size),
            }
          },
        };

        let checksum = if descriptor.content_checksum_flag() {
          ChecksumBehavior::HasContentChecksum
        } else {
          ChecksumBehavior::None
        };

        let consumed_bytes = original_length - data.len();
        ParseResult::Success {
          result: FrameHeader {
            window,
            dictionary,
            checksum,
          },
          consumed_bytes,
        }
      }
    }
  }

  pub mod block {
    use core::{error, fmt};

    use crate::frame::{ParseResult, SliceParse};

    const HEADER_SIZE: usize = 3;

    /* 128kb global limit to block size, regardless of window_size. */
    pub(crate) const BLOCK_SIZE_MAX: u32 = 1 << 17;

    #[derive(Debug, Copy, Clone)]
    pub struct Block<'data> {
      pub content: BlockContent<'data>,
      pub sequence_behavior: SequenceBehavior,
    }

    #[derive(Debug, Copy, Clone)]
    pub enum BlockContent<'data> {
      Raw { data: &'data [u8] },
      RunLength { byte: &'data u8, block_size: u32 },
      Compressed { data: &'data [u8] },
    }

    #[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
    pub enum SequenceBehavior {
      LastBlock,
      Continue,
    }

    #[repr(transparent)]
    struct BlockHeader(u32);

    impl BlockHeader {
      #[inline(always)]
      fn from_le_bytes(x: &[u8; HEADER_SIZE]) -> Self {
        static_assertions::const_assert!(HEADER_SIZE <= core::mem::size_of::<u32>());
        let ret: u32 = (0..HEADER_SIZE)
          .map(|i| (x[i] as u32) << (u8::BITS * (i as u32)))
          .sum();
        Self(ret)
      }

      #[inline(always)]
      const fn last_block(&self) -> bool { (self.0 & 0b1) != 0 }

      #[inline(always)]
      fn block_type(&self) -> BlockType {
        match (self.0 & 0b110) >> 1 {
          0 => BlockType::RawBlock,
          1 => BlockType::RLEBlock,
          2 => BlockType::CompressedBlock,
          3 => BlockType::Reserved,
          _ => unreachable!("block type is limited to two bits"),
        }
      }

      #[inline(always)]
      const fn block_size(&self) -> u32 { self.0 >> 3 }
    }

    #[repr(u8)]
    #[derive(Debug, Copy, Clone)]
    enum BlockType {
      RawBlock = 0,
      RLEBlock = 1,
      CompressedBlock = 2,
      Reserved = 3,
    }

    #[derive(Debug, Copy, Clone)]
    pub enum BlockParseResult<'data> {
      Success {
        result: Block<'data>,
        is_last_block: bool,
        consumed_bytes: usize,
      },
      NeedsMoreInput {
        at_least_this_many_more_bytes: usize,
      },
      Error(BlockParseError),
    }

    #[derive(Debug, Copy, Clone)]
    pub enum BlockParseError {
      TooLarge { max_size: u32, block_size: u32 },
      ReservedBlockType,
    }

    impl fmt::Display for BlockParseError {
      fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        match self {
          Self::TooLarge {
            max_size,
            block_size,
          } => {
            assert!(block_size > max_size);
            write!(
              f,
              "Block_Size ({block_size}) was greater than Block_Maximum_Size ({max_size})"
            )
          },
          Self::ReservedBlockType => {
            write!(f, "reserved block type specified in block header")
          },
        }
      }
    }

    impl error::Error for BlockParseError {}

    impl SliceParse for Block<'_> {
      type Success<'data> = Block<'data>;
      type Error = BlockParseError;

      type Arg = u32;
      /* NB: max_size should be the result of WindowBounds::block_maximum_size()! */
      fn parse<'data>(
        max_size: u32,
        data: &'data [u8],
      ) -> ParseResult<Self::Success<'data>, Self::Error> {
        debug_assert!(max_size <= BLOCK_SIZE_MAX);
        let original_length = data.len();
        let (block_header, data) = match data.split_at_checked(HEADER_SIZE) {
          None => {
            return ParseResult::NeedsMoreInput {
              at_least_this_many_more_bytes: data.len() - HEADER_SIZE,
            };
          },
          Some((header, rest)) => {
            let block_header = BlockHeader::from_le_bytes(header.try_into().unwrap());
            (block_header, rest)
          },
        };

        let block_size: u32 = {
          let block_size = block_header.block_size();
          if block_size > max_size {
            return ParseResult::Error(BlockParseError::TooLarge {
              max_size,
              block_size,
            });
          }
          block_size
        };

        let sequence_behavior = if block_header.last_block() {
          SequenceBehavior::LastBlock
        } else {
          SequenceBehavior::Continue
        };

        let (block, data) = match block_header.block_type() {
          BlockType::RawBlock => match data.split_at_checked(block_size as usize) {
            None => {
              return ParseResult::NeedsMoreInput {
                at_least_this_many_more_bytes: data.len() - (block_size as usize),
              };
            },
            Some((block, rest)) => {
              let block = BlockContent::Raw { data: block };
              (block, rest)
            },
          },
          BlockType::RLEBlock => match data.split_first() {
            None => {
              return ParseResult::NeedsMoreInput {
                at_least_this_many_more_bytes: 1,
              };
            },
            Some((byte, rest)) => {
              let block = BlockContent::RunLength { byte, block_size };
              (block, rest)
            },
          },
          BlockType::CompressedBlock => match data.split_at_checked(block_size as usize) {
            None => {
              return ParseResult::NeedsMoreInput {
                at_least_this_many_more_bytes: data.len() - (block_size as usize),
              };
            },
            Some((block, rest)) => {
              let block = BlockContent::Compressed { data: block };
              (block, rest)
            },
          },
          BlockType::Reserved => {
            return ParseResult::Error(BlockParseError::ReservedBlockType);
          },
        };

        let consumed_bytes = original_length - data.len();
        ParseResult::Success {
          result: Block {
            content: block,
            sequence_behavior,
          },
          consumed_bytes,
        }
      }
    }
  }
}

/// Encoding of a skippable frame.
///
/// A skippable frame carries a fixed-size numeric identifier in its magic number as well as
/// variable-sized arbitrary bytes. It does *not* decompose into any internal block format like
/// [`data`] frames. It also has no decoder behavior specified by RFC 8788, which instead explicitly
/// clarifies its intent to support "user-defined metadata":
/// > From a compliant decoder perspective, skippable frames simply need to be skipped, and their
/// > content ignored, resuming decoding after the skippable frame.
///
/// This frame type's encoding is specified in section 3.1.2 of IETF RFC 8878[^sec-3.1.2]:
/// ```custom,{class=language-md}
///                  +==============+============+===========+
///                  | Magic_Number | Frame_Size | User_Data |
///                  +==============+============+===========+
///                  |   4 bytes    |  4 bytes   |  n bytes  |
///                  +--------------+------------+-----------+
/// ```
///
/// [^sec-3.1.2]: <https://datatracker.ietf.org/doc/html/rfc8878#section-3.1.2>
///
/// # Privacy Risk: Watermarking
/// The IETF RFC *repeatedly* notes the potential for watermarking and other forms of tracking
/// possible via skippable frames in this standard:
/// > It should be noted that a skippable frame can be used to watermark a stream of concatenated
/// > frames embedding any kind of tracking information (even just a Universally Unique Identifier
/// > (UUID)). Users wary of such possibility should scan the stream of concatenated frames in an
/// > attempt to detect such frames for analysis or removal.
///
/// Because the specification does not specify the behavior of skippable frames, this risk can go
/// undetected unless the decoder explicitly handles such frames. Removing such frames will modify
/// the resulting stream (which itself may impose its own risk of watermarking), but should make it
/// possible for two independent implementations (or two independent users of this library) to avoid
/// being individually watermarked by skippable frames alone if they were to reproduce a zstd stream
/// from an untrusted source.
///
/// ## Data Frames Contain Hidden States
/// However, the Zstandard stream format contains many further opportunities for individually
/// watermarking a stream beyond skippable frames which are *not* mentioned in the spec, and which
/// generally revolve around the immense flexibility of standard [`data`] frames.
///
/// These opportunities are almost too numerous to name, but take on a few broad categories:
/// - **degenerate states:** *when decoded output is empty*
///   - Like skippable frames, these also have no effect upon the decoded output, but can store
///     arbitrary user data.
///   - examples include:
///     - when `Frame_Content_Size` is 0 (this also limits all subsequent `Window_Size` and
///       `Block_Size`).
///     - when `Block_Size` is 0 (for `Raw_Block` or `RLE_Block`).
///     - when `Number_of_Sequences` is 0.
///     - **TODO:** probably when a literal or offset is zero-length in sequence execution?
/// - **synonymous/fungible states:** *when the same output data is representable with distinct byte
///   strings*
///   - This comes in three basic forms:
///     1. _using a more *complex* data structure than necessary_, e.g.:
///        - a `Raw_Block` for a single repeating byte.
///        - a `Compressed_Block` for uncompressible data.
///     2. _using a sequence of too *simple* data structures_, e.g.:
///        - two consecutive `RLE_Block`s with `Block_Size == 1` vs `Raw_Block` with 2 bytes.
///        - a `Raw_Block` for highly compressible data.
///     3. _using `Block_Type` vs `Literals_Block_Type`:_
///        - `Block_Type` provides simpler forms of `RLE_Block` and `Raw_Literals_Block`, whereas
///          the `Sequences_Section`[^seq-sec] from `Compressed_Block` can describe a program to
///          execute a sequence of run-length literals or directly-copied bytes.
///   - Note that "compressibility" is highly domain-specific, and decisions may be performed
///     arbitrarily by the encoder.
///     - *This therefore exposes the encoder to watermarking.*
/// - **dict/literal encoding:** *when decisions are made regarding prefix data or symbol
///   distributions*
///   - **TODO:** it is still unclear how this works and the directions seem to contradict
///     each other.
///   - This technique can be supremely difficult to detect heuristically.
///     - It may be possible through re-encoding to compare against a symbol distribution table
///       built up by hand.
///     - In general, the space of possible compression encodings is vast, and as compression is
///       compared by both speed and size ratio, the decisions a compressor makes are hard to judge.
///       - *However, this individuality streak makes encoders susceptible to watermarking too.*
/// - **block index selection:** *when the encoder decides how to chunk up the stream*
///   - As with dict encoding, this is generally considered an arbitrary decision by the encoder.
///     - *As a result, encoding is also watermarkable.*
///
/// [^seq-sec]: <https://datatracker.ietf.org/doc/html/rfc8878#section-3.1.1.3.2>
///
/// ### "Unused Bit" is a Skippable Frame
/// Also worth calling out in particular is **the "Unused Bit"
/// from section 3.1.1.1.1.3[^sec-3.1.1.1.1.3]:**
/// > A decoder compliant with this specification version shall not interpret this bit.
///
/// This is actually even *stronger* than a skippable frame, as it claims compliance *requires* not
/// looking at the value of the bit, whereas skippable frames do not impose any interpretation
/// (forbidding an interpretation is also an interpretation!). Luckily, as it states at the top:
/// > This document is not an Internet Standards Track specification.
///
/// So for now we can do what it suggests:
/// > An encoder compliant with this specification must set this bit to zero.
///
/// [^sec-3.1.1.1.1.3]: <https://datatracker.ietf.org/doc/html/rfc8878#section-3.1.1.1.1.3>
///
/// ## Timing Attacks on Decoding
/// Yet decoders can be deanonymized in yet another way, even just by downloading a Zstandard
/// data stream: in particular, by their choice of internal buffering.
///
/// The spec makes it clear that decoders are *free to choose* their own buffer limits, saying this
/// *two separate times*! In `Single_Segment_Flag`[^single-seg]:
/// > For broader compatibility, decoders are recommended to support memory sizes of at least 8 MB.
/// > This is only a recommendation; each decoder is free to support higher or lower limits,
/// > depending on local limitations.
///
/// [^single-seg]: <https://datatracker.ietf.org/doc/html/rfc8878#section-3.1.1.1.1.2>
///
/// And then in `Window_Descriptor`[^win-desc]:
/// > For improved interoperability, it's recommended for decoders to support values of
/// > `Window_Size` up to 8 MB and for encoders not to generate frames requiring a `Window_Size`
/// > larger than 8 MB.
/// > It's merely a recommendation though, and decoders are free to support higher or lower limits,
/// > depending on local limitations.
///
/// [^win-desc]: <https://datatracker.ietf.org/doc/html/rfc8878#name-window-descriptor>
///
/// `curl` allows specifying a buffer size to receive output (including decompressed Zstandard
/// stream data) into[^curl-buf-size], and this can be used to validate the effect of buffer
/// selection (using `curl`'s internal buffer reallocation heuristics) upon remote latencies.
///
/// [^curl-buf-size]: <https://docs.rs/curl/latest/curl/easy/struct.Easy2.html#method.buffer_size>
///
/// ### Window Size is Fingerprintable Entropy
/// Unfortunately, this freedom of choice in buffer size defines a fingerprintable time series,
/// visible to the remote end through variable latency and packet size over the course of the
/// download (the proof of this is left as an exercise to the reader).
///
/// To quote a tor browser developer[^tor-dev]:
/// > Window dimensions are a big source of fingerprintable entropy on the web.
///
/// Analogously, the variable latency between reads from the network socket introduced by
/// a particular buffer size can likely be used to fingerprint a decoder. Tor hidden services have
/// been fingerprinted through a time series analysis of packet sizes in this way[^tor-fingerprint].
///
/// [^tor-dev]: <https://bugzilla.mozilla.org/show_bug.cgi?id=1407366>
/// [^tor-fingerprint]: <https://www.informatik.tu-cottbus.de/~andriy/papers/acmccs-wpes17-hidden-services-fp.pdf>
///
/// ## How to Achieve Anonymity
/// Given all of this uncertainty, how can a decoder expect to avoid fingerprinting?
///
/// **In general, this is simply not possible by merely scanning and discarding frames from the
/// decoder alone (as the spec recommends).** The author of this library can identify three main
/// strategies to mitigate the issues described above:
/// 1. Fully read out Zstandard network streams to disk.
///    - Instead of imparting backpressure by stream processing, decouple the Zstandard
///      decompression from network operations.
///      - Note that there are other forms of fingerprinting unrelated to Zstandard that may remain
///        despite this mitigation.
///    - It may be possible to select buffer sizes according to some degree of randomness to thwart
///      fingerprinting, but that would require a much more thorough analysis to formalize
///      and prove.
/// 2. Fully decode each stream, then re-encode it.
///    - Note that this inverts the threat model: instead of fingerprinting by correlating a stream
///      sent to a particular individual to de-anonymize them, this now risks fingerprinting an
///      individual by their choice of encoder settings.
///      - However, this effectively breaks the link from received Zstandard data stream to
///        recipient, so Zstandard data streams can be received from untrusted sources.
///      - Also note that if the resulting Zstandard data stream is *never* going to be used
///        anywhere else (if it completely stays on the local node or internal network), this
///        mitigation is unnecessary.
///        - Note that encryption is *not* a sufficient protection here if the Zstandard data stream
///          is attacker-controlled! See the CRIME exploit[^crime] linked in the spec.
/// 3. Re-encode using deterministic settings to avoid leaking machine-specific info.
///    - **TODO:** this needs to be fleshed out when the encoder is built!
///    - Especially consider how the translation of symbol frequency tables may incur rounding
///      errors from machine precision boundaries and how this may induce deterministic differences.
///
/// [^crime]: <https://en.wikipedia.org/w/index.php?title=CRIME&oldid=844538656>
pub mod skippable {}