charon_error/report/

error_frame.rs

//! Individual error frames, attachments, and sensitivity labels.
//!
//! An [`ErrorFrame`] captures a single error with its source location,
//! backtrace, timestamp, tracing span, and key-value attachments.
//! [`ErrorSensitivityLabel`] wraps values to control their visibility
//! in reports.

use backtrace::Backtrace;
use chrono::{DateTime, Utc};
use colored::Colorize;
use regex::Regex;
use std::fmt::Display;
use std::{collections::HashMap, error::Error};
use tracing::{Metadata, Span, instrument};
use tracing_error::SpanTrace;

use crate::{
    ErrorFmt, ErrorFmtLoD, ErrorFmtSettings, ErrorFormatObj, ResultER, ResultExt, SourceLocation,
    StringError, map,
};

/// A single frame in an error chain, capturing one error with its full context.
///
/// Each `ErrorFrame` records:
/// - The error message and original error object
/// - Source location (file, line, column) via `#[track_caller]`
/// - Timestamp of when the frame was created
/// - Backtrace at the point of creation
/// - Current `tracing` span and span trace
/// - Arbitrary key-value attachments with sensitivity labels
///
/// Frames are collected inside an [`ErrorReport`](crate::ErrorReport).
#[derive(Debug)]
pub struct ErrorFrame {
    /// Error message text, wrapped in a sensitivity label.
    pub message: ErrorSensitivityLabel<String>,
    /// The original error object.
    pub error: Box<dyn Error + Send + Sync + 'static>,
    /// Source code location where this frame was created.
    pub source: SourceLocation,
    /// Timestamp of when this error frame was created (UTC).
    pub date_time: DateTime<Utc>,
    /// Suggestions that could help resolve the error.
    pub suggestions: Vec<ErrorSensitivityLabel<String>>,
    /// Context/circumstances the error occurred in.
    pub context: ErrorSensitivityLabel<String>,
    /// Key-value attachments with sensitivity labels for additional diagnostic data.
    pub attachments: HashMap<String, Box<ErrorSensitivityLabel<ErrorAttachment>>>,
    /// Captured backtrace at the point this frame was created.
    /// Should always be considered Internal sensitivity.
    pub backtrace: Backtrace,
    /// The current `tracing` Span when this frame was created.
    /// Should always be considered Internal sensitivity.
    /// This can be used instead of Backtrace for creating a stack.
    pub span: Span,
    /// The span trace captured from `tracing-error`.
    pub span_trace: SpanTrace,
}

impl ErrorFmt for ErrorFrame {
    #[instrument]
    fn create_format_obj(&self, settings: ErrorFmtSettings) -> ResultER<ErrorFormatObj> {
        let object = ErrorFormatObj::Object(map! {
            "message" => ErrorFormatObj::ColorString(self.message.to_string().bright_red().bold()),
            "source_location" => ErrorFormatObj::SourceLocation(self.source.clone()),
            "span_trace" => self.span_trace.create_format_obj(settings)?,
            "attachments" => self.attachments.create_format_obj(settings)?,
            "date_time" => self.date_time.create_format_obj(settings)?,
        });
        Ok(match settings.level_of_detail {
            ErrorFmtLoD::Compact => object.filter_object_fields(vec![
                "message",
                "source_location",
                "span_trace",
                "attachments",
            ])?,
            ErrorFmtLoD::SubmitReport => object.filter_object_fields(vec![
                "message",
                "source_location",
                "span_trace",
                "attachments",
            ])?,
            ErrorFmtLoD::Medium => object,
            ErrorFmtLoD::Full | ErrorFmtLoD::Debug => object,
        })
    }
}

