## High-Performance Hashing Utilities
##
## This module provides fast, non-cryptographic hashing for cache keys,
## content addressing, and integrity verification.
##
## **Hash Algorithm:** xxh3_128
## - Speed: 40-60 GiB/s single-threaded
## - Output: 128-bit (collision-safe for cosmic scale: 2^-100)
## - Portability: Excellent on all architectures
##
## **Use Cases:**
## - Cache key calculation (non-cryptographic)
## - Content-addressable storage (CAS)
## - Merkle tree node hashing
## - Build hash calculation
##
## **NOT for:**
## - Cryptographic signatures (use BLAKE3)
## - Security-critical operations (use BLAKE3)
## - Protocol authentication (use BLAKE3)

import ../xxhash

# Re-export xxhash functions for convenience
export calculateXXH3

proc xxh3_128*(data: string): string =
  ## Calculate xxh3_128 hash of binary data.
  ##
  ## **Parameters:**
  ## - data: Binary string to hash
  ##
  ## **Returns:** 128-bit hash as hex string with "xxh3-" prefix
  ##
  ## **Performance:** ~40-60 GiB/s on modern CPUs
  ##
  ## **Example:**
  ## ```nim
  ## let hash = xxh3_128("hello world")
  ## echo hash  # "xxh3-a1b2c3d4e5f6..."
  ## ```
  
  return $calculateXXH3(data)

proc xxh3_128*(data: seq[byte]): string =
  ## Calculate xxh3_128 hash of byte sequence.
  ##
  ## **Parameters:**
  ## - data: Byte sequence to hash
  ##
  ## **Returns:** 128-bit hash as hex string with "xxh3-" prefix
  
  return $calculateXXH3(data)

# ============================================================================
# Hash Verification Utilities
# ============================================================================

proc verifyHash*(data: string, expectedHash: string): bool =
  ## Verify that data matches expected hash.
  ##
  ## **Parameters:**
  ## - data: Binary data to verify
  ## - expectedHash: Expected xxh3_128 hash (hex string)
  ##
  ## **Returns:** true if hash matches, false otherwise
  ##
  ## **Example:**
  ## ```nim
  ## let data = "hello world"
  ## let hash = xxh3_128(data)
  ## assert verifyHash(data, hash)
  ## ```
  
  let actualHash = xxh3_128(data)
  return actualHash == expectedHash

# ============================================================================
# Performance Benchmarking
# ============================================================================

when isMainModule:
  import times
  import strformat
  
  proc benchmarkHashing() =
    ## Benchmark xxh3_128 performance
    
    # Generate test data (1 MB)
    let dataSize = 1024 * 1024
    var testData = newString(dataSize)
    for i in 0..<dataSize:
      testData[i] = char(i mod 256)
    
    # Warm up
    for i in 0..<10:
      discard xxh3_128(testData)
    
    # Benchmark
    let iterations = 1000
    let startTime = cpuTime()
    
    for i in 0..<iterations:
      discard xxh3_128(testData)
    
    let endTime = cpuTime()
    let elapsed = endTime - startTime
    
    # Calculate throughput
    let totalBytes = dataSize * iterations
    let throughputMBps = (totalBytes.float / (1024.0 * 1024.0)) / elapsed
    let throughputGBps = throughputMBps / 1024.0
    
    echo fmt"xxh3_128 Performance:"
    echo fmt"  Data size: {dataSize} bytes"
    echo fmt"  Iterations: {iterations}"
    echo fmt"  Time: {elapsed:.3f} seconds"
    echo fmt"  Throughput: {throughputMBps:.2f} MB/s ({throughputGBps:.2f} GB/s)"
  
  # Run benchmark
  benchmarkHashing()
