simd_r_drive/utils/
namespace_hasher.rs

1use crate::storage_engine::digest::compute_hash;
2
3/// A utility struct for namespacing keys using XXH3 hashing.
4///
5/// This ensures that keys are uniquely identified within a given namespace,
6/// even if they share the same suffix. By hashing both the namespace and key
7/// separately before combining them, it prevents unintended collisions.
8///
9/// # Example:
10/// ```
11/// use simd_r_drive::utils::NamespaceHasher;
12///
13/// let hasher = NamespaceHasher::new(b"opt");
14/// let namespaced_key = hasher.namespace(b"my_key");
15/// assert_eq!(namespaced_key.len(), 16, "Namespaced key should be exactly 16 bytes");
16/// ```
17pub struct NamespaceHasher {
18    prefix: u64,
19}
20
21impl NamespaceHasher {
22    /// Creates a new `NamespaceHasher` with a given prefix.
23    ///
24    /// The prefix itself is hashed using XXH3 to ensure a unique namespace identifier.
25    /// This avoids collisions between different namespaces while keeping the hashing fast.
26    ///
27    /// # Arguments
28    /// - `prefix`: A byte slice representing the namespace prefix.
29    ///
30    /// # Returns
31    /// - A `NamespaceHasher` instance with a precomputed prefix hash.
32    #[inline]
33    pub fn new(prefix: &[u8]) -> Self {
34        Self {
35            prefix: compute_hash(prefix),
36        }
37    }
38
39    /// Computes a namespaced key, returning it as a **16-byte vector**.
40    ///
41    /// The final namespaced key is derived by:
42    /// 1. Hashing the key separately to ensure uniqueness.
43    /// 2. Combining it with the precomputed namespace hash.
44    /// 3. Returning the **concatenation of both hashes** as a **16-byte key**.
45    ///
46    /// This ensures that:
47    /// - **Different namespaces** do not generate overlapping keys.
48    /// - **Keys within a namespace** remain **uniquely identifiable**.
49    ///
50    /// # Arguments
51    /// - `key`: A byte slice representing the key to be namespaced.
52    ///
53    /// # Returns
54    /// - A `Vec<u8>` containing the **16-byte** namespaced key (`8-byte prefix hash + 8-byte key hash`).
55    #[inline]
56    pub fn namespace(&self, key: &[u8]) -> Vec<u8> {
57        let key_hash = compute_hash(key);
58
59        // Combine both hashes into a 16-byte buffer
60        let mut buffer = Vec::with_capacity(16);
61        buffer.extend_from_slice(&self.prefix.to_le_bytes()); // Prefix hash (8 bytes)
62        buffer.extend_from_slice(&key_hash.to_le_bytes()); // Key hash (8 bytes)
63
64        buffer
65    }
66}
simd_r_drive/utils/namespace_hasher.rs

simd_r_drive/utils/
namespace_hasher.rs
