waddling_errors_hash/

lib.rs

//! Hash computation for waddling-errors diagnostic codes
//!
//! This crate provides hash computation utilities that can be used both at
//! compile time (in proc macros) and at runtime. The hash function is designed
//! to be:
//!
//! - **Deterministic**: Same input always produces same hash
//! - **Compact**: 5-character base62 encoding (916M combinations)
//! - **Fast**: Uses ahash for performance
//! - **Safe**: Alphanumeric only, safe for all logging systems
//! - **no_std compatible**: Works in constrained environments
//!
//! ## Usage in Proc Macros (Compile Time)
//!
//! ```ignore
//! use waddling_errors_hash::compute_hash;
//!
//! let hash = compute_hash("E.AUTH.TOKEN.001");
//! // Embed hash as a compile-time constant
//! ```
//!
//! ## Usage at Runtime
//!
//! ```ignore
//! use waddling_errors_hash::compute_hash;
//!
//! fn main() {
//!     let code = "E.AUTH.TOKEN.001";
//!     let hash = compute_hash(code);
//!     println!("Hash: {}", hash); // e.g., "aB3xY"
//! }
//! ```

#![cfg_attr(not(feature = "std"), no_std)]

#[cfg(not(feature = "std"))]
extern crate alloc;

#[cfg(feature = "std")]
use std::string::String;

#[cfg(not(feature = "std"))]
use alloc::string::String;

use ahash::RandomState;
use core::hash::{BuildHasher, Hash, Hasher};

/// Compute a 5-character base62 hash from an input string
///
/// Uses ahash with a fixed "Waddling" salt to ensure deterministic results
/// across compilations and platforms. Returns an alphanumeric-only hash
/// that is safe for all logging systems and provides 916M+ combinations.
///
/// # Algorithm
///
/// 1. Initialize ahash with fixed seeds (derived from "Waddling")
/// 2. Hash the salt + input string
/// 3. Take the first 5 bytes of the 64-bit hash
/// 4. Convert to base62 (0-9, A-Z, a-z)
///
/// # Examples
///
/// ```
/// use waddling_errors_hash::compute_hash;
///
/// let hash = compute_hash("E.AUTH.TOKEN.001");
/// assert_eq!(hash.len(), 5);
/// assert!(hash.chars().all(|c| c.is_ascii_alphanumeric()));
/// ```
///
/// # Determinism
///
/// The same input will always produce the same hash:
///
/// ```
/// use waddling_errors_hash::compute_hash;
///
/// let hash1 = compute_hash("E.AUTH.TOKEN.001");
/// let hash2 = compute_hash("E.AUTH.TOKEN.001");
/// assert_eq!(hash1, hash2);
/// ```
pub fn compute_hash(input: &str) -> String {
    const SALT: &str = "Waddling";

    // Fixed seeds for deterministic hashing across compilations
    // Derived from UTF-8 bytes of "Waddling"
    let state = RandomState::with_seeds(
        0x576164646c696e67, // "Waddling" as u64 (big-endian)
        0x0000000000000000,
        0x0000000000000000,
        0x0000000000000000,
    );

    // Compute hash with salt + input
    let mut hasher = state.build_hasher();
    SALT.hash(&mut hasher);
    input.hash(&mut hasher);
    let hash_result = hasher.finish();

    // Extract first 5 bytes from the 64-bit hash
    let bytes = [
        (hash_result >> 56) as u8,
        (hash_result >> 48) as u8,
        (hash_result >> 40) as u8,
        (hash_result >> 32) as u8,
        (hash_result >> 24) as u8,
    ];

    // Convert to base62 (0-9, A-Z, a-z)
    const BASE62_CHARS: &[u8] = b"0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
    const BASE: u64 = 62;

    // Combine bytes into a single number
    let mut num = 0u64;
    for &byte in &bytes {
        num = (num << 8) | (byte as u64);
    }

    // Convert to base62 with exactly 5 characters
    let mut result_chars = [0u8; 5];
    let mut n = num;

    for i in (0..5).rev() {
        result_chars[i] = BASE62_CHARS[(n % BASE) as usize];
        n /= BASE;
    }

    // Safety: base62 encoding always produces valid UTF-8
    String::from_utf8(result_chars.to_vec()).expect("base62 encoding produces valid UTF-8")
}

/// Verify that a hash was computed from the given input
///
/// This is useful for validating that a hash matches an error code,
/// which can help detect mismatches or corruption.
///
/// # Examples
///
/// ```
/// use waddling_errors_hash::{compute_hash, verify_hash};
///
/// let code = "E.AUTH.TOKEN.001";
/// let hash = compute_hash(code);
/// assert!(verify_hash(code, &hash));
/// assert!(!verify_hash("E.AUTH.TOKEN.002", &hash));
/// ```
pub fn verify_hash(input: &str, hash: &str) -> bool {
    let computed = compute_hash(input);
    computed == hash
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_compute_hash_deterministic() {
        let input = "E.AUTH.TOKEN.001";
        let hash1 = compute_hash(input);
        let hash2 = compute_hash(input);
        assert_eq!(hash1, hash2, "Hash should be deterministic");
    }

    #[test]
    fn test_hash_length() {
        let hash = compute_hash("E.AUTH.TOKEN.001");
        assert_eq!(hash.len(), 5, "Hash should be exactly 5 characters");
    }

    #[test]
    fn test_hash_alphanumeric() {
        let hash = compute_hash("E.AUTH.TOKEN.001");
        assert!(
            hash.chars().all(|c| c.is_ascii_alphanumeric()),
            "Hash should contain only alphanumeric characters"
        );
    }

    #[test]
    fn test_different_inputs_produce_different_hashes() {
        let hash1 = compute_hash("E.AUTH.TOKEN.001");
        let hash2 = compute_hash("E.AUTH.TOKEN.002");
        assert_ne!(
            hash1, hash2,
            "Different inputs should produce different hashes"
        );
    }

    #[test]
    fn test_verify_hash() {
        let input = "E.AUTH.TOKEN.001";
        let hash = compute_hash(input);
        assert!(
            verify_hash(input, &hash),
            "Hash verification should succeed"
        );
        assert!(
            !verify_hash("E.AUTH.TOKEN.002", &hash),
            "Hash verification should fail for different input"
        );
    }

    #[test]
    fn test_hash_examples() {
        // Test a few known inputs to ensure consistency across runs
        let test_cases = vec![
            "E.AUTH.TOKEN.001",
            "W.DB.CONNECTION.002",
            "I.API.RATE_LIMIT.003",
            "E.CACHE.MISS.004",
        ];

        for input in test_cases {
            let hash = compute_hash(input);
            assert_eq!(hash.len(), 5);
            assert!(hash.chars().all(|c| c.is_ascii_alphanumeric()));

            // Verify it's reproducible
            assert_eq!(hash, compute_hash(input));
        }
    }

    #[test]
    fn test_empty_string() {
        let hash = compute_hash("");
        assert_eq!(hash.len(), 5);
        assert!(hash.chars().all(|c| c.is_ascii_alphanumeric()));
    }

    #[test]
    fn test_unicode_input() {
        let hash = compute_hash("E.AUTH.TOKEN.🦆");
        assert_eq!(hash.len(), 5);
        assert!(hash.chars().all(|c| c.is_ascii_alphanumeric()));
    }

    #[test]
    fn test_long_input() {
        let long_input = "E.AUTH.TOKEN.".to_string() + &"A".repeat(1000);
        let hash = compute_hash(&long_input);
        assert_eq!(hash.len(), 5);
        assert!(hash.chars().all(|c| c.is_ascii_alphanumeric()));
    }
}