1use std::fmt;
11
12use futures::future::BoxFuture;
13use indexmap::IndexMap;
14use serde::{Deserialize, Serialize};
15
16use crate::event::{Event, PauseReason, Usage};
17use crate::snapshot::Snapshot;
18use crate::value::Value;
19
20#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
22#[serde(rename_all = "snake_case")]
23#[non_exhaustive]
24pub enum RunStatus {
25 Running,
26 Paused,
27 Succeeded,
28 Failed,
29 Aborted,
30}
31
32impl RunStatus {
33 pub fn is_terminal(self) -> bool {
35 matches!(self, RunStatus::Succeeded | RunStatus::Failed | RunStatus::Aborted)
36 }
37
38 pub fn parse(text: &str) -> Option<Self> {
40 match text {
41 "running" => Some(RunStatus::Running),
42 "paused" => Some(RunStatus::Paused),
43 "succeeded" => Some(RunStatus::Succeeded),
44 "failed" => Some(RunStatus::Failed),
45 "aborted" => Some(RunStatus::Aborted),
46 _ => None,
47 }
48 }
49}
50
51#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
53pub struct RunRecord {
54 pub run_id: String,
55 pub workflow: String,
57 pub fingerprint: String,
59 pub status: RunStatus,
60 pub created_ms: u64,
61 pub updated_ms: u64,
62 #[serde(default)]
64 pub pause_reasons: Vec<PauseReason>,
65 #[serde(default)]
66 pub outputs: IndexMap<String, Value>,
67 #[serde(default)]
69 pub answer: String,
70 #[serde(default)]
71 pub error: Option<String>,
72 #[serde(default)]
73 pub error_type: Option<String>,
74 #[serde(default)]
75 pub usage: Usage,
76 #[serde(default)]
78 pub event_count: u64,
79 #[serde(default)]
81 pub events_truncated: bool,
82}
83
84impl RunRecord {
85 pub fn running(
87 run_id: impl Into<String>,
88 workflow: impl Into<String>,
89 fingerprint: impl Into<String>,
90 now_ms: u64,
91 ) -> Self {
92 Self {
93 run_id: run_id.into(),
94 workflow: workflow.into(),
95 fingerprint: fingerprint.into(),
96 status: RunStatus::Running,
97 created_ms: now_ms,
98 updated_ms: now_ms,
99 pause_reasons: Vec::new(),
100 outputs: IndexMap::new(),
101 answer: String::new(),
102 error: None,
103 error_type: None,
104 usage: Usage::default(),
105 event_count: 0,
106 events_truncated: false,
107 }
108 }
109
110 pub fn apply_terminal(&mut self, event: &Event, now_ms: u64) -> Option<Snapshot> {
113 self.updated_ms = now_ms;
114 match event {
115 Event::RunSucceeded { outputs, usage, .. } => {
116 self.status = RunStatus::Succeeded;
117 self.outputs.clone_from(outputs);
118 self.usage = *usage;
119 self.pause_reasons.clear();
120 None
121 }
122 Event::RunFailed { error, error_type, usage, .. } => {
123 self.status = RunStatus::Failed;
124 self.error = Some(error.clone());
125 self.error_type = Some(error_type.clone());
126 self.usage = *usage;
127 self.pause_reasons.clear();
128 None
129 }
130 Event::RunAborted { reason, .. } => {
131 self.status = RunStatus::Aborted;
132 self.error = Some(reason.clone());
133 self.pause_reasons.clear();
134 None
135 }
136 Event::RunPaused { reasons, snapshot } => {
137 self.status = RunStatus::Paused;
138 self.pause_reasons.clone_from(reasons);
139 self.usage = snapshot.usage;
140 Some((**snapshot).clone())
141 }
142 _ => None,
143 }
144 }
145}
146
147#[derive(Clone, Debug, Default, PartialEq, Eq)]
149pub struct RunFilter {
150 pub workflow: Option<String>,
151 pub status: Option<RunStatus>,
152 pub limit: usize,
154 pub cursor: Option<String>,
156}
157
158#[derive(Clone, Debug, Default, PartialEq, Serialize)]
160pub struct RunPage {
161 pub runs: Vec<RunRecord>,
162 pub next_cursor: Option<String>,
163}
164
165#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
167#[non_exhaustive]
168pub enum StoreError {
169 #[error("run `{0}` not found")]
170 NotFound(String),
171 #[error("{0}")]
174 Conflict(String),
175 #[error("invalid run id `{0}`")]
176 InvalidId(String),
177 #[error("run store I/O error: {0}")]
178 Io(String),
179 #[error("corrupt run store entry: {0}")]
180 Corrupt(String),
181}
182
183pub type StoreResult<T> = Result<T, StoreError>;
185
186pub trait RunStore: Send + Sync + fmt::Debug {
191 fn create(&self, record: RunRecord) -> BoxFuture<'_, StoreResult<()>>;
193 fn put(&self, record: RunRecord) -> BoxFuture<'_, StoreResult<()>>;
195 fn get<'a>(&'a self, run_id: &'a str) -> BoxFuture<'a, StoreResult<Option<RunRecord>>>;
196 fn list(&self, filter: RunFilter) -> BoxFuture<'_, StoreResult<RunPage>>;
197 fn delete<'a>(&'a self, run_id: &'a str) -> BoxFuture<'a, StoreResult<bool>>;
199 fn append_events<'a>(&'a self, run_id: &'a str, events: Vec<serde_json::Value>) -> BoxFuture<'a, StoreResult<()>>;
202 fn events<'a>(&'a self, run_id: &'a str, from: u64) -> BoxFuture<'a, StoreResult<Vec<serde_json::Value>>>;
204 fn save_snapshot<'a>(&'a self, run_id: &'a str, snapshot: &'a Snapshot) -> BoxFuture<'a, StoreResult<()>>;
205 fn load_snapshot<'a>(&'a self, run_id: &'a str) -> BoxFuture<'a, StoreResult<Option<Snapshot>>>;
206 fn claim_resume<'a>(&'a self, run_id: &'a str, now_ms: u64) -> BoxFuture<'a, StoreResult<RunRecord>>;
210 fn recover_interrupted(&self, now_ms: u64) -> BoxFuture<'_, StoreResult<usize>>;
213 fn purge_before(&self, cutoff_ms: u64) -> BoxFuture<'_, StoreResult<usize>>;
215}
216
217pub const INTERRUPTED_BY_RESTART: &str = "interrupted by restart";
219
220pub fn event_to_json(event: &Event) -> serde_json::Value {
223 let mut json = serde_json::to_value(event).unwrap_or(serde_json::Value::Null);
224 if let Some(obj) = json.as_object_mut() {
225 if obj.get("type").and_then(serde_json::Value::as_str) == Some("run_paused") {
226 obj.remove("snapshot");
227 }
228 }
229 json
230}
231
232pub fn validate_run_id(run_id: &str) -> StoreResult<()> {
235 let ok = !run_id.is_empty()
236 && run_id.len() <= 128
237 && !run_id.starts_with('.')
238 && run_id.chars().all(|c| c.is_ascii_alphanumeric() || matches!(c, '-' | '_' | '.'));
239 if ok { Ok(()) } else { Err(StoreError::InvalidId(run_id.chars().take(64).collect())) }
240}
241
242pub fn now_ms() -> u64 {
244 #[cfg(all(target_arch = "wasm32", target_os = "unknown"))]
245 {
246 0
247 }
248 #[cfg(not(all(target_arch = "wasm32", target_os = "unknown")))]
249 {
250 std::time::SystemTime::now()
251 .duration_since(std::time::UNIX_EPOCH)
252 .map(|d| u64::try_from(d.as_millis()).unwrap_or(u64::MAX))
253 .unwrap_or(0)
254 }
255}
256
257pub fn page_of(mut sorted: Vec<RunRecord>, filter: &RunFilter, max_limit: usize) -> RunPage {
259 sorted.retain(|r| {
260 filter.workflow.as_deref().is_none_or(|w| r.workflow == w) && filter.status.is_none_or(|s| r.status == s)
261 });
262 let start = match &filter.cursor {
263 Some(cursor) => sorted.iter().position(|r| &r.run_id == cursor).map_or(sorted.len(), |i| i + 1),
264 None => 0,
265 };
266 let limit = if filter.limit == 0 { max_limit } else { filter.limit.min(max_limit) };
267 let runs: Vec<RunRecord> = sorted.into_iter().skip(start).take(limit.saturating_add(1)).collect();
268 let mut runs = runs;
269 let next_cursor = if runs.len() > limit {
270 runs.truncate(limit);
271 runs.last().map(|r| r.run_id.clone())
272 } else {
273 None
274 };
275 RunPage { runs, next_cursor }
276}
277
278pub fn sort_newest_first(records: &mut [RunRecord]) {
280 records.sort_by(|a, b| b.created_ms.cmp(&a.created_ms).then_with(|| b.run_id.cmp(&a.run_id)));
281}
282
283#[cfg(test)]
284mod tests {
285 use super::*;
286
287 fn rec(id: &str, wf: &str, created: u64, status: RunStatus) -> RunRecord {
288 let mut r = RunRecord::running(id, wf, "fp", created);
289 r.status = status;
290 r
291 }
292
293 #[test]
294 fn run_ids_are_validated() {
295 assert!(validate_run_id("run-1a2b_3.c").is_ok());
296 for bad in ["", "../x", ".hidden", "a/b", "a b", &"x".repeat(129)] {
297 assert!(validate_run_id(bad).is_err(), "{bad}");
298 }
299 }
300
301 #[test]
302 fn paging_and_filtering() {
303 let mut all = vec![
304 rec("a", "w1", 1, RunStatus::Succeeded),
305 rec("b", "w1", 2, RunStatus::Paused),
306 rec("c", "w2", 3, RunStatus::Paused),
307 rec("d", "w1", 4, RunStatus::Failed),
308 ];
309 sort_newest_first(&mut all);
310 let page = page_of(all.clone(), &RunFilter { limit: 2, ..Default::default() }, 100);
311 assert_eq!(page.runs.iter().map(|r| r.run_id.as_str()).collect::<Vec<_>>(), ["d", "c"]);
312 assert_eq!(page.next_cursor.as_deref(), Some("c"));
313 let next = page_of(all.clone(), &RunFilter { limit: 2, cursor: page.next_cursor, ..Default::default() }, 100);
314 assert_eq!(next.runs.iter().map(|r| r.run_id.as_str()).collect::<Vec<_>>(), ["b", "a"]);
315 assert_eq!(next.next_cursor, None);
316 let paused = page_of(
317 all.clone(),
318 &RunFilter { status: Some(RunStatus::Paused), workflow: Some("w1".into()), ..Default::default() },
319 100,
320 );
321 assert_eq!(paused.runs.len(), 1);
322 assert_eq!(paused.runs[0].run_id, "b");
323 }
324
325 #[test]
326 fn paused_event_json_drops_snapshot() {
327 let snapshot = Snapshot {
328 format: crate::snapshot::SNAPSHOT_FORMAT,
329 run_id: "r".into(),
330 graph_fingerprint: "fp".into(),
331 elapsed_ms: 0,
332 steps: 0,
333 usage: Usage::default(),
334 handled_errors: 0,
335 root: crate::snapshot::FrameSnapshot::default(),
336 };
337 let event = Event::RunPaused { reasons: Vec::new(), snapshot: Box::new(snapshot) };
338 let json = event_to_json(&event);
339 assert_eq!(json["type"], "run_paused");
340 assert!(json.get("snapshot").is_none());
341 }
342}