zexc 1.2.1

zex native lossless compressor — CLI zexc, library zexc, files *.zex
Documentation
//! ZEX frame header — magic, version, flags, sizes, dictionary id.
//!
//! Wire layout (little-endian unless noted):
//! ```text
//! offset  size  field
//! 0       4     Magic          "ZEX1"  (0x5A, 0x45, 0x58, 0x31)
//! 4       2     Version        u16 LE  (currently 1)
//! 6       2     Flags          HeaderFlags bitfield
//! 8       1     Mode           CompressionMode
//! 9       1     Level          1..=22 (algorithm hint; stored for info)
//! 10      4     BlockSize      max uncompressed block size (power of 2)
//! 14      8     ContentSize    original size (u64::MAX = unknown)
//! 22      4     DictionaryId   0 = none
//! ```
//! Total fixed header including magic: 26 bytes.

use crate::{Error, Result};
#[cfg(feature = "std")]
use std::io::{Read, Write};

/// ASCII magic: `Z E X 1`
pub const MAGIC: [u8; 4] = *b"ZEX1";

/// Current format version.
pub const VERSION: u16 = 1;

/// Fixed size of the header including magic (bytes).
pub const HEADER_SIZE: usize = 26;

/// Default max uncompressed block size (256 KiB) — good for MT + cache.
pub const DEFAULT_BLOCK_SIZE: u32 = 256 * 1024;

// ─── Minimal bitflags (no extra crate) ───────────────────────────────────────