impl ErrorFrame {
    /// Create a new error frame from any error type.
    ///
    /// Captures source location, backtrace, timestamp, and current tracing span.
    #[must_use]
    #[track_caller]
    pub fn new<E: Error + Send + Sync + 'static>(error: E) -> Self {
        Self {
            message: ErrorSensitivityLabel::Public(error.to_string()),
            error: Box::new(error),
            source: SourceLocation::from_caller_location(),
            date_time: Utc::now(),
            suggestions: Vec::new(),
            context: ErrorSensitivityLabel::Public(String::new()),
            attachments: HashMap::new(),
            backtrace: Backtrace::new_unresolved(),
            span: Span::current(),
            span_trace: SpanTrace::capture(),
        }
    }

    /// Create a new error frame from a boxed dynamic error.
    #[must_use]
    #[track_caller]
    pub fn from_dyn_error(error: Box<dyn Error + Send + Sync + 'static>) -> Self {
        Self {
            message: ErrorSensitivityLabel::Public(error.to_string()),
            error,
            source: SourceLocation::from_caller_location(),
            date_time: Utc::now(),
            suggestions: Vec::new(),
            context: ErrorSensitivityLabel::Public(String::new()),
            attachments: HashMap::new(),
            backtrace: Backtrace::new_unresolved(),
            span: Span::current(),
            span_trace: SpanTrace::capture(),
        }
    }

    /// Create an error frame from a plain message string.
    ///
    /// The message is labeled as [`Internal`](ErrorSensitivityLabel::Internal).
    #[must_use]
    #[track_caller]
    pub fn from_message<S: Into<String>>(msg: S) -> Self {
        let error = StringError::new(msg);
        Self {
            message: ErrorSensitivityLabel::Internal(error.to_string()),
            error: Box::new(error),
            source: SourceLocation::from_caller_location(),
            date_time: Utc::now(),
            suggestions: Vec::new(),
            context: ErrorSensitivityLabel::Internal(String::new()),
            attachments: HashMap::new(),
            backtrace: Backtrace::new_unresolved(),
            span: Span::current(),
            span_trace: SpanTrace::capture(),
        }
    }

    /// Get the error message as a string.
    #[must_use]
    pub fn get_error_title(&self) -> String {
        self.message.to_string()
    }

    /// Get the list of tracing span metadata from the span trace.
    #[must_use]
    pub fn get_span_list(&self) -> Vec<&'static Metadata<'static>> {
        let mut span_list = Vec::new();
        self.span_trace.with_spans(|meta_data, _field_values| {
            span_list.push(meta_data);
            true
        });
        span_list
    }

    /// Resolve and format the backtrace as a human-readable string.
    ///
    /// Cleans up paths by removing the current directory prefix, cargo registry
    /// paths, and rustlib paths to keep output concise.
    #[must_use]
    pub fn create_backtrace_string(&self) -> String {
        let mut bt = self.backtrace.clone();
        bt.resolve();
        let frames = bt.frames();
        let mut backtrace_string = String::new();
        let max_line = 11;
        let current_folder: String = std::env::current_dir().unwrap_error().display().to_string();
        let cargo_registry_folder =
            Regex::new(r"\/.cargo\/registry\/[^/]*\/[^/]*\/").unwrap_error();
        let rustlib_folder =
            Regex::new(r"\/.rustup\/toolchains\/[^/]*\/lib\/rustlib\/src\/").unwrap_error();
        for (frame, line) in frames.iter().zip(0..max_line) {
            let symbol = if let Some(first_symbol) = frame.symbols().first() {
                first_symbol
            } else {
                backtrace_string = format!("{backtrace_string}{line}: <unknown>\n");
                continue;
            };
            let mut name = String::new();
            if let Some(name_value) = &symbol.name() {
                let full_name = name_value.to_string();
                let parts: Vec<&str> = full_name.split("::").collect();
                if parts.len() >= 3 {
                    // Take almost last 2 parts
                    // Example: std::rt::lang_start::h2c4217f9057b6ddb
                    // Name:         ^^::^^^^^^^^^^
                    name = format!(
                        "{}::{}",
                        parts.get(parts.len() - 3).unwrap_or(&""),
                        parts.get(parts.len() - 2).unwrap_or(&""),
                    );
                } else {
                    // Otherwise take whole name
                    name = full_name
                }
            }
            // Will not be set on some systems.
            // see: https://docs.rs/backtrace/latest/backtrace/struct.Symbol.html
            let mut filepath = String::new();
            if let Some(filename) = &symbol.filename() {
                let line_nr = &symbol.lineno().unwrap_or_default();
                let path = filename.to_str().unwrap_error();
                // Remove path to main repo
                let (_, path) = path.split_at(
                    path.rfind(&current_folder)
                        .map(|pos| pos + current_folder.len() + 1) // add 1 for `/`
                        .unwrap_or(0),
                );
                // Remove path to cargo registry
                let (_, path) = path.split_at(
                    cargo_registry_folder
                        .find(path)
                        .map(|m| m.end())
                        .unwrap_or(0),
                );
                // Remove path to rustlib
                let (_, path) =
                    path.split_at(rustlib_folder.find(path).map(|m| m.end()).unwrap_or(0));
                if !path.starts_with("/rustc/") {
                    filepath = format!(" => {path}:{line_nr}");
                }
            }
            if line != 0 {
                backtrace_string = format!("{backtrace_string}{line}: {name}{filepath}\n");
            }
        }
        backtrace_string
    }
}

/// Data that can be attached to an [`ErrorFrame`] for additional diagnostics.
///
/// Attachments carry either raw bytes or a string value, and are always
/// wrapped in an [`ErrorSensitivityLabel`] to control their visibility.
#[derive(Debug, Clone)]
pub enum ErrorAttachment {
    /// Raw binary data (displayed as `<raw_data>` in output).
    RawData(Vec<u8>),
    /// A human-readable string value.
    String(String),
}

impl Display for ErrorAttachment {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::RawData(_data) => write!(f, "<raw_data>"),
            Self::String(data) => write!(f, "{data}"),
        }
    }
}

/// Controls the visibility and handling of data based on its sensitivity.
///
/// Each variant wraps a value of type `T` and determines who can see that data
/// and whether it should be encrypted.
///
/// Data Owner: Data that should only be shared with the user, not other users.
///
/// Data Can be shared with:
/// | Level              | Data Owner | Other Users | Internal | Encrypted        |
/// |--------------------|:----------:|:-----------:|:--------:|:----------------:|
/// | Public             |     yes    |     yes     |    yes   |       no         |
/// | Private            |     yes    |      no     |    yes   |       no         |
/// | PrivateConfidential|     yes    |      no     |     no   | yes (user key)   |
/// |                    |            |             |          |                  |
/// | Internal           |      no    |      no     |    yes   |       no         |
/// | Confidential       |      no    |      no     |    yes   | yes (app key)    |
/// | HighlyConfidential |      no    |      no     |    yes   | yes (specific)   |
///
/// # Example
///
/// ```rust
/// use charon_error::ErrorSensitivityLabel;
///
/// // Safe to include in any report
/// let public = ErrorSensitivityLabel::Public("config.toml".to_string());
/// assert_eq!(public.to_string(), "config.toml");
///
/// // Only visible in internal/debug reports
/// let internal = ErrorSensitivityLabel::Internal("/etc/secrets".to_string());
/// assert_eq!(internal.to_string(), "Data is only for internal use");
///
/// // User-private data
/// let private = ErrorSensitivityLabel::Private("user@example.com".to_string());
/// assert_eq!(private.to_string(), "Data is private");
/// ```
#[derive(Debug, Clone)]
pub enum ErrorSensitivityLabel<T> {
    /// Data that can be shared with any user, no restrictions.
    Public(T),
    /// Data that should only be shared with the user who owns the data, no other users.
    /// The data can be shared using Internal channels.
    Private(T),
    /// Data that should only be shared with the user, no other users.
    /// The data can NOT be shared using Internal channels.
    /// TODO: Data should be Encrypted using users public key.
    PrivateConfidential(T),

    /// Data that should only be shared Internally within the organization.
    /// TODO: Data is should never be shared outside of organization.
    Internal(T),
    /// Data is considered sensitive and access is limited.
    /// TODO: Data should be Encrypted using application public key.
    Confidential(T),
    /// Data is Very sensitive, and should not be stored unless encrypted.
    /// TODO: Data is/should always be Encrypted using highly specific keys.
    /// Data is only available in specific circumstances:
    ///  - Only in Debug Builds
    ///  - Never Stored in JSON
    ///  - Printed as encrypted string
    HighlyConfidential(T),
}

impl<T: Display> Display for ErrorSensitivityLabel<T> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        let result = match self {
            ErrorSensitivityLabel::Public(t) => t.to_string(),
            ErrorSensitivityLabel::Private(_) => "Data is private".to_owned(),
            ErrorSensitivityLabel::PrivateConfidential(_) => "Data is private".to_owned(),
            ErrorSensitivityLabel::Internal(_) => "Data is only for internal use".to_owned(),
            ErrorSensitivityLabel::Confidential(_) => "Data is only for internal use".to_owned(),
            ErrorSensitivityLabel::HighlyConfidential(_) => {
                "Data is only for internal use".to_owned()
            }
        };
        write!(f, "{result}")
    }
}