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)]
50 pub source_map: BTreeMap<String, SourceLocation>,
51}
52
53#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
56pub struct QueryIr {
57 pub expr: Expr,
58 pub output_type: Type,
59}
60
61#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
62pub struct SourceLocation {
63 pub file: String,
64 pub line: usize,
65 pub column: usize,
66}
67
68#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
69pub struct TaskContract {
70 pub name: String,
71 pub version: String,
72 pub input: Type,
73 pub output: Type,
74 #[serde(default, skip_serializing_if = "std::ops::Not::not")]
76 pub builtin: bool,
77 #[serde(default, skip_serializing_if = "Option::is_none")]
81 pub workflow_hash: Option<String>,
82 #[serde(default, skip_serializing_if = "Option::is_none")]
85 pub compensated_by: Option<String>,
86}
87
88pub const WORKFLOW_CONTRACT_PREFIX: &str = "workflow:";
90
91#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
93pub struct ForEach {
94 pub variable: String,
95 pub items: Expr,
96 #[serde(default, skip_serializing_if = "Option::is_none")]
97 pub max_parallel: Option<u32>,
98}
99
100#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
101pub struct StepIr {
102 pub id: String,
103 pub action: Action,
104 pub dependencies: Vec<String>,
106 #[serde(default, skip_serializing_if = "Option::is_none")]
107 pub condition: Option<Expr>,
108 #[serde(default, skip_serializing_if = "Option::is_none")]
109 pub for_each: Option<ForEach>,
110 #[serde(default, skip_serializing_if = "Option::is_none")]
111 pub compensation: Option<Invocation>,
112 pub output_type: Type,
114}
115
116#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
117#[serde(tag = "type", rename_all = "snake_case")]
118pub enum Action {
119 Task(Invocation),
120 Sleep {
122 duration_ms: u64,
123 },
124 Workflow(Invocation),
127 Await {
130 signal: String,
131 #[serde(default, skip_serializing_if = "Option::is_none")]
132 timeout_ms: Option<u64>,
133 },
134 Compute {
136 expr: Expr,
137 },
138}
139
140#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
141pub struct Invocation {
142 pub task: String,
143 pub contract_version: String,
144 #[serde(default, skip_serializing_if = "Option::is_none")]
146 pub language: Option<String>,
147 pub input: Expr,
148 #[serde(default, skip_serializing_if = "Option::is_none")]
149 pub idempotency_key: Option<Expr>,
150 #[serde(default, skip_serializing_if = "Option::is_none")]
152 pub timeout_ms: Option<u64>,
153 #[serde(default, skip_serializing_if = "Option::is_none")]
155 pub queue_timeout_ms: Option<u64>,
156 pub retry: RetryPolicy,
157}
158
159#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
160#[serde(rename_all = "snake_case")]
161pub enum Backoff {
162 Fixed,
163 Exponential,
164}
165
166#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
167pub struct RetryPolicy {
168 pub max_attempts: u32,
170 pub backoff: Backoff,
171 pub initial_delay_ms: u64,
172 pub max_delay_ms: u64,
173 #[serde(default, skip_serializing_if = "Vec::is_empty")]
175 pub non_retryable: Vec<String>,
176}
177
178impl Default for RetryPolicy {
179 fn default() -> Self {
180 RetryPolicy {
181 max_attempts: 1,
182 backoff: Backoff::Fixed,
183 initial_delay_ms: 1000,
184 max_delay_ms: 60_000,
185 non_retryable: vec![],
186 }
187 }
188}
189
190impl RetryPolicy {
191 pub fn delay_before(&self, next_attempt: u32) -> u64 {
193 match self.backoff {
194 Backoff::Fixed => self
195 .initial_delay_ms
196 .min(self.max_delay_ms.max(self.initial_delay_ms)),
197 Backoff::Exponential => {
198 let exp = next_attempt.saturating_sub(2).min(40);
199 self.initial_delay_ms
200 .saturating_mul(1u64 << exp)
201 .min(self.max_delay_ms)
202 }
203 }
204 }
205}
206
207impl StepIr {
208 pub fn invocation(&self) -> Option<&Invocation> {
209 match &self.action {
210 Action::Task(i) | Action::Workflow(i) => Some(i),
211 Action::Sleep { .. } | Action::Await { .. } | Action::Compute { .. } => None,
212 }
213 }
214}
215
216#[derive(Debug, Clone, PartialEq, Eq)]
217pub struct IrError(pub String);
218
219impl fmt::Display for IrError {
220 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
221 f.write_str(&self.0)
222 }
223}
224
225impl std::error::Error for IrError {}
226
227impl WorkflowIr {
228 pub fn step(&self, id: &str) -> Option<&StepIr> {
229 self.steps.iter().find(|s| s.id == id)
230 }
231
232 pub fn compute_hash(&self) -> String {
234 let mut copy = self.clone();
235 copy.definition_hash = String::new();
236 copy.source_map.clear();
237 let bytes = serde_json::to_vec(©).expect("IR serialises");
238 let digest = Sha256::digest(&bytes);
239 let hex: String = digest.iter().map(|b| format!("{b:02x}")).collect();
240 format!("sha256:{hex}")
241 }
242
243 pub fn seal(mut self) -> Self {
244 self.definition_hash = self.compute_hash();
245 self
246 }
247
248 pub fn from_json(text: &str) -> Result<WorkflowIr, IrError> {
249 let raw: serde_json::Value =
252 serde_json::from_str(text).map_err(|e| IrError(format!("invalid IR JSON: {e}")))?;
253 match raw.get("ir_version").and_then(|v| v.as_str()) {
254 Some(v) if SUPPORTED_IR_VERSIONS.contains(&v) => {}
255 Some(other) => {
256 return Err(IrError(format!(
257 "unsupported IR version `{other}`; this runtime supports {}",
258 SUPPORTED_IR_VERSIONS
259 .iter()
260 .map(|v| format!("`{v}`"))
261 .collect::<Vec<_>>()
262 .join(", ")
263 )))
264 }
265 None => return Err(IrError("missing `ir_version`".into())),
266 }
267 let ir: WorkflowIr =
268 serde_json::from_value(raw).map_err(|e| IrError(format!("malformed IR: {e}")))?;
269 ir.validate()?;
270 Ok(ir)
271 }
272
273 pub fn validate(&self) -> Result<(), IrError> {
276 let e = |m: String| Err(IrError(m));
277 if !SUPPORTED_IR_VERSIONS.contains(&self.ir_version.as_str()) {
278 return e(format!("unsupported IR version `{}`", self.ir_version));
279 }
280 if self.ir_version == IR_VERSION && self.uses_v2_features() {
281 return e(format!(
282 "`{IR_VERSION}` cannot use signals, queries, `await`, `compute` or lambdas; use `{IR_VERSION_2}`"
283 ));
284 }
285 if self.name.is_empty() || self.version.is_empty() {
286 return e("workflow name and version are required".into());
287 }
288 if !matches!(self.input, Type::Record { .. }) {
289 return e("workflow input must be a record type".into());
290 }
291 let mut ids = HashSet::new();
292 for s in &self.steps {
293 if !ids.insert(s.id.as_str()) {
294 return e(format!("duplicate step id `{}`", s.id));
295 }
296 }
297 let mut seen = HashSet::new();
298 for s in &self.steps {
299 for d in &s.dependencies {
300 if !ids.contains(d.as_str()) {
301 return e(format!("step `{}` depends on unknown step `{d}`", s.id));
302 }
303 if !seen.contains(d.as_str()) {
305 return e(format!(
306 "dependency graph is cyclic or not topologically ordered at `{}` -> `{d}`",
307 s.id
308 ));
309 }
310 }
311 let mut refs = vec![];
312 if let Some(c) = &s.condition {
313 c.step_refs(&mut refs);
314 }
315 if let Some(f) = &s.for_each {
316 f.items.step_refs(&mut refs);
317 if f.max_parallel == Some(0) {
318 return e(format!("step `{}`: max_parallel must be at least 1", s.id));
319 }
320 }
321 match &s.action {
322 Action::Compute { expr } => expr.step_refs(&mut refs),
323 Action::Await { signal, .. } if !self.signals.contains_key(signal) => {
324 return e(format!(
325 "step `{}` awaits undeclared signal `{signal}`",
326 s.id
327 ))
328 }
329 _ => {}
330 }
331 if let Some(inv) = s.invocation() {
332 inv.input.step_refs(&mut refs);
333 if let Some(k) = &inv.idempotency_key {
334 k.step_refs(&mut refs);
335 }
336 }
337 let ancestors = self.ancestors(&s.id);
338 for r in &refs {
339 if !ancestors.contains(r.as_str()) {
340 return e(format!(
341 "step `{}` reads `{r}` which is not one of its dependencies",
342 s.id
343 ));
344 }
345 }
346 for inv in s.invocation().into_iter().chain(s.compensation.as_ref()) {
347 match self.contracts.get(&inv.task) {
348 None => {
349 return e(format!(
350 "step `{}` uses task `{}` with no contract",
351 s.id, inv.task
352 ))
353 }
354 Some(c) if c.version != inv.contract_version => {
355 return e(format!(
356 "step `{}` expects {}@{} but contract is {}",
357 s.id, inv.task, inv.contract_version, c.version
358 ))
359 }
360 _ => {}
361 }
362 if inv.retry.max_attempts == 0 {
363 return e(format!(
364 "step `{}`: retry attempts must be at least 1",
365 s.id
366 ));
367 }
368 }
369 seen.insert(s.id.as_str());
370 }
371 if !self.definition_hash.is_empty() && self.definition_hash != self.compute_hash() {
372 return e(
373 "definition_hash does not match the IR content (was the file modified?)".into(),
374 );
375 }
376 Ok(())
377 }
378
379 pub fn required_ir_version(&self) -> &'static str {
382 if self.uses_v2_features() {
383 IR_VERSION_2
384 } else {
385 IR_VERSION
386 }
387 }
388
389 fn uses_v2_features(&self) -> bool {
390 let lambda = |e: &Expr| e.contains_lambda();
391 !self.signals.is_empty()
392 || !self.queries.is_empty()
393 || self.result.as_ref().is_some_and(lambda)
394 || self.steps.iter().any(|s| {
395 matches!(s.action, Action::Await { .. } | Action::Compute { .. })
396 || s.condition.as_ref().is_some_and(lambda)
397 || s.for_each.as_ref().is_some_and(|f| lambda(&f.items))
398 || s.invocation()
399 .into_iter()
400 .chain(s.compensation.as_ref())
401 .any(|i| lambda(&i.input) || i.idempotency_key.as_ref().is_some_and(lambda))
402 })
403 }
404
405 pub fn ancestors(&self, id: &str) -> HashSet<&str> {
407 let by_id: HashMap<&str, &StepIr> = self.steps.iter().map(|s| (s.id.as_str(), s)).collect();
408 let mut out = HashSet::new();
409 let mut stack: Vec<&str> = by_id
410 .get(id)
411 .map(|s| s.dependencies.iter().map(String::as_str).collect())
412 .unwrap_or_default();
413 while let Some(n) = stack.pop() {
414 if out.insert(n) {
415 if let Some(s) = by_id.get(n) {
416 stack.extend(s.dependencies.iter().map(String::as_str));
417 }
418 }
419 }
420 out
421 }
422}