Skip to main content

dispatch_core/
error.rs

1use core::{error::Error, fmt};
2
3use crate::ResourceId;
4
5/// A failure reported while extracting one resource parameter.
6#[derive(Debug, Clone, Copy, PartialEq, Eq)]
7#[non_exhaustive]
8pub enum FetchError {
9    /// The requested capability is not currently available.
10    Unavailable,
11
12    /// The resource backend could not grant the requested borrow.
13    BorrowConflict,
14
15    /// The resource backend returned a null or misaligned pointer.
16    InvalidPointer,
17
18    /// An application-defined, allocation-free error code.
19    Custom(u16),
20}
21
22impl fmt::Display for FetchError {
23    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
24        match self {
25            Self::Unavailable => formatter.write_str("resource is unavailable"),
26            Self::BorrowConflict => formatter.write_str("resource borrow conflicts"),
27            Self::InvalidPointer => formatter.write_str("resource pointer is invalid"),
28            Self::Custom(code) => write!(formatter, "resource backend error {code}"),
29        }
30    }
31}
32
33impl Error for FetchError {}
34
35/// A resource-parameter preparation failure.
36#[derive(Debug, Clone, Copy, PartialEq, Eq)]
37pub enum ParamError {
38    /// Two parameters requested incompatible access to one resource.
39    AccessConflict {
40        /// Zero-based position of the earlier parameter.
41        first: u8,
42
43        /// Zero-based position of the later parameter.
44        second: u8,
45
46        /// Identity shared by the conflicting accesses.
47        resource: ResourceId,
48    },
49
50    /// A parameter backend failed while fetching an argument.
51    Fetch {
52        /// Zero-based position of the parameter.
53        index: u8,
54
55        /// Error returned by the parameter backend.
56        error: FetchError,
57    },
58}
59
60impl fmt::Display for ParamError {
61    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
62        match self {
63            Self::AccessConflict {
64                first,
65                second,
66                resource,
67            } => write!(
68                formatter,
69                "parameters {first} and {second} conflict on resource {}",
70                resource.get()
71            ),
72            Self::Fetch { index, error } => {
73                write!(formatter, "failed to fetch parameter {index}: {error}")
74            }
75        }
76    }
77}
78
79impl Error for ParamError {
80    fn source(&self) -> Option<&(dyn Error + 'static)> {
81        match self {
82            Self::AccessConflict { .. } => None,
83            Self::Fetch { error, .. } => Some(error),
84        }
85    }
86}
87
88/// One stage in the dispatch execution pipeline.
89#[derive(Debug, Clone, Copy, PartialEq, Eq)]
90pub enum DispatchStage {
91    /// Logic run after selection and before the command.
92    Before,
93
94    /// The selected command function.
95    Command,
96
97    /// Logic run after a successful command.
98    After,
99
100    /// Final successful-response transformation.
101    Response,
102}
103
104impl fmt::Display for DispatchStage {
105    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
106        match self {
107            Self::Before => formatter.write_str("before"),
108            Self::Command => formatter.write_str("command"),
109            Self::After => formatter.write_str("after"),
110            Self::Response => formatter.write_str("response"),
111        }
112    }
113}
114
115/// A failure raised while preparing or calling one typed function.
116#[derive(Debug, Clone, Copy, PartialEq, Eq)]
117pub enum StageError<E> {
118    /// Resource arguments could not be prepared safely.
119    Param(ParamError),
120
121    /// The application function returned an error.
122    User(E),
123}
124
125impl<E> fmt::Display for StageError<E>
126where
127    E: fmt::Display,
128{
129    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
130        match self {
131            Self::Param(error) => write!(formatter, "parameter error: {error}"),
132            Self::User(error) => write!(formatter, "function failed: {error}"),
133        }
134    }
135}
136
137impl<E> Error for StageError<E>
138where
139    E: Error + 'static,
140{
141    fn source(&self) -> Option<&(dyn Error + 'static)> {
142        match self {
143            Self::Param(error) => Some(error),
144            Self::User(error) => Some(error),
145        }
146    }
147}
148
149/// An error raised while selecting or executing a command.
150#[derive(Debug, Clone, Copy, PartialEq, Eq)]
151pub enum DispatchError<E> {
152    /// No command in the table matched the current context.
153    NotFound,
154
155    /// Resource arguments for one pipeline stage could not be prepared safely.
156    Param {
157        /// Stage whose parameters could not be prepared.
158        stage: DispatchStage,
159
160        /// Parameter validation or fetch failure.
161        error: ParamError,
162    },
163
164    /// The configured before hook returned an application error.
165    Before(E),
166
167    /// The selected command returned an application error.
168    Command(E),
169
170    /// The configured after hook returned an application error.
171    After(E),
172
173    /// The configured response handler returned an application error.
174    Response(E),
175}
176
177impl<E> DispatchError<E> {
178    pub(crate) fn at(stage: DispatchStage, error: StageError<E>) -> Self {
179        match error {
180            StageError::Param(error) => Self::Param { stage, error },
181            StageError::User(error) => match stage {
182                DispatchStage::Before => Self::Before(error),
183                DispatchStage::Command => Self::Command(error),
184                DispatchStage::After => Self::After(error),
185                DispatchStage::Response => Self::Response(error),
186            },
187        }
188    }
189}
190
191impl<E> fmt::Display for DispatchError<E>
192where
193    E: fmt::Display,
194{
195    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
196        match self {
197            Self::NotFound => formatter.write_str("no matching command"),
198            Self::Param { stage, error } => write!(formatter, "{stage} parameter error: {error}"),
199            Self::Before(error) => write!(formatter, "before hook failed: {error}"),
200            Self::Command(error) => write!(formatter, "command execution failed: {error}"),
201            Self::After(error) => write!(formatter, "after hook failed: {error}"),
202            Self::Response(error) => write!(formatter, "response handling failed: {error}"),
203        }
204    }
205}
206
207impl<E> Error for DispatchError<E>
208where
209    E: Error + 'static,
210{
211    fn source(&self) -> Option<&(dyn Error + 'static)> {
212        match self {
213            Self::NotFound => None,
214            Self::Param { error, .. } => Some(error),
215            Self::Before(error)
216            | Self::Command(error)
217            | Self::After(error)
218            | Self::Response(error) => Some(error),
219        }
220    }
221}