# Decrust-Core 🦀🔧
**Advanced Error Handling Framework for Rust - Core Components**
[](https://crates.io/crates/decrust-core)
[](https://docs.rs/decrust-core)
[](../LICENSE)
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
```rust
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.
```rust
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.
```rust
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.
```rust
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.
```rust
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.
```rust
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
---
**Made with ❤️ by [ArcMoon Studios](https://github.com/arcmoonstudios)**