multiio 0.2.3

A unified I/O orchestration library for CLI/server applications
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114

//! Error types and policies for multiio I/O operations.
//!
//! This module provides:
//! - `ErrorPolicy`: Controls whether to fail fast or accumulate errors
//! - `Stage`: Indicates where an error occurred in the I/O pipeline
//! - `SingleIoError`: A single I/O error with context
//! - `AggregateError`: A collection of errors when using `Accumulate` policy

use std::fmt;

use thiserror::Error;

#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum ErrorPolicy {
    /// Stop at the first error encountered
    FastFail,
    /// Collect all errors and return them together
    #[default]
    Accumulate,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Stage {
    ResolveInput,
    ResolveOutput,
    /// Error while opening the I/O stream
    Open,
    Parse,
    Serialize,
}

impl fmt::Display for Stage {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Stage::ResolveInput => write!(f, "ResolveInput"),
            Stage::ResolveOutput => write!(f, "ResolveOutput"),
            Stage::Open => write!(f, "Open"),
            Stage::Parse => write!(f, "Parse"),
            Stage::Serialize => write!(f, "Serialize"),
        }
    }
}

#[derive(Debug)]
pub struct SingleIoError {
    /// Stage where the error occurred
    pub stage: Stage,
    /// Identifier of the target (file path, "-" for stdin/stdout, etc.)
    pub target: String,
    /// The underlying error
    pub error: Box<dyn std::error::Error + Send + Sync>,
}

impl fmt::Display for SingleIoError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "[{}] {}: {}", self.stage, self.target, self.error)
    }
}

impl std::error::Error for SingleIoError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        Some(self.error.as_ref())
    }
}

/// An aggregate of multiple I/O errors.
///
/// This is returned when using `ErrorPolicy::Accumulate` and multiple errors occurred.
#[derive(Debug, Error)]
pub struct AggregateError {
    /// Collection of individual errors
    pub errors: Vec<SingleIoError>,
}

impl fmt::Display for AggregateError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        writeln!(f, "I/O encountered {} error(s):", self.errors.len())?;
        for (i, e) in self.errors.iter().enumerate() {
            writeln!(f, "  #{}: {}", i + 1, e)?;
        }
        Ok(())
    }
}

impl AggregateError {
    /// Create a new aggregate error with a single error.
    pub fn single(error: SingleIoError) -> Self {
        Self {
            errors: vec![error],
        }
    }

    /// Check if there are no errors.
    pub fn is_empty(&self) -> bool {
        self.errors.is_empty()
    }

    /// Get the number of errors.
    pub fn len(&self) -> usize {
        self.errors.len()
    }
}

impl From<SingleIoError> for AggregateError {
    fn from(error: SingleIoError) -> Self {
        Self::single(error)
    }
}

#[cfg(feature = "miette")]
mod miette_impl;

#[cfg(feature = "miette")]
pub use miette_impl::*;