use crate::expr::Expr;
use crate::types::Type;
use serde::{Deserialize, Serialize};
use sha2::{Digest, Sha256};
use std::collections::{BTreeMap, HashMap, HashSet};
use std::fmt;
pub const IR_VERSION: &str = "orbit-ir/1";
pub const IR_VERSION_2: &str = "orbit-ir/2";
pub const SUPPORTED_IR_VERSIONS: &[&str] = &[IR_VERSION, IR_VERSION_2];
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct WorkflowIr {
pub ir_version: String,
pub name: String,
pub version: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub description: Option<String>,
#[serde(default)]
pub definition_hash: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub timeout_ms: Option<u64>,
pub input: Type,
pub output: Type,
pub steps: Vec<StepIr>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub result: Option<Expr>,
pub contracts: BTreeMap<String, TaskContract>,
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
pub signals: BTreeMap<String, Type>,
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
pub queries: BTreeMap<String, QueryIr>,
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
pub handlers: BTreeMap<String, Vec<StepIr>>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub limits: Option<WorkflowLimits>,
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
pub events: BTreeMap<String, Vec<StepIr>>,
#[serde(default)]
pub source_map: BTreeMap<String, SourceLocation>,
}
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct WorkflowLimits {
#[serde(default, skip_serializing_if = "Option::is_none")]
pub max_fan_out: Option<u64>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub max_history_events: Option<u64>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub max_payload_bytes: Option<u64>,
}
pub const WORKFLOW_LIMITS: &[&str] = &["max_fan_out", "max_history_events", "max_payload_bytes"];
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct QueryIr {
pub expr: Expr,
pub output_type: Type,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SourceLocation {
pub file: String,
pub line: usize,
pub column: usize,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct TaskContract {
pub name: String,
pub version: String,
pub input: Type,
pub output: Type,
#[serde(default, skip_serializing_if = "std::ops::Not::not")]
pub builtin: bool,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub workflow_hash: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub compensated_by: Option<String>,
}
pub const HANDLER_KINDS: &[&str] = &["failure", "cancel", "timeout"];
pub fn handler_key(kind: &str, step: &str) -> String {
format!("on_{kind}:{step}")
}
pub fn event_instance_key(signal: &str, seq: u64) -> String {
format!("on_event:{signal}@{seq}")
}
pub fn parse_event_key(key: &str) -> Option<(&str, &str, &str)> {
let rest = key.strip_prefix("on_event:")?;
let (head, step) = rest.split_once(':')?;
let (signal, seq) = head.split_once('@')?;
seq.parse::<u64>().ok()?;
let instance = &key[..key.len() - step.len() - 1];
Some((instance, signal, step))
}
pub fn parse_handler_key(key: &str) -> Option<(&str, &str)> {
let rest = key.strip_prefix("on_")?;
let (kind, step) = rest.split_once(':')?;
HANDLER_KINDS.contains(&kind).then_some((kind, step))
}
pub const WORKFLOW_CONTRACT_PREFIX: &str = "workflow:";
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ForEach {
pub variable: String,
pub items: Expr,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub max_parallel: Option<u32>,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct StepIr {
pub id: String,
pub action: Action,
pub dependencies: Vec<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub condition: Option<Expr>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub for_each: Option<ForEach>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub compensation: Option<Invocation>,
pub output_type: Type,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum Action {
Task(Invocation),
Sleep {
duration_ms: u64,
},
Workflow(Invocation),
Await {
signal: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
timeout_ms: Option<u64>,
},
Compute {
expr: Expr,
},
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Invocation {
pub task: String,
pub contract_version: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub language: Option<String>,
pub input: Expr,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub idempotency_key: Option<Expr>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub timeout_ms: Option<u64>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub queue_timeout_ms: Option<u64>,
pub retry: RetryPolicy,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Backoff {
Fixed,
Exponential,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct RetryPolicy {
pub max_attempts: u32,
pub backoff: Backoff,
pub initial_delay_ms: u64,
pub max_delay_ms: u64,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub non_retryable: Vec<String>,
}
impl Default for RetryPolicy {
fn default() -> Self {
RetryPolicy {
max_attempts: 1,
backoff: Backoff::Fixed,
initial_delay_ms: 1000,
max_delay_ms: 60_000,
non_retryable: vec![],
}
}
}
impl RetryPolicy {
pub fn delay_before(&self, next_attempt: u32) -> u64 {
match self.backoff {
Backoff::Fixed => self
.initial_delay_ms
.min(self.max_delay_ms.max(self.initial_delay_ms)),
Backoff::Exponential => {
let exp = next_attempt.saturating_sub(2).min(40);
self.initial_delay_ms
.saturating_mul(1u64 << exp)
.min(self.max_delay_ms)
}
}
}
}
impl StepIr {
pub fn invocation(&self) -> Option<&Invocation> {
match &self.action {
Action::Task(i) | Action::Workflow(i) => Some(i),
Action::Sleep { .. } | Action::Await { .. } | Action::Compute { .. } => None,
}
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct IrError(pub String);
impl fmt::Display for IrError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(&self.0)
}
}
impl std::error::Error for IrError {}
impl WorkflowIr {
pub fn step(&self, id: &str) -> Option<&StepIr> {
self.steps.iter().find(|s| s.id == id)
}
pub fn compute_hash(&self) -> String {
let mut copy = self.clone();
copy.definition_hash = String::new();
copy.source_map.clear();
let bytes = serde_json::to_vec(©).expect("IR serialises");
let digest = Sha256::digest(&bytes);
let hex: String = digest.iter().map(|b| format!("{b:02x}")).collect();
format!("sha256:{hex}")
}
pub fn seal(mut self) -> Self {
self.definition_hash = self.compute_hash();
self
}
pub fn from_json(text: &str) -> Result<WorkflowIr, IrError> {
let raw: serde_json::Value =
serde_json::from_str(text).map_err(|e| IrError(format!("invalid IR JSON: {e}")))?;
match raw.get("ir_version").and_then(|v| v.as_str()) {
Some(v) if SUPPORTED_IR_VERSIONS.contains(&v) => {}
Some(other) => {
return Err(IrError(format!(
"unsupported IR version `{other}`; this runtime supports {}",
SUPPORTED_IR_VERSIONS
.iter()
.map(|v| format!("`{v}`"))
.collect::<Vec<_>>()
.join(", ")
)))
}
None => return Err(IrError("missing `ir_version`".into())),
}
let ir: WorkflowIr =
serde_json::from_value(raw).map_err(|e| IrError(format!("malformed IR: {e}")))?;
ir.validate()?;
Ok(ir)
}
pub fn validate(&self) -> Result<(), IrError> {
let e = |m: String| Err(IrError(m));
if !SUPPORTED_IR_VERSIONS.contains(&self.ir_version.as_str()) {
return e(format!("unsupported IR version `{}`", self.ir_version));
}
if self.ir_version == IR_VERSION && self.uses_v2_features() {
return e(format!(
"`{IR_VERSION}` cannot use signals, queries, `await`, `compute` or lambdas; use `{IR_VERSION_2}`"
));
}
if self.name.is_empty() || self.version.is_empty() {
return e("workflow name and version are required".into());
}
if !matches!(self.input, Type::Record { .. }) {
return e("workflow input must be a record type".into());
}
let mut ids = HashSet::new();
for s in &self.steps {
if !ids.insert(s.id.as_str()) {
return e(format!("duplicate step id `{}`", s.id));
}
}
let mut seen = HashSet::new();
for s in &self.steps {
for d in &s.dependencies {
if !ids.contains(d.as_str()) {
return e(format!("step `{}` depends on unknown step `{d}`", s.id));
}
if !seen.contains(d.as_str()) {
return e(format!(
"dependency graph is cyclic or not topologically ordered at `{}` -> `{d}`",
s.id
));
}
}
let mut refs = vec![];
if let Some(c) = &s.condition {
c.step_refs(&mut refs);
}
if let Some(f) = &s.for_each {
f.items.step_refs(&mut refs);
if f.max_parallel == Some(0) {
return e(format!("step `{}`: max_parallel must be at least 1", s.id));
}
}
match &s.action {
Action::Compute { expr } => expr.step_refs(&mut refs),
Action::Await { signal, .. } if !self.signals.contains_key(signal) => {
return e(format!(
"step `{}` awaits undeclared signal `{signal}`",
s.id
))
}
_ => {}
}
if let Some(inv) = s.invocation() {
inv.input.step_refs(&mut refs);
if let Some(k) = &inv.idempotency_key {
k.step_refs(&mut refs);
}
}
let ancestors = self.ancestors(&s.id);
for r in &refs {
if !ancestors.contains(r.as_str()) {
return e(format!(
"step `{}` reads `{r}` which is not one of its dependencies",
s.id
));
}
}
for inv in s.invocation().into_iter().chain(s.compensation.as_ref()) {
match self.contracts.get(&inv.task) {
None => {
return e(format!(
"step `{}` uses task `{}` with no contract",
s.id, inv.task
))
}
Some(c) if c.version != inv.contract_version => {
return e(format!(
"step `{}` expects {}@{} but contract is {}",
s.id, inv.task, inv.contract_version, c.version
))
}
_ => {}
}
if inv.retry.max_attempts == 0 {
return e(format!(
"step `{}`: retry attempts must be at least 1",
s.id
));
}
}
seen.insert(s.id.as_str());
}
for (kind, steps) in &self.handlers {
if !HANDLER_KINDS.contains(&kind.as_str()) {
return e(format!("unknown handler kind `{kind}`"));
}
for s in steps {
if let Some(inv) = s.invocation() {
if self.contracts.get(&inv.task).map(|c| &c.version)
!= Some(&inv.contract_version)
{
return e(format!(
"handler step `{}` uses task `{}` with no matching contract",
s.id, inv.task
));
}
}
}
}
if !self.definition_hash.is_empty() && self.definition_hash != self.compute_hash() {
return e(
"definition_hash does not match the IR content (was the file modified?)".into(),
);
}
Ok(())
}
pub fn required_ir_version(&self) -> &'static str {
if self.uses_v2_features() {
IR_VERSION_2
} else {
IR_VERSION
}
}
pub fn event_step(&self, signal: &str, id: &str) -> Option<&StepIr> {
self.events.get(signal)?.iter().find(|s| s.id == id)
}
pub fn handler_step(&self, kind: &str, id: &str) -> Option<&StepIr> {
self.handlers.get(kind)?.iter().find(|s| s.id == id)
}
fn uses_v2_features(&self) -> bool {
let lambda = |e: &Expr| e.contains_lambda();
!self.signals.is_empty()
|| !self.queries.is_empty()
|| !self.handlers.is_empty()
|| self.limits.is_some()
|| !self.events.is_empty()
|| self.result.as_ref().is_some_and(lambda)
|| self.steps.iter().any(|s| {
matches!(s.action, Action::Await { .. } | Action::Compute { .. })
|| s.condition.as_ref().is_some_and(lambda)
|| s.for_each.as_ref().is_some_and(|f| lambda(&f.items))
|| s.invocation()
.into_iter()
.chain(s.compensation.as_ref())
.any(|i| lambda(&i.input) || i.idempotency_key.as_ref().is_some_and(lambda))
})
}
pub fn ancestors(&self, id: &str) -> HashSet<&str> {
let by_id: HashMap<&str, &StepIr> = self.steps.iter().map(|s| (s.id.as_str(), s)).collect();
let mut out = HashSet::new();
let mut stack: Vec<&str> = by_id
.get(id)
.map(|s| s.dependencies.iter().map(String::as_str).collect())
.unwrap_or_default();
while let Some(n) = stack.pop() {
if out.insert(n) {
if let Some(s) = by_id.get(n) {
stack.extend(s.dependencies.iter().map(String::as_str));
}
}
}
out
}
}