Error Types

use horus::prelude::*;

// Result<T> = std::result::Result<T, HorusError>
// Error = HorusError
fn my_function() -> Result<()> {
    let topic: Topic<f32> = Topic::new("sensor")?;
    Ok(())
}

use horus::prelude::*;

fn handle_topic_error(err: Error) {
    match err {
        HorusError::Communication(CommunicationError::TopicFull { topic }) => {
            // Back-pressure: subscriber is slower than publisher
            hlog!(warn, "Topic '{}' full, dropping message", topic);
        }
        HorusError::Communication(CommunicationError::TopicNotFound { topic }) => {
            // Topic doesn't exist yet
            hlog!(error, "Topic '{}' not found — is the publisher running?", topic);
        }
        HorusError::Memory(MemoryError::PoolExhausted { reason }) => {
            // Image/PointCloud pool has no free slots
            hlog!(warn, "Pool exhausted: {} — waiting for consumers", reason);
        }
        HorusError::Transform(TransformError::Stale { frame, age, threshold }) => {
            // Transform data is too old
            hlog!(warn, "Frame '{}' stale: {:?} > {:?}", frame, age, threshold);
        }
        other => {
            hlog!(error, "Unexpected error: {}", other);
            // Check for actionable hints
            if let Some(hint) = other.help() {
                hlog!(info, "  hint: {}", hint);
            }
        }
    }
}

if let Err(e) = Topic::<f32>::new("sensor") {
    eprintln!("error: {}", e);
    if let Some(hint) = e.help() {
        eprintln!("  hint: {}", hint);
    }
}

match err.severity() {
    Severity::Transient => { /* retry */ }
    Severity::Permanent => { hlog!(warn, "{}", err); }
    Severity::Fatal     => { /* emergency stop */ }
}

use horus::prelude::*;

fn load_sensor_config(path: &str) -> Result<String> {
    // .horus_context() wraps std::io::Error with a message
    let data = std::fs::read_to_string(path)
        .horus_context(format!("reading sensor config '{}'", path))?;
    Ok(data)
}

fn load_calibration(path: &str) -> Result<String> {
    // .horus_context_with() is lazy — closure only called on Err
    std::fs::read_to_string(path)
        .horus_context_with(|| format!("reading calibration '{}'", path))
}

use horus::prelude::*;

let config = RetryConfig {
    max_retries: 3,
    base_delay: 100_u64.ms(),
    ..Default::default()
};

let result = retry_transient(&config, || {
    connect_to_sensor()
});

TopicFull { topic }              // Ring buffer full
TopicNotFound { topic }          // No such topic
TopicCreationFailed { topic, reason }  // SHM setup failed
NetworkFault { peer, reason }    // Peer unreachable
ActionFailed { reason }          // Action system error

Frame { name }     // TransformFrame lookup
Topic { name }     // Topic lookup
Node { name }      // Node lookup
Service { name }   // Service lookup
Action { name }    // Action lookup
Parameter { name } // RuntimeParams lookup

OutOfRange { field, min, max, actual }  // Value outside bounds
InvalidFormat { field, expected_format, actual }  // Wrong format
InvalidEnum { field, valid_options, actual }  // Not an allowed value
MissingRequired { field }  // Required field absent
ConstraintViolation { field, constraint }  // Custom constraint
Conflict { field_a, field_b, reason }  // Two fields conflict

ParseFailed { format, reason, source }       // Failed to parse config file
MissingField { field, context }              // Required field missing
ValidationFailed { field, expected, actual } // Value doesn't match constraint
InvalidValue { key, reason }                 // Invalid configuration value
Other(String)                                // General config error

Json { source: serde_json::Error }     // JSON parse/emit failure
Yaml { source: serde_yaml::Error }     // YAML parse/emit failure
Toml { source: toml::ser::Error }      // TOML parse/emit failure
Other { format, reason }               // Other format error

PoolExhausted { reason }        // Tensor pool out of slots
AllocationFailed { reason }     // Memory allocation failed
ShmCreateFailed { path, reason } // Shared memory region creation failed
MmapFailed { reason }           // Memory mapping failed
DLPackImportFailed { reason }   // DLPack tensor import failed
OffsetOverflow                  // Tensor offset exceeds region

InitPanic { node }              // Node panicked during init()
ReInitPanic { node }            // Node panicked during re-init
ShutdownPanic { node }          // Node panicked during shutdown()
InitFailed { node, reason }     // init() returned Err
TickFailed { node, reason }     // Tick error
Other { node, message }         // General node error

AlreadyExists { resource_type, name }         // Resource already registered
PermissionDenied { resource, required_permission } // Insufficient permissions
Unsupported { feature, reason }               // Feature not available on this platform

Int { input, source: ParseIntError }     // Integer parsing failed
Float { input, source: ParseFloatError } // Float parsing failed
Bool { input, source: ParseBoolError }   // Boolean parsing failed
Custom { type_name, input, reason }      // Custom type parse failed

Extrapolation { frame, requested_ns, oldest_ns, newest_ns }  // Out of buffer range
Stale { frame, age, threshold }  // Transform too old

TimeoutError { resource, elapsed, deadline }  // Operation timed out

// Internal error with source location (use horus_internal!() macro)
Internal { message: String, file: &'static str, line: u32 }

// Error with preserved source chain (use .horus_context() on Results)
Contextual { message: String, source: Box<dyn Error + Send + Sync> }

// Adding context to errors
let device = Device::open("/dev/ttyUSB0")
    .horus_context("opening motor controller serial port")?;