1use std::error::Error as StdError;
4use std::io;
5
6use thiserror::Error;
7
8use crate::msp::{ErrorData, ErrorKind, ErrorObject};
9use crate::spawn::SpawnError;
10
11pub use crate::msp::error::ErrorCode;
12
13#[derive(Clone, Debug, Error, PartialEq)]
15#[error("MSP error {code}: {message}")]
16pub struct MspError {
17 code: i64,
18 message: String,
19 data: Box<ErrorData>,
20}
21
22impl MspError {
23 #[must_use]
25 pub const fn code(&self) -> i64 {
26 self.code
27 }
28
29 #[must_use]
31 pub fn message(&self) -> &str {
32 &self.message
33 }
34
35 #[must_use]
37 pub const fn kind(&self) -> ErrorKind {
38 self.data.kind
39 }
40
41 #[must_use]
43 pub const fn data(&self) -> &ErrorData {
44 &self.data
45 }
46
47 #[must_use]
49 pub fn matches(&self, expected: ErrorCode) -> bool {
50 self.code == expected.code()
51 && (self.kind() == expected.kind() || expected.override_kinds().contains(&self.kind()))
52 }
53
54 #[must_use]
56 pub fn retryable(&self) -> Option<bool> {
57 self.data.retryable.or_else(|| {
58 ErrorCode::ALL
59 .into_iter()
60 .find(|code| self.matches(*code))
61 .and_then(ErrorCode::retryable)
62 })
63 }
64}
65
66impl TryFrom<ErrorObject> for MspError {
67 type Error = ProtocolError;
68
69 fn try_from(error: ErrorObject) -> Result<Self, Self::Error> {
70 let Some(data) = error.data else {
71 return Err(ProtocolError::MissingErrorData);
72 };
73 Ok(Self {
74 code: error.code,
75 message: error.message,
76 data,
77 })
78 }
79}
80
81#[derive(Debug, Error, Clone, PartialEq, Eq)]
84#[non_exhaustive]
85pub enum ProtocolError {
86 #[error("MSP error response has no data.kind")]
89 MissingErrorData,
90 #[error("{message}")]
100 Other {
101 message: String,
103 line: Option<String>,
106 },
107}
108
109impl ProtocolError {
110 pub(crate) fn new(message: impl Into<String>, line: Option<&str>) -> Self {
111 Self::Other {
112 message: message.into(),
113 line: line.map(str::to_owned),
114 }
115 }
116
117 #[must_use]
119 pub fn message(&self) -> &str {
120 match self {
121 Self::MissingErrorData => "MSP error response has no data.kind",
122 Self::Other { message, .. } => message,
123 }
124 }
125
126 #[must_use]
128 pub fn line(&self) -> Option<&str> {
129 match self {
130 Self::MissingErrorData => None,
131 Self::Other { line, .. } => line.as_deref(),
132 }
133 }
134}
135
136#[derive(Debug, Error)]
138#[non_exhaustive]
139pub enum MuseError {
140 #[error("client is closed")]
142 ClientClosed,
143 #[error("transport ended before the server answered")]
146 TransportEnded,
147 #[error("session {0} was discarded after an ephemeral transport ended")]
150 SessionDiscarded(String),
151 #[error(
155 "required permission profile {requested:?} was not applied: the committed selection is {} (session {session_id})",
156 served.as_deref().map_or_else(|| "unknown".to_owned(), |served| format!("{served:?}"))
157 )]
158 PermissionProfileNotApplied {
159 requested: String,
161 served: Option<String>,
164 session_id: String,
166 },
167 #[error("command {command_id} was discarded locally")]
170 Discarded {
171 command_id: String,
173 },
174 #[error("transport failed: {0}")]
176 Transport(#[from] io::Error),
177 #[error(transparent)]
179 Spawn(#[from] SpawnError),
180 #[error(transparent)]
182 Msp(#[from] MspError),
183 #[error(transparent)]
186 Protocol(#[from] ProtocolError),
187}
188
189#[derive(Debug, Error, Clone, PartialEq, Eq)]
191#[error("event for session {actual} was routed to session {expected}")]
192pub struct ForeignSessionError {
193 pub expected: String,
195 pub actual: String,
197}
198
199#[derive(Debug, Error)]
201#[non_exhaustive]
202pub enum GapFillError {
203 #[error("view/gap ({after}, {next}) page failed")]
209 PageFailed {
210 after: String,
213 next: String,
216 #[source]
218 source: Box<dyn StdError + Send + Sync>,
219 },
220 #[error("view/gap ({after}, {next}) page stalled at {cursor}")]
223 PageStalled {
224 after: String,
226 next: String,
228 cursor: String,
230 },
231}
232
233#[derive(Debug)]
235#[non_exhaustive]
236pub enum GapPageFailure<'a> {
237 NoPendingGap(&'a ProtocolError),
239 ForeignSession(&'a ForeignSessionError),
241 Msp(&'a MspError),
243 Protocol(&'a ProtocolError),
245 Transport(&'a (dyn StdError + Send + Sync + 'static)),
247}
248
249impl GapFillError {
250 #[must_use]
252 pub const fn is_page_failed(&self) -> bool {
253 matches!(self, Self::PageFailed { .. })
254 }
255
256 #[must_use]
258 pub const fn is_page_stalled(&self) -> bool {
259 matches!(self, Self::PageStalled { .. })
260 }
261
262 #[must_use]
264 pub fn page_failure(&self) -> Option<GapPageFailure<'_>> {
265 let Self::PageFailed { source, .. } = self else {
266 return None;
267 };
268 if let Some(error) = source.downcast_ref::<ProtocolError>() {
269 return Some(match error {
270 ProtocolError::Other { .. } => GapPageFailure::NoPendingGap(error),
271 ProtocolError::MissingErrorData => GapPageFailure::Protocol(error),
272 });
273 }
274 if let Some(error) = source.downcast_ref::<ForeignSessionError>() {
275 return Some(GapPageFailure::ForeignSession(error));
276 }
277 if let Some(error) = source.downcast_ref::<MspError>() {
278 return Some(GapPageFailure::Msp(error));
279 }
280 Some(GapPageFailure::Transport(source.as_ref()))
281 }
282}
283
284#[cfg(test)]
285mod tests {
286 use crate::msp::error::ErrorCode;
287
288 use crate::msp::{ErrorData, ErrorObject};
289
290 use super::{MspError, ProtocolError};
291
292 type TestResult = Result<(), Box<dyn std::error::Error>>;
293
294 #[test]
295 fn typed_msp_errors_are_bound_to_every_generated_registry_pair() -> TestResult {
296 for code in ErrorCode::ALL {
297 for kind in std::iter::once(code.kind()).chain(code.override_kinds().iter().copied()) {
298 let object = ErrorObject {
299 code: code.code(),
300 message: format!("{kind:?}"),
301 data: Some(Box::new(ErrorData::new(kind))),
302 };
303 let error = MspError::try_from(object.clone())?;
304
305 assert_eq!(error.code(), code.code());
306 assert_eq!(error.kind(), kind);
307 assert_eq!(Some(error.data()), object.data.as_deref());
308 assert_eq!(error.retryable(), code.retryable());
309 assert!(error.matches(code));
310 }
311 }
312 Ok(())
313 }
314
315 #[test]
316 fn contradictory_code_and_kind_remain_visible_but_do_not_match() -> TestResult {
317 let code = ErrorCode::ALL[0];
318 let other = ErrorCode::ALL[1];
319 let object = ErrorObject {
320 code: code.code(),
321 message: "contradictory registry pair".to_owned(),
322 data: Some(Box::new(ErrorData::new(other.kind()))),
323 };
324 let error = MspError::try_from(object)?;
325
326 assert_eq!(error.code(), code.code());
327 assert_eq!(error.kind(), other.kind());
328 assert!(!error.matches(code));
329 assert_eq!(error.retryable(), None);
330 Ok(())
331 }
332
333 #[test]
334 fn missing_error_kind_is_a_typed_protocol_failure() {
335 let object = ErrorObject {
336 code: ErrorCode::ALL[0].code(),
337 message: "missing data".to_owned(),
338 data: None,
339 };
340 let error = MspError::try_from(object).expect_err("MSP errors require data.kind");
341
342 assert!(matches!(error, ProtocolError::MissingErrorData));
343 }
344
345 #[test]
346 fn payload_retry_guidance_overrides_the_generated_default() -> TestResult {
347 let Some(code) = ErrorCode::ALL
348 .into_iter()
349 .find(|code| code.retryable() == Some(false))
350 else {
351 return Err("the registry has no non-retryable row".into());
352 };
353 let mut data = ErrorData::new(code.kind());
354 data.retryable = Some(true);
355 let error = MspError::try_from(ErrorObject {
356 code: code.code(),
357 message: "payload override".to_owned(),
358 data: Some(Box::new(data)),
359 })?;
360
361 assert_eq!(error.retryable(), Some(true));
362 Ok(())
363 }
364}