waddling_errors_hash/

lib.rs

//! WDP-compliant hash computation for waddling-errors diagnostic codes
//!
//! This crate provides WDP-specified hash computation for error codes.
//! Per WDP Part 5: Compact IDs, all error codes use xxHash3 with seed `0x000031762D706477`.
//!
//! ## Features
//!
//! - **WDP Compliant**: Uses xxHash3 with the standard WDP seed
//! - **Deterministic**: Same input always produces same hash
//! - **Compact**: 5-character base62 encoding (916M combinations)
//! - **Fast**: xxHash3 is optimized for small inputs (~30 GB/s)
//! - **Cross-language**: xxHash3 available in C, Python, JS, Go, Java, Rust
//! - **no_std compatible**: Works in constrained environments
//!
//! ## Quick Start
//!
//! ```
//! use waddling_errors_hash::{compute_hash, compute_wdp_hash};
//!
//! // Standard hash (no normalization)
//! let hash = compute_hash("E.AUTH.TOKEN.001");
//!
//! // WDP-compliant hash (with case normalization)
//! let wdp_hash = compute_wdp_hash("e.auth.token.001");
//! ```
//!
//! ## WDP Specification
//!
//! Per WDP Part 5:
//! - Algorithm: xxHash3
//! - Seed: `0x000031762D706477` (ASCII "wdp-v1\0\0" as little-endian u64)
//! - Output: 5 characters (base62)
//! - Input normalization: uppercase for consistency

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

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

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

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

// Public modules
pub mod algorithm;
pub mod base62;
#[cfg(feature = "std")]
pub mod config_loader;
pub mod wdp; // WDP-conformant hash functions (Part 5 & 7)
pub mod xxhash_impl;

// Re-export public types
pub use algorithm::{HashAlgorithm, HashConfig, ParseHashAlgorithmError, WDP_SEED, WDP_SEED_STR};
pub use base62::{to_base62, u64_to_base62};
#[cfg(feature = "std")]
pub use config_loader::{DocGenConfig, apply_overrides, load_doc_gen_config, load_global_config};

// Re-export namespace loader (std only)
#[cfg(feature = "std")]
pub use config_loader::load_namespace;

// Re-export WDP-conformant functions
pub use wdp::{
    WDP_CODE_SEED, WDP_NAMESPACE_SEED, compute_wdp_full_id, compute_wdp_hash,
    compute_wdp_namespace_hash, normalize_wdp_input, parse_wdp_full_id, verify_wdp_hash,
    verify_wdp_namespace_hash,
};

// Re-export const (compile-time) WDP hash functions
pub use wdp::{
    const_format_sequence, const_hash_to_base62, const_wdp_hash, const_wdp_hash_bytes,
    const_wdp_hash_from_parts,
};

/// Compute a 5-character base62 hash from an input string
///
/// Uses xxHash3 with the WDP seed `0x000031762D706477` to ensure deterministic
/// results across compilations and platforms.
///
/// **Note:** This function does NOT normalize input (no uppercase conversion).
/// For WDP-conformant hashing with normalization, use [`compute_wdp_hash`].
///
/// # 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 {
    compute_hash_with_config(input, &HashConfig::default())
}

/// Compute hash with custom configuration
///
/// Allows using a custom seed while still using xxHash3.
///
/// # Examples
///
/// ```
/// use waddling_errors_hash::{compute_hash_with_config, HashConfig};
///
/// // Use a custom seed for isolated hash space
/// let config = HashConfig::with_seed(0x12345678);
/// let hash = compute_hash_with_config("E.AUTH.TOKEN.001", &config);
/// assert_eq!(hash.len(), 5);
/// ```
pub fn compute_hash_with_config(input: &str, config: &HashConfig) -> String {
    xxhash_impl::compute_xxhash3(input, config.seed)
}

/// 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 {
    compute_hash(input) == hash
}

/// Verify that a hash was computed from the given input using custom config
///
/// # Examples
///
/// ```
/// use waddling_errors_hash::{compute_hash_with_config, verify_hash_with_config, HashConfig};
///
/// let config = HashConfig::with_seed(0x12345678);
/// let code = "E.AUTH.TOKEN.001";
/// let hash = compute_hash_with_config(code, &config);
/// assert!(verify_hash_with_config(code, &hash, &config));
/// assert!(!verify_hash_with_config("E.AUTH.TOKEN.002", &hash, &config));
/// ```
pub fn verify_hash_with_config(input: &str, hash: &str, config: &HashConfig) -> bool {
    compute_hash_with_config(input, config) == hash
}

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

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

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

    #[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_custom_seed() {
        let input = "E.AUTH.TOKEN.001";
        let config1 = HashConfig::with_seed(0x12345678);
        let config2 = HashConfig::with_seed(0x87654321);

        let hash1 = compute_hash_with_config(input, &config1);
        let hash2 = compute_hash_with_config(input, &config2);

        assert_ne!(
            hash1, hash2,
            "Different seeds should produce different hashes"
        );
    }

    #[test]
    fn test_verify_hash_with_config() {
        let input = "E.AUTH.TOKEN.001";
        let config = HashConfig::with_seed(0x12345678);
        let hash = compute_hash_with_config(input, &config);

        assert!(verify_hash_with_config(input, &hash, &config));
        assert!(!verify_hash_with_config("E.AUTH.TOKEN.002", &hash, &config));
    }

    #[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()));
    }

    #[test]
    fn test_wdp_seed_value() {
        // Verify the WDP seed constant
        assert_eq!(WDP_SEED, 0x000031762D706477);
    }

    #[test]
    fn test_compute_hash_is_case_sensitive() {
        // compute_hash does NOT normalize - it's case sensitive
        let hash_mixed = compute_hash("E.Auth.Token.001");
        let hash_upper = compute_hash("E.AUTH.TOKEN.001");

        // These produce DIFFERENT hashes because compute_hash doesn't normalize
        assert_ne!(
            hash_mixed, hash_upper,
            "compute_hash should be case-sensitive (no normalization)"
        );
    }

    #[test]
    fn test_compute_wdp_hash_is_case_insensitive() {
        use wdp::compute_wdp_hash;

        // compute_wdp_hash normalizes - it's case insensitive
        let hash_mixed = compute_wdp_hash("E.Auth.Token.001");
        let hash_upper = compute_wdp_hash("E.AUTH.TOKEN.001");

        // These produce IDENTICAL hashes because compute_wdp_hash normalizes
        assert_eq!(
            hash_mixed, hash_upper,
            "compute_wdp_hash should be case-insensitive (normalizes to uppercase)"
        );
    }
}