rar_stream/lib.rs
1//! # rar-stream
2//!
3//! A high-performance RAR archive streaming library for Rust, Node.js, and browsers.
4//!
5//! This library provides streaming access to files within RAR archives, optimized for
6//! video streaming with fast seeking via binary search. It supports both RAR4 (1.5-4.x)
7//! and RAR5 (5.0+) formats with full decompression and optional encryption support.
8//!
9//! ## Features
10//!
11//! | Feature | Default | Description |
12//! |---------|---------|-------------|
13//! | `async` | No | Async archive reading via tokio (RarFilesPackage, InnerFile) |
14//! | `crypto` | No | Encrypted archive support (AES-256 for RAR5, AES-128 for RAR4) |
15//! | `napi` | No | Node.js native bindings via napi-rs (implies `async` + `parallel`) |
16//! | `wasm` | No | Browser WebAssembly bindings |
17//!
18//! ## Supported Formats
19//!
20//! | Format | Versions | Compression | Encryption |
21//! |--------|----------|-------------|------------|
22//! | RAR4 | 1.5-4.x | LZSS, PPMd | AES-128-CBC (SHA-1 KDF) |
23//! | RAR5 | 5.0+ | LZSS + filters | AES-256-CBC (PBKDF2-HMAC-SHA256) |
24//!
25//! ## Architecture
26//!
27//! The library is organized into layers:
28//!
29//! ```text
30//! ┌─────────────────────────────────────────────────────┐
31//! │ Application Layer (async feature) │
32//! │ RarFilesPackage → InnerFile → read_to_end() │
33//! ├─────────────────────────────────────────────────────┤
34//! │ Parsing Layer │
35//! │ MarkerHeader → ArchiveHeader → FileHeader │
36//! ├─────────────────────────────────────────────────────┤
37//! │ Decompression Layer │
38//! │ Rar29Decoder (RAR4) / Rar5Decoder (RAR5) │
39//! ├─────────────────────────────────────────────────────┤
40//! │ Crypto Layer (crypto feature) │
41//! │ Rar4Crypto (AES-128) / Rar5Crypto (AES-256) │
42//! └─────────────────────────────────────────────────────┘
43//! ```
44//!
45//! ## Quick Start
46//!
47//! ### High-Level API (requires `async` feature)
48//!
49//! ```rust,ignore
50//! use rar_stream::{RarFilesPackage, ParseOptions, LocalFileMedia, FileMedia};
51//! use std::sync::Arc;
52//!
53//! #[tokio::main]
54//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
55//! let file: Arc<dyn FileMedia> = Arc::new(LocalFileMedia::new("archive.rar")?);
56//! let package = RarFilesPackage::new(vec![file]);
57//!
58//! let files = package.parse(ParseOptions::default()).await?;
59//! for f in &files {
60//! println!("{}: {} bytes", f.name, f.length);
61//! }
62//!
63//! let content = files[0].read_to_end().await?;
64//! Ok(())
65//! }
66//! ```
67//!
68//! ### Low-Level Decompression (no features required)
69//!
70//! ```rust
71//! use rar_stream::Rar29Decoder;
72//!
73//! // Create a decoder for RAR4 LZSS data
74//! let mut decoder = Rar29Decoder::new();
75//!
76//! // Decompress raw compressed data (obtained from file header)
77//! // let decompressed = decoder.decompress(&compressed_data, expected_size)?;
78//! ```
79//!
80//! ## Encrypted Archives
81//!
82//! With the `crypto` feature, you can read encrypted archives:
83//!
84//! ```rust,ignore
85//! use rar_stream::{RarFilesPackage, ParseOptions};
86//!
87//! let opts = ParseOptions {
88//! password: Some("secret".to_string()),
89//! ..Default::default()
90//! };
91//! let files = package.parse(opts).await?;
92//!
93//! // Content is automatically decrypted and decompressed
94//! let content = files[0].read_decompressed().await?;
95//! ```
96//!
97//! ## Error Handling
98//!
99//! All operations return [`Result<T, RarError>`]. Common errors include:
100//!
101//! - [`RarError::InvalidSignature`] - Not a valid RAR file
102//! - [`RarError::PasswordRequired`] - Encrypted archive, no password provided
103//! - [`RarError::DecryptionFailed`] - Wrong password or corrupt data
104//! - [`RarError::DecompressionNotSupported`] - Unsupported compression method
105//!
106//! ## Module Overview
107//!
108//! - [`error`] - Error types for all operations
109//! - [`parsing`] - RAR header parsing (both RAR4 and RAR5)
110//! - [`decompress`] - Decompression algorithms (LZSS, PPMd, filters)
111//! - [`crypto`] - Encryption/decryption (requires `crypto` feature)
112//! - [`formats`] - Low-level format constants and utilities
113//!
114//! ## Performance Notes
115//!
116//! - **Streaming**: Files are read on-demand, not loaded entirely into memory
117//! - **Binary search**: Chunk lookup uses binary search for O(log n) seeking
118//! - **Zero-copy parsing**: Headers are parsed without unnecessary allocations
119//! - **Cached decompression**: Decompressed data is cached for repeated reads
120//!
121//! ## Browser/WASM Usage
122//!
123//! With the `wasm` feature, the library compiles to WebAssembly for browser use.
124//! See the npm package documentation for JavaScript API details.
125
126// Note: unsafe_code = "warn" in Cargo.toml allows targeted unsafe for performance
127// All unsafe blocks should be minimal and well-documented with SAFETY comments
128
129#![cfg_attr(docsrs, feature(doc_cfg))]
130
131mod crc32;
132#[cfg(feature = "crypto")]
133#[cfg_attr(docsrs, doc(cfg(feature = "crypto")))]
134pub mod crypto;
135pub mod decompress;
136pub mod error;
137mod file_media;
138pub mod formats;
139pub mod parsing;
140
141// Async modules (require 'async' feature for tokio-based I/O)
142#[cfg(feature = "async")]
143#[cfg_attr(docsrs, doc(cfg(feature = "async")))]
144mod inner_file;
145#[cfg(feature = "async")]
146mod rar_file_chunk;
147#[cfg(feature = "async")]
148#[cfg_attr(docsrs, doc(cfg(feature = "async")))]
149mod rar_files_package;
150
151#[cfg(feature = "napi")]
152mod napi_bindings;
153
154#[cfg(feature = "wasm")]
155mod wasm_bindings;
156
157pub use error::RarError;
158pub use file_media::{LocalFileMedia, ReadInterval};
159
160#[cfg(feature = "async")]
161#[cfg_attr(docsrs, doc(cfg(feature = "async")))]
162pub use file_media::FileMedia;
163#[cfg(feature = "async")]
164#[cfg_attr(docsrs, doc(cfg(feature = "async")))]
165pub use inner_file::{ChunkMapEntry, InnerFile, InnerFileStream, StreamChunkInfo};
166#[cfg(feature = "async")]
167pub use rar_file_chunk::RarFileChunk;
168#[cfg(feature = "async")]
169#[cfg_attr(docsrs, doc(cfg(feature = "async")))]
170pub use rar_files_package::{ParseOptions, RarFilesPackage};
171
172// Re-export decompression types
173pub use decompress::{CompressionMethod, DecompressError, Rar29Decoder};
174
175// Re-export NAPI bindings when feature is enabled
176#[cfg(all(feature = "napi", not(feature = "wasm")))]
177pub use napi_bindings::*;
178
179// Re-export WASM bindings when feature is enabled
180#[cfg(all(feature = "wasm", not(feature = "napi")))]
181pub use wasm_bindings::*;