pulith_verify/lib.rs
1//! Content verification primitives for downloaded artifacts.
2//!
3//! Zero-copy streaming verification for downloaded artifacts, ensuring integrity
4//! without additional memory overhead.
5//!
6//! # Design Principles
7//!
8//! - **Zero-Copy Verification**: CPU cache touches bytes only once (hashing + I/O)
9//! - **Composability**: Generic over any `Hasher` trait implementation
10//! - **Extensibility**: Built on `digest::Digest` for broad algorithm support
11//! - **Error Handling**: Concrete error types using `thiserror`
12//!
13//! # Key Features
14//!
15//! - **Zero-copy verification**: CPU cache touches bytes only once (for both hashing and writing)
16//! - **Incremental**: Computes digests as data streams through
17//! - **Extensible**: Minimal `Hasher` trait allows custom implementations
18//! - **Thread-safe**: All public types implement `Send + Sync`
19//!
20//! # Example
21//!
22//! ```
23//! use pulith_verify::{VerifiedReader, Sha256Hasher, VerifyError};
24//! use std::fs::File;
25//! use std::io::{self, Read};
26//!
27//! fn verify_artifact(path: &str, expected_hash_hex: &str) -> Result<(), VerifyError> {
28//! let expected = hex::decode(expected_hash_hex)?;
29//! let file = File::open(path)?;
30//! let hasher = Sha256Hasher::new();
31//! let mut reader = VerifiedReader::new(file, hasher);
32//!
33//! let mut buffer = vec![0; 8192];
34//! loop {
35//! match reader.read(&mut buffer) {
36//! Ok(0) => break,
37//! Ok(_) => {},
38//! Err(e) => return Err(VerifyError::Io(e)),
39//! }
40//! }
41//!
42//! reader.finish(&expected)?;
43//! Ok(())
44//! }
45//! ```
46
47pub use self::error::{Result, VerifyError};
48pub use self::hasher::{DigestHasher, Hasher};
49pub use self::reader::{VerificationReceipt, VerifiedReader, verify_stream};
50
51#[cfg(feature = "sha256")]
52pub use self::hasher::Sha256Hasher;
53
54#[cfg(feature = "blake3")]
55pub use self::hasher::Blake3Hasher;
56
57#[cfg(feature = "sha3")]
58pub use self::hasher::Sha3_256Hasher;
59
60mod error;
61mod hasher;
62mod reader;