Enum YoshiKind

#[non_exhaustive]
pub enum YoshiKind {
    Io(Error),
    Network {
        message: Arc<str>,
        source: Option<Box<Yoshi>>,
        error_code: Option<u32>,
    },
    Config {
        message: Arc<str>,
        source: Option<Box<Yoshi>>,
        config_path: Option<Arc<str>>,
    },
    Validation {
        field: Arc<str>,
        message: Arc<str>,
        expected: Option<Arc<str>>,
        actual: Option<Arc<str>>,
    },
    Internal {
        message: Arc<str>,
        source: Option<Box<Yoshi>>,
        component: Option<Arc<str>>,
    },
    NotFound {
        resource_type: Arc<str>,
        identifier: Arc<str>,
        search_locations: Option<Vec<Arc<str>>>,
    },
    Timeout {
        operation: Arc<str>,
        duration: Duration,
        expected_max: Option<Duration>,
    },
    ResourceExhausted {
        resource: Arc<str>,
        limit: Arc<str>,
        current: Arc<str>,
        usage_percentage: Option<f64>,
    },
    Foreign {
        error: Box<dyn Error + Send + Sync + 'static>,
        error_type_name: Arc<str>,
    },
    Multiple {
        errors: Vec<Yoshi>,
        primary_index: Option<usize>,
    },
}

High‑level categories for recoverable failures with performance optimizations.

This enum represents the fundamental classification of an error within the Yoshi framework. Each variant provides specific fields relevant to its error category, enabling rich, structured error reporting and programmatic error handling.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Io(Error)

Available on crate feature std only.

Standard I/O failure with optimized error representation. /// This variant wraps std::io::Error when the std feature is enabled, or NoStdIo for no_std environments.

Network

Network-related error with connection and protocol context.

This variant represents errors that occur during network operations, including connectivity issues, protocol errors, and communication failures.

Fields

• message - A human-readable description of the network error
• source - An optional nested Yoshi error that caused this network issue
• error_code - An optional numeric error code from the underlying network layer

Examples

let network_error = YoshiKind::Network {
    message: Arc::from("Connection refused"),
    source: None,
    error_code: Some(111),
};

Fields

message: Arc<str>

A human-readable description of the network error.

source: Option<Box<Yoshi>>

An optional nested Yoshi error that caused this network issue.

error_code: Option<u32>

An optional network-specific error code (e.g., HTTP status code).

Config

Configuration error with enhanced diagnostics.

Fields:

• message: A human-readable description of the configuration error.
• source: An optional nested Yoshi error that caused this configuration issue.
• config_path: An optional path to the configuration file or source.

Fields

message: Arc<str>

A human-readable description of the configuration error.

source: Option<Box<Yoshi>>

An optional nested Yoshi error that caused this configuration issue.

config_path: Option<Arc<str>>

An optional path to the configuration file or source.

Validation

Data validation failure with field-level precision.

Fields:

• field: The name of the field that failed validation.
• message: A description of why the validation failed.
• expected: An optional description of the expected value or format.
• actual: An optional string representation of the actual value received.

Fields

field: Arc<str>

The name of the field that failed validation.

message: Arc<str>

A description of why the validation failed.

expected: Option<Arc<str>>

An optional description of the expected value or format.

actual: Option<Arc<str>>

An optional string representation of the actual value received.

Internal

Internal invariant breakage with debugging context.

This typically indicates a bug within the application’s own logic or an unexpected state.

Fields:

• message: A description of the internal error.
• source: An optional nested Yoshi error that caused this internal issue.
• component: An optional name of the component where the error occurred.

Fields

message: Arc<str>

A description of the internal error.

source: Option<Box<Yoshi>>

An optional nested Yoshi error that caused this internal issue.

component: Option<Arc<str>>

An optional name of the component where the error occurred.

NotFound

Resource not found with typed identification.

Fields:

• resource_type: The type of resource (e.g., “User”, “Product”, “File”).
• identifier: The specific identifier of the resource that was not found.
• search_locations: Optional list of locations where the resource was searched.

Fields

resource_type: Arc<str>

The type of resource (e.g., “User”, “Product”, “File”).

identifier: Arc<str>

The specific identifier of the resource that was not found.

search_locations: Option<Vec<Arc<str>>>

Optional list of locations where the resource was searched.

Timeout

Operation timeout with detailed timing information.

Fields:

• operation: A description of the operation that timed out.
• duration: The duration for which the operation ran before timing out.
• expected_max: An optional maximum expected duration for the operation.

Fields

operation: Arc<str>

A description of the operation that timed out.

duration: Duration

The duration for which the operation ran before timing out.

expected_max: Option<Duration>

An optional maximum expected duration for the operation.

ResourceExhausted

Resource exhaustion with precise metrics.

This indicates that a system resource (e.g., memory, CPU, disk space) has been exhausted.

Fields:

• resource: The type of resource exhausted (e.g., “memory”, “thread pool”).
• limit: The configured limit for the resource.
• current: The current usage or allocation of the resource when exhaustion occurred.
• usage_percentage: Optional percentage of resource usage at the time of error.

Fields

resource: Arc<str>

The type of resource exhausted (e.g., “memory”, “thread pool”).

limit: Arc<str>

The configured limit for the resource.

current: Arc<str>

The current usage or allocation of the resource when exhaustion occurred.

usage_percentage: Option<f64>

Optional percentage of resource usage at the time of error.

Foreign

Foreign error wrapper with enhanced type information.

This variant allows wrapping any type that implements std::error::Error, providing a uniform way to integrate external error types into the Yoshi framework.

Fields:

• error: The boxed foreign error object.
• error_type_name: The fully qualified type name of the original error.

Fields

error: Box<dyn Error + Send + Sync + 'static>

The boxed foreign error object.

error_type_name: Arc<str>

The fully qualified type name of the original error.

Multiple

Multiple errors with categorization and priority.

This variant can be used to aggregate several errors into a single Yoshi instance, useful for scenarios like batch processing or validation where multiple failures can occur.

Fields:

• errors: A vector of nested Yoshi errors.
• primary_index: An optional index indicating which error in the errors vector should be considered the primary error.

Fields

errors: Vec<Yoshi>

A vector of nested Yoshi errors.

primary_index: Option<usize>

An optional index indicating which error in the errors vector should be considered the primary error.

Implementations

impl YoshiKind

pub fn from_foreign_with_context<E>( error: E, context: impl Into<String>, ) -> Self

where E: Error + Send + Sync + 'static,

Enhanced foreign error conversion with better type preservation and sanitization

pub const fn severity(&self) -> u8

Gets the severity level of this error kind (0-100, higher is more severe).

This method provides a numerical indication of how critical an error is, allowing for programmatic decision-making based on severity (e.g., logging level, alerting, retry behavior).

Returns

A u8 value representing the severity, where 0 is least severe and 100 is most severe.

Examples

let internal_error = YoshiKind::Internal {
    message: "simulated error".into(),
    source: None,
    component: None,
};
assert_eq!(internal_error.severity(), 80);

let validation_error = YoshiKind::Validation {
    field: "email".into(),
    message: "Invalid format".into(),
    expected: None,
    actual: None,
};
assert_eq!(validation_error.severity(), 20);

pub const fn is_transient(&self) -> bool

Checks if this error kind represents a transient (retryable) error.

Transient errors are typically temporary issues that might resolve themselves if the operation is retried after a short delay (e.g., network glitches, temporary resource unavailability).

Returns

true if the error is considered transient, false otherwise.

Examples

let timeout_error = YoshiKind::Timeout {
    operation: "API call".into(),
    duration: Duration::from_secs(10),
    expected_max: None,
};
assert!(timeout_error.is_transient());

let config_error = YoshiKind::Config {
    message: "Missing key".into(),
    source: None,
    config_path: None,
};
assert!(!config_error.is_transient());

Trait Implementations

impl Clone for YoshiKind

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for YoshiKind

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for YoshiKind

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the YoshiKind for display.

This implementation provides a human-readable string representation of the error kind, including relevant details from its fields.

Arguments

• f - The formatter to write into.

Returns

A fmt::Result indicating success or failure of the formatting.

impl Error for YoshiKind

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the underlying source of the error, if any.

This method delegates to the internal source method, enabling YoshiKind to participate in Rust’s standard error chaining mechanism.

Returns

An Option containing a reference to the underlying error that caused this YoshiKind, or None if there is no direct source.

fn description(&self) -> &str

👎Deprecated since 1.42.0: use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0: replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.