integration_thiserror/

integration_thiserror.rs

//! **OPTIONAL INTEGRATION**: waddling-errors with thiserror
//!
//! This example demonstrates how to use waddling-errors with `thiserror`,
//! a popular error handling crate. This integration is **completely optional**.
//!
//! waddling-errors works standalone or with ANY error handling approach:
//! - Standalone (no dependencies)
//! - With thiserror (shown here)
//! - With anyhow
//! - With your own Error enum
//! - Direct Result<T, ErrorCode> returns
//!
//! Run with: cargo run --example integration_thiserror
//!
//! **Note**: This example shows thiserror patterns in comments since we don't
//! want to add thiserror as a dependency. In your project, you would add:
//! ```toml
//! [dependencies]
//! thiserror = "1.0"
//! waddling-errors = { version = "0.1", default-features = false }
//! ```

use waddling_errors::{ErrorCode, Severity};

// ============================================================================
// IMPORTANT: This example shows OPTIONAL integration with thiserror
// ============================================================================
//
// waddling-errors does NOT require thiserror! You can use error codes:
// - Standalone: just return ErrorCode directly
// - With thiserror: wrap in enum (shown below)
// - With anyhow: use .context() with error codes
// - DIY: build your own error type
//
// This example demonstrates thiserror patterns for users who choose that path.

// Note: In a real project, add thiserror to Cargo.toml:
// [dependencies]
// thiserror = "1.0"
// waddling-errors = { version = "0.1", default-features = false }

// ============================================================================
// Error Code Definitions
// ============================================================================

const ERR_INVALID_SALT: ErrorCode = ErrorCode::new(Severity::Error, "CRYPTO", "SALT", 1);
const ERR_INVALID_KEY: ErrorCode = ErrorCode::new(Severity::Error, "CRYPTO", "KEY", 2);
const ERR_MAC_FAILED: ErrorCode = ErrorCode::new(Severity::Error, "CRYPTO", "MAC", 3);

const WARN_DEPRECATED: ErrorCode = ErrorCode::new(Severity::Warning, "API", "DEPR", 1);

const CRIT_DATA_CORRUPT: ErrorCode = ErrorCode::new(Severity::Critical, "DATA", "CORRUPT", 1);

// ============================================================================
// Error Enum (would use thiserror in real code)
// ============================================================================

// In a real project, this would use #[derive(Error)] from thiserror:
//
// use thiserror::Error;
//
// #[derive(Error, Debug)]
// pub enum CryptoError {
//     #[error("[MYLIB.{0}] Invalid salt length: expected {1} bytes, got {2} bytes")]
//     InvalidSaltLength(ErrorCode, usize, usize),
//
//     #[error("[MYLIB.{0}] Invalid key length: expected {1} bytes, got {2} bytes")]
//     InvalidKeyLength(ErrorCode, usize, usize),
//
//     #[error("[MYLIB.{0}] MAC verification failed")]
//     MacVerificationFailed(ErrorCode),
// }

#[derive(Debug)]
pub enum CryptoError {
    InvalidSaltLength(ErrorCode, usize, usize),
    InvalidKeyLength(ErrorCode, usize, usize),
    MacVerificationFailed(ErrorCode),
}

impl std::fmt::Display for CryptoError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            CryptoError::InvalidSaltLength(code, expected, got) => {
                write!(
                    f,
                    "[MYLIB.{}] Invalid salt length: expected {} bytes, got {} bytes",
                    code.code(),
                    expected,
                    got
                )
            }
            CryptoError::InvalidKeyLength(code, expected, got) => {
                write!(
                    f,
                    "[MYLIB.{}] Invalid key length: expected {} bytes, got {} bytes",
                    code.code(),
                    expected,
                    got
                )
            }
            CryptoError::MacVerificationFailed(code) => {
                write!(f, "[MYLIB.{}] MAC verification failed", code.code())
            }
        }
    }
}

impl std::error::Error for CryptoError {}

// ============================================================================
// Usage Examples
// ============================================================================

fn validate_salt(salt: &[u8]) -> Result<(), CryptoError> {
    const EXPECTED_LEN: usize = 32;
    if salt.len() != EXPECTED_LEN {
        return Err(CryptoError::InvalidSaltLength(
            ERR_INVALID_SALT,
            EXPECTED_LEN,
            salt.len(),
        ));
    }
    Ok(())
}

fn validate_key(key: &[u8]) -> Result<(), CryptoError> {
    const EXPECTED_LEN: usize = 32;
    if key.len() != EXPECTED_LEN {
        return Err(CryptoError::InvalidKeyLength(
            ERR_INVALID_KEY,
            EXPECTED_LEN,
            key.len(),
        ));
    }
    Ok(())
}

fn verify_mac(data: &[u8], mac: &[u8]) -> Result<(), CryptoError> {
    // Simulate MAC verification failure
    if data.is_empty() || mac.len() != 32 {
        return Err(CryptoError::MacVerificationFailed(ERR_MAC_FAILED));
    }
    Ok(())
}

fn main() {
    println!("🦆 Waddling-Errors + Thiserror Integration Demo 🦆\n");

    // Example 1: Invalid salt length
    println!("Example 1: Invalid Salt Length");
    println!("═══════════════════════════════════════════════════");
    let short_salt = [0u8; 16];
    match validate_salt(&short_salt) {
        Ok(_) => println!("✓ Salt valid"),
        Err(e) => {
            println!("✗ Error: {}", e);
            println!("  Error code: E.CRYPTO.SALT.001");
            println!("  Severity: Error");
        }
    }
    println!();

    // Example 2: Invalid key length
    println!("Example 2: Invalid Key Length");
    println!("═══════════════════════════════════════════════════");
    let short_key = [0u8; 8];
    match validate_key(&short_key) {
        Ok(_) => println!("✓ Key valid"),
        Err(e) => {
            println!("✗ Error: {}", e);
            println!("  Error code: E.CRYPTO.KEY.002");
            println!("  Severity: Error");
        }
    }
    println!();

    // Example 3: MAC verification failed
    println!("Example 3: MAC Verification Failed");
    println!("═══════════════════════════════════════════════════");
    let data = b"";
    let mac = [0u8; 32];
    match verify_mac(data, &mac) {
        Ok(_) => println!("✓ MAC valid"),
        Err(e) => {
            println!("✗ Error: {}", e);
            println!("  Error code: E.CRYPTO.MAC.003");
            println!("  Severity: Error");
        }
    }
    println!();

    // Example 4: Demonstrating severity information
    println!("Example 4: Severity Information");
    println!("═══════════════════════════════════════════════════");
    let codes = [
        (ERR_INVALID_SALT, "Error - Invalid salt"),
        (WARN_DEPRECATED, "Warning - Deprecated API"),
        (CRIT_DATA_CORRUPT, "Critical - Data corruption"),
    ];

    for (code, desc) in &codes {
        println!("Code: {} | {}", code.code(), desc);
        println!("  Severity: {:?}", code.severity());
        println!();
    }

    println!("Key Takeaways:");
    println!("══════════════");
    println!("✓ Error codes are const fn - zero runtime overhead");
    println!("✓ Integrates cleanly with thiserror for professional errors");
    println!("✓ Only ~500 bytes binary size overhead");
    println!("✓ Error codes stable across versions (001, 002, 003...)");
    println!("✓ Severity matrix enables nuanced error handling");
    println!("\n🦆 Happy error handling! 🦆\n");
}