Skip to main content

orbit_ir/
workflow.rs

1//! The compiled workflow document (`orbit-ir/1`).
2//!
3//! The IR is the contract between compiler and runtime. It is fully resolved:
4//! named schemas are inlined, step dependencies are explicit (including those
5//! implied by data references), and every expression is typed and checked.
6
7use 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";
15/// IR version for workflows that use signals, queries, `await` or `compute`
16/// steps, or lambdas. Workflows that use none of these keep `orbit-ir/1` (and
17/// their definition hashes), so existing deployments are unaffected.
18pub const IR_VERSION_2: &str = "orbit-ir/2";
19/// Every IR version this crate reads and validates.
20pub 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    /// `sha256:<hex>` over the semantic content (excludes `source_map`).
30    #[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    /// Steps in a deterministic topological order.
37    pub steps: Vec<StepIr>,
38    #[serde(default, skip_serializing_if = "Option::is_none")]
39    pub result: Option<Expr>,
40    /// Every worker contract referenced by this workflow.
41    pub contracts: BTreeMap<String, TaskContract>,
42    /// Typed signals this workflow accepts (`signal <name> { ... }`), by name.
43    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
44    pub signals: BTreeMap<String, Type>,
45    /// Read-only queries over the execution state (`query <name> = <expr>`).
46    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
47    pub queries: BTreeMap<String, QueryIr>,
48    /// `on failure|cancel|timeout { ... }`: steps run after compensation when
49    /// the execution fails, is cancelled or times out. Keyed by kind; each list
50    /// is in topological order. Unit keys are `on_<kind>:<step>`.
51    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
52    pub handlers: BTreeMap<String, Vec<StepIr>>,
53    /// Source locations for diagnostics and tooling (not hashed).
54    #[serde(default)]
55    pub source_map: BTreeMap<String, SourceLocation>,
56}
57
58/// `query <name> = <expr>`: evaluated on demand against the current state.
59/// Step outputs read by a query are optional (the step may not have run yet).
60#[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    /// True for tasks executed inside the runtime (e.g. `orbit.http.request`).
80    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
81    pub builtin: bool,
82    /// Set when this contract is a child workflow (`workflow "Name"` steps): the
83    /// definition hash of the exact child version to start. The contract name is
84    /// then `workflow:<Name>`.
85    #[serde(default, skip_serializing_if = "Option::is_none")]
86    pub workflow_hash: Option<String>,
87    /// `compensated_by "<task>"`: steps calling this task must declare a
88    /// compensation that calls the named task (checked by the compiler).
89    #[serde(default, skip_serializing_if = "Option::is_none")]
90    pub compensated_by: Option<String>,
91}
92
93/// Handler kinds, in the order `on <kind>` accepts them.
94pub const HANDLER_KINDS: &[&str] = &["failure", "cancel", "timeout"];
95
96/// Unit key of a handler step: `on_<kind>:<step>`.
97pub fn handler_key(kind: &str, step: &str) -> String {
98    format!("on_{kind}:{step}")
99}
100
101/// `(kind, step)` for a handler unit key.
102pub 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
108/// Prefix of contract names that refer to child workflows.
109pub const WORKFLOW_CONTRACT_PREFIX: &str = "workflow:";
110
111/// `for <variable> in <items>`: the step runs once per list element.
112#[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    /// Direct dependencies, sorted. Explicit `after` plus data references.
125    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    /// The type other expressions see when they reference this step.
133    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    /// Durable timer handled by the runtime.
141    Sleep {
142        duration_ms: u64,
143    },
144    /// Start a child workflow. `task` is `workflow:<Name>`; its contract carries
145    /// the child's definition hash.
146    Workflow(Invocation),
147    /// Wait for the next signal of this name; its payload is the step output.
148    /// `timeout_ms` fails the step with `SIGNAL_TIMEOUT` if no signal arrives.
149    Await {
150        signal: String,
151        #[serde(default, skip_serializing_if = "Option::is_none")]
152        timeout_ms: Option<u64>,
153    },
154    /// Evaluate a pure expression in the runtime; the value is the step output.
155    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    /// Optional routing constraint: only workers announcing this runtime receive the task.
165    #[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    /// Start-to-close limit for one attempt.
171    #[serde(default, skip_serializing_if = "Option::is_none")]
172    pub timeout_ms: Option<u64>,
173    /// Maximum time the task may wait in the queue before a worker picks it up.
174    #[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    /// Maximum total attempts, including the first.
189    pub max_attempts: u32,
190    pub backoff: Backoff,
191    pub initial_delay_ms: u64,
192    pub max_delay_ms: u64,
193    /// Error codes that fail the step immediately.
194    #[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    /// Delay before attempt `next_attempt` (2 = first retry).
212    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    /// Canonical hash of the semantic content of the workflow.
253    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(&copy).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        // Check the version before attempting a full parse so that future IR
270        // versions produce a clear error instead of a confusing schema error.
271        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    /// Enforce the IR invariants from RFC-0001 ยง7.3. The runtime calls this on
294    /// every definition it accepts, so a hand-edited IR cannot bypass them.
295    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                // Steps are in topological order, so dependencies must already be seen.
324                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    /// The IR version this workflow needs: `orbit-ir/2` when it uses any
417    /// feature introduced with it, `orbit-ir/1` otherwise.
418    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    /// A handler step by kind and id.
427    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    /// Transitive dependencies of a step.
449    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}