Skip to main content

Traceable

torrust_tracker_deployer_lib::shared

Trait Traceable 

Source 
pub trait Traceable: Error {
    // Required methods
    fn trace_format(&self) -> String;
    fn trace_source(&self) -> Option<&dyn Traceable>;
    fn error_kind(&self) -> ErrorKind;
}
Expand description

Trait for errors that can generate detailed traces

This trait enables errors to provide custom formatted trace entries and maintain error chain information. Unlike requiring Serialize, this approach allows errors to contain non-serializable data while still generating comprehensive trace files.

§Example

use torrust_tracker_deployer_types::error::Traceable;
use torrust_tracker_deployer_types::ErrorKind;

#[derive(Debug, thiserror::Error)]
enum MyError {
    #[error("Operation failed: {reason}")]
    OperationFailed {
        reason: String,
        #[source]
        source: std::io::Error,
    },
}

impl Traceable for MyError {
    fn trace_format(&self) -> String {
        match self {
            Self::OperationFailed { reason, .. } => {
                format!("MyError: Operation failed - {}", reason)
            }
        }
    }

    fn trace_source(&self) -> Option<&dyn Traceable> {
        match self {
            Self::OperationFailed { source, .. } => {
                // Would return Some if source implemented Traceable
                None
            }
        }
    }

    fn error_kind(&self) -> ErrorKind {
        match self {
            Self::OperationFailed { .. } => ErrorKind::FileSystem,
        }
    }
}

Required Methods§

Source

fn trace_format(&self) -> String

Generate a formatted trace entry for this error

This method should return a human-readable string describing the error with relevant context. It will be used to build the error chain in trace files.

§Returns

A formatted string representing this error in the trace

Source

fn trace_source(&self) -> Option<&dyn Traceable>

Get the underlying source error that implements Traceable, if any

This method enables walking the error chain to capture complete error information in trace files. Return Some if the source error implements Traceable, None otherwise.

§Returns

An optional reference to the source error as a Traceable trait object

Source

fn error_kind(&self) -> ErrorKind

Get the error kind for high-level categorization

Returns a high-level category for this error, used in trace files and failure context for debugging and potential recovery strategies.

Error kinds provide an easy way to understand what type of error occurred without parsing detailed trace files. They serve as a high-level summary that can be:

  • Displayed to users without technical details
  • Used for filtering/grouping errors
  • Foundation for future retry/recovery strategies based on error category
§Returns

An ErrorKind variant representing this error’s category

§Example
use torrust_tracker_deployer_types::{Traceable, ErrorKind};

fn handle_error<E: Traceable>(error: &E) {
    let kind = error.error_kind();
    println!("Error category: {:?}", kind);
}

Dyn Compatibility§

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§