zexc 1.2.1

zex native lossless compressor — CLI zexc, library zexc, files *.zex
Documentation
//! # ZEX — original high-speed secure compressor
//!
//! Pure-Rust **native** compression algorithm and `.zex` container.
//!
//! **Author:** Ali Zain \<alizain@zainiumdynamics.tech\>  
//! **Website:** <https://zainiumdynamics.tech>  
//! **License:** [GPL-3.0-only](https://www.gnu.org/licenses/gpl-3.0.html)
//! (GNU General Public License version 3 **only** — not “or later”).
//! Full text: project root `LICENSE`.
//!
//! ## Not a wrapper
//!
//! ZEX is **not** “LZ4 + Zstd glued together”. Match finding, block format, and
//! entropy (optional) are an **original design**. LZ4/Zstd sources were studied
//! only for engineering ideas (hash tables, acceleration, levels).
//!
//! ## Goals
//!
//! | Goal | How |
//! |------|-----|
//! | **Fast** | Hash-table matcher + adaptive skip on incompressible data |
//! | **Secure** | Safe Rust, hard size caps, match bounds checks, CRC32 default |
//! | **Simple** | One algorithm; profiles only tune search depth |
//!
//! ### Profiles ([`CompressionMode`])
//!
//! - **Turbo** — max speed (shallow search)
//! - **Balanced** — default
//! - **Max** — deeper search + optional literal Huffman
//!
//! ## Quick start
//!
//! ```
//! use zexc::{compress, decompress, CompressOptions, CompressionMode};
//!
//! let src = b"Hello ZEX! Hello ZEX! Hello ZEX!";
//! let opts = CompressOptions::default().mode(CompressionMode::Balanced).level(3);
//! let compressed = compress(src, &opts).unwrap();
//! let restored = decompress(&compressed).unwrap();
//! assert_eq!(src.as_slice(), restored.as_slice());
//! ```
//!
//! ## Streaming
//!
//! ```
//! use std::io::{Cursor, Read, Write};
//! use zexc::{StreamEncoder, StreamDecoder, CompressOptions};
//!
//! let mut sink = Vec::new();
//! {
//!     let mut enc = StreamEncoder::new(&mut sink, CompressOptions::default());
//!     enc.write_all(b"stream me").unwrap();
//!     enc.finish().unwrap();
//! }
//! let mut out = Vec::new();
//! StreamDecoder::new(Cursor::new(&sink)).read_to_end(&mut out).unwrap();
//! assert_eq!(out, b"stream me");
//! ```
//!
//! Full docs: `docs/ARCHITECTURE.md`, `docs/FORMAT.md`, `docs/API.md`.

#![cfg_attr(not(feature = "std"), no_std)]
#![deny(unsafe_op_in_unsafe_fn)]
#![warn(missing_docs, rust_2018_idioms)]

//! ## `no_std`
//!
//! With `default-features = false` (dropping the default-on `std`
//! feature), this crate builds `#![no_std]` + `alloc`, exposing the core
//! compress/decompress path
//! (`compress`/`decompress`, [`Encoder`], [`Decoder`]) for embedding in
//! freestanding environments — see `zainix-kernel/libzainix/src/
//! firmware.rs`'s `ZexDecompressor` for a real consumer. Everything that
//! inherently needs an OS (file-based streaming via [`StreamEncoder`]/
//! [`StreamDecoder`], the `archive`/`seekable`/`cli` modules, parallel
//! compression via `rayon`) stays behind the `std` feature, which is on
//! by default — existing host users see no change.

#[macro_use]
extern crate alloc;

use alloc::string::String;

pub mod algorithms;
#[cfg(feature = "std")]
pub mod archive;
#[cfg(feature = "cli")]
pub mod cli;
pub mod core;
#[cfg(feature = "encryption")]
pub mod crypto;
#[cfg(feature = "c-api")]
pub mod ffi;
pub mod format;
#[cfg(feature = "std")]
pub mod seekable;
pub mod utils;

#[cfg(feature = "std")]
pub use archive::{
    ARCHIVE_MAGIC, ARCHIVE_VERSION, ArchiveEntry, ArchiveListItem, create_archive,
    create_from_paths, extract_archive, extract_to_dir, is_archive, list_archive,
};
#[cfg(feature = "std")]
pub use core::cover::{CoverParams, train_cover};
pub use core::decoder::{Decoder, DecompressOptions, decompress, decompress_with_options};
pub use core::dictionary::Dictionary;
pub use core::encoder::{CompressOptions, Encoder, compress, compress_with_dict};
#[cfg(feature = "std")]
pub use core::frame::{FrameInfo, FrameReader};
#[cfg(feature = "std")]
pub use core::stream::{StreamDecoder, StreamEncoder};
pub use format::block::{BlockHeader, BlockType};
pub use format::header::{CompressionMode, HeaderFlags, MAGIC, VERSION, ZexHeader};
#[cfg(feature = "std")]
pub use seekable::{
    SEEK_MAGIC, SEEK_VERSION, SeekEntry, SeekTable, compress_seekable, compress_seekable_writer,
    decompress_range, decompress_seekable, read_seek_table,
};
pub use utils::security::SecurityPolicy;

#[cfg(feature = "encryption")]
pub use crypto::EncryptionKey;

/// Crate version string.
pub const ZEX_VERSION: &str = env!("CARGO_PKG_VERSION");

/// Library-level error type.
#[derive(Debug, thiserror::Error)]
pub enum Error {
    /// Invalid or unsupported `.zex` header / magic.
    #[error("invalid ZEX header: {0}")]
    InvalidHeader(String),

    /// Unsupported format version.
    #[error("unsupported ZEX version {found} (this build supports {supported})")]
    UnsupportedVersion {
        /// Version found in the stream.
        found: u16,
        /// Version supported by this library.
        supported: u16,
    },

    /// Corrupt or truncated block.
    #[error("corrupt block: {0}")]
    CorruptBlock(String),

    /// CRC32 checksum mismatch.
    #[error("checksum mismatch: expected 0x{expected:08x}, got 0x{actual:08x}")]
    ChecksumMismatch {
        /// Expected CRC from the trailer.
        expected: u32,
        /// Computed CRC over decompressed data.
        actual: u32,
    },

    /// Decompressed size does not match the size declared in the header/block.
    #[error("size mismatch: expected {expected} bytes, got {actual}")]
    SizeMismatch {
        /// Declared size.
        expected: u64,
        /// Actual size.
        actual: u64,
    },

    /// Compression failed (internal encoder error).
    #[error("compression error: {0}")]
    Compression(String),

    /// Decompression failed (internal decoder error).
    #[error("decompression error: {0}")]
    Decompression(String),

    /// Dictionary required but missing / wrong id.
    #[error("dictionary error: {0}")]
    Dictionary(String),

    /// I/O error (`std`-only — the `no_std` core path never produces one).
    #[cfg(feature = "std")]
    #[error("I/O error: {0}")]
    Io(#[from] std::io::Error),

    /// Parameter out of range / security policy violation.
    #[error("invalid parameter: {0}")]
    InvalidParameter(String),
}

/// Convenient `Result` alias for this crate.
pub type Result<T> = ::core::result::Result<T, Error>;