khive_types/
hash.rs

1//! 256-bit content hash for checkpoint integrity verification.
2
3use core::fmt;
4
5#[cfg(feature = "serde")]
6use serde::{Deserialize, Serialize};
7
8/// 256-bit (32-byte) content hash.
9///
10/// Used as a content-addressed identifier for HNSW checkpoints and other
11/// snapshot artifacts. The underlying algorithm is caller-defined; the type
12/// carries the raw bytes without encoding assumptions.
13#[derive(Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
14#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
15#[cfg_attr(feature = "serde", serde(transparent))]
16pub struct Hash32([u8; 32]);
17
18impl Hash32 {
19    /// Zero hash (nil value).
20    pub const ZERO: Self = Self([0u8; 32]);
21
22    /// Construct from raw bytes.
23    #[inline]
24    pub const fn from_bytes(bytes: [u8; 32]) -> Self {
25        Self(bytes)
26    }
27
28    /// Return the raw byte representation.
29    #[inline]
30    pub const fn as_bytes(&self) -> &[u8; 32] {
31        &self.0
32    }
33
34    /// Compute a BLAKE3 hash over the given byte slice.
35    ///
36    /// Requires the `blake3` feature.
37    #[cfg(feature = "blake3")]
38    #[inline]
39    pub fn from_blake3(data: &[u8]) -> Self {
40        let hash = blake3::hash(data);
41        Self(*hash.as_bytes())
42    }
43
44    /// Constant-time equality check.
45    ///
46    /// Accumulates XOR over all 32 bytes without early exit so the comparison
47    /// takes the same number of iterations regardless of where bytes differ.
48    /// Suitable for integrity comparisons where timing side-channels are a
49    /// concern.  The `#[inline(never)]` attribute discourages the compiler from
50    /// inlining and optimising away the full-loop traversal.
51    #[inline(never)]
52    pub fn eq_ct(&self, other: &Self) -> bool {
53        let diff = self
54            .0
55            .iter()
56            .zip(other.0.iter())
57            .fold(0u8, |acc, (a, b)| acc | (a ^ b));
58        diff == 0
59    }
60}
61
62impl From<[u8; 32]> for Hash32 {
63    #[inline]
64    fn from(bytes: [u8; 32]) -> Self {
65        Self(bytes)
66    }
67}
68
69impl fmt::Debug for Hash32 {
70    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
71        write!(f, "Hash32(")?;
72        for b in &self.0 {
73            write!(f, "{b:02x}")?;
74        }
75        write!(f, ")")
76    }
77}
78
79impl fmt::Display for Hash32 {
80    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
81        for b in &self.0 {
82            write!(f, "{b:02x}")?;
83        }
84        Ok(())
85    }
86}
khive_types/hash.rs

khive_types/
hash.rs
