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    /// Source locations for diagnostics and tooling (not hashed).
49    #[serde(default)]
50    pub source_map: BTreeMap<String, SourceLocation>,
51}
52
53/// `query <name> = <expr>`: evaluated on demand against the current state.
54/// Step outputs read by a query are optional (the step may not have run yet).
55#[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    /// True for tasks executed inside the runtime (e.g. `orbit.http.request`).
75    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
76    pub builtin: bool,
77    /// Set when this contract is a child workflow (`workflow "Name"` steps): the
78    /// definition hash of the exact child version to start. The contract name is
79    /// then `workflow:<Name>`.
80    #[serde(default, skip_serializing_if = "Option::is_none")]
81    pub workflow_hash: Option<String>,
82    /// `compensated_by "<task>"`: steps calling this task must declare a
83    /// compensation that calls the named task (checked by the compiler).
84    #[serde(default, skip_serializing_if = "Option::is_none")]
85    pub compensated_by: Option<String>,
86}
87
88/// Prefix of contract names that refer to child workflows.
89pub const WORKFLOW_CONTRACT_PREFIX: &str = "workflow:";
90
91/// `for <variable> in <items>`: the step runs once per list element.
92#[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    /// Direct dependencies, sorted. Explicit `after` plus data references.
105    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    /// The type other expressions see when they reference this step.
113    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    /// Durable timer handled by the runtime.
121    Sleep {
122        duration_ms: u64,
123    },
124    /// Start a child workflow. `task` is `workflow:<Name>`; its contract carries
125    /// the child's definition hash.
126    Workflow(Invocation),
127    /// Wait for the next signal of this name; its payload is the step output.
128    /// `timeout_ms` fails the step with `SIGNAL_TIMEOUT` if no signal arrives.
129    Await {
130        signal: String,
131        #[serde(default, skip_serializing_if = "Option::is_none")]
132        timeout_ms: Option<u64>,
133    },
134    /// Evaluate a pure expression in the runtime; the value is the step output.
135    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    /// Optional routing constraint: only workers announcing this runtime receive the task.
145    #[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    /// Start-to-close limit for one attempt.
151    #[serde(default, skip_serializing_if = "Option::is_none")]
152    pub timeout_ms: Option<u64>,
153    /// Maximum time the task may wait in the queue before a worker picks it up.
154    #[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    /// Maximum total attempts, including the first.
169    pub max_attempts: u32,
170    pub backoff: Backoff,
171    pub initial_delay_ms: u64,
172    pub max_delay_ms: u64,
173    /// Error codes that fail the step immediately.
174    #[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    /// Delay before attempt `next_attempt` (2 = first retry).
192    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    /// Canonical hash of the semantic content of the workflow.
233    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(&copy).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        // Check the version before attempting a full parse so that future IR
250        // versions produce a clear error instead of a confusing schema error.
251        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    /// Enforce the IR invariants from RFC-0001 ยง7.3. The runtime calls this on
274    /// every definition it accepts, so a hand-edited IR cannot bypass them.
275    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                // Steps are in topological order, so dependencies must already be seen.
304                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    /// The IR version this workflow needs: `orbit-ir/2` when it uses any
380    /// feature introduced with it, `orbit-ir/1` otherwise.
381    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    /// Transitive dependencies of a step.
406    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}