Skip to main content

fv_streams_ops/
error.rs

1//! The state tier's errors — what the immutable-file layer under the operators reports when the
2//! filesystem, or a file's contents, refuse what the runtime asked. Every message names the
3//! operation and the path; where the state is unrecoverable it names the remedy
4//! (`STREAM_RESET_STATE=1`), so a FAILED build says what to do, not only what broke.
5//!
6//! Two escalation paths share this type. Once-per-epoch and once-at-start work (a checkpoint, a
7//! restore) returns it as a `Result`, and the engine fails the build with the message. The data
8//! path (`push` / `advance`) is deliberately infallible — a `Result` per key would put a branch on
9//! the hottest loop in the engine — so its two I/O sites (thawing a frozen window shard, freezing
10//! a join batch under memory pressure) escalate through [`state_fault`]: a `#[cold]` panic
11//! carrying the same typed diagnostic, which the task runtime already catches and reports as a
12//! FAILED build. The success path of both sites is byte-for-byte what it was.
13
14use std::fmt;
15use std::path::{Path, PathBuf};
16
17/// Why the state tier could not do what the runtime asked.
18#[derive(Debug)]
19pub enum StateError {
20    /// A filesystem operation on a state file failed: a lost spill directory, a full disk,
21    /// permissions.
22    Io {
23        /// What was being done (`"thaw shard 3"`, `"write checkpoint file"`).
24        op: String,
25        path: PathBuf,
26        source: std::io::Error,
27    },
28    /// A write or encode step on a state file failed for a reason that is not a plain I/O error
29    /// (an Arrow writer refused the batch, say).
30    Failed { op: String, path: PathBuf, detail: String },
31    /// A state file or snapshot did not decode as this operator's state.
32    Corrupt {
33        /// What was being read (`"thaw shard 3 from …"`).
34        what: String,
35        detail: String,
36    },
37    /// A checkpoint references a state shape this operator never writes — it belongs to another
38    /// topology.
39    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/// The data path's escalation for a state fault it cannot return: a `#[cold]` panic carrying the
97/// typed diagnostic. The task runtime catches it (`catch_unwind`) and fails the BUILD with this
98/// message — the same outcome a `Result` would reach, without a branch on the success path.
99#[cold]
100#[inline(never)]
101pub fn state_fault(e: StateError) -> ! {
102    panic!("{e}")
103}
104
105/// A join's naming that the first schemas it meets make impossible (a `rightRename` onto a taken
106/// name): decided once per pair of schemas, never per row, and ends the build like [`state_fault`].
107#[cold]
108#[inline(never)]
109pub fn config_fault(message: &str) -> ! {
110    panic!("{message}")
111}
112
113/// A sink that cannot deliver rows it was given (the destination refused them past its retry
114/// bound): never dropped in silence — it ends the build like [`state_fault`].
115#[cold]
116#[inline(never)]
117pub fn delivery_fault(message: &str) -> ! {
118    panic!("{message}")
119}
120
121/// A compute step whose transform failed on a batch: the batch is never dropped, so the build ends
122/// like [`state_fault`], and a restart replays it from the last checkpoint once the transform is
123/// fixed.
124#[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}