Decrust-Core 🦀🔧

Advanced Error Handling Framework for Rust - Core Components

Decrust-Core is the foundation of the Decrust error handling framework, providing comprehensive, production-ready error handling with rich error context, automatic error recovery, circuit breaker patterns, and powerful debugging capabilities.

🚀 Quick Start

use decrust_core::{DecrustError, DecrustResultExt, DecrustOptionExt, oops, validation_error};

// Basic error creation with rich context
fn process_user_data(data: Option<&str>) -> Result<String, DecrustError> {
    let user_data = data.decrust_ok_or_missing_value("user data")?;

    if user_data.is_empty() {
        return Err(validation_error!("user_data", "Data cannot be empty"));
    }

    // Simulate an IO operation that might fail
    std::fs::read_to_string("config.json")
        .map_err(|e| oops!("Failed to read configuration", e))
        .and_then(|_| Ok(format!("Processed: {}", user_data)))
}

🎯 Core Features

1. Rich Error Context 📍

Every error includes comprehensive context with location tracking, severity levels, and metadata for better debugging and monitoring.

use decrust_core::{error_context, types::ErrorSeverity, oops};

// Create rich error context with metadata
let context = error_context!(
    "Database connection failed",
    severity: ErrorSeverity::Critical
).with_component("database")
 .with_correlation_id("req-123")
 .with_recovery_suggestion("Check database connectivity");

2. Circuit Breaker Pattern ⚡

Built-in circuit breaker for handling external service failures gracefully.

use decrust_core::{circuit_breaker::{CircuitBreaker, CircuitBreakerConfig}, DecrustError};
use std::time::Duration;

// Configure circuit breaker
let config = CircuitBreakerConfig {
    failure_threshold: 5,
    reset_timeout: Duration::from_secs(30),
    operation_timeout: Some(Duration::from_secs(5)),
    ..Default::default()
};

let circuit_breaker = CircuitBreaker::new("external-api", config);

// Execute operations through circuit breaker
let result = circuit_breaker.execute(|| {
    external_api_call()
});

3. Automatic Error Recovery 🔄

Smart error recovery with configurable retry strategies and fix suggestions.

use decrust_core::{DecrustError, decrust::{Decrust, AutocorrectableError}};

let mut decrust = Decrust::new();

// Apply fixes automatically
if let Some(fix) = decrust.suggest_autocorrection(&error, None) {
    println!("Suggested fix: {}", fix.description);
}

4. Powerful Macros 🛠️

Ergonomic macros for common error handling patterns.

use decrust_core::{oops, validation_error, error_context, location, types::ErrorSeverity};

// Quick error creation
let error = oops!("Something went wrong", source_error);

// Validation errors with suggestions
let validation_err = validation_error!(
    "email",
    "Invalid email format",
    suggestion: "Use format: user@domain.com"
);

// Rich context with location tracking
let context = error_context!("Operation failed", severity: ErrorSeverity::Error);
let loc = location!(context: "user authentication", function: "login");

5. Comprehensive Error Types 📋

Pre-built error variants for common scenarios with rich metadata.

use decrust_core::{DecrustError, Backtrace, OptionalError};

// Network errors with retry information
let network_error = DecrustError::Network {
    source: Box::new(std::io::Error::new(std::io::ErrorKind::ConnectionRefused, "refused")),
    kind: "HTTP".to_string(),
    url: Some("https://api.example.com".to_string()),
    backtrace: Backtrace::generate(),
};

// Configuration errors with suggestions
let config_error = DecrustError::Config {
    message: "Invalid database URL format".to_string(),
    path: Some("config.toml".into()),
    source: OptionalError(None),
    backtrace: Backtrace::generate(),
};

🏗️ Architecture

Decrust-Core provides the following modules:

• backtrace - Enhanced backtrace capture and analysis
• circuit_breaker - Circuit breaker pattern implementation
• decrust - Core error handling and autocorrection engine
• reporter - Error reporting and formatting
• syntax - AST-driven fix generation and templates
• types - Core type definitions and utilities

📚 Feature Flags

• std-thread: Enables threading support for circuit breaker timeouts
• serde: Enables serialization support for error types
• tracing: Enables integration with the tracing ecosystem

🎨 Best Practices

1. Use specific error variants for different error categories
2. Add rich context with decrust_context_msg() for better debugging
3. Implement circuit breakers for external service calls
4. Use macros for common error patterns to reduce boilerplate
5. Configure error reporting for production monitoring
6. Create domain-specific error types that convert to DecrustError

🛡️ Licensing

This project is licensed under the Business Source License 1.1 (BSL 1.1).

• ✅ Non-production use is FREE (development, testing, academic, personal)
• 💰 Commercial/production use requires a paid license from ArcMoon Studios
• 📧 Contact: LordXyn@proton.me for commercial licensing inquiries

Change Date: 2029-05-25 | Change License: GNU GPL v3

Made with ❤️ by ArcMoon Studios