waddling_errors_hash/

algorithm.rs

//! WDP-compliant hash algorithm
//!
//! This module provides the WDP-specified xxHash3 algorithm for error code hashing.
//! Per WDP Part 5: Compact IDs, all error codes use xxHash3 with seed `0x000031762D706477`.

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

/// Hash algorithm selection
///
/// WDP specifies xxHash3 as the standard algorithm for error code hashing.
/// xxHash3 is optimized for small inputs (15-30 byte error codes), making it
/// ideal for WDP's use case.
///
/// Note: This enum is kept for API compatibility but only xxHash3 is WDP-compliant.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum HashAlgorithm {
    /// xxHash3 - WDP-specified algorithm (default)
    ///
    /// - Speed: ~30 GB/s
    /// - Optimized for small inputs (perfect for error codes!)
    /// - Security: NOT cryptographically secure (not needed for error codes)
    /// - Cross-platform: C, Python, JS, Go, Java, Rust, etc.
    /// - Standard: WDP Part 5 mandates xxHash3 with seed 0x000031762D706477
    #[default]
    XxHash3,
}

impl HashAlgorithm {
    /// Get the algorithm name as a string
    pub fn as_str(&self) -> &'static str {
        match self {
            HashAlgorithm::XxHash3 => "xxHash3",
        }
    }

    /// Check if algorithm is WDP-compliant
    ///
    /// Returns true for xxHash3 (the only WDP-compliant algorithm).
    pub fn is_wdp_compliant(&self) -> bool {
        matches!(self, HashAlgorithm::XxHash3)
    }

    /// Check if algorithm is cross-language compatible
    ///
    /// xxHash3 is supported in C, Python, JS, Go, Java, Rust, and more.
    pub fn is_cross_language(&self) -> bool {
        true // xxHash3 is cross-language
    }
}

/// Error type for parsing HashAlgorithm from string
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ParseHashAlgorithmError;

impl core::fmt::Display for ParseHashAlgorithmError {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        write!(f, "unknown hash algorithm (only 'xxhash3' is supported)")
    }
}

impl core::str::FromStr for HashAlgorithm {
    type Err = ParseHashAlgorithmError;

    /// Parse algorithm from string (case-insensitive)
    ///
    /// Only xxHash3 is WDP-compliant.
    ///
    /// # Examples
    ///
    /// ```
    /// use waddling_errors_hash::HashAlgorithm;
    /// use std::str::FromStr;
    ///
    /// assert_eq!(HashAlgorithm::from_str("xxHash3"), Ok(HashAlgorithm::XxHash3));
    /// assert_eq!(HashAlgorithm::from_str("xxh3"), Ok(HashAlgorithm::XxHash3));
    /// assert!(HashAlgorithm::from_str("unknown").is_err());
    /// ```
    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s.to_lowercase().as_str() {
            "xxhash3" | "xxh3" | "xx3" | "xxhash" | "default" => Ok(HashAlgorithm::XxHash3),
            _ => Err(ParseHashAlgorithmError),
        }
    }
}

/// WDP v1 seed as a numeric value
///
/// Per WDP Part 5: Compact IDs specification.
/// ASCII bytes of "wdp-v1\0\0" interpreted as little-endian u64 = 0x000031762D706477
pub const WDP_SEED: u64 = 0x000031762D706477;

/// WDP v1 seed as a string (for display/documentation)
pub const WDP_SEED_STR: &str = "wdp-v1";

/// Hash configuration
///
/// For WDP compliance, use `HashConfig::wdp_compliant()` which uses
/// xxHash3 with the standard WDP seed.
#[derive(Debug, Clone)]
pub struct HashConfig {
    /// The hash algorithm to use (only xxHash3 for WDP)
    pub algorithm: HashAlgorithm,

    /// Seed for the hash
    ///
    /// Default is `0x000031762D706477` per WDP specification.
    pub seed: u64,
}

impl Default for HashConfig {
    fn default() -> Self {
        Self::wdp_compliant()
    }
}

impl HashConfig {
    /// Create a new hash config with custom seed
    pub fn new(seed: u64) -> Self {
        Self {
            algorithm: HashAlgorithm::XxHash3,
            seed,
        }
    }

    /// Create a WDP-compliant config (xxHash3 + WDP seed)
    ///
    /// This is the standard configuration per WDP Part 5.
    pub fn wdp_compliant() -> Self {
        Self {
            algorithm: HashAlgorithm::XxHash3,
            seed: WDP_SEED,
        }
    }

    /// Create a config with a custom seed (for testing/isolation)
    pub fn with_seed(seed: u64) -> Self {
        Self {
            algorithm: HashAlgorithm::XxHash3,
            seed,
        }
    }
}

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

    #[test]
    fn test_algorithm_from_str() {
        use core::str::FromStr;
        assert_eq!(
            HashAlgorithm::from_str("xxHash3"),
            Ok(HashAlgorithm::XxHash3)
        );
        assert_eq!(HashAlgorithm::from_str("xxh3"), Ok(HashAlgorithm::XxHash3));
        assert_eq!(
            HashAlgorithm::from_str("xxhash"),
            Ok(HashAlgorithm::XxHash3)
        );
        assert!(HashAlgorithm::from_str("unknown").is_err());
    }

    #[test]
    fn test_algorithm_is_wdp_compliant() {
        assert!(HashAlgorithm::XxHash3.is_wdp_compliant());
    }

    #[test]
    fn test_algorithm_is_cross_language() {
        assert!(HashAlgorithm::XxHash3.is_cross_language());
    }

    #[test]
    fn test_default_config() {
        let config = HashConfig::default();
        assert_eq!(config.algorithm, HashAlgorithm::XxHash3);
        assert_eq!(config.seed, WDP_SEED);
    }

    #[test]
    fn test_config_with_seed() {
        let config = HashConfig::with_seed(0x12345678);
        assert_eq!(config.algorithm, HashAlgorithm::XxHash3);
        assert_eq!(config.seed, 0x12345678);
    }

    #[test]
    fn test_config_wdp_compliant() {
        let config = HashConfig::wdp_compliant();
        assert_eq!(config.algorithm, HashAlgorithm::XxHash3);
        assert_eq!(config.seed, 0x000031762D706477);
    }

    #[test]
    fn test_wdp_seed_value() {
        // Verify the seed is ASCII "wdp-v1\0\0" as little-endian u64
        assert_eq!(WDP_SEED, 0x000031762D706477);
    }
}