1use indexmap::IndexMap;
39use serde::{Deserialize, Serialize};
40
41use crate::source_map::DocPath;
42use crate::validate::{Diagnostic, suggest};
43use crate::value::{Value, ValueType};
44
45pub const FORMAT_VERSION: &str = "1";
47
48#[derive(Debug, thiserror::Error)]
50#[non_exhaustive]
51pub enum DocumentError {
52 #[error("invalid JSON workflow document: {0}")]
53 Json(#[from] serde_json::Error),
54 #[error("invalid YAML workflow document: {0}")]
57 Yaml(String),
58 #[error("invalid node `{id}`: {message}")]
59 Node { id: String, message: String },
60 #[error("{path}: {message}")]
62 Field { path: String, message: String },
63}
64
65#[derive(Clone, Debug, Default, Serialize)]
67pub struct Workflow {
68 pub version: String,
70 pub name: Option<String>,
71 pub description: Option<String>,
72 pub env: Vec<VariableDecl>,
74 pub conversation: Vec<VariableDecl>,
76 pub graph: GraphDoc,
77}
78
79#[derive(Clone, Debug, Serialize, Deserialize)]
81pub struct VariableDecl {
82 pub name: String,
83 #[serde(rename = "type", alias = "value_type", default = "any_type")]
84 pub ty: ValueType,
85 #[serde(default)]
86 pub value: Option<Value>,
87 #[serde(default)]
88 pub description: Option<String>,
89}
90
91fn any_type() -> ValueType {
92 ValueType::Any
93}
94
95#[derive(Clone, Debug, Default, Serialize)]
97pub struct GraphDoc {
98 pub nodes: Vec<NodeDoc>,
99 pub edges: Vec<EdgeDoc>,
100}
101
102#[derive(Clone, Debug)]
108pub struct NodeDoc {
109 pub id: String,
110 pub kind: String,
112 pub title: Option<String>,
113 pub parent: Option<String>,
115 pub policy: NodePolicy,
116 pub config: serde_json::Map<String, serde_json::Value>,
118 pub strict: bool,
122}
123
124impl NodeDoc {
125 pub fn new(id: impl Into<String>, kind: impl Into<String>, config: serde_json::Value) -> Self {
127 let config = match config {
128 serde_json::Value::Object(map) => map,
129 _ => serde_json::Map::new(),
130 };
131 Self {
132 id: id.into(),
133 kind: kind.into(),
134 title: None,
135 parent: None,
136 policy: NodePolicy::default(),
137 config,
138 strict: true,
139 }
140 }
141
142 pub fn with_parent(mut self, parent: impl Into<String>) -> Self {
144 self.parent = Some(parent.into());
145 self
146 }
147
148 pub fn with_policy(mut self, policy: NodePolicy) -> Self {
150 self.policy = policy;
151 self
152 }
153
154 pub fn parse_config<T: serde::de::DeserializeOwned>(&self) -> Result<T, DocumentError> {
156 parse_config_at(&self.config)
157 .map_err(|(path, e)| DocumentError::Node { id: self.id.clone(), message: with_field(&path, &e) })
158 }
159
160 pub fn label(&self) -> &str {
162 self.title.as_deref().unwrap_or(&self.id)
163 }
164}
165
166pub(crate) fn parse_config_at<T: serde::de::DeserializeOwned>(
169 config: &serde_json::Map<String, serde_json::Value>,
170) -> Result<T, (String, serde_json::Error)> {
171 let value = serde_json::Value::Object(config.clone());
172 serde_path_to_error::deserialize(value).map_err(|e| (e.path().to_string(), e.into_inner()))
173}
174
175fn with_field(path: &str, error: &serde_json::Error) -> String {
176 if path == "." { error.to_string() } else { format!("{path}: {error}") }
177}
178
179#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
181pub struct NodePolicy {
182 #[serde(default)]
183 pub on_error: ErrorStrategy,
184 #[serde(default)]
185 pub retry: RetryPolicy,
186 #[serde(default)]
188 pub timeout_ms: Option<u64>,
189}
190
191#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
193#[serde(tag = "strategy", rename_all = "kebab-case")]
194#[non_exhaustive]
195pub enum ErrorStrategy {
196 #[default]
198 Fail,
199 FailBranch,
202 DefaultValue {
204 #[serde(default)]
205 values: IndexMap<String, Value>,
206 },
207}
208
209#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
211pub struct RetryPolicy {
212 #[serde(default)]
213 pub max_retries: u32,
214 #[serde(default)]
216 pub interval_ms: u64,
217 #[serde(default = "one")]
219 pub backoff: f64,
220}
221
222fn one() -> f64 {
223 1.0
224}
225
226impl Default for RetryPolicy {
227 fn default() -> Self {
228 Self { max_retries: 0, interval_ms: 0, backoff: 1.0 }
229 }
230}
231
232impl RetryPolicy {
233 pub fn delay_ms(&self, attempt: u32) -> u64 {
235 let factor = self.backoff.max(1.0).powi(i32::try_from(attempt.saturating_sub(1)).unwrap_or(i32::MAX));
236 #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss, clippy::cast_precision_loss)]
237 let ms = (self.interval_ms as f64 * factor).min(3_600_000.0) as u64;
238 ms
239 }
240}
241
242#[derive(Clone, Debug, Serialize, Deserialize)]
244pub struct EdgeDoc {
245 #[serde(default)]
246 pub id: Option<String>,
247 pub source: String,
248 pub target: String,
249 #[serde(default, alias = "sourceHandle", alias = "source_handle", skip_serializing_if = "Option::is_none")]
250 pub handle: Option<String>,
251}
252
253impl EdgeDoc {
254 pub fn new(source: impl Into<String>, target: impl Into<String>) -> Self {
255 Self { id: None, source: source.into(), target: target.into(), handle: None }
256 }
257
258 pub fn with_handle(mut self, handle: impl Into<String>) -> Self {
259 self.handle = Some(handle.into());
260 self
261 }
262}
263
264impl Workflow {
265 pub fn from_json(text: &str) -> Result<Self, DocumentError> {
267 let raw: serde_json::Value = serde_json::from_str(text)?;
268 Self::from_value(raw)
269 }
270
271 #[cfg(feature = "yaml")]
273 pub fn from_yaml(text: &str) -> Result<Self, DocumentError> {
274 let options = serde_saphyr::options! { strict_booleans: true };
276 let raw: serde_json::Value =
277 serde_saphyr::from_str_with_options(text, options).map_err(|e| DocumentError::Yaml(e.to_string()))?;
278 Self::from_value(raw)
279 }
280
281 pub fn parse(text: &str) -> Result<Self, DocumentError> {
283 let first = text.trim_start().chars().next();
284 if matches!(first, Some('{')) {
285 return Self::from_json(text);
286 }
287 #[cfg(feature = "yaml")]
288 {
289 Self::from_yaml(text)
290 }
291 #[cfg(not(feature = "yaml"))]
292 {
293 Self::from_json(text)
294 }
295 }
296
297 pub fn from_value(raw: serde_json::Value) -> Result<Self, DocumentError> {
300 let decoded = decode(raw);
301 match decoded.diagnostics.into_iter().find(Diagnostic::is_error) {
302 None => Ok(decoded.workflow),
303 Some(d) => {
304 let message = match &d.suggestion {
305 Some(s) => format!("{}; did you mean `{s}`?", d.message),
306 None => d.message,
307 };
308 Err(match d.node {
309 Some(id) => DocumentError::Node { id, message },
310 None => DocumentError::Field { path: d.path.to_string(), message },
311 })
312 }
313 }
314 }
315}
316
317pub(crate) struct Decoded {
320 pub workflow: Workflow,
321 pub node_paths: Vec<DocPath>,
323 pub edge_paths: Vec<DocPath>,
325 pub diagnostics: Vec<Diagnostic>,
326}
327
328struct KeyRules<'a> {
330 what: &'a str,
331 known: &'a [&'a str],
332 deprecated: &'a [(&'a str, &'a str)],
334 reserved: &'a [&'a str],
336}
337
338const TOP_LEVEL: KeyRules<'static> = KeyRules {
339 what: "the document",
340 known: &["version", "name", "description", "env", "conversation", "graph"],
341 deprecated: &[("environment_variables", "env"), ("conversation_variables", "conversation")],
342 reserved: &["imports", "inputs", "outputs", "triggers", "metadata", "requires", "subgraphs"],
343};
344
345const GRAPH_KEYS: KeyRules<'static> =
346 KeyRules { what: "`graph`", known: &["nodes", "edges"], deprecated: &[], reserved: &[] };
347
348const NODE_KEYS: KeyRules<'static> = KeyRules {
350 what: "a node",
351 known: &[],
352 deprecated: &[
353 ("parentId", "parent"),
354 ("container_id", "parent"),
355 ("iteration_id", "parent"),
356 ("loop_id", "parent"),
357 ("error_strategy", "on_error"),
358 ("default_value", "on_error"),
359 ("retry_config", "retry"),
360 ],
361 reserved: &["disabled", "cache", "metadata"],
362};
363
364pub const COMMON_NODE_FIELDS: &[&str] = &["id", "type", "title", "parent", "retry", "timeout_ms", "on_error"];
366
367pub const RESERVED_NODE_FIELDS: &[&str] = NODE_KEYS.reserved;
369
370const EDGE_KEYS: KeyRules<'static> = KeyRules {
371 what: "an edge",
372 known: &["id", "source", "target", "handle"],
373 deprecated: &[("sourceHandle", "handle"), ("source_handle", "handle")],
374 reserved: &[],
375};
376
377const DECL_KEYS: KeyRules<'static> = KeyRules {
378 what: "a variable declaration",
379 known: &["name", "type", "value", "description"],
380 deprecated: &[("value_type", "type")],
381 reserved: &[],
382};
383
384const RETRY_KEYS: KeyRules<'static> =
385 KeyRules { what: "`retry`", known: &["max_retries", "interval_ms", "backoff"], deprecated: &[], reserved: &[] };
386
387const ON_ERROR_KEYS: KeyRules<'static> =
388 KeyRules { what: "`on_error`", known: &["strategy", "values"], deprecated: &[], reserved: &[] };
389
390const STRATEGIES: &[&str] = &["fail", "fail-branch", "default-value"];
391
392const BUILDER_KEYS: &[&str] = &[
394 "desc",
395 "selected",
396 "position",
397 "positionAbsolute",
398 "width",
399 "height",
400 "sourcePosition",
401 "targetPosition",
402 "zIndex",
403 "isInIteration",
404 "isInLoop",
405];
406
407pub fn is_extension_key(key: &str) -> bool {
409 key.starts_with("x-")
410}
411
412fn check_keys(
416 obj: &serde_json::Map<String, serde_json::Value>,
417 path: &DocPath,
418 rules: &KeyRules<'_>,
419 unknown_is_error: bool,
420 out: &mut Vec<Diagnostic>,
421) {
422 for key in obj.keys() {
423 let key_path = path.key(key);
424 if is_extension_key(key) || rules.known.contains(&key.as_str()) {
425 continue;
426 }
427 if let Some((_, new)) = rules.deprecated.iter().find(|(old, _)| old == key) {
428 out.push(
429 Diagnostic::warning("deprecated", key_path, format!("`{key}` in {} is deprecated", rules.what))
430 .at_key()
431 .with_suggestion(Some((*new).to_owned())),
432 );
433 } else if rules.reserved.contains(&key.as_str()) {
434 out.push(
435 Diagnostic::error(
436 "reserved-field",
437 key_path,
438 format!("`{key}` in {} is reserved for a future version of the format", rules.what),
439 )
440 .at_key()
441 .with_help("keys starting with `x-` are free for tools and ignored"),
442 );
443 } else if unknown_is_error {
444 out.push(
445 Diagnostic::error("unknown-field", key_path, format!("unknown field `{key}` in {}", rules.what))
446 .at_key()
447 .with_suggestion(suggest(key, rules.known.iter().copied()))
448 .with_help(format!("expected one of: {}", rules.known.join(", "))),
449 );
450 }
451 }
452}
453
454pub(crate) fn decode(raw: serde_json::Value) -> Decoded {
456 let mut out = Vec::new();
457 let mut decoded = Decoded {
458 workflow: Workflow { version: FORMAT_VERSION.to_owned(), ..Workflow::default() },
459 node_paths: Vec::new(),
460 edge_paths: Vec::new(),
461 diagnostics: Vec::new(),
462 };
463 let serde_json::Value::Object(mut root) = raw else {
464 out.push(Diagnostic::error("invalid-value", DocPath::root(), "a workflow document must be an object"));
465 decoded.diagnostics = out;
466 return decoded;
467 };
468 let import = matches!(root.get("workflow"), Some(serde_json::Value::Object(_))) || root.contains_key("app");
470 let strict = !import;
471 let mut inner_keys = std::collections::HashSet::new();
472 if let Some(serde_json::Value::Object(inner)) = root.remove("workflow") {
473 for (k, v) in inner {
474 if !root.contains_key(&k) {
475 inner_keys.insert(k.clone());
476 root.insert(k, v);
477 }
478 }
479 }
480 let at = |key: &str| {
481 if inner_keys.contains(key) { DocPath::root().key("workflow").key(key) } else { DocPath::root().key(key) }
482 };
483 if strict {
484 check_keys(&root, &DocPath::root(), &TOP_LEVEL, true, &mut out);
485 }
486
487 let wf = &mut decoded.workflow;
488 if strict {
489 wf.version = check_version(root.get("version"), &at("version"), &mut out);
490 } else if let Some(v) = str_field(&root, "version") {
491 wf.version = v;
492 }
493 let app = root.get("app").and_then(|a| a.as_object());
494 wf.name =
495 text_field(&root, "name", &at("name"), strict, &mut out).or_else(|| app.and_then(|a| str_field(a, "name")));
496 wf.description = text_field(&root, "description", &at("description"), strict, &mut out)
497 .or_else(|| app.and_then(|a| str_field(a, "description")));
498
499 for (field, legacy) in [("env", "environment_variables"), ("conversation", "conversation_variables")] {
500 let (key, raw) = match root.remove(field) {
501 Some(v) => (field, Some(v)),
502 None => (legacy, root.remove(legacy)),
503 };
504 let decls = decode_decls(raw, &at(key), strict, &mut out);
505 if field == "env" {
506 wf.env = decls;
507 } else {
508 wf.conversation = decls;
509 }
510 }
511
512 let graph_path = at("graph");
513 let graph = match root.remove("graph") {
514 Some(serde_json::Value::Object(g)) => g,
515 Some(_) => {
516 out.push(Diagnostic::error(
517 "invalid-value",
518 graph_path,
519 "`graph` must be an object with `nodes` and `edges`",
520 ));
521 decoded.diagnostics = out;
522 return decoded;
523 }
524 None => {
525 out.push(
526 Diagnostic::error("missing-field", DocPath::root(), "missing `graph`")
527 .with_help("a workflow needs `graph: {nodes: [...], edges: [...]}`"),
528 );
529 decoded.diagnostics = out;
530 return decoded;
531 }
532 };
533 if strict {
534 check_keys(&graph, &graph_path, &GRAPH_KEYS, true, &mut out);
535 }
536 for (i, raw) in list_field(&graph, "nodes", &graph_path, &mut out).into_iter().enumerate() {
537 let path = graph_path.key("nodes").index(i);
538 if let Some(doc) = NodeDoc::decode(raw, &path, strict, &mut out) {
539 wf.graph.nodes.push(doc);
540 decoded.node_paths.push(path);
541 }
542 }
543 for (i, raw) in list_field(&graph, "edges", &graph_path, &mut out).into_iter().enumerate() {
544 let path = graph_path.key("edges").index(i);
545 if let Some(edge) = decode_edge(raw, &path, strict, &mut out) {
546 wf.graph.edges.push(edge);
547 decoded.edge_paths.push(path);
548 }
549 }
550 decoded.diagnostics = out;
551 decoded
552}
553
554fn check_version(raw: Option<&serde_json::Value>, path: &DocPath, out: &mut Vec<Diagnostic>) -> String {
556 match raw {
557 None => FORMAT_VERSION.to_owned(),
558 Some(serde_json::Value::String(s)) if s == FORMAT_VERSION => s.clone(),
559 Some(serde_json::Value::Number(n)) if n.as_u64() == Some(1) => FORMAT_VERSION.to_owned(),
560 Some(other) => {
561 let shown = other.as_str().map_or_else(|| other.to_string(), str::to_owned);
562 out.push(
563 Diagnostic::error(
564 "unsupported-version",
565 path.clone(),
566 format!("unsupported document version `{shown}`; this build reads version \"{FORMAT_VERSION}\""),
567 )
568 .with_help("newer documents need a newer graphrt"),
569 );
570 shown
571 }
572 }
573}
574
575fn str_field(map: &serde_json::Map<String, serde_json::Value>, key: &str) -> Option<String> {
576 map.get(key).and_then(|v| v.as_str()).map(str::to_owned)
577}
578
579fn text_field(
581 map: &serde_json::Map<String, serde_json::Value>,
582 key: &str,
583 path: &DocPath,
584 strict: bool,
585 out: &mut Vec<Diagnostic>,
586) -> Option<String> {
587 match map.get(key) {
588 None | Some(serde_json::Value::Null) => None,
589 Some(serde_json::Value::String(s)) => Some(s.clone()),
590 Some(_) => {
591 if strict {
592 out.push(Diagnostic::error("invalid-value", path.clone(), format!("`{key}` must be a string")));
593 }
594 None
595 }
596 }
597}
598
599fn list_field(
601 map: &serde_json::Map<String, serde_json::Value>,
602 key: &str,
603 parent: &DocPath,
604 out: &mut Vec<Diagnostic>,
605) -> Vec<serde_json::Value> {
606 match map.get(key) {
607 None | Some(serde_json::Value::Null) => Vec::new(),
608 Some(serde_json::Value::Array(items)) => items.clone(),
609 Some(_) => {
610 out.push(Diagnostic::error("invalid-value", parent.key(key), format!("`{key}` must be a list")));
611 Vec::new()
612 }
613 }
614}
615
616fn decode_decls(
617 raw: Option<serde_json::Value>,
618 path: &DocPath,
619 strict: bool,
620 out: &mut Vec<Diagnostic>,
621) -> Vec<VariableDecl> {
622 let items = match raw {
623 None | Some(serde_json::Value::Null) => return Vec::new(),
624 Some(serde_json::Value::Array(items)) => items,
625 Some(_) => {
626 out.push(Diagnostic::error("invalid-value", path.clone(), "variable declarations must be a list"));
627 return Vec::new();
628 }
629 };
630 let mut decls: Vec<VariableDecl> = Vec::with_capacity(items.len());
631 for (i, item) in items.into_iter().enumerate() {
632 let item_path = path.index(i);
633 if strict {
634 if let serde_json::Value::Object(obj) = &item {
635 check_keys(obj, &item_path, &DECL_KEYS, true, out);
636 }
637 }
638 match serde_json::from_value::<VariableDecl>(item) {
639 Ok(decl) => {
640 if decls.iter().any(|d| d.name == decl.name) {
641 out.push(Diagnostic::error(
642 "duplicate-variable",
643 item_path.key("name"),
644 format!("variable `{}` is declared twice", decl.name),
645 ));
646 }
647 decls.push(decl);
648 }
649 Err(e) => {
650 out.push(Diagnostic::error("invalid-value", item_path, format!("invalid variable declaration: {e}")))
651 }
652 }
653 }
654 decls
655}
656
657fn decode_edge(raw: serde_json::Value, path: &DocPath, strict: bool, out: &mut Vec<Diagnostic>) -> Option<EdgeDoc> {
658 let serde_json::Value::Object(mut obj) = raw else {
659 out.push(Diagnostic::error("invalid-value", path.clone(), "an edge must be an object `{source, target}`"));
660 return None;
661 };
662 if strict {
663 check_keys(&obj, path, &EDGE_KEYS, true, out);
664 }
665 obj.retain(|k, _| !is_extension_key(k));
666 let mut ok = true;
667 for end in ["source", "target"] {
668 match obj.get(end) {
669 Some(serde_json::Value::String(s)) if !s.is_empty() => {}
670 Some(_) => {
671 out.push(Diagnostic::error("invalid-value", path.key(end), format!("edge `{end}` must be a node id")));
672 ok = false;
673 }
674 None => {
675 out.push(Diagnostic::error("missing-field", path.clone(), format!("edge is missing `{end}`")));
676 ok = false;
677 }
678 }
679 }
680 if !ok {
681 return None;
682 }
683 match serde_json::from_value::<EdgeDoc>(serde_json::Value::Object(obj)) {
684 Ok(edge) => Some(edge),
685 Err(e) => {
686 out.push(Diagnostic::error("invalid-value", path.clone(), format!("invalid edge: {e}")));
687 None
688 }
689 }
690}
691
692const POLICY_KEYS: &[&str] = &["on_error", "error_strategy", "default_value", "retry", "retry_config", "timeout_ms"];
694
695impl NodeDoc {
696 pub fn from_raw(raw: serde_json::Value) -> Result<Option<Self>, DocumentError> {
698 let mut out = Vec::new();
699 let doc = Self::decode(raw, &DocPath::root(), true, &mut out);
700 match out.into_iter().find(Diagnostic::is_error) {
701 Some(d) => Err(DocumentError::Node {
702 id: d.node.unwrap_or_else(|| "<node>".to_owned()),
703 message: match d.suggestion {
704 Some(s) => format!("{}; did you mean `{s}`?", d.message),
705 None => d.message,
706 },
707 }),
708 None => Ok(doc),
709 }
710 }
711
712 fn decode(raw: serde_json::Value, path: &DocPath, strict_doc: bool, out: &mut Vec<Diagnostic>) -> Option<Self> {
715 let serde_json::Value::Object(mut obj) = raw else {
716 out.push(Diagnostic::error("invalid-value", path.clone(), "a node must be an object `{id, type, ...}`"));
717 return None;
718 };
719 let id = match obj.remove("id") {
720 Some(serde_json::Value::String(s)) if !s.is_empty() => s,
721 Some(_) => {
722 out.push(Diagnostic::error("invalid-value", path.key("id"), "node `id` must be a non-empty string"));
723 return None;
724 }
725 None => {
726 out.push(Diagnostic::error("missing-field", path.clone(), "node is missing `id`"));
727 return None;
728 }
729 };
730 let wrapped = matches!(obj.get("data"), Some(serde_json::Value::Object(_)));
731 let strict = strict_doc && !wrapped;
732 if strict {
733 let before = out.len();
734 check_keys(&obj, path, &NODE_KEYS, false, out);
735 for d in out.iter_mut().skip(before) {
736 d.node = Some(id.clone());
737 }
738 }
739 let legacy_parent = obj.remove("parentId").and_then(as_string);
740 let mut parent = obj.remove("parent").and_then(as_string).or(legacy_parent);
741 if let Some(serde_json::Value::Object(data)) = obj.remove("data") {
743 for (k, v) in data {
744 obj.insert(k, v);
745 }
746 }
747 for key in ["container_id", "iteration_id", "loop_id"] {
748 let v = obj.remove(key).and_then(as_string);
749 if parent.is_none() {
750 parent = v;
751 }
752 }
753 let kind = match obj.remove("type") {
754 Some(serde_json::Value::String(s)) if !s.is_empty() => s,
755 Some(_) => {
756 out.push(
757 Diagnostic::error("invalid-value", path.key("type"), "node `type` must be a non-empty string")
758 .with_node(&id),
759 );
760 return None;
761 }
762 None => {
763 out.push(Diagnostic::error("missing-field", path.clone(), "node is missing `type`").with_node(&id));
764 return None;
765 }
766 };
767 if kind == "custom-note" || kind == "note" {
768 return None;
769 }
770 let title = match obj.remove("title") {
771 Some(serde_json::Value::String(s)) if !s.is_empty() => Some(s),
772 None | Some(serde_json::Value::Null | serde_json::Value::String(_)) => None,
773 Some(_) => {
774 if strict {
775 out.push(
776 Diagnostic::error("invalid-value", path.key("title"), "node `title` must be a string")
777 .with_node(&id),
778 );
779 }
780 None
781 }
782 };
783 let policy = extract_policy(&id, &mut obj, path, strict, out);
784 for k in BUILDER_KEYS {
785 obj.remove(*k);
786 }
787 obj.retain(|k, _| !is_extension_key(k));
788 Some(Self { id, kind, title, parent, policy, config: obj, strict })
789 }
790}
791
792fn as_string(v: serde_json::Value) -> Option<String> {
793 match v {
794 serde_json::Value::String(s) if !s.is_empty() => Some(s),
795 _ => None,
796 }
797}
798
799fn extract_policy(
800 id: &str,
801 obj: &mut serde_json::Map<String, serde_json::Value>,
802 path: &DocPath,
803 strict: bool,
804 out: &mut Vec<Diagnostic>,
805) -> NodePolicy {
806 let mut policy = NodePolicy::default();
807 let mut push = |d: Diagnostic| out.push(d.with_node(id));
808
809 if let Some(v) = obj.remove("on_error") {
810 let at = path.key("on_error");
811 if let serde_json::Value::Object(map) = &v {
812 if strict {
813 let mut found = Vec::new();
814 check_keys(map, &at, &ON_ERROR_KEYS, true, &mut found);
815 found.into_iter().for_each(&mut push);
816 }
817 }
818 let strategy = v.get("strategy").and_then(serde_json::Value::as_str).map(str::to_owned);
819 match (&strategy, serde_json::from_value::<ErrorStrategy>(v)) {
820 (_, Ok(s)) => policy.on_error = s,
821 (Some(name), Err(_)) if !STRATEGIES.contains(&name.as_str()) => push(
822 Diagnostic::error("invalid-value", at.key("strategy"), format!("unknown `on_error` strategy `{name}`"))
823 .with_suggestion(suggest(name, STRATEGIES.iter().copied()))
824 .with_help("expected `fail`, `fail-branch` or `default-value`"),
825 ),
826 (_, Err(e)) => push(
827 Diagnostic::error("invalid-value", at, format!("invalid `on_error`: {e}"))
828 .with_help("expected `{strategy: fail | fail-branch | default-value, values: {...}}`"),
829 ),
830 }
831 } else if let Some(serde_json::Value::String(strategy)) = obj.remove("error_strategy") {
832 policy.on_error = match strategy.as_str() {
833 "fail-branch" => ErrorStrategy::FailBranch,
834 "" | "none" | "fail" => ErrorStrategy::Fail,
835 "default-value" => {
836 let values = match obj.remove("default_value") {
838 Some(serde_json::Value::Array(items)) => items
839 .into_iter()
840 .filter_map(|item| {
841 let key = item.get("key")?.as_str()?.to_owned();
842 let declared = item.get("type").and_then(|t| t.as_str()).unwrap_or("any").to_owned();
843 let value = item.get("value").cloned().unwrap_or(serde_json::Value::Null);
844 Some((key, default_value(&declared, value)))
845 })
846 .collect(),
847 Some(serde_json::Value::Object(map)) => {
848 map.into_iter().map(|(k, v)| (k, Value::from_json(v))).collect()
849 }
850 _ => IndexMap::new(),
851 };
852 ErrorStrategy::DefaultValue { values }
853 }
854 other => {
855 push(
856 Diagnostic::error(
857 "invalid-value",
858 path.key("error_strategy"),
859 format!("unknown error_strategy `{other}` (expected `fail`, `fail-branch` or `default-value`)"),
860 )
861 .with_suggestion(suggest(other, STRATEGIES.iter().copied())),
862 );
863 ErrorStrategy::Fail
864 }
865 };
866 }
867 obj.remove("default_value");
868
869 if let Some(v) = obj.remove("retry") {
870 let at = path.key("retry");
871 if let serde_json::Value::Object(map) = &v {
872 if strict {
873 let mut found = Vec::new();
874 check_keys(map, &at, &RETRY_KEYS, true, &mut found);
875 found.into_iter().for_each(&mut push);
876 }
877 }
878 match serde_json::from_value(v) {
879 Ok(retry) => policy.retry = retry,
880 Err(e) => push(Diagnostic::error("invalid-value", at, format!("invalid `retry`: {e}"))),
881 }
882 } else if let Some(serde_json::Value::Object(cfg)) = obj.remove("retry_config") {
883 let enabled = cfg.get("retry_enabled").and_then(serde_json::Value::as_bool).unwrap_or(false);
884 if enabled {
885 policy.retry.max_retries = cfg
886 .get("max_retries")
887 .and_then(serde_json::Value::as_u64)
888 .and_then(|n| u32::try_from(n).ok())
889 .unwrap_or(0);
890 policy.retry.interval_ms = cfg.get("retry_interval").and_then(serde_json::Value::as_u64).unwrap_or(0);
891 }
892 }
893 match obj.remove("timeout_ms") {
894 None | Some(serde_json::Value::Null) => {}
895 Some(v) => match v.as_u64() {
896 Some(ms) => policy.timeout_ms = Some(ms),
897 None => push(Diagnostic::error(
898 "invalid-value",
899 path.key("timeout_ms"),
900 format!("timeout_ms must be a non-negative integer number of milliseconds, got {v}"),
901 )),
902 },
903 }
904 for k in POLICY_KEYS {
905 obj.remove(*k);
906 }
907 policy
908}
909
910fn default_value(declared: &str, value: serde_json::Value) -> Value {
912 match (declared, value) {
913 ("string", v) => Value::from_json(v),
914 (_, serde_json::Value::String(s)) => match serde_json::from_str::<serde_json::Value>(&s) {
915 Ok(parsed) => Value::from_json(parsed),
916 Err(_) => Value::from(s),
917 },
918 (_, v) => Value::from_json(v),
919 }
920}
921
922#[cfg(test)]
923mod tests {
924 use super::*;
925
926 #[test]
927 fn parses_flat_layout() {
928 let doc = Workflow::from_json(
929 r#"{"graph":{"nodes":[{"id":"s","type":"start","variables":[]},
930 {"id":"h","type":"http-request","retry":{"max_retries":2,"interval_ms":10},"timeout_ms":500}],
931 "edges":[{"source":"s","target":"h"}]}}"#,
932 );
933 let doc = doc.unwrap();
934 assert_eq!(doc.graph.nodes.len(), 2);
935 let h = &doc.graph.nodes[1];
936 assert_eq!(h.policy.retry.max_retries, 2);
937 assert_eq!(h.policy.timeout_ms, Some(500));
938 assert!(!h.config.contains_key("retry"));
939 }
940
941 #[test]
942 fn parses_data_wrapper_layout() {
943 let doc = Workflow::from_json(
944 r#"{"workflow":{"environment_variables":[{"name":"K","value_type":"secret","value":"x"}],
945 "graph":{"nodes":[
946 {"id":"a","type":"custom","data":{"type":"llm","title":"LLM","error_strategy":"default-value",
947 "default_value":[{"key":"n","type":"number","value":"42"}],
948 "retry_config":{"retry_enabled":true,"max_retries":3,"retry_interval":100}}},
949 {"id":"b","type":"custom","parentId":"it","data":{"type":"code"}},
950 {"id":"note","type":"custom-note","data":{"type":"custom-note"}}],
951 "edges":[{"source":"a","target":"b","sourceHandle":"source"}]}}}"#,
952 );
953 let doc = doc.unwrap();
954 assert_eq!(doc.env.len(), 1);
955 assert_eq!(doc.env[0].ty, ValueType::Secret);
956 assert_eq!(doc.graph.nodes.len(), 2);
957 let a = &doc.graph.nodes[0];
958 assert_eq!(a.kind, "llm");
959 assert_eq!(a.title.as_deref(), Some("LLM"));
960 assert_eq!(a.policy.retry.max_retries, 3);
961 match &a.policy.on_error {
962 ErrorStrategy::DefaultValue { values } => assert_eq!(values.get("n"), Some(&Value::Int(42))),
963 other => panic!("unexpected {other:?}"),
964 }
965 assert_eq!(doc.graph.nodes[1].parent.as_deref(), Some("it"));
966 assert_eq!(doc.graph.edges[0].handle.as_deref(), Some("source"));
967 }
968
969 #[test]
970 fn backoff_delay() {
971 let p = RetryPolicy { max_retries: 3, interval_ms: 100, backoff: 2.0 };
972 assert_eq!(p.delay_ms(1), 100);
973 assert_eq!(p.delay_ms(3), 400);
974 }
975
976 #[cfg(feature = "yaml")]
977 #[test]
978 fn parses_yaml() {
979 let doc = Workflow::parse("graph:\n nodes:\n - {id: s, type: start}\n edges: []\n");
980 assert!(matches!(doc, Ok(d) if d.graph.nodes.len() == 1));
981 }
982
983 #[cfg(feature = "yaml")]
984 #[test]
985 fn yaml_uses_strict_booleans() {
986 let doc = Workflow::parse("graph:\n nodes:\n - {id: s, type: start, label: n, flag: true}\n").unwrap();
987 let cfg = &doc.graph.nodes[0].config;
988 assert_eq!(cfg.get("label"), Some(&serde_json::json!("n")));
989 assert_eq!(cfg.get("flag"), Some(&serde_json::json!(true)));
990 }
991}
992
993impl Serialize for NodeDoc {
994 fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
995 use serde::ser::{Error as _, SerializeMap};
996 let mut map = serializer.serialize_map(None)?;
997 map.serialize_entry("id", &self.id)?;
998 map.serialize_entry("type", &self.kind)?;
999 if let Some(title) = &self.title {
1000 map.serialize_entry("title", title)?;
1001 }
1002 if let Some(parent) = &self.parent {
1003 map.serialize_entry("parent", parent)?;
1004 }
1005 if self.policy.on_error != ErrorStrategy::Fail {
1006 map.serialize_entry("on_error", &self.policy.on_error)?;
1007 }
1008 if self.policy.retry != RetryPolicy::default() {
1009 map.serialize_entry("retry", &self.policy.retry)?;
1010 }
1011 if let Some(ms) = self.policy.timeout_ms {
1012 map.serialize_entry("timeout_ms", &ms)?;
1013 }
1014 for (key, value) in &self.config {
1015 if matches!(key.as_str(), "id" | "type" | "title" | "parent") || POLICY_KEYS.contains(&key.as_str()) {
1016 return Err(S::Error::custom(format!("node `{}`: config key `{key}` is reserved", self.id)));
1017 }
1018 map.serialize_entry(key, value)?;
1019 }
1020 map.end()
1021 }
1022}
1023
1024impl Workflow {
1025 pub fn to_json(&self) -> Result<String, DocumentError> {
1027 Ok(serde_json::to_string(self)?)
1028 }
1029
1030 pub fn canonical_graph_json(&self) -> Result<String, DocumentError> {
1033 let value = serde_json::to_value(&self.graph)?;
1034 Ok(serde_json::to_string(&canonicalize(value))?)
1035 }
1036}
1037
1038fn canonicalize(value: serde_json::Value) -> serde_json::Value {
1040 match value {
1041 serde_json::Value::Object(map) => {
1042 let mut entries: Vec<(String, serde_json::Value)> = map.into_iter().collect();
1043 entries.sort_by(|a, b| a.0.cmp(&b.0));
1044 serde_json::Value::Object(entries.into_iter().map(|(k, v)| (k, canonicalize(v))).collect())
1045 }
1046 serde_json::Value::Array(items) => serde_json::Value::Array(items.into_iter().map(canonicalize).collect()),
1047 other => other,
1048 }
1049}
1050
1051#[cfg(test)]
1052mod roundtrip_tests {
1053 use super::*;
1054
1055 const DOC: &str = r#"{"name":"demo","env":[{"name":"K","type":"secret"}],"graph":{"nodes":[
1056 {"id":"s","type":"start","variables":[]},
1057 {"id":"h","type":"custom","data":{"type":"http-request","title":"Call","url":"https://x",
1058 "error_strategy":"default-value","default_value":{"body":"none"},
1059 "retry_config":{"retry_enabled":true,"max_retries":2,"retry_interval":10},"timeout_ms":500}},
1060 {"id":"b","type":"code","parentId":"it"}],
1061 "edges":[{"source":"s","target":"h","sourceHandle":"source"}]}}"#;
1062
1063 #[test]
1064 fn workflow_round_trips() {
1065 let a = Workflow::from_json(DOC).unwrap();
1066 let text = a.to_json().unwrap();
1067 let b = Workflow::from_json(&text).unwrap();
1068 assert_eq!(text, b.to_json().unwrap());
1069 let h = &b.graph.nodes[1];
1070 assert_eq!(h.kind, "http-request");
1071 assert_eq!(h.title.as_deref(), Some("Call"));
1072 assert_eq!(h.policy, a.graph.nodes[1].policy);
1073 assert_eq!(h.policy.timeout_ms, Some(500));
1074 assert_eq!(h.config.get("url"), Some(&serde_json::json!("https://x")));
1075 assert!(!h.config.contains_key("config"));
1076 assert_eq!(b.graph.nodes[2].parent.as_deref(), Some("it"));
1077 assert_eq!(a.canonical_graph_json().unwrap(), b.canonical_graph_json().unwrap());
1078 }
1079
1080 #[test]
1081 fn canonical_json_ignores_key_order() {
1082 let a = Workflow::from_json(r#"{"graph":{"nodes":[{"id":"s","type":"start","x":1,"y":2}],"edges":[]}}"#);
1083 let b = Workflow::from_json(r#"{"graph":{"nodes":[{"y":2,"x":1,"type":"start","id":"s"}],"edges":[]}}"#);
1084 assert_eq!(a.unwrap().canonical_graph_json().unwrap(), b.unwrap().canonical_graph_json().unwrap());
1085 }
1086
1087 #[test]
1088 fn typos_are_errors() {
1089 let bad_strategy = r#"{"graph":{"nodes":[{"id":"s","type":"start","error_strategy":"fail-brnch"}]}}"#;
1090 assert!(matches!(Workflow::from_json(bad_strategy), Err(DocumentError::Node { .. })));
1091 let bad_timeout = r#"{"graph":{"nodes":[{"id":"s","type":"start","timeout_ms":"5s"}]}}"#;
1092 assert!(matches!(Workflow::from_json(bad_timeout), Err(DocumentError::Node { .. })));
1093 let none = r#"{"graph":{"nodes":[{"id":"s","type":"start","error_strategy":"none"}]}}"#;
1094 assert!(Workflow::from_json(none).is_ok());
1095 }
1096}