1use std::collections::{HashMap, HashSet, VecDeque};
4use std::fmt;
5
6use hatchet_proto::v1;
7use serde_json::Value;
8
9use super::task::Task;
10use super::{
11 Concurrency, ConditionAction, Gates, Idempotency, Priority, RegisteredAction, StickyStrategy,
12 TaskDef, TaskOptions, WorkflowOptions, action_id, timeout_string, wire_name,
13};
14use crate::config::namespace;
15use crate::{Error, Result};
16
17mod sealed {
18 pub trait Sealed {}
19}
20
21pub trait Register: sealed::Sealed {
23 #[doc(hidden)]
25 fn definition(&self) -> WorkflowDef;
26}
27
28#[derive(Clone)]
67#[must_use = "a declared workflow runs nothing until it is registered on a worker"]
68pub struct Workflow {
69 name: String,
70 options: WorkflowOptions,
71 tasks: Vec<TaskDef>,
72 on_failure: Vec<TaskDef>,
75 on_success: Vec<TaskDef>,
78 tasks_with_standalone_options: Vec<String>,
80}
81
82impl fmt::Debug for Workflow {
85 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
86 f.debug_struct("Workflow")
87 .field("name", &self.name)
88 .field("tasks", &task_names(&self.tasks))
89 .finish_non_exhaustive()
90 }
91}
92
93impl fmt::Debug for WorkflowDef {
94 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
95 f.debug_struct("WorkflowDef")
96 .field("name", &self.name)
97 .field("tasks", &task_names(&self.tasks))
98 .field("is_standalone", &self.is_standalone)
99 .finish_non_exhaustive()
100 }
101}
102
103fn task_names(tasks: &[TaskDef]) -> Vec<&str> {
104 tasks.iter().map(|task| task.name.as_str()).collect()
105}
106
107impl Workflow {
108 pub fn new(name: impl Into<String>) -> Self {
110 Self {
111 name: name.into(),
112 options: WorkflowOptions::default(),
113 tasks: Vec::new(),
114 on_failure: Vec::new(),
115 on_success: Vec::new(),
116 tasks_with_standalone_options: Vec::new(),
117 }
118 }
119
120 pub fn name(&self) -> &str {
122 &self.name
123 }
124
125 pub fn description(mut self, description: impl Into<String>) -> Self {
127 self.options.description = Some(description.into());
128 self
129 }
130
131 pub fn version(mut self, version: impl Into<String>) -> Self {
133 self.options.version = Some(version.into());
134 self
135 }
136
137 pub fn on_events(mut self, keys: impl IntoIterator<Item = impl Into<String>>) -> Self {
140 self.options
141 .on_events
142 .extend(keys.into_iter().map(Into::into));
143 self
144 }
145
146 pub fn cron(mut self, expression: impl Into<String>) -> Self {
149 self.options.on_crons.push(expression.into());
150 self
151 }
152
153 pub fn cron_input(mut self, input: Value) -> Self {
155 self.options.cron_input = Some(input);
156 self
157 }
158
159 pub fn default_priority(mut self, priority: Priority) -> Self {
161 self.options.default_priority = Some(priority);
162 self
163 }
164
165 pub fn concurrency(mut self, concurrency: Concurrency) -> Self {
167 self.options.concurrency.push(concurrency);
168 self
169 }
170
171 pub fn sticky(mut self, strategy: StickyStrategy) -> Self {
181 self.options.sticky = Some(strategy);
182 self
183 }
184
185 pub fn idempotency(mut self, idempotency: Idempotency) -> Self {
199 self.options.idempotency = Some(idempotency);
200 self
201 }
202
203 pub fn task<I, O>(mut self, task: &Task<I, O>) -> Self {
214 if !task.standalone.is_empty() {
215 self.tasks_with_standalone_options
216 .push(task.def.name.clone());
217 }
218 self.tasks.push(task.def.clone());
219 self
220 }
221
222 pub fn on_failure<I, O>(mut self, task: &Task<I, O>) -> Self {
258 if !task.standalone.is_empty() {
259 self.tasks_with_standalone_options
260 .push(task.def.name.clone());
261 }
262 self.on_failure.push(task.def.clone());
263 self
264 }
265
266 pub fn on_success<I, O>(mut self, task: &Task<I, O>) -> Self {
310 if !task.standalone.is_empty() {
311 self.tasks_with_standalone_options
312 .push(task.def.name.clone());
313 }
314 self.on_success.push(task.def.clone());
315 self
316 }
317}
318
319impl sealed::Sealed for Workflow {}
320
321impl Register for Workflow {
322 fn definition(&self) -> WorkflowDef {
323 WorkflowDef {
324 name: self.name.clone(),
325 options: self.options.clone(),
326 tasks: self.tasks.clone(),
327 on_failure: self.on_failure.clone(),
328 on_success: self.on_success.clone(),
329 tasks_with_standalone_options: self.tasks_with_standalone_options.clone(),
330 is_standalone: false,
331 }
332 }
333}
334
335impl<I, O> sealed::Sealed for Task<I, O> {}
336
337impl<I, O> Register for Task<I, O> {
338 fn definition(&self) -> WorkflowDef {
339 WorkflowDef {
340 name: self.def.name.clone(),
341 options: self.standalone.clone(),
342 tasks: vec![self.def.clone()],
343 on_failure: Vec::new(),
344 on_success: Vec::new(),
345 tasks_with_standalone_options: Vec::new(),
346 is_standalone: true,
347 }
348 }
349}
350
351#[derive(Clone)]
353pub struct WorkflowDef {
354 name: String,
355 options: WorkflowOptions,
356 tasks: Vec<TaskDef>,
357 on_failure: Vec<TaskDef>,
358 on_success: Vec<TaskDef>,
359 tasks_with_standalone_options: Vec<String>,
360 is_standalone: bool,
363}
364
365impl WorkflowDef {
366 pub(crate) fn wire_name(&self, namespace: &str) -> String {
367 wire_name(namespace, &self.name)
368 }
369
370 pub(crate) fn actions(&self, namespace: &str) -> Result<Vec<(String, RegisteredAction)>> {
374 self.validate()?;
375 let workflow = self.wire_name(namespace);
376 Ok(self
377 .declared_tasks()
378 .map(|task| {
379 (
380 action_id(&workflow, &task.name),
381 RegisteredAction {
382 handler: task.handler.clone(),
383 durable: task.durable,
384 eviction_policy: task.options.eviction_policy.clone(),
385 batch: task.batch.as_ref().map(|batch| batch.handler.clone()),
386 },
387 )
388 })
389 .collect())
390 }
391
392 fn declared_tasks(&self) -> impl Iterator<Item = &TaskDef> {
394 self.tasks
395 .iter()
396 .chain(self.on_failure.iter())
397 .chain(self.on_success.iter())
398 }
399
400 pub(crate) fn has_default(&self) -> bool {
406 self.declared_tasks().any(|task| !task.durable)
407 }
408
409 pub(crate) fn has_durable(&self) -> bool {
411 self.declared_tasks().any(|task| task.durable)
412 }
413
414 pub(crate) fn to_request(&self, namespace: &str) -> Result<v1::CreateWorkflowVersionRequest> {
416 self.validate()?;
417 let workflow = self.wire_name(namespace);
418 let options = &self.options;
419
420 let mut tasks: Vec<v1::CreateTaskOpts> = self
421 .tasks
422 .iter()
423 .map(|task| task_opts(namespace, &workflow, task))
424 .collect();
425 if let Some(hook) = self.on_success.first() {
426 let mut opts = task_opts(namespace, &workflow, hook);
427 opts.parents = leaf_names(&self.tasks);
428 tasks.push(opts);
429 }
430
431 Ok(v1::CreateWorkflowVersionRequest {
432 tasks,
433 description: options.description.clone().unwrap_or_default(),
434 version: options.version.clone().unwrap_or_default(),
435 event_triggers: options
436 .on_events
437 .iter()
438 .map(|key| namespace::apply(namespace, key))
439 .collect(),
440 cron_triggers: options.on_crons.clone(),
441 cron_input: options.cron_input.as_ref().map(Value::to_string),
442 default_priority: options.default_priority.map(Priority::to_proto),
443 concurrency_arr: options
444 .concurrency
445 .iter()
446 .map(Concurrency::to_proto)
447 .collect(),
448 on_failure_task: self
449 .on_failure
450 .first()
451 .map(|task| task_opts(namespace, &workflow, task)),
452 sticky: options.sticky.map(StickyStrategy::to_proto),
453 idempotency: options.idempotency.as_ref().map(Idempotency::to_proto),
454 name: workflow,
455 ..Default::default()
456 })
457 }
458
459 pub(crate) fn check_engine_features(&self, engine_version: &str) -> Result<()> {
463 if self.options.idempotency.is_some() {
464 crate::version::ensure_feature(
465 "idempotency",
466 crate::version::IDEMPOTENCY_MIN_ENGINE_VERSION,
467 engine_version,
468 )?;
469 }
470 if self.declared_tasks().any(|task| task.batch.is_some()) {
471 crate::version::ensure_feature(
476 "batch tasks",
477 crate::version::BATCH_MIN_ENGINE_VERSION,
478 engine_version,
479 )?;
480 }
481 Ok(())
482 }
483
484 fn validate(&self) -> Result<()> {
485 let name = &self.name;
486
487 if let Some(reason) = invalid_name_reason(name) {
488 return Err(Error::InvalidDeclaration(format!(
489 "a workflow or standalone task name `{name}` is invalid: {reason}"
490 )));
491 }
492 if self.tasks.is_empty() {
493 return Err(Error::InvalidDeclaration(format!(
494 "workflow `{name}` has no tasks"
495 )));
496 }
497 if let Some(task) = self.tasks_with_standalone_options.first() {
498 return Err(Error::InvalidDeclaration(format!(
499 "task `{task}` in workflow `{name}` sets standalone-only options \
500 (description, version, event or cron triggers, cron input, default \
501 priority, workflow concurrency, sticky, idempotency); set them on the \
502 workflow instead"
503 )));
504 }
505
506 let mut seen = HashSet::new();
507 for task in &self.tasks {
508 if let Some(reason) = invalid_name_reason(&task.name) {
509 return Err(Error::InvalidDeclaration(format!(
510 "task `{}` in workflow `{name}` has an invalid name: {reason}",
511 task.name
512 )));
513 }
514 if !seen.insert(task.name.to_lowercase()) {
515 return Err(Error::InvalidDeclaration(format!(
516 "workflow `{name}` has more than one task named `{}` (names are compared case-insensitively)",
517 task.name
518 )));
519 }
520 }
521
522 for (label, hooks) in [
523 ("on_failure", &self.on_failure),
524 ("on_success", &self.on_success),
525 ] {
526 if hooks.len() > 1 {
527 return Err(Error::InvalidDeclaration(format!(
528 "workflow `{name}` declares {label} more than once; there can be only one"
529 )));
530 }
531 for hook in hooks {
532 if let Some(reason) = invalid_name_reason(&hook.name) {
533 return Err(Error::InvalidDeclaration(format!(
534 "the {label} task `{}` of workflow `{name}` has an invalid name: {reason}",
535 hook.name
536 )));
537 }
538 if !hook.parents.is_empty() {
539 return Err(Error::InvalidDeclaration(format!(
540 "the {label} task `{}` of workflow `{name}` has parents; they are set \
541 automatically, so it cannot declare its own",
542 hook.name
543 )));
544 }
545 if !seen.insert(hook.name.to_lowercase()) {
546 return Err(Error::InvalidDeclaration(format!(
547 "task `{}` of workflow `{name}` is used more than once (as a task, an \
548 on-failure task or an on-success task); names are compared \
549 case-insensitively",
550 hook.name
551 )));
552 }
553 for concurrency in &hook.options.concurrency {
554 concurrency.validate().map_err(|reason| {
555 Error::InvalidDeclaration(format!(
556 "the {label} task `{}` of workflow `{name}`: {reason}",
557 hook.name
558 ))
559 })?;
560 }
561 for limit in &hook.options.rate_limits {
562 limit.validate().map_err(|reason| {
563 Error::InvalidDeclaration(format!(
564 "the {label} task `{}` of workflow `{name}`: {reason}",
565 hook.name
566 ))
567 })?;
568 }
569 if label == "on_failure" && !conditions_are_empty(&hook.options) {
570 return Err(Error::InvalidDeclaration(format!(
571 "the on_failure task `{}` of workflow `{name}` sets wait_for, \
572 skip_if or cancel_if; an on-failure task runs because the \
573 workflow failed, and the engine is not sent conditions for it",
574 hook.name
575 )));
576 }
577 if label == "on_success" {
578 check_conditions(name, &hook.name, &hook.options, &leaf_names(&self.tasks))?;
580 }
581 }
582 }
583
584 if self.is_standalone && self.tasks.iter().any(|task| !task.parents.is_empty()) {
585 return Err(Error::InvalidDeclaration(
586 "a standalone task cannot have parents".to_string(),
587 ));
588 }
589
590 let known: HashSet<&str> = self.tasks.iter().map(|task| task.name.as_str()).collect();
591 for task in &self.tasks {
592 if let Some(parent) = task
593 .parents
594 .iter()
595 .find(|parent| !known.contains(parent.as_str()))
596 {
597 return Err(Error::InvalidDeclaration(format!(
598 "task `{}` has parent `{parent}`, which is not part of workflow `{name}`",
599 task.name
600 )));
601 }
602 }
603
604 for task in &self.tasks {
605 if task.parents.iter().any(|parent| parent == &task.name) {
606 return Err(Error::InvalidDeclaration(format!(
607 "task `{}` in workflow `{name}` lists itself as a parent",
608 task.name
609 )));
610 }
611 }
612
613 self.check_no_cycles(name)?;
614
615 for task in self.declared_tasks() {
621 let Some(policy) = &task.options.eviction_policy else {
622 continue;
623 };
624 if !task.durable {
625 return Err(Error::InvalidDeclaration(format!(
626 "task `{}` in workflow `{name}` has an eviction policy but an ordinary \
627 handler; only a durable task is ever parked on the engine, so only a \
628 `durable_handler` can be evicted",
629 task.name
630 )));
631 }
632 if !policy.has_ttl() {
633 return Err(Error::InvalidDeclaration(format!(
634 "task `{}` in workflow `{name}` has an eviction policy with a TTL of zero, \
635 which never evicts on time at all; give it the time a wait may last, or \
636 leave the policy off",
637 task.name
638 )));
639 }
640 }
641
642 for task in self.declared_tasks() {
649 let Some(batch) = &task.batch else {
650 continue;
651 };
652 if let Some(reason) = batch.config.invalid_reason() {
653 return Err(Error::InvalidDeclaration(format!(
654 "task `{}` in workflow `{name}`: {reason}",
655 task.name
656 )));
657 }
658 if task.options.retries != 0 {
659 return Err(Error::InvalidDeclaration(format!(
660 "task `{}` in workflow `{name}` is a batch task with retries ({}); a batch \
661 handler runs once for a whole group of runs, so there is no single run for \
662 the task's retries to be about. Engines do honour the field, but both \
663 official SDKs force it to zero and this one refuses the declaration rather \
664 than quietly changing it — fail a member with a retryable `TaskError` \
665 instead, and the engine re-batches that member on its own",
666 task.name, task.options.retries
667 )));
668 }
669 }
670 for (label, hooks) in [
671 ("on_failure", &self.on_failure),
672 ("on_success", &self.on_success),
673 ] {
674 if let Some(hook) = hooks.iter().find(|hook| hook.batch.is_some()) {
675 return Err(Error::InvalidDeclaration(format!(
676 "the {label} task `{}` of workflow `{name}` is a batch task; a hook runs \
677 because one particular run ended, so there is nothing to batch it with",
678 hook.name
679 )));
680 }
681 }
682
683 for concurrency in &self.options.concurrency {
684 concurrency.validate().map_err(|reason| {
685 Error::InvalidDeclaration(format!("workflow `{name}`: {reason}"))
686 })?;
687 }
688 if let Some(idempotency) = &self.options.idempotency {
689 idempotency.validate().map_err(|reason| {
690 Error::InvalidDeclaration(format!("workflow `{name}`: {reason}"))
691 })?;
692 }
693 for task in &self.tasks {
694 for concurrency in &task.options.concurrency {
695 concurrency.validate().map_err(|reason| {
696 Error::InvalidDeclaration(format!(
697 "task `{}` in workflow `{name}`: {reason}",
698 task.name
699 ))
700 })?;
701 }
702 for limit in &task.options.rate_limits {
703 limit.validate().map_err(|reason| {
704 Error::InvalidDeclaration(format!(
705 "task `{}` in workflow `{name}`: {reason}",
706 task.name
707 ))
708 })?;
709 }
710 }
711
712 for task in &self.tasks {
713 check_conditions(name, &task.name, &task.options, &task.parents)?;
714 }
715
716 Ok(())
717 }
718
719 fn check_no_cycles(&self, name: &str) -> Result<()> {
722 let mut in_degree: HashMap<&str, usize> = self
723 .tasks
724 .iter()
725 .map(|task| (task.name.as_str(), task.parents.len()))
726 .collect();
727 let mut children: HashMap<&str, Vec<&str>> = HashMap::new();
728 for task in &self.tasks {
729 for parent in &task.parents {
730 children
731 .entry(parent.as_str())
732 .or_default()
733 .push(task.name.as_str());
734 }
735 }
736
737 let mut queue: VecDeque<&str> = in_degree
738 .iter()
739 .filter(|&(_, °ree)| degree == 0)
740 .map(|(&task, _)| task)
741 .collect();
742 let mut processed = 0usize;
743 while let Some(task) = queue.pop_front() {
744 processed += 1;
745 if let Some(kids) = children.get(task) {
746 for &kid in kids {
747 if let Some(degree) = in_degree.get_mut(kid) {
748 *degree -= 1;
749 if *degree == 0 {
750 queue.push_back(kid);
751 }
752 }
753 }
754 }
755 }
756
757 if processed < self.tasks.len() {
758 let cyclic = in_degree
759 .iter()
760 .find(|&(_, °ree)| degree > 0)
761 .map(|(&task, _)| task)
762 .unwrap_or_default();
763 return Err(Error::InvalidDeclaration(format!(
764 "workflow `{name}` has a cycle among task parents, involving task `{cyclic}`"
765 )));
766 }
767 Ok(())
768 }
769}
770
771fn invalid_name_reason(name: &str) -> Option<&'static str> {
775 if name.trim().is_empty() {
776 Some("names must not be empty or whitespace-only")
777 } else if name.contains(':') {
778 Some("names must not contain `:`")
779 } else {
780 None
781 }
782}
783
784fn leaf_names(tasks: &[TaskDef]) -> Vec<String> {
790 let has_a_child: HashSet<&str> = tasks
791 .iter()
792 .flat_map(|task| task.parents.iter().map(String::as_str))
793 .collect();
794 tasks
795 .iter()
796 .filter(|task| !has_a_child.contains(task.name.as_str()))
797 .map(|task| task.name.clone())
798 .collect()
799}
800
801fn gates(options: &TaskOptions) -> Gates<'_> {
804 [
805 (ConditionAction::Queue, &options.wait_for),
806 (ConditionAction::Skip, &options.skip_if),
807 (ConditionAction::Cancel, &options.cancel_if),
808 ]
809}
810
811fn conditions_are_empty(options: &TaskOptions) -> bool {
812 options.wait_for.is_empty() && options.skip_if.is_empty() && options.cancel_if.is_empty()
813}
814
815fn check_conditions(
821 workflow: &str,
822 task: &str,
823 options: &TaskOptions,
824 parents: &[String],
825) -> Result<()> {
826 super::condition::validate(gates(options)).map_err(|reason| {
827 Error::InvalidDeclaration(format!("task `{task}` in workflow `{workflow}`: {reason}"))
828 })?;
829 for (_, set) in gates(options) {
830 for parent in set.parent_names() {
831 if !parents.iter().any(|declared| declared == parent) {
832 return Err(Error::InvalidDeclaration(format!(
833 "task `{task}` in workflow `{workflow}` has a condition on parent \
834 `{parent}`, which is not one of its parents; a parent condition reads \
835 that parent's output, so the task must run after it"
836 )));
837 }
838 }
839 }
840 Ok(())
841}
842
843fn task_opts(namespace: &str, workflow_wire_name: &str, task: &TaskDef) -> v1::CreateTaskOpts {
844 let options = &task.options;
845 v1::CreateTaskOpts {
846 readable_id: task.name.clone(),
847 action: action_id(workflow_wire_name, &task.name),
848 timeout: options
849 .execution_timeout
850 .map(timeout_string)
851 .unwrap_or_default(),
852 schedule_timeout: options.schedule_timeout.map(timeout_string),
853 inputs: "{}".to_string(),
854 parents: task.parents.clone(),
855 retries: super::options::saturating_i32(options.retries),
856 backoff_factor: options.backoff.map(|(factor, _)| factor),
857 backoff_max_seconds: options
858 .backoff
859 .map(|(_, max)| super::options::saturating_i32(max)),
860 rate_limits: options
861 .rate_limits
862 .iter()
863 .map(|limit| limit.to_proto())
864 .collect(),
865 concurrency: options
866 .concurrency
867 .iter()
868 .map(Concurrency::to_proto)
869 .collect(),
870 worker_labels: options
871 .worker_labels
872 .iter()
873 .map(|(key, label)| (key.clone(), label.to_proto()))
874 .collect(),
875 is_durable: task.durable,
876 slot_requests: HashMap::from([(
881 if task.durable { "durable" } else { "default" }.to_string(),
882 1,
883 )]),
884 conditions: super::condition::to_proto(namespace, gates(options)),
885 batch: task
890 .batch
891 .as_ref()
892 .map(|batch| batch.config.to_proto(batch.broadcast)),
893 }
894}
895
896#[cfg(test)]
897mod tests {
898 use super::*;
899 use crate::{
900 Concurrency, ConcurrencyLimitStrategy, Condition, DesiredLabel, Error, Idempotency,
901 Priority, RateLimit, StickyStrategy, TaskBuilder,
902 };
903 use hatchet_proto::v1;
904 use serde_json::json;
905 use std::collections::HashMap;
906 use std::sync::Arc;
907 use std::time::Duration;
908
909 fn task(name: &str) -> crate::Task<serde_json::Value, serde_json::Value> {
910 TaskBuilder::new(name).handler(|_ctx, input| async move { Ok(input) })
911 }
912
913 fn default_slots() -> HashMap<String, i32> {
914 HashMap::from([("default".to_string(), 1)])
915 }
916
917 #[test]
918 fn debug_names_the_workflow_and_its_tasks_and_says_it_is_not_all_of_it() {
919 let workflow = Workflow::new("pipeline")
920 .task(&task("fetch"))
921 .task(&task("build"));
922
923 let debug = format!("{workflow:?}");
924 assert!(debug.starts_with("Workflow"), "{debug}");
925 assert!(debug.contains("pipeline"), "{debug}");
926 assert!(
927 debug.contains("fetch") && debug.contains("build"),
928 "{debug}"
929 );
930 assert!(debug.contains(".."), "{debug}");
931
932 let debug = format!("{:?}", workflow.definition());
933 assert!(debug.starts_with("WorkflowDef"), "{debug}");
934 assert!(debug.contains("pipeline"), "{debug}");
935 }
936
937 #[test]
938 fn standalone_task_maps_to_a_one_task_workflow() {
939 let agent_run = TaskBuilder::<serde_json::Value, serde_json::Value>::new("Agent-Run")
940 .retries(1)
941 .execution_timeout(Duration::from_secs(2 * 3600))
942 .handler(|_ctx, input| async move { Ok(input) });
943
944 let request = agent_run.definition().to_request("dev_").unwrap();
945
946 assert_eq!(
947 request,
948 v1::CreateWorkflowVersionRequest {
949 name: "dev_agent-run".to_string(),
950 tasks: vec![v1::CreateTaskOpts {
951 readable_id: "Agent-Run".to_string(),
952 action: "dev_agent-run:agent-run".to_string(),
953 timeout: "7200s".to_string(),
954 inputs: "{}".to_string(),
955 retries: 1,
956 slot_requests: default_slots(),
957 ..Default::default()
958 }],
959 ..Default::default()
960 }
961 );
962 }
963
964 #[test]
967 fn a_durable_task_registers_as_durable_and_asks_for_a_durable_slot() {
968 let durable = TaskBuilder::<Value, Value>::new("approve")
969 .durable_handler(|_ctx, input| async move { Ok(input) });
970 let request = durable.definition().to_request("dev_").unwrap();
971
972 let task = &request.tasks[0];
973 assert!(task.is_durable);
974 assert_eq!(
975 task.slot_requests,
976 HashMap::from([("durable".to_string(), 1)])
977 );
978
979 let plain = self::task("fetch").definition().to_request("dev_").unwrap();
980 assert!(!plain.tasks[0].is_durable);
981 assert_eq!(plain.tasks[0].slot_requests, default_slots());
982 }
983
984 #[test]
986 fn a_declaration_reports_which_slot_kinds_it_needs() {
987 let durable = TaskBuilder::<Value, Value>::new("approve")
988 .durable_handler(|_ctx, input| async move { Ok(input) });
989 let plain = task("fetch");
990
991 let only_durable = durable.definition();
992 assert!(only_durable.has_durable());
993 assert!(!only_durable.has_default());
994
995 let only_default = plain.definition();
996 assert!(!only_default.has_durable());
997 assert!(only_default.has_default());
998
999 let mixed = Workflow::new("pipeline")
1000 .task(&plain)
1001 .task(&durable)
1002 .definition();
1003 assert!(mixed.has_durable());
1004 assert!(mixed.has_default());
1005
1006 let hooked = Workflow::new("hooked")
1009 .task(&plain)
1010 .on_failure(&durable)
1011 .definition();
1012 assert!(hooked.has_durable());
1013 }
1014
1015 #[test]
1016 fn without_a_namespace_names_are_only_lowercased() {
1017 let request = task("Agent-Run").definition().to_request("").unwrap();
1018 assert_eq!(request.name, "agent-run");
1019 assert_eq!(request.tasks[0].action, "agent-run:agent-run");
1020 }
1021
1022 #[test]
1023 fn a_name_that_already_carries_the_namespace_is_not_prefixed_again() {
1024 let request = task("dev_agent-run")
1025 .definition()
1026 .to_request("dev_")
1027 .unwrap();
1028 assert_eq!(request.name, "dev_agent-run");
1029 }
1030
1031 #[test]
1032 fn dag_parents_are_readable_ids() {
1033 let fetch = task("Fetch");
1034 let build = task("build").parent(&fetch);
1035 let workflow = Workflow::new("Pipeline").task(&fetch).task(&build);
1036
1037 let request = workflow.definition().to_request("dev_").unwrap();
1038
1039 assert_eq!(request.name, "dev_pipeline");
1040 assert_eq!(request.tasks.len(), 2);
1041 assert_eq!(request.tasks[0].readable_id, "Fetch");
1042 assert_eq!(request.tasks[0].action, "dev_pipeline:fetch");
1043 assert!(request.tasks[0].parents.is_empty());
1044 assert_eq!(request.tasks[1].readable_id, "build");
1045 assert_eq!(request.tasks[1].action, "dev_pipeline:build");
1046 assert_eq!(request.tasks[1].parents, ["Fetch"]);
1047 }
1048
1049 #[test]
1050 fn task_level_options_map_onto_create_task_opts() {
1051 let task = TaskBuilder::<serde_json::Value, serde_json::Value>::new("agent-run")
1052 .retries(2)
1053 .retry_backoff(1.5, 120)
1054 .execution_timeout(Duration::from_secs(90))
1055 .schedule_timeout(Duration::from_secs(30))
1056 .concurrency(
1057 Concurrency::expr("input.device_id")
1058 .max_runs(1)
1059 .strategy(ConcurrencyLimitStrategy::GroupRoundRobin),
1060 )
1061 .rate_limit(RateLimit::new("github-api", 2))
1062 .worker_label("os", DesiredLabel::eq("macos").required())
1063 .worker_label("mem", DesiredLabel::gte(8).weight(50))
1064 .handler(|_ctx, input| async move { Ok(input) });
1065
1066 let request = task.definition().to_request("").unwrap();
1067
1068 assert_eq!(
1069 request.tasks[0],
1070 v1::CreateTaskOpts {
1071 readable_id: "agent-run".to_string(),
1072 action: "agent-run:agent-run".to_string(),
1073 timeout: "90s".to_string(),
1074 schedule_timeout: Some("30s".to_string()),
1075 inputs: "{}".to_string(),
1076 retries: 2,
1077 backoff_factor: Some(1.5),
1078 backoff_max_seconds: Some(120),
1079 concurrency: vec![v1::Concurrency {
1080 expression: "input.device_id".to_string(),
1081 max_runs: Some(1),
1082 limit_strategy: Some(v1::ConcurrencyLimitStrategy::GroupRoundRobin as i32),
1083 ..Default::default()
1084 }],
1085 rate_limits: vec![v1::CreateTaskRateLimit {
1086 key: "github-api".to_string(),
1087 units: Some(2),
1088 ..Default::default()
1089 }],
1090 worker_labels: HashMap::from([
1091 (
1092 "os".to_string(),
1093 v1::DesiredWorkerLabels {
1094 str_value: Some("macos".to_string()),
1095 required: Some(true),
1096 comparator: Some(v1::WorkerLabelComparator::Equal as i32),
1097 ..Default::default()
1098 },
1099 ),
1100 (
1101 "mem".to_string(),
1102 v1::DesiredWorkerLabels {
1103 int_value: Some(8),
1104 required: Some(false),
1105 comparator: Some(v1::WorkerLabelComparator::GreaterThanOrEqual as i32),
1106 weight: Some(50),
1107 ..Default::default()
1108 },
1109 ),
1110 ]),
1111 slot_requests: default_slots(),
1112 ..Default::default()
1113 }
1114 );
1115 assert!(
1116 request.concurrency_arr.is_empty(),
1117 "task concurrency stays on the task"
1118 );
1119 assert!(request.concurrency.is_none());
1120 }
1121
1122 #[test]
1123 fn workflow_options_map_onto_the_request() {
1124 let workflow = Workflow::new("pipeline")
1125 .description("Build and ship")
1126 .version("v3")
1127 .on_events(["approval.granted"])
1128 .cron("0 * * * *")
1129 .cron_input(json!({"repo": "hatchet-rs"}))
1130 .default_priority(Priority::High)
1131 .concurrency(Concurrency::expr("input.repo").max_runs(2))
1132 .task(&task("build"));
1133
1134 let request = workflow.definition().to_request("dev_").unwrap();
1135
1136 assert_eq!(request.description, "Build and ship");
1137 assert_eq!(request.version, "v3");
1138 assert_eq!(
1139 request.event_triggers,
1140 ["dev_approval.granted"],
1141 "event keys are namespaced"
1142 );
1143 assert_eq!(
1144 request.cron_triggers,
1145 ["0 * * * *"],
1146 "cron expressions are not"
1147 );
1148 assert_eq!(
1149 request.cron_input.as_deref(),
1150 Some(r#"{"repo":"hatchet-rs"}"#)
1151 );
1152 assert_eq!(request.default_priority, Some(3));
1153 assert_eq!(
1154 request.concurrency_arr,
1155 [v1::Concurrency {
1156 expression: "input.repo".to_string(),
1157 max_runs: Some(2),
1158 ..Default::default()
1159 }]
1160 );
1161 assert!(
1162 request.concurrency.is_none(),
1163 "the singular field is never used"
1164 );
1165 }
1166
1167 #[test]
1168 fn standalone_trigger_options_map_onto_the_request() {
1169 let task = TaskBuilder::<serde_json::Value, serde_json::Value>::new("on-approval")
1170 .on_events(["approval.granted"])
1171 .cron("*/5 * * * *")
1172 .default_priority(Priority::Low)
1173 .handler(|_ctx, input| async move { Ok(input) });
1174
1175 let request = task.definition().to_request("dev_").unwrap();
1176
1177 assert_eq!(request.event_triggers, ["dev_approval.granted"]);
1178 assert_eq!(request.cron_triggers, ["*/5 * * * *"]);
1179 assert_eq!(request.default_priority, Some(1));
1180 }
1181
1182 #[test]
1183 fn duplicate_task_names_are_an_error_not_a_panic() {
1184 let workflow = Workflow::new("pipeline")
1185 .task(&task("build"))
1186 .task(&task("build"));
1187 let err = workflow.definition().to_request("").unwrap_err();
1188 assert!(matches!(err, Error::InvalidDeclaration(_)), "{err:?}");
1189 assert!(err.to_string().contains("build"), "{err}");
1190 }
1191
1192 #[test]
1193 fn task_names_that_collide_after_lowercasing_are_an_error() {
1194 let workflow = Workflow::new("pipeline")
1195 .task(&task("Build"))
1196 .task(&task("build"));
1197 let err = workflow.definition().to_request("").unwrap_err();
1198 assert!(matches!(err, Error::InvalidDeclaration(_)), "{err:?}");
1199 }
1200
1201 #[test]
1202 fn a_parent_outside_the_workflow_is_an_error_naming_it() {
1203 let fetch = task("fetch");
1204 let workflow = Workflow::new("pipeline").task(&task("build").parent(&fetch));
1205 let err = workflow.definition().to_request("").unwrap_err();
1206 assert!(matches!(err, Error::InvalidDeclaration(_)), "{err:?}");
1207 assert!(err.to_string().contains("fetch"), "{err}");
1208 }
1209
1210 #[test]
1211 fn a_hook_task_cannot_be_a_parent_of_an_ordinary_task() {
1212 for hook_is_on_failure in [true, false] {
1213 let hook = task("cleanup");
1214 let build = task("build").parent(&hook);
1215 let workflow = Workflow::new("pipeline").task(&task("fetch")).task(&build);
1216 let workflow = if hook_is_on_failure {
1217 workflow.on_failure(&hook)
1218 } else {
1219 workflow.on_success(&hook)
1220 };
1221 let err = workflow.definition().to_request("").unwrap_err();
1222 assert!(matches!(err, Error::InvalidDeclaration(_)), "{err:?}");
1223 assert!(err.to_string().contains("cleanup"), "{err}");
1224 }
1225 }
1226
1227 #[test]
1228 fn a_workflow_without_tasks_is_an_error() {
1229 let err = Workflow::new("empty")
1230 .definition()
1231 .to_request("")
1232 .unwrap_err();
1233 assert!(matches!(err, Error::InvalidDeclaration(_)), "{err:?}");
1234 }
1235
1236 #[test]
1237 fn empty_names_are_errors() {
1238 assert!(task("").definition().to_request("").is_err());
1239 assert!(
1240 Workflow::new("")
1241 .task(&task("a"))
1242 .definition()
1243 .to_request("")
1244 .is_err()
1245 );
1246 }
1247
1248 #[test]
1249 fn trigger_options_on_a_task_inside_a_workflow_are_an_error() {
1250 let triggered = TaskBuilder::<serde_json::Value, serde_json::Value>::new("build")
1251 .on_events(["push"])
1252 .handler(|_ctx, input| async move { Ok(input) });
1253 let err = Workflow::new("pipeline")
1254 .task(&triggered)
1255 .definition()
1256 .to_request("")
1257 .unwrap_err();
1258 assert!(matches!(err, Error::InvalidDeclaration(_)), "{err:?}");
1259 assert!(err.to_string().contains("build"), "{err}");
1260 }
1261
1262 #[test]
1263 fn standalone_parents_are_an_error() {
1264 let fetch = task("fetch");
1265 let err = task("build")
1266 .parent(&fetch)
1267 .definition()
1268 .to_request("")
1269 .unwrap_err();
1270 assert!(matches!(err, Error::InvalidDeclaration(_)), "{err:?}");
1271 }
1272
1273 #[test]
1274 fn actions_pair_each_action_id_with_its_handler() {
1275 let fetch = task("Fetch");
1276 let build = task("build").parent(&fetch);
1277 let fetch_handler = fetch.def.handler.clone();
1281 let build_handler = build.def.handler.clone();
1282 let definition = Workflow::new("Pipeline")
1283 .task(&fetch)
1284 .task(&build)
1285 .definition();
1286
1287 let actions = definition.actions("dev_").unwrap();
1288 let ids: Vec<&str> = actions.iter().map(|(id, _)| id.as_str()).collect();
1289 assert_eq!(ids, ["dev_pipeline:fetch", "dev_pipeline:build"]);
1290 assert_eq!(definition.wire_name("dev_"), "dev_pipeline");
1291
1292 let fetch_action = actions
1293 .iter()
1294 .find(|(id, _)| id == "dev_pipeline:fetch")
1295 .unwrap();
1296 let build_action = actions
1297 .iter()
1298 .find(|(id, _)| id == "dev_pipeline:build")
1299 .unwrap();
1300 assert!(
1301 Arc::ptr_eq(&fetch_action.1.handler, &fetch_handler),
1302 "dev_pipeline:fetch should be paired with fetch's own handler"
1303 );
1304 assert!(
1305 Arc::ptr_eq(&build_action.1.handler, &build_handler),
1306 "dev_pipeline:build should be paired with build's own handler"
1307 );
1308 assert!(
1309 !Arc::ptr_eq(&fetch_action.1.handler, &build_handler),
1310 "fetch's action must not be paired with build's handler"
1311 );
1312 }
1313
1314 #[test]
1317 fn an_eviction_policy_reaches_the_worker_and_never_the_wire() {
1318 let plain = TaskBuilder::<serde_json::Value, serde_json::Value>::new("approve")
1319 .durable_handler(|_ctx, input| async move { Ok(input) });
1320 let policy = crate::EvictionPolicy::ttl(Duration::from_secs(30)).priority(-3);
1321 let evictable = TaskBuilder::<serde_json::Value, serde_json::Value>::new("approve")
1322 .eviction_policy(policy.clone())
1323 .durable_handler(|_ctx, input| async move { Ok(input) });
1324
1325 assert_eq!(
1326 evictable.definition().to_request("dev_").unwrap(),
1327 plain.definition().to_request("dev_").unwrap(),
1328 );
1329 let actions = evictable.definition().actions("dev_").unwrap();
1330 assert_eq!(actions[0].1.eviction_policy.as_ref(), Some(&policy));
1331 assert!(actions[0].1.durable);
1332 assert_eq!(
1333 plain.definition().actions("dev_").unwrap()[0]
1334 .1
1335 .eviction_policy,
1336 None,
1337 );
1338 }
1339
1340 #[test]
1341 fn an_eviction_policy_on_an_ordinary_task_is_refused() {
1342 let wrong = TaskBuilder::<serde_json::Value, serde_json::Value>::new("approve")
1343 .eviction_policy(crate::EvictionPolicy::default())
1344 .handler(|_ctx, input| async move { Ok(input) });
1345 let err = wrong.definition().to_request("dev_").unwrap_err();
1346 assert!(matches!(err, Error::InvalidDeclaration(_)), "{err:?}");
1347 assert!(err.to_string().contains("durable_handler"), "{err}");
1348 let inside = Workflow::new("pipeline").task(&wrong).definition();
1350 assert!(
1351 matches!(inside.actions("dev_"), Err(Error::InvalidDeclaration(_))),
1352 "a policy on an ordinary task in a workflow is refused too",
1353 );
1354 let err = Workflow::new("pipeline")
1355 .task(&task("build"))
1356 .on_failure(&wrong)
1357 .definition()
1358 .to_request("dev_")
1359 .unwrap_err();
1360 assert!(matches!(err, Error::InvalidDeclaration(_)), "{err:?}");
1361 }
1362
1363 #[test]
1364 fn an_eviction_policy_with_no_ttl_at_all_is_refused() {
1365 let never = TaskBuilder::<serde_json::Value, serde_json::Value>::new("approve")
1366 .eviction_policy(crate::EvictionPolicy::ttl(Duration::ZERO))
1367 .durable_handler(|_ctx, input| async move { Ok(input) });
1368 let err = never.definition().to_request("dev_").unwrap_err();
1369 assert!(matches!(err, Error::InvalidDeclaration(_)), "{err:?}");
1370 assert!(err.to_string().contains("TTL"), "{err}");
1371 TaskBuilder::<serde_json::Value, serde_json::Value>::new("approve")
1373 .eviction_policy(crate::EvictionPolicy::ttl(Duration::from_millis(1)))
1374 .durable_handler(|_ctx, input| async move { Ok(input) })
1375 .definition()
1376 .to_request("dev_")
1377 .unwrap();
1378 }
1379
1380 #[test]
1381 fn actions_reject_what_to_request_rejects() {
1382 let definition = Workflow::new("pipeline")
1383 .task(&task("build"))
1384 .task(&task("build"))
1385 .definition();
1386
1387 assert!(
1388 matches!(definition.actions(""), Err(Error::InvalidDeclaration(_))),
1389 "actions should reject what to_request rejects"
1390 );
1391 assert!(matches!(
1392 definition.to_request(""),
1393 Err(Error::InvalidDeclaration(_))
1394 ));
1395 }
1396
1397 #[test]
1398 fn whitespace_only_names_are_invalid() {
1399 let err = task(" ").definition().to_request("").unwrap_err();
1400 assert!(matches!(err, Error::InvalidDeclaration(_)), "{err:?}");
1401
1402 let err = Workflow::new("pipeline")
1403 .task(&task(" "))
1404 .definition()
1405 .to_request("")
1406 .unwrap_err();
1407 assert!(matches!(err, Error::InvalidDeclaration(_)), "{err:?}");
1408 assert!(err.to_string().contains("pipeline"), "{err}");
1409 }
1410
1411 #[test]
1412 fn a_colon_in_a_name_is_invalid() {
1413 let err = Workflow::new("dev:pipeline")
1414 .task(&task("build"))
1415 .definition()
1416 .to_request("")
1417 .unwrap_err();
1418 assert!(matches!(err, Error::InvalidDeclaration(_)), "{err:?}");
1419 assert!(err.to_string().contains("dev:pipeline"), "{err}");
1420
1421 let err = Workflow::new("pipeline")
1422 .task(&task("build:step"))
1423 .definition()
1424 .to_request("")
1425 .unwrap_err();
1426 assert!(matches!(err, Error::InvalidDeclaration(_)), "{err:?}");
1427 assert!(err.to_string().contains("build:step"), "{err}");
1428 }
1429
1430 #[test]
1431 fn a_task_that_lists_itself_as_a_parent_is_invalid_inside_a_workflow() {
1432 let a = task("s");
1433 let err = Workflow::new("w")
1434 .task(&a.clone().parent(&a))
1435 .definition()
1436 .to_request("")
1437 .unwrap_err();
1438 assert!(matches!(err, Error::InvalidDeclaration(_)), "{err:?}");
1439 assert!(err.to_string().contains('s'), "{err}");
1440 }
1441
1442 #[test]
1443 fn a_standalone_task_that_lists_itself_as_a_parent_says_standalone_tasks_cannot_have_parents() {
1444 let a = task("s");
1445 let err = a
1446 .clone()
1447 .parent(&a)
1448 .definition()
1449 .to_request("")
1450 .unwrap_err();
1451 assert!(matches!(err, Error::InvalidDeclaration(_)), "{err:?}");
1452 assert!(
1453 err.to_string()
1454 .contains("standalone task cannot have parents"),
1455 "{err}"
1456 );
1457 }
1458
1459 #[test]
1460 fn a_cycle_among_task_parents_is_invalid_and_names_a_task_on_it() {
1461 let a0 = task("a");
1462 let b = task("b").parent(&a0);
1463 let a = task("a").parent(&b);
1464 let err = Workflow::new("w")
1465 .task(&a)
1466 .task(&b)
1467 .definition()
1468 .to_request("")
1469 .unwrap_err();
1470 assert!(matches!(err, Error::InvalidDeclaration(_)), "{err:?}");
1471 let message = err.to_string();
1472 assert!(message.contains('a') || message.contains('b'), "{message}");
1473 }
1474
1475 #[test]
1476 fn concurrency_max_runs_zero_is_invalid_at_workflow_level() {
1477 let err = Workflow::new("pipeline")
1478 .concurrency(Concurrency::expr("input.repo").max_runs(0))
1479 .task(&task("build"))
1480 .definition()
1481 .to_request("")
1482 .unwrap_err();
1483 assert!(matches!(err, Error::InvalidDeclaration(_)), "{err:?}");
1484 assert!(err.to_string().contains("max_runs"), "{err}");
1485 }
1486
1487 #[test]
1488 fn concurrency_max_runs_zero_is_invalid_at_task_level() {
1489 let bad_task = TaskBuilder::<serde_json::Value, serde_json::Value>::new("build")
1490 .concurrency(Concurrency::expr("input.repo").max_runs(0))
1491 .handler(|_ctx, input| async move { Ok(input) });
1492 let err = Workflow::new("pipeline")
1493 .task(&bad_task)
1494 .definition()
1495 .to_request("")
1496 .unwrap_err();
1497 assert!(matches!(err, Error::InvalidDeclaration(_)), "{err:?}");
1498 assert!(err.to_string().contains("max_runs"), "{err}");
1499 }
1500
1501 #[test]
1502 fn a_dynamic_rate_limit_without_a_limit_is_an_invalid_declaration() {
1503 let bad_task = TaskBuilder::<serde_json::Value, serde_json::Value>::new("build")
1504 .rate_limit(RateLimit::dynamic("input.tenant"))
1505 .handler(|_ctx, input| async move { Ok(input) });
1506 let err = Workflow::new("pipeline")
1507 .task(&bad_task)
1508 .definition()
1509 .to_request("")
1510 .unwrap_err();
1511 assert!(matches!(err, Error::InvalidDeclaration(_)), "{err:?}");
1512 assert!(err.to_string().contains("limit_expr"), "{err}");
1513 }
1514
1515 #[test]
1516 fn a_task_without_timeouts_maps_to_the_engine_defaults() {
1517 let request = task("build").definition().to_request("").unwrap();
1518 assert_eq!(request.tasks[0].timeout, "");
1519 assert_eq!(request.tasks[0].schedule_timeout, None);
1520 }
1521
1522 #[test]
1523 fn task_level_concurrency_inside_a_workflow_stays_on_the_task() {
1524 let concurrent_task = TaskBuilder::<serde_json::Value, serde_json::Value>::new("build")
1525 .concurrency(Concurrency::expr("input.repo").max_runs(1))
1526 .handler(|_ctx, input| async move { Ok(input) });
1527 let request = Workflow::new("pipeline")
1528 .task(&concurrent_task)
1529 .definition()
1530 .to_request("")
1531 .unwrap();
1532
1533 assert_eq!(
1534 request.tasks[0].concurrency,
1535 [v1::Concurrency {
1536 expression: "input.repo".to_string(),
1537 max_runs: Some(1),
1538 ..Default::default()
1539 }]
1540 );
1541 assert!(
1542 request.concurrency_arr.is_empty(),
1543 "task-level concurrency must not leak into the workflow-level field"
1544 );
1545 }
1546
1547 #[test]
1548 fn an_on_failure_task_maps_to_its_own_field_and_not_to_tasks() {
1549 let build = task("build");
1550 let cleanup = task("cleanup");
1551 let definition = Workflow::new("pipeline")
1552 .task(&build)
1553 .on_failure(&cleanup)
1554 .definition();
1555
1556 let request = definition.to_request("dev_").unwrap();
1557 assert_eq!(
1558 task_names(&definition.tasks),
1559 ["build"],
1560 "the on-failure task is not one of the workflow's tasks"
1561 );
1562 assert_eq!(request.tasks.len(), 1);
1563 assert_eq!(request.tasks[0].readable_id, "build");
1564 let on_failure = request
1565 .on_failure_task
1566 .expect("the on-failure task is sent in its own field");
1567 assert_eq!(
1568 on_failure,
1569 v1::CreateTaskOpts {
1570 readable_id: "cleanup".to_string(),
1571 action: "dev_pipeline:cleanup".to_string(),
1572 inputs: "{}".to_string(),
1573 slot_requests: default_slots(),
1574 ..Default::default()
1575 }
1576 );
1577
1578 let ids: Vec<String> = definition
1579 .actions("dev_")
1580 .unwrap()
1581 .into_iter()
1582 .map(|(id, _)| id)
1583 .collect();
1584 assert_eq!(
1585 ids,
1586 ["dev_pipeline:build", "dev_pipeline:cleanup"],
1587 "the worker must register the on-failure action too"
1588 );
1589 }
1590
1591 #[test]
1592 fn the_same_task_in_task_and_on_failure_is_an_error_not_a_panic() {
1593 let build = task("build");
1594 let err = Workflow::new("pipeline")
1595 .task(&build)
1596 .on_failure(&build)
1597 .definition()
1598 .to_request("")
1599 .unwrap_err();
1600 assert!(matches!(err, Error::InvalidDeclaration(_)), "{err:?}");
1601 assert!(err.to_string().contains("build"), "{err}");
1602 }
1603
1604 #[test]
1605 fn declaring_two_on_failure_tasks_is_an_error() {
1606 let err = Workflow::new("pipeline")
1607 .task(&task("build"))
1608 .on_failure(&task("a"))
1609 .on_failure(&task("b"))
1610 .definition()
1611 .to_request("")
1612 .unwrap_err();
1613 assert!(matches!(err, Error::InvalidDeclaration(_)), "{err:?}");
1614 assert!(err.to_string().contains("on_failure"), "{err}");
1615 }
1616
1617 #[test]
1618 fn an_on_failure_task_with_a_parent_is_an_error() {
1619 let build = task("build");
1620 let err = Workflow::new("pipeline")
1621 .task(&build)
1622 .on_failure(&task("cleanup").parent(&build))
1623 .definition()
1624 .to_request("")
1625 .unwrap_err();
1626 assert!(matches!(err, Error::InvalidDeclaration(_)), "{err:?}");
1627 assert!(err.to_string().contains("cleanup"), "{err}");
1628 }
1629
1630 #[test]
1631 fn standalone_only_options_on_an_on_failure_task_are_an_error() {
1632 let triggered = TaskBuilder::<serde_json::Value, serde_json::Value>::new("cleanup")
1633 .on_events(["push"])
1634 .handler(|_ctx, input| async move { Ok(input) });
1635 let err = Workflow::new("pipeline")
1636 .task(&task("build"))
1637 .on_failure(&triggered)
1638 .definition()
1639 .to_request("")
1640 .unwrap_err();
1641 assert!(matches!(err, Error::InvalidDeclaration(_)), "{err:?}");
1642 assert!(err.to_string().contains("cleanup"), "{err}");
1643 }
1644
1645 #[test]
1646 fn an_on_success_task_is_an_ordinary_task_parented_on_every_leaf() {
1647 let fetch = task("fetch");
1649 let build = task("build").parent(&fetch);
1650 let package = task("package").parent(&build);
1651 let lint = task("lint").parent(&fetch);
1652 let announce = task("announce");
1653
1654 let request = Workflow::new("pipeline")
1655 .task(&fetch)
1656 .task(&build)
1657 .task(&package)
1658 .task(&lint)
1659 .on_success(&announce)
1660 .definition()
1661 .to_request("dev_")
1662 .unwrap();
1663
1664 assert_eq!(
1665 request
1666 .tasks
1667 .iter()
1668 .map(|task| task.readable_id.as_str())
1669 .collect::<Vec<_>>(),
1670 ["fetch", "build", "package", "lint", "announce"],
1671 "the on-success task is the last of the workflow's tasks"
1672 );
1673 let announce_opts = request.tasks.last().unwrap();
1674 assert_eq!(announce_opts.action, "dev_pipeline:announce");
1675 assert_eq!(
1676 announce_opts.parents,
1677 ["package", "lint"],
1678 "its parents are exactly the leaves, in declaration order"
1679 );
1680 assert!(request.on_failure_task.is_none());
1681 }
1682
1683 #[test]
1684 fn a_single_task_workflow_parents_its_on_success_task_on_that_task() {
1685 let build = task("build");
1686 let request = Workflow::new("pipeline")
1687 .task(&build)
1688 .on_success(&task("announce"))
1689 .definition()
1690 .to_request("")
1691 .unwrap();
1692 assert_eq!(request.tasks.last().unwrap().parents, ["build"]);
1693 }
1694
1695 #[test]
1696 fn an_on_success_task_may_not_collide_with_a_task_or_be_declared_twice() {
1697 let build = task("build");
1698 let err = Workflow::new("pipeline")
1699 .task(&build)
1700 .on_success(&build)
1701 .definition()
1702 .to_request("")
1703 .unwrap_err();
1704 assert!(matches!(err, Error::InvalidDeclaration(_)), "{err:?}");
1705
1706 let err = Workflow::new("pipeline")
1707 .task(&task("build"))
1708 .on_success(&task("a"))
1709 .on_success(&task("b"))
1710 .definition()
1711 .to_request("")
1712 .unwrap_err();
1713 assert!(matches!(err, Error::InvalidDeclaration(_)), "{err:?}");
1714 assert!(err.to_string().contains("on_success"), "{err}");
1715 }
1716
1717 #[test]
1718 fn on_success_and_on_failure_may_not_share_a_name() {
1719 let err = Workflow::new("pipeline")
1720 .task(&task("build"))
1721 .on_failure(&task("after"))
1722 .on_success(&task("After"))
1723 .definition()
1724 .to_request("")
1725 .unwrap_err();
1726 assert!(matches!(err, Error::InvalidDeclaration(_)), "{err:?}");
1727 }
1728
1729 #[test]
1730 fn an_on_success_task_is_registered_as_an_action() {
1731 let definition = Workflow::new("pipeline")
1732 .task(&task("build"))
1733 .on_failure(&task("cleanup"))
1734 .on_success(&task("announce"))
1735 .definition();
1736 let ids: Vec<String> = definition
1737 .actions("")
1738 .unwrap()
1739 .into_iter()
1740 .map(|(id, _)| id)
1741 .collect();
1742 assert_eq!(
1743 ids,
1744 ["pipeline:build", "pipeline:cleanup", "pipeline:announce"]
1745 );
1746 }
1747
1748 #[test]
1749 fn workflow_concurrency_on_a_standalone_task_goes_to_the_workflow_field() {
1750 let agent_run = TaskBuilder::<serde_json::Value, serde_json::Value>::new("agent-run")
1751 .workflow_concurrency(Concurrency::expr("input.key").max_runs(1))
1752 .handler(|_ctx, input| async move { Ok(input) });
1753
1754 let request = agent_run.definition().to_request("").unwrap();
1755
1756 assert_eq!(
1757 request.concurrency_arr,
1758 [v1::Concurrency {
1759 expression: "input.key".to_string(),
1760 max_runs: Some(1),
1761 ..Default::default()
1762 }]
1763 );
1764 assert!(
1765 request.tasks[0].concurrency.is_empty(),
1766 "workflow-level concurrency must not land on the task"
1767 );
1768 assert!(
1769 request.concurrency.is_none(),
1770 "the singular field is never used"
1771 );
1772 }
1773
1774 #[test]
1775 fn task_concurrency_on_a_standalone_task_stays_on_the_task() {
1776 let agent_run = TaskBuilder::<serde_json::Value, serde_json::Value>::new("agent-run")
1777 .concurrency(Concurrency::expr("input.key").max_runs(1))
1778 .handler(|_ctx, input| async move { Ok(input) });
1779
1780 let request = agent_run.definition().to_request("").unwrap();
1781
1782 assert_eq!(request.tasks[0].concurrency.len(), 1);
1783 assert!(request.concurrency_arr.is_empty());
1784 }
1785
1786 #[test]
1787 fn workflow_concurrency_on_a_task_inside_a_workflow_is_an_error() {
1788 let bad = TaskBuilder::<serde_json::Value, serde_json::Value>::new("build")
1789 .workflow_concurrency(Concurrency::expr("input.key").max_runs(1))
1790 .handler(|_ctx, input| async move { Ok(input) });
1791 let err = Workflow::new("pipeline")
1792 .task(&bad)
1793 .definition()
1794 .to_request("")
1795 .unwrap_err();
1796 assert!(matches!(err, Error::InvalidDeclaration(_)), "{err:?}");
1797 assert!(err.to_string().contains("workflow concurrency"), "{err}");
1798 }
1799
1800 #[test]
1801 fn a_tenant_scoped_entry_without_a_name_is_rejected_at_registration() {
1802 let err = Workflow::new("pipeline")
1803 .concurrency(Concurrency::expr("input.tenant").tenant_scoped())
1804 .task(&task("build"))
1805 .definition()
1806 .to_request("")
1807 .unwrap_err();
1808 assert!(matches!(err, Error::InvalidDeclaration(_)), "{err:?}");
1809 assert!(err.to_string().contains("name"), "{err}");
1810 }
1811
1812 #[test]
1816 fn a_wait_for_sleep_maps_to_a_queue_sleep_condition() {
1817 let gated = TaskBuilder::<serde_json::Value, serde_json::Value>::new("gated")
1818 .wait_for(Condition::sleep(Duration::from_secs(30)))
1819 .handler(|_ctx, input| async move { Ok(input) });
1820 let request = Workflow::new("pipeline")
1821 .task(&gated)
1822 .definition()
1823 .to_request("dev_")
1824 .unwrap();
1825
1826 let conditions = request.tasks[0]
1827 .conditions
1828 .as_ref()
1829 .expect("the task carries conditions");
1830 assert!(conditions.user_event_conditions.is_empty());
1831 assert!(conditions.parent_override_conditions.is_empty());
1832 let [sleep] = conditions.sleep_conditions.as_slice() else {
1833 panic!("one sleep condition: {conditions:?}");
1834 };
1835 assert_eq!(sleep.sleep_for, "30000ms");
1836 let base = sleep.base.as_ref().unwrap();
1837 assert_eq!(base.action, v1::Action::Queue as i32);
1838 assert_eq!(base.readable_data_key, "sleep:30000ms");
1839 assert_eq!(base.or_group_id.len(), 36);
1840 }
1841
1842 #[test]
1844 fn a_skip_if_parent_maps_to_a_skip_parent_override_condition() {
1845 let a = task("a");
1846 let b = TaskBuilder::<serde_json::Value, serde_json::Value>::new("b")
1847 .skip_if(Condition::parent(&a).expression("output.ok == false"))
1848 .handler(|_ctx, input| async move { Ok(input) })
1849 .parent(&a);
1850 let request = Workflow::new("pipeline")
1851 .task(&a)
1852 .task(&b)
1853 .definition()
1854 .to_request("dev_")
1855 .unwrap();
1856
1857 let conditions = request.tasks[1].conditions.as_ref().expect("conditions");
1858 let [parent] = conditions.parent_override_conditions.as_slice() else {
1859 panic!("one parent condition: {conditions:?}");
1860 };
1861 assert_eq!(parent.parent_readable_id, "a");
1862 let base = parent.base.as_ref().unwrap();
1863 assert_eq!(base.action, v1::Action::Skip as i32);
1864 assert_eq!(base.expression, "output.ok == false");
1865 assert!(
1866 request.tasks[0].conditions.is_none(),
1867 "`a` has no conditions"
1868 );
1869 }
1870
1871 #[test]
1875 fn a_cancel_if_event_is_namespaced() {
1876 let gated = TaskBuilder::<serde_json::Value, serde_json::Value>::new("gated")
1877 .wait_for(Condition::sleep(Duration::from_secs(60)))
1878 .cancel_if(Condition::on_event("kill"))
1879 .handler(|_ctx, input| async move { Ok(input) });
1880 let request = Workflow::new("pipeline")
1881 .task(&gated)
1882 .definition()
1883 .to_request("dev_")
1884 .unwrap();
1885
1886 let conditions = request.tasks[0].conditions.as_ref().expect("conditions");
1887 let [event] = conditions.user_event_conditions.as_slice() else {
1888 panic!("one event condition: {conditions:?}");
1889 };
1890 assert_eq!(event.user_event_key, "dev_kill");
1891 let base = event.base.as_ref().unwrap();
1892 assert_eq!(base.action, v1::Action::Cancel as i32);
1893 assert_eq!(base.readable_data_key, "kill");
1894 }
1895
1896 #[test]
1899 fn two_conditions_sharing_a_readable_key_are_an_error() {
1900 let gated = TaskBuilder::<serde_json::Value, serde_json::Value>::new("gated")
1901 .wait_for(Condition::on_event("go"))
1902 .skip_if(Condition::on_event("go"))
1903 .handler(|_ctx, input| async move { Ok(input) });
1904 let err = Workflow::new("pipeline")
1905 .task(&gated)
1906 .definition()
1907 .to_request("dev_")
1908 .unwrap_err();
1909 assert!(matches!(err, Error::InvalidDeclaration(_)), "{err:?}");
1910 assert!(err.to_string().contains("gated"), "{err}");
1911 assert!(err.to_string().contains("readable_key"), "{err}");
1912 }
1913
1914 #[test]
1915 fn a_parent_condition_naming_a_task_that_is_not_a_parent_is_an_error() {
1916 let a = task("a");
1917 let b = TaskBuilder::<serde_json::Value, serde_json::Value>::new("b")
1918 .skip_if(Condition::parent(&a).expression("output.ok"))
1919 .handler(|_ctx, input| async move { Ok(input) });
1920 let err = Workflow::new("pipeline")
1922 .task(&a)
1923 .task(&b)
1924 .definition()
1925 .to_request("")
1926 .unwrap_err();
1927 assert!(matches!(err, Error::InvalidDeclaration(_)), "{err:?}");
1928 assert!(err.to_string().contains("`a`"), "{err}");
1929 assert!(err.to_string().contains("parent"), "{err}");
1930 }
1931
1932 #[test]
1937 fn a_parent_condition_whose_case_differs_from_the_parent_is_an_error() {
1938 let a = task("a");
1939 let b = TaskBuilder::<serde_json::Value, serde_json::Value>::new("b")
1940 .skip_if(Condition::parent_by_name("A").expression("output.ok"))
1941 .handler(|_ctx, input| async move { Ok(input) })
1942 .parent(&a);
1943 let err = Workflow::new("pipeline")
1944 .task(&a)
1945 .task(&b)
1946 .definition()
1947 .to_request("")
1948 .unwrap_err();
1949 assert!(matches!(err, Error::InvalidDeclaration(_)), "{err:?}");
1950 assert!(err.to_string().contains("`A`"), "{err}");
1951 assert!(err.to_string().contains("parent"), "{err}");
1952 }
1953
1954 #[test]
1955 fn a_parent_condition_on_a_standalone_task_is_an_error() {
1956 let lonely = TaskBuilder::<serde_json::Value, serde_json::Value>::new("lonely")
1957 .wait_for(Condition::parent_by_name("nobody"))
1958 .handler(|_ctx, input| async move { Ok(input) });
1959 let err = lonely.definition().to_request("").unwrap_err();
1960 assert!(matches!(err, Error::InvalidDeclaration(_)), "{err:?}");
1961 assert!(err.to_string().contains("nobody"), "{err}");
1962 }
1963
1964 #[test]
1965 fn a_standalone_task_may_still_wait_for_a_sleep_or_an_event() {
1966 let lonely = TaskBuilder::<serde_json::Value, serde_json::Value>::new("lonely")
1967 .wait_for(Condition::sleep(Duration::from_secs(5)))
1968 .cancel_if(Condition::on_event("stop"))
1969 .handler(|_ctx, input| async move { Ok(input) });
1970 let request = lonely.definition().to_request("dev_").unwrap();
1971 let conditions = request.tasks[0].conditions.as_ref().expect("conditions");
1972 assert_eq!(conditions.sleep_conditions.len(), 1);
1973 assert_eq!(conditions.user_event_conditions.len(), 1);
1974 }
1975
1976 #[test]
1979 fn a_skip_if_event_without_a_wait_for_is_an_error() {
1980 let gated = TaskBuilder::<serde_json::Value, serde_json::Value>::new("gated")
1981 .skip_if(Condition::on_event("skip"))
1982 .handler(|_ctx, input| async move { Ok(input) });
1983 let err = Workflow::new("pipeline")
1984 .task(&task("build"))
1985 .task(&gated)
1986 .definition()
1987 .to_request("")
1988 .unwrap_err();
1989 assert!(matches!(err, Error::InvalidDeclaration(_)), "{err:?}");
1990 assert!(err.to_string().contains("gated"), "{err}");
1991 assert!(err.to_string().contains("wait_for"), "{err}");
1992 }
1993
1994 #[test]
1998 fn conditions_on_the_on_failure_hook_are_an_error() {
1999 let cleanup = TaskBuilder::<serde_json::Value, serde_json::Value>::new("cleanup")
2000 .wait_for(Condition::sleep(Duration::from_secs(5)))
2001 .handler(|_ctx, input| async move { Ok(input) });
2002 let err = Workflow::new("pipeline")
2003 .task(&task("build"))
2004 .on_failure(&cleanup)
2005 .definition()
2006 .to_request("")
2007 .unwrap_err();
2008 assert!(matches!(err, Error::InvalidDeclaration(_)), "{err:?}");
2009 assert!(err.to_string().contains("cleanup"), "{err}");
2010 assert!(err.to_string().contains("on_failure"), "{err}");
2011 }
2012
2013 #[test]
2014 fn the_on_success_hook_may_carry_conditions_but_only_on_a_leaf() {
2015 let build = task("build");
2016 let announce = TaskBuilder::<serde_json::Value, serde_json::Value>::new("announce")
2017 .skip_if(Condition::parent(&build).expression("output.quiet == true"))
2018 .handler(|_ctx, input| async move { Ok(input) });
2019 let request = Workflow::new("pipeline")
2020 .task(&build)
2021 .on_success(&announce)
2022 .definition()
2023 .to_request("")
2024 .unwrap();
2025 let hook = request.tasks.last().expect("the on-success task is last");
2026 assert_eq!(hook.readable_id, "announce");
2027 assert_eq!(hook.parents, ["build"]);
2028 assert_eq!(
2029 hook.conditions
2030 .as_ref()
2031 .expect("conditions")
2032 .parent_override_conditions[0]
2033 .parent_readable_id,
2034 "build"
2035 );
2036
2037 let stray = TaskBuilder::<serde_json::Value, serde_json::Value>::new("announce")
2038 .skip_if(Condition::parent_by_name("root").expression("output.x"))
2039 .handler(|_ctx, input| async move { Ok(input) });
2040 let root = task("root");
2041 let leaf = task("leaf").parent(&root);
2042 let err = Workflow::new("pipeline")
2043 .task(&root)
2044 .task(&leaf)
2045 .on_success(&stray)
2046 .definition()
2047 .to_request("")
2048 .unwrap_err();
2049 assert!(matches!(err, Error::InvalidDeclaration(_)), "{err:?}");
2050 assert!(err.to_string().contains("root"), "{err}");
2051 }
2052
2053 #[test]
2054 fn a_sticky_workflow_carries_its_strategy() {
2055 let request = Workflow::new("pipeline")
2056 .sticky(StickyStrategy::Hard)
2057 .task(&task("work"))
2058 .definition()
2059 .to_request("dev_")
2060 .unwrap();
2061 assert_eq!(request.sticky, Some(v1::StickyStrategy::Hard as i32));
2062 }
2063
2064 #[test]
2065 fn a_workflow_without_sticky_leaves_the_field_unset() {
2066 let request = Workflow::new("pipeline")
2067 .task(&task("work"))
2068 .definition()
2069 .to_request("dev_")
2070 .unwrap();
2071 assert_eq!(request.sticky, None);
2072 }
2073
2074 #[test]
2075 fn a_standalone_task_carries_its_own_sticky_strategy() {
2076 let solo = TaskBuilder::<(), ()>::new("solo")
2077 .sticky(StickyStrategy::Soft)
2078 .handler(|_ctx, _input| async { Ok(()) });
2079 let request = solo.definition().to_request("dev_").unwrap();
2080 assert_eq!(request.sticky, Some(v1::StickyStrategy::Soft as i32));
2081 }
2082
2083 #[test]
2084 fn sticky_on_a_task_inside_a_workflow_is_a_standalone_only_option() {
2085 let work = TaskBuilder::<(), ()>::new("work")
2086 .sticky(StickyStrategy::Hard)
2087 .handler(|_ctx, _input| async { Ok(()) });
2088 let error = Workflow::new("pipeline")
2089 .task(&work)
2090 .definition()
2091 .to_request("dev_")
2092 .unwrap_err();
2093 assert!(matches!(error, Error::InvalidDeclaration(_)), "{error:?}");
2094 assert!(error.to_string().contains("standalone-only"), "{error}");
2095 }
2096
2097 #[test]
2098 fn an_idempotent_workflow_carries_its_config() {
2099 let request = Workflow::new("checkout")
2100 .idempotency(Idempotency::until_run_ends(
2101 "input.order_id",
2102 Duration::from_secs(600),
2103 ))
2104 .task(&task("charge"))
2105 .definition()
2106 .to_request("dev_")
2107 .unwrap();
2108 assert_eq!(
2109 request.idempotency,
2110 Some(v1::IdempotencyConfig {
2111 expression: "input.order_id".to_string(),
2112 ttl_ms: 600_000,
2113 method: Some(v1::IdempotencyMethod::Status as i32),
2114 })
2115 );
2116 }
2117
2118 #[test]
2119 fn an_empty_idempotency_expression_is_an_invalid_declaration_not_a_panic() {
2120 let error = Workflow::new("checkout")
2121 .idempotency(Idempotency::ttl("", Duration::from_secs(60)))
2122 .task(&task("charge"))
2123 .definition()
2124 .to_request("dev_")
2125 .unwrap_err();
2126 assert!(matches!(error, Error::InvalidDeclaration(_)), "{error:?}");
2127 assert!(error.to_string().contains("checkout"), "{error}");
2128 }
2129
2130 #[test]
2131 fn a_task_added_to_a_workflow_is_still_usable_afterwards() {
2132 let fetch = task("fetch");
2133 let build = task("build").parent(&fetch);
2134 let workflow = Workflow::new("pipeline").task(&fetch).task(&build);
2135
2136 assert_eq!(fetch.name(), "fetch");
2140 assert_eq!(build.name(), "build");
2141 assert_eq!(task_names(&workflow.definition().tasks), ["fetch", "build"]);
2142 }
2143}