codeq/config/
mod.rs

1//! Configuration for checksum calculation and verification.
2
3use core::hash::Hasher;
4use std::fmt::Debug;
5use std::hash::Hash;
6use std::io;
7
8use crate::ChecksumReader;
9use crate::ChecksumWriter;
10use crate::Segment;
11use crate::WithChecksum;
12
13/// Static Configuration for checksum calculation and verification.
14///
15/// This trait defines how checksums are calculated and verified for data integrity.
16/// It allows applications to:
17/// - Choose their preferred checksum algorithm (e.g., CRC32, CRC64)
18/// - Create checksum-enabled readers and writers
19/// - Wrap data with checksums
20///
21/// # Examples
22///
23/// Using the default CRC32 implementation:
24#[cfg_attr(not(feature = "crc32fast"), doc = "```ignore")]
25#[cfg_attr(feature = "crc32fast", doc = "```rust")]
26/// use codeq::config::Crc32fast;
27/// # use codeq::config::CodeqConfig;
28/// # use std::io::Write;
29///
30/// let mut writer = Crc32fast::new_writer(Vec::new());
31/// writer.write_all(b"hello").unwrap();
32/// ```
33/// 
34/// Custom implementation:
35/// ```
36/// use codeq::config::CodeqConfig;
37///
38/// #[derive(Debug, Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
39/// struct CustomConfig;
40/// impl CodeqConfig for CustomConfig {
41///     type Hasher = std::collections::hash_map::DefaultHasher;
42/// }
43/// ```
44/// 
45/// Note: Data encoded with one configuration cannot be decoded with a different configuration.
46/// For example, data encoded with CRC32 cannot be decoded with CRC64, and vice versa.
47///
48/// Standard bounds (`Debug`, `Clone`, `Default`, etc.) required for use as a generic parameter
49/// in types like `WithChecksum<C,T>` and `Segment<C>` throughout the codebase.
50pub trait CodeqConfig
51where Self: Debug + Clone + Copy + Default + PartialEq + Eq + PartialOrd + Ord + Hash + Sized
52{
53    /// The hasher type used for checksum calculation.
54    type Hasher: Hasher + Default;
55
56    /// Calculates a checksum for the given buffer.
57    fn hash(buf: &[u8]) -> u64 {
58        let mut hasher = Self::Hasher::default();
59        hasher.write(buf);
60        hasher.finish()
61    }
62
63    /// Creates a new checksum writer wrapping the given writer.
64    fn new_writer<W: io::Write>(inner: W) -> ChecksumWriter<Self, W> {
65        ChecksumWriter::new(inner)
66    }
67
68    /// Creates a new checksum reader wrapping the given reader.
69    fn new_reader<R: io::Read>(inner: R) -> ChecksumReader<Self, R> {
70        ChecksumReader::new(inner)
71    }
72
73    /// Wraps data with checksum protection.
74    fn wrap<T>(data: T) -> WithChecksum<Self, T> {
75        WithChecksum::<Self, _>::new(data)
76    }
77
78    /// Creates a new segment with the given offset and size.
79    fn segment(offset: u64, size: u64) -> Segment<Self> {
80        Segment::<Self>::new(offset, size)
81    }
82}
83
84#[cfg(feature = "crc32fast")]
85pub mod crc32fast_impl {
86    use super::CodeqConfig;
87
88    /// CRC32 checksum implementation.
89    ///
90    /// Derives standard traits to allow this type to be used as a generic type parameter,
91    /// when the containing type requires these bounds.
92    #[derive(Debug, Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
93    pub struct Crc32fast;
94
95    impl CodeqConfig for Crc32fast {
96        type Hasher = crc32fast::Hasher;
97    }
98}
99
100#[cfg(feature = "crc32fast")]
101pub use crc32fast_impl::Crc32fast;
102
103#[cfg(feature = "crc64fast-nvme")]
104mod crc64fast_nvme_impl {
105    use crate::config::CodeqConfig;
106
107    #[derive(Default, Clone)]
108    pub struct Crc64fastNvmeHasher(crc64fast_nvme::Digest);
109
110    impl core::hash::Hasher for Crc64fastNvmeHasher {
111        fn finish(&self) -> u64 {
112            self.0.sum64()
113        }
114
115        fn write(&mut self, bytes: &[u8]) {
116            self.0.write(bytes);
117        }
118    }
119
120    /// CRC64-NVME checksum implementation.
121    ///
122    /// Derives standard traits to allow this type to be used as a generic type parameter,
123    /// when the containing type requires these bounds.
124    #[derive(Debug, Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
125    pub struct Crc64fastNvme;
126
127    impl CodeqConfig for Crc64fastNvme {
128        type Hasher = Crc64fastNvmeHasher;
129    }
130}
131
132#[cfg(feature = "crc64fast-nvme")]
133pub use crc64fast_nvme_impl::Crc64fastNvme;
codeq/config/mod.rs

codeq/config/
mod.rs