macro_rules! bitflags_struct {
    (
        $(#[$meta:meta])*
        pub struct $name:ident: $ty:ty {
            $(
                $(#[$fmeta:meta])*
                const $flag:ident = $val:expr;
            )*
        }
    ) => {
        $(#[$meta])*
        pub struct $name(pub $ty);

        impl $name {
            $(
                $(#[$fmeta])*
                pub const $flag: Self = Self($val);
            )*

            /// Empty flags.
            pub const fn empty() -> Self { Self(0) }

            /// All defined bits.
            #[allow(dead_code)]
            pub const fn all() -> Self {
                Self(0 $(| $val)*)
            }

            /// Raw bits.
            pub const fn bits(self) -> $ty { self.0 }

            /// From raw bits (unknown bits preserved).
            pub const fn from_bits_truncate(bits: $ty) -> Self { Self(bits) }

            /// Contains flag?
            pub const fn contains(self, other: Self) -> bool {
                self.0 & other.0 == other.0
            }

            /// Insert flag bits.
            pub fn insert(&mut self, other: Self) { self.0 |= other.0; }

            /// Remove flag bits.
            pub fn remove(&mut self, other: Self) { self.0 &= !other.0; }

            /// Set or clear a flag.
            pub fn set(&mut self, other: Self, on: bool) {
                if on { self.insert(other) } else { self.remove(other) }
            }
        }

        impl Default for $name {
            fn default() -> Self { Self::empty() }
        }

        impl ::core::ops::BitOr for $name {
            type Output = Self;
            fn bitor(self, rhs: Self) -> Self { Self(self.0 | rhs.0) }
        }

        impl ::core::ops::BitOrAssign for $name {
            fn bitor_assign(&mut self, rhs: Self) { self.0 |= rhs.0; }
        }
    };
}

/// Speed / ratio **profile** for the single native ZEX algorithm.
///
/// This is **not** “pick LZ4 vs Zstd”. One codec; profiles only bias level defaults
/// and search aggressiveness hints stored in the header for tooling.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
#[repr(u8)]
pub enum CompressionMode {
    /// Maximum throughput (low search depth, high acceleration).
    Turbo = 0,
    /// Default balance of speed and ratio.
    #[default]
    Balanced = 1,
    /// Prefer ratio (deeper search, optional entropy on literals).
    Max = 2,
}

impl CompressionMode {
    /// Parse from wire byte.
    pub fn from_u8(v: u8) -> Result<Self> {
        match v {
            0 => Ok(Self::Turbo),
            1 => Ok(Self::Balanced),
            2 => Ok(Self::Max),
            // Accept early prototype names stored as 0/1/2 already.
            other => Err(Error::InvalidHeader(format!("unknown mode {other}"))),
        }
    }

    /// Suggested default level for this profile.
    pub fn default_level(self) -> u8 {
        match self {
            Self::Turbo => 1,
            Self::Balanced => 3,
            Self::Max => 12,
        }
    }

    /// Map profile + user level into the effective codec level (1–22).
    pub fn effective_level(self, user_level: u8) -> u8 {
        let l = user_level.clamp(1, 22);
        match self {
            Self::Turbo => l.min(4),
            Self::Balanced => l,
            Self::Max => l.max(8),
        }
    }

    /// Human-readable name.
    pub fn as_str(self) -> &'static str {
        match self {
            Self::Turbo => "turbo",
            Self::Balanced => "balanced",
            Self::Max => "max",
        }
    }
}

impl ::core::fmt::Display for CompressionMode {
    fn fmt(&self, f: &mut ::core::fmt::Formatter<'_>) -> ::core::fmt::Result {
        f.write_str(self.as_str())
    }
}

impl ::core::str::FromStr for CompressionMode {
    type Err = Error;
    fn from_str(s: &str) -> Result<Self> {
        match s.to_ascii_lowercase().as_str() {
            "turbo" | "fast" | "speed" => Ok(Self::Turbo),
            "balanced" | "normal" | "default" | "hybrid" => Ok(Self::Balanced),
            "max" | "high" | "ratio" | "best" => Ok(Self::Max),
            other => Err(Error::InvalidParameter(format!(
                "unknown profile '{other}' (use turbo|balanced|max)"
            ))),
        }
    }
}

bitflags_struct! {
    /// Header flag bits (u16).
    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
    pub struct HeaderFlags: u16 {
        /// Content CRC32 trailer present.
        const CHECKSUM     = 0b0000_0000_0001;
        /// Frame has a content size field that is valid (not u64::MAX).
        const CONTENT_SIZE = 0b0000_0000_0010;
        /// Dictionary was used during compression.
        const DICTIONARY   = 0b0000_0000_0100;
        /// Blocks are independent (safe for multi-threaded decode).
        const INDEPENDENT  = 0b0000_0000_1000;
        /// Multi-threaded compression was used (informational).
        const MULTITHREAD  = 0b0000_0001_0000;
        /// Secure policy was applied at compress time (strict caps).
        const SECURE       = 0b0000_0010_0000;
        /// Frame body is ChaCha20-Poly1305 encrypted (after header).
        const ENCRYPTED    = 0b0000_0100_0000;
    }
}

/// ZEX frame header.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ZexHeader {
    /// Format version.
    pub version: u16,
    /// Feature flags.
    pub flags: HeaderFlags,
    /// Default compression mode for the frame.
    pub mode: CompressionMode,
    /// Compression level used (1–22).
    pub level: u8,
    /// Maximum uncompressed block size.
    pub block_size: u32,
    /// Original content size, or `u64::MAX` if unknown.
    pub content_size: u64,
    /// Dictionary identifier (`0` = none).
    pub dictionary_id: u32,
}

impl Default for ZexHeader {
    fn default() -> Self {
        Self {
            version: VERSION,
            flags: HeaderFlags::CHECKSUM | HeaderFlags::CONTENT_SIZE | HeaderFlags::INDEPENDENT,
            mode: CompressionMode::Balanced,
            level: 3,
            block_size: DEFAULT_BLOCK_SIZE,
            content_size: u64::MAX,
            dictionary_id: 0,
        }
    }
}

impl ZexHeader {
    /// Build a header for known content length.
    pub fn new(content_size: u64, mode: CompressionMode, level: u8) -> Self {
        let mut h = Self {
            content_size,
            mode,
            level: level.clamp(1, 22),
            ..Default::default()
        };
        h.flags
            .set(HeaderFlags::CONTENT_SIZE, content_size != u64::MAX);
        h
    }

    /// Serialize header (including magic) to `out` — `no_std`-safe,
    /// no I/O trait needed (the only real consumer of a generic `Write`
    /// version is the `std`-only streaming path below).
    pub fn to_bytes(&self) -> [u8; HEADER_SIZE] {
        let mut buf = [0u8; HEADER_SIZE];
        buf[0..4].copy_from_slice(&MAGIC);
        buf[4..6].copy_from_slice(&self.version.to_le_bytes());
        buf[6..8].copy_from_slice(&self.flags.bits().to_le_bytes());
        buf[8] = self.mode as u8;
        buf[9] = self.level;
        buf[10..14].copy_from_slice(&self.block_size.to_le_bytes());
        buf[14..22].copy_from_slice(&self.content_size.to_le_bytes());
        buf[22..26].copy_from_slice(&self.dictionary_id.to_le_bytes());
        buf
    }

    /// `std`-only streaming twin of [`Self::to_bytes`], for
    /// [`crate::core::stream`]'s incremental `Write`-based encoder.
    #[cfg(feature = "std")]
    pub fn write_to<W: Write>(&self, out: &mut W) -> Result<()> {
        out.write_all(&self.to_bytes())?;
        Ok(())
    }

    /// `std`-only streaming twin of [`Self::from_bytes`], for
    /// [`crate::core::stream`]'s incremental `Read`-based decoder.
    #[cfg(feature = "std")]
    pub fn read_from<R: Read>(inp: &mut R) -> Result<Self> {
        let mut buf = [0u8; HEADER_SIZE];
        inp.read_exact(&mut buf)?;
        Self::from_bytes(&buf)
    }

    /// Parse from a full byte slice (must include magic) — `no_std`-safe,
    /// no I/O trait needed. Validates magic and version.
    pub fn from_bytes(buf: &[u8]) -> Result<Self> {
        if buf.len() < HEADER_SIZE {
            return Err(Error::InvalidHeader(format!(
                "buffer too short: {} < {HEADER_SIZE}",
                buf.len()
            )));
        }

        let magic = &buf[0..4];
        if magic != MAGIC {
            return Err(Error::InvalidHeader(format!(
                "bad magic {:02x?} (expected ZEX1)",
                magic
            )));
        }

        let version = u16::from_le_bytes([buf[4], buf[5]]);
        if version != VERSION {
            return Err(Error::UnsupportedVersion {
                found: version,
                supported: VERSION,
            });
        }

        let flags = HeaderFlags::from_bits_truncate(u16::from_le_bytes([buf[6], buf[7]]));
        let mode = CompressionMode::from_u8(buf[8])?;
        let level = buf[9];
        let block_size = u32::from_le_bytes(buf[10..14].try_into().unwrap());
        let content_size = u64::from_le_bytes(buf[14..22].try_into().unwrap());
        let dictionary_id = u32::from_le_bytes(buf[22..26].try_into().unwrap());

        if !(1024..=128 * 1024 * 1024).contains(&block_size) {
            return Err(Error::InvalidHeader(format!(
                "block_size {block_size} out of range"
            )));
        }

        Ok(Self {
            version,
            flags,
            mode,
            level,
            block_size,
            content_size,
            dictionary_id,
        })
    }

    /// Whether content CRC is expected after the last block.
    pub fn has_checksum(&self) -> bool {
        self.flags.contains(HeaderFlags::CHECKSUM)
    }

    /// Whether blocks are independent (no cross-block window).
    pub fn independent_blocks(&self) -> bool {
        self.flags.contains(HeaderFlags::INDEPENDENT)
    }

    /// Whether the frame body is ChaCha20-Poly1305 encrypted.
    pub fn is_encrypted(&self) -> bool {
        self.flags.contains(HeaderFlags::ENCRYPTED)
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn header_roundtrip() {
        let h = ZexHeader::new(12345, CompressionMode::Max, 9);
        let bytes = h.to_bytes();
        assert_eq!(&bytes[..4], b"ZEX1");
        let parsed = ZexHeader::from_bytes(&bytes).unwrap();
        assert_eq!(parsed, h);
    }

    #[test]
    fn bad_magic() {
        let mut bad = ZexHeader::default().to_bytes();
        bad[0] = b'X';
        assert!(ZexHeader::from_bytes(&bad).is_err());
    }
}