1use std::fmt;
15use std::path::{Path, PathBuf};
16
17#[derive(Debug)]
19pub enum StateError {
20 Io {
23 op: String,
25 path: PathBuf,
26 source: std::io::Error,
27 },
28 Failed { op: String, path: PathBuf, detail: String },
31 Corrupt {
33 what: String,
35 detail: String,
36 },
37 Unsupported { what: String },
40}
41
42impl StateError {
43 pub fn io(op: impl Into<String>, path: impl AsRef<Path>, source: std::io::Error) -> Self {
44 Self::Io {
45 op: op.into(),
46 path: path.as_ref().to_path_buf(),
47 source,
48 }
49 }
50 pub fn failed(op: impl Into<String>, path: impl AsRef<Path>, detail: impl Into<String>) -> Self {
51 Self::Failed {
52 op: op.into(),
53 path: path.as_ref().to_path_buf(),
54 detail: detail.into(),
55 }
56 }
57 pub fn corrupt(what: impl Into<String>, detail: impl Into<String>) -> Self {
58 Self::Corrupt {
59 what: what.into(),
60 detail: detail.into(),
61 }
62 }
63 pub fn unsupported(what: impl Into<String>) -> Self {
64 Self::Unsupported { what: what.into() }
65 }
66}
67
68const RESET: &str = "set STREAM_RESET_STATE=1 to start fresh and discard the checkpoint";
69
70impl fmt::Display for StateError {
71 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
72 match self {
73 Self::Io { op, path, source } => write!(f, "state io: {op} {}: {source}", path.display()),
74 Self::Failed { op, path, detail } => write!(f, "state: {op} {}: {detail}", path.display()),
75 Self::Corrupt { what, detail } => write!(f, "state corrupt: {what}: {detail} — {RESET}"),
76 Self::Unsupported { what } => write!(f, "state unsupported: {what} — {RESET}"),
77 }
78 }
79}
80
81impl std::error::Error for StateError {
82 fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
83 match self {
84 Self::Io { source, .. } => Some(source),
85 _ => None,
86 }
87 }
88}
89
90impl From<StateError> for String {
91 fn from(e: StateError) -> Self {
92 e.to_string()
93 }
94}
95
96#[cold]
100#[inline(never)]
101pub fn state_fault(e: StateError) -> ! {
102 panic!("{e}")
103}
104
105#[cold]
108#[inline(never)]
109pub fn config_fault(message: &str) -> ! {
110 panic!("{message}")
111}
112
113#[cold]
116#[inline(never)]
117pub fn delivery_fault(message: &str) -> ! {
118 panic!("{message}")
119}
120
121#[cold]
125#[inline(never)]
126pub fn transform_fault(message: &str) -> ! {
127 panic!("{message}")
128}
129
130#[cfg(test)]
131mod tests {
132 use super::*;
133
134 #[test]
135 fn messages_name_the_operation_the_path_and_the_remedy_where_there_is_one() {
136 let io = StateError::io(
137 "thaw shard 3",
138 "/spill/shard-3.arrow",
139 std::io::Error::from(std::io::ErrorKind::NotFound),
140 );
141 let s = io.to_string();
142 assert!(s.contains("thaw shard 3") && s.contains("/spill/shard-3.arrow"), "{s}");
143 assert!(
144 !s.contains("STREAM_RESET_STATE"),
145 "an io fault is not a reset case: {s}"
146 );
147
148 let c = StateError::corrupt("thaw shard 3 from /spill/x", "bad envelope").to_string();
149 assert!(c.contains("bad envelope") && c.contains("STREAM_RESET_STATE=1"), "{c}");
150
151 let u = StateError::unsupported("file-backed state for a lookup join").to_string();
152 assert!(u.contains("STREAM_RESET_STATE=1"), "{u}");
153
154 let as_string: String = StateError::failed("freeze join batch", "/spill/j.arrow", "writer refused").into();
155 assert!(as_string.starts_with("state: freeze join batch"), "{as_string}");
156 }
157
158 #[test]
159 fn state_fault_panics_with_the_typed_message() {
160 let r = std::panic::catch_unwind(|| {
161 state_fault(StateError::unsupported("a foreign manifest"));
162 });
163 let msg = r.unwrap_err().downcast::<String>().expect("a String payload");
164 assert!(msg.contains("state unsupported: a foreign manifest"), "{msg}");
165 }
166}