1use crate::expr::Expr;
8use crate::types::Type;
9use serde::{Deserialize, Serialize};
10use sha2::{Digest, Sha256};
11use std::collections::{BTreeMap, HashMap, HashSet};
12use std::fmt;
13
14pub const IR_VERSION: &str = "orbit-ir/1";
15pub const IR_VERSION_2: &str = "orbit-ir/2";
19pub const SUPPORTED_IR_VERSIONS: &[&str] = &[IR_VERSION, IR_VERSION_2];
21
22#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
23pub struct WorkflowIr {
24 pub ir_version: String,
25 pub name: String,
26 pub version: String,
27 #[serde(default, skip_serializing_if = "Option::is_none")]
28 pub description: Option<String>,
29 #[serde(default)]
31 pub definition_hash: String,
32 #[serde(default, skip_serializing_if = "Option::is_none")]
33 pub timeout_ms: Option<u64>,
34 pub input: Type,
35 pub output: Type,
36 pub steps: Vec<StepIr>,
38 #[serde(default, skip_serializing_if = "Option::is_none")]
39 pub result: Option<Expr>,
40 pub contracts: BTreeMap<String, TaskContract>,
42 #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
44 pub signals: BTreeMap<String, Type>,
45 #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
47 pub queries: BTreeMap<String, QueryIr>,
48 #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
52 pub handlers: BTreeMap<String, Vec<StepIr>>,
53 #[serde(default)]
55 pub source_map: BTreeMap<String, SourceLocation>,
56}
57
58#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
61pub struct QueryIr {
62 pub expr: Expr,
63 pub output_type: Type,
64}
65
66#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
67pub struct SourceLocation {
68 pub file: String,
69 pub line: usize,
70 pub column: usize,
71}
72
73#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
74pub struct TaskContract {
75 pub name: String,
76 pub version: String,
77 pub input: Type,
78 pub output: Type,
79 #[serde(default, skip_serializing_if = "std::ops::Not::not")]
81 pub builtin: bool,
82 #[serde(default, skip_serializing_if = "Option::is_none")]
86 pub workflow_hash: Option<String>,
87 #[serde(default, skip_serializing_if = "Option::is_none")]
90 pub compensated_by: Option<String>,
91}
92
93pub const HANDLER_KINDS: &[&str] = &["failure", "cancel", "timeout"];
95
96pub fn handler_key(kind: &str, step: &str) -> String {
98 format!("on_{kind}:{step}")
99}
100
101pub fn parse_handler_key(key: &str) -> Option<(&str, &str)> {
103 let rest = key.strip_prefix("on_")?;
104 let (kind, step) = rest.split_once(':')?;
105 HANDLER_KINDS.contains(&kind).then_some((kind, step))
106}
107
108pub const WORKFLOW_CONTRACT_PREFIX: &str = "workflow:";
110
111#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
113pub struct ForEach {
114 pub variable: String,
115 pub items: Expr,
116 #[serde(default, skip_serializing_if = "Option::is_none")]
117 pub max_parallel: Option<u32>,
118}
119
120#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
121pub struct StepIr {
122 pub id: String,
123 pub action: Action,
124 pub dependencies: Vec<String>,
126 #[serde(default, skip_serializing_if = "Option::is_none")]
127 pub condition: Option<Expr>,
128 #[serde(default, skip_serializing_if = "Option::is_none")]
129 pub for_each: Option<ForEach>,
130 #[serde(default, skip_serializing_if = "Option::is_none")]
131 pub compensation: Option<Invocation>,
132 pub output_type: Type,
134}
135
136#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
137#[serde(tag = "type", rename_all = "snake_case")]
138pub enum Action {
139 Task(Invocation),
140 Sleep {
142 duration_ms: u64,
143 },
144 Workflow(Invocation),
147 Await {
150 signal: String,
151 #[serde(default, skip_serializing_if = "Option::is_none")]
152 timeout_ms: Option<u64>,
153 },
154 Compute {
156 expr: Expr,
157 },
158}
159
160#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
161pub struct Invocation {
162 pub task: String,
163 pub contract_version: String,
164 #[serde(default, skip_serializing_if = "Option::is_none")]
166 pub language: Option<String>,
167 pub input: Expr,
168 #[serde(default, skip_serializing_if = "Option::is_none")]
169 pub idempotency_key: Option<Expr>,
170 #[serde(default, skip_serializing_if = "Option::is_none")]
172 pub timeout_ms: Option<u64>,
173 #[serde(default, skip_serializing_if = "Option::is_none")]
175 pub queue_timeout_ms: Option<u64>,
176 pub retry: RetryPolicy,
177}
178
179#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
180#[serde(rename_all = "snake_case")]
181pub enum Backoff {
182 Fixed,
183 Exponential,
184}
185
186#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
187pub struct RetryPolicy {
188 pub max_attempts: u32,
190 pub backoff: Backoff,
191 pub initial_delay_ms: u64,
192 pub max_delay_ms: u64,
193 #[serde(default, skip_serializing_if = "Vec::is_empty")]
195 pub non_retryable: Vec<String>,
196}
197
198impl Default for RetryPolicy {
199 fn default() -> Self {
200 RetryPolicy {
201 max_attempts: 1,
202 backoff: Backoff::Fixed,
203 initial_delay_ms: 1000,
204 max_delay_ms: 60_000,
205 non_retryable: vec![],
206 }
207 }
208}
209
210impl RetryPolicy {
211 pub fn delay_before(&self, next_attempt: u32) -> u64 {
213 match self.backoff {
214 Backoff::Fixed => self
215 .initial_delay_ms
216 .min(self.max_delay_ms.max(self.initial_delay_ms)),
217 Backoff::Exponential => {
218 let exp = next_attempt.saturating_sub(2).min(40);
219 self.initial_delay_ms
220 .saturating_mul(1u64 << exp)
221 .min(self.max_delay_ms)
222 }
223 }
224 }
225}
226
227impl StepIr {
228 pub fn invocation(&self) -> Option<&Invocation> {
229 match &self.action {
230 Action::Task(i) | Action::Workflow(i) => Some(i),
231 Action::Sleep { .. } | Action::Await { .. } | Action::Compute { .. } => None,
232 }
233 }
234}
235
236#[derive(Debug, Clone, PartialEq, Eq)]
237pub struct IrError(pub String);
238
239impl fmt::Display for IrError {
240 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
241 f.write_str(&self.0)
242 }
243}
244
245impl std::error::Error for IrError {}
246
247impl WorkflowIr {
248 pub fn step(&self, id: &str) -> Option<&StepIr> {
249 self.steps.iter().find(|s| s.id == id)
250 }
251
252 pub fn compute_hash(&self) -> String {
254 let mut copy = self.clone();
255 copy.definition_hash = String::new();
256 copy.source_map.clear();
257 let bytes = serde_json::to_vec(©).expect("IR serialises");
258 let digest = Sha256::digest(&bytes);
259 let hex: String = digest.iter().map(|b| format!("{b:02x}")).collect();
260 format!("sha256:{hex}")
261 }
262
263 pub fn seal(mut self) -> Self {
264 self.definition_hash = self.compute_hash();
265 self
266 }
267
268 pub fn from_json(text: &str) -> Result<WorkflowIr, IrError> {
269 let raw: serde_json::Value =
272 serde_json::from_str(text).map_err(|e| IrError(format!("invalid IR JSON: {e}")))?;
273 match raw.get("ir_version").and_then(|v| v.as_str()) {
274 Some(v) if SUPPORTED_IR_VERSIONS.contains(&v) => {}
275 Some(other) => {
276 return Err(IrError(format!(
277 "unsupported IR version `{other}`; this runtime supports {}",
278 SUPPORTED_IR_VERSIONS
279 .iter()
280 .map(|v| format!("`{v}`"))
281 .collect::<Vec<_>>()
282 .join(", ")
283 )))
284 }
285 None => return Err(IrError("missing `ir_version`".into())),
286 }
287 let ir: WorkflowIr =
288 serde_json::from_value(raw).map_err(|e| IrError(format!("malformed IR: {e}")))?;
289 ir.validate()?;
290 Ok(ir)
291 }
292
293 pub fn validate(&self) -> Result<(), IrError> {
296 let e = |m: String| Err(IrError(m));
297 if !SUPPORTED_IR_VERSIONS.contains(&self.ir_version.as_str()) {
298 return e(format!("unsupported IR version `{}`", self.ir_version));
299 }
300 if self.ir_version == IR_VERSION && self.uses_v2_features() {
301 return e(format!(
302 "`{IR_VERSION}` cannot use signals, queries, `await`, `compute` or lambdas; use `{IR_VERSION_2}`"
303 ));
304 }
305 if self.name.is_empty() || self.version.is_empty() {
306 return e("workflow name and version are required".into());
307 }
308 if !matches!(self.input, Type::Record { .. }) {
309 return e("workflow input must be a record type".into());
310 }
311 let mut ids = HashSet::new();
312 for s in &self.steps {
313 if !ids.insert(s.id.as_str()) {
314 return e(format!("duplicate step id `{}`", s.id));
315 }
316 }
317 let mut seen = HashSet::new();
318 for s in &self.steps {
319 for d in &s.dependencies {
320 if !ids.contains(d.as_str()) {
321 return e(format!("step `{}` depends on unknown step `{d}`", s.id));
322 }
323 if !seen.contains(d.as_str()) {
325 return e(format!(
326 "dependency graph is cyclic or not topologically ordered at `{}` -> `{d}`",
327 s.id
328 ));
329 }
330 }
331 let mut refs = vec![];
332 if let Some(c) = &s.condition {
333 c.step_refs(&mut refs);
334 }
335 if let Some(f) = &s.for_each {
336 f.items.step_refs(&mut refs);
337 if f.max_parallel == Some(0) {
338 return e(format!("step `{}`: max_parallel must be at least 1", s.id));
339 }
340 }
341 match &s.action {
342 Action::Compute { expr } => expr.step_refs(&mut refs),
343 Action::Await { signal, .. } if !self.signals.contains_key(signal) => {
344 return e(format!(
345 "step `{}` awaits undeclared signal `{signal}`",
346 s.id
347 ))
348 }
349 _ => {}
350 }
351 if let Some(inv) = s.invocation() {
352 inv.input.step_refs(&mut refs);
353 if let Some(k) = &inv.idempotency_key {
354 k.step_refs(&mut refs);
355 }
356 }
357 let ancestors = self.ancestors(&s.id);
358 for r in &refs {
359 if !ancestors.contains(r.as_str()) {
360 return e(format!(
361 "step `{}` reads `{r}` which is not one of its dependencies",
362 s.id
363 ));
364 }
365 }
366 for inv in s.invocation().into_iter().chain(s.compensation.as_ref()) {
367 match self.contracts.get(&inv.task) {
368 None => {
369 return e(format!(
370 "step `{}` uses task `{}` with no contract",
371 s.id, inv.task
372 ))
373 }
374 Some(c) if c.version != inv.contract_version => {
375 return e(format!(
376 "step `{}` expects {}@{} but contract is {}",
377 s.id, inv.task, inv.contract_version, c.version
378 ))
379 }
380 _ => {}
381 }
382 if inv.retry.max_attempts == 0 {
383 return e(format!(
384 "step `{}`: retry attempts must be at least 1",
385 s.id
386 ));
387 }
388 }
389 seen.insert(s.id.as_str());
390 }
391 for (kind, steps) in &self.handlers {
392 if !HANDLER_KINDS.contains(&kind.as_str()) {
393 return e(format!("unknown handler kind `{kind}`"));
394 }
395 for s in steps {
396 if let Some(inv) = s.invocation() {
397 if self.contracts.get(&inv.task).map(|c| &c.version)
398 != Some(&inv.contract_version)
399 {
400 return e(format!(
401 "handler step `{}` uses task `{}` with no matching contract",
402 s.id, inv.task
403 ));
404 }
405 }
406 }
407 }
408 if !self.definition_hash.is_empty() && self.definition_hash != self.compute_hash() {
409 return e(
410 "definition_hash does not match the IR content (was the file modified?)".into(),
411 );
412 }
413 Ok(())
414 }
415
416 pub fn required_ir_version(&self) -> &'static str {
419 if self.uses_v2_features() {
420 IR_VERSION_2
421 } else {
422 IR_VERSION
423 }
424 }
425
426 pub fn handler_step(&self, kind: &str, id: &str) -> Option<&StepIr> {
428 self.handlers.get(kind)?.iter().find(|s| s.id == id)
429 }
430
431 fn uses_v2_features(&self) -> bool {
432 let lambda = |e: &Expr| e.contains_lambda();
433 !self.signals.is_empty()
434 || !self.queries.is_empty()
435 || !self.handlers.is_empty()
436 || self.result.as_ref().is_some_and(lambda)
437 || self.steps.iter().any(|s| {
438 matches!(s.action, Action::Await { .. } | Action::Compute { .. })
439 || s.condition.as_ref().is_some_and(lambda)
440 || s.for_each.as_ref().is_some_and(|f| lambda(&f.items))
441 || s.invocation()
442 .into_iter()
443 .chain(s.compensation.as_ref())
444 .any(|i| lambda(&i.input) || i.idempotency_key.as_ref().is_some_and(lambda))
445 })
446 }
447
448 pub fn ancestors(&self, id: &str) -> HashSet<&str> {
450 let by_id: HashMap<&str, &StepIr> = self.steps.iter().map(|s| (s.id.as_str(), s)).collect();
451 let mut out = HashSet::new();
452 let mut stack: Vec<&str> = by_id
453 .get(id)
454 .map(|s| s.dependencies.iter().map(String::as_str).collect())
455 .unwrap_or_default();
456 while let Some(n) = stack.pop() {
457 if out.insert(n) {
458 if let Some(s) = by_id.get(n) {
459 stack.extend(s.dependencies.iter().map(String::as_str));
460 }
461 }
462 }
463 out
464 }
465}