Skip to main content

hatchet_client/declare/
workflow.rs

1//! Workflows, and the mapping from a declaration to the registration request.
2
3use 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
21/// Something a worker can register: a standalone [`Task`] or a [`Workflow`].
22pub trait Register: sealed::Sealed {
23    /// The type-erased declaration.
24    #[doc(hidden)]
25    fn definition(&self) -> WorkflowDef;
26}
27
28/// A named set of tasks, ordered into a DAG by their parents.
29///
30/// Every task in a workflow receives the *workflow's* input; a task reads
31/// what came before it with
32/// [`Context::parent_output`](crate::Context::parent_output). Triggers
33/// (events, crons), the description, the version and the default priority
34/// belong to the workflow rather than to its tasks.
35///
36/// Parents are attached to a task before it is moved in, so declare them in
37/// dependency order:
38///
39/// ```
40/// use hatchet_client::{TaskBuilder, Workflow};
41///
42/// let fetch = TaskBuilder::<(), u32>::new("fetch").handler(|_ctx, _input| async { Ok(21) });
43/// let summarize = TaskBuilder::<(), String>::new("summarize")
44///     .handler({
45///         let fetch = fetch.clone();
46///         move |ctx: hatchet_client::Context, _input: ()| {
47///             let fetch = fetch.clone();
48///             async move {
49///                 let total: u32 = ctx.parent_output(&fetch)?;
50///                 Ok(format!("total {total}"))
51///             }
52///         }
53///     })
54///     .parent(&fetch);
55///
56/// let pipeline = Workflow::new("pipeline")
57///     .cron("0 * * * *")
58///     .task(&fetch)
59///     .task(&summarize);
60/// assert_eq!(pipeline.name(), "pipeline");
61/// ```
62///
63/// Mistakes — duplicate task names, a parent that was never added, trigger
64/// options set on a task instead of on the workflow — are reported as
65/// [`Error::InvalidDeclaration`] when the workflow is registered.
66#[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    /// The task to run when the workflow fails. At most one; a second
73    /// declaration is reported by `validate`, not by a panic.
74    on_failure: Vec<TaskDef>,
75    /// The task to run once, after every other task has succeeded. At most
76    /// one; a second declaration is reported by `validate`, not by a panic.
77    on_success: Vec<TaskDef>,
78    /// Tasks that carried standalone-only options; reported at registration.
79    tasks_with_standalone_options: Vec<String>,
80}
81
82/// Names the workflow and its tasks; the tasks' handlers are closures with
83/// nothing to print.
84impl 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    /// Starts declaring a workflow.
109    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    /// The workflow's name as declared.
121    pub fn name(&self) -> &str {
122        &self.name
123    }
124
125    /// Describes the workflow.
126    pub fn description(mut self, description: impl Into<String>) -> Self {
127        self.options.description = Some(description.into());
128        self
129    }
130
131    /// Labels this version of the workflow.
132    pub fn version(mut self, version: impl Into<String>) -> Self {
133        self.options.version = Some(version.into());
134        self
135    }
136
137    /// Runs the workflow whenever one of these event keys is pushed. May be
138    /// called repeatedly; event keys accumulate.
139    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    /// Runs the workflow on a cron schedule. May be called repeatedly; cron
147    /// expressions accumulate.
148    pub fn cron(mut self, expression: impl Into<String>) -> Self {
149        self.options.on_crons.push(expression.into());
150        self
151    }
152
153    /// The input given to cron-triggered runs.
154    pub fn cron_input(mut self, input: Value) -> Self {
155        self.options.cron_input = Some(input);
156        self
157    }
158
159    /// The priority of runs that do not specify one.
160    pub fn default_priority(mut self, priority: Priority) -> Self {
161        self.options.default_priority = Some(priority);
162        self
163    }
164
165    /// Adds a concurrency limit across runs of the whole workflow.
166    pub fn concurrency(mut self, concurrency: Concurrency) -> Self {
167        self.options.concurrency.push(concurrency);
168        self
169    }
170
171    /// Pins each run's tasks to one worker.
172    ///
173    /// ```
174    /// use hatchet_client::{StickyStrategy, TaskBuilder, Workflow};
175    ///
176    /// let load = TaskBuilder::<(), ()>::new("load").handler(|_ctx, _input| async { Ok(()) });
177    /// let build = Workflow::new("build").sticky(StickyStrategy::Hard).task(&load);
178    /// # let _ = build;
179    /// ```
180    pub fn sticky(mut self, strategy: StickyStrategy) -> Self {
181        self.options.sticky = Some(strategy);
182        self
183    }
184
185    /// Makes the engine refuse a second run whose key matches a claimed one.
186    ///
187    /// ```
188    /// use std::time::Duration;
189    ///
190    /// use hatchet_client::{Idempotency, TaskBuilder, Workflow};
191    ///
192    /// let charge = TaskBuilder::<(), ()>::new("charge").handler(|_ctx, _input| async { Ok(()) });
193    /// let checkout = Workflow::new("checkout")
194    ///     .idempotency(Idempotency::until_run_ends("input.order_id", Duration::from_secs(600)))
195    ///     .task(&charge);
196    /// # let _ = checkout;
197    /// ```
198    pub fn idempotency(mut self, idempotency: Idempotency) -> Self {
199        self.options.idempotency = Some(idempotency);
200        self
201    }
202
203    /// Adds a task. Its parents must be added to this workflow too.
204    ///
205    /// The task is taken by reference and cloned in (a [`Task`] is a cheap
206    /// handle: an `Arc` around the handler plus its options), so the caller
207    /// keeps its own handle for `Context::parent_output` and
208    /// [`WorkflowResult::output`](crate::WorkflowResult::output).
209    ///
210    /// Mistakes (duplicate names, unknown parents, trigger options set on the
211    /// task instead of the workflow) are reported as
212    /// [`Error::InvalidDeclaration`] when the workflow is registered.
213    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    /// Runs `task` once if the workflow fails, whatever failed in it.
223    ///
224    /// The task receives the *workflow's* input, and its output is
225    /// discarded. It reads what went wrong with
226    /// [`Context::step_run_errors`](crate::Context::step_run_errors). It is
227    /// not one of the workflow's tasks — it has no parents, nothing depends
228    /// on it, and it never runs when the workflow succeeds.
229    ///
230    /// Declaring it twice, giving it a parent, passing a task that is
231    /// already one of the workflow's tasks, or setting standalone-only
232    /// options on it are all [`Error::InvalidDeclaration`] at registration.
233    ///
234    /// It keeps the name it was declared with, which is a third behaviour:
235    /// the official Go SDK renames the on-failure task to `on-failure`, and
236    /// the official Python SDK appends `-on-failure` to the declared name.
237    /// Only a [`Workflow`] can have one — unlike Go, a standalone task
238    /// cannot; wrap it in a one-task workflow instead.
239    ///
240    /// ```
241    /// use hatchet_client::{Context, TaskBuilder, Workflow};
242    ///
243    /// let charge = TaskBuilder::<(), ()>::new("charge")
244    ///     .handler(|_ctx, _input| async { Ok(()) });
245    /// let alert = TaskBuilder::<(), ()>::new("alert").handler(|ctx: Context, _input: ()| async move {
246    ///     for (task, error) in ctx.step_run_errors() {
247    ///         eprintln!("{task} failed: {error}");
248    ///     }
249    ///     Ok(())
250    /// });
251    ///
252    /// let checkout = Workflow::new("checkout")
253    ///     .task(&charge)
254    ///     .on_failure(&alert);
255    /// # let _ = checkout;
256    /// ```
257    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    /// Runs `task` once, after every other task in the workflow has
267    /// succeeded.
268    ///
269    /// The engine has no field for this — `CreateWorkflowVersionRequest`
270    /// only carries `on_failure_task`. So this is registered as an ordinary
271    /// task whose parents are every *leaf* of the workflow (the tasks no
272    /// other task depends on), which is how the official Python SDK does
273    /// it. The Go SDK has no equivalent at all.
274    ///
275    /// Being an ordinary task, it can read its parents' outputs with
276    /// [`Context::parent_output`](crate::Context::parent_output), and a
277    /// failure anywhere upstream means it never runs.
278    ///
279    /// Declaring it twice, giving it parents of its own, passing a task
280    /// that is already one of the workflow's tasks or its on-failure task,
281    /// or setting standalone-only options on it are all
282    /// [`Error::InvalidDeclaration`] at registration.
283    ///
284    /// It keeps the name it was declared with, where the official Python SDK
285    /// appends `-on-success` to it.
286    ///
287    /// ```
288    /// use hatchet_client::{TaskBuilder, Workflow};
289    ///
290    /// let fetch = TaskBuilder::<(), u32>::new("fetch").handler(|_ctx, _input| async { Ok(1) });
291    /// let lint = TaskBuilder::<(), ()>::new("lint")
292    ///     .handler(|_ctx, _input| async { Ok(()) })
293    ///     .parent(&fetch);
294    /// let build = TaskBuilder::<(), ()>::new("build")
295    ///     .handler(|_ctx, _input| async { Ok(()) })
296    ///     .parent(&fetch);
297    /// let announce = TaskBuilder::<(), ()>::new("announce")
298    ///     .handler(|_ctx, _input| async { Ok(()) });
299    ///
300    /// // `announce` is registered with `lint` and `build` as its parents:
301    /// // they are the workflow's leaves, and `fetch` is not.
302    /// let pipeline = Workflow::new("pipeline")
303    ///     .task(&fetch)
304    ///     .task(&lint)
305    ///     .task(&build)
306    ///     .on_success(&announce);
307    /// # let _ = pipeline;
308    /// ```
309    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/// A declaration with its types erased. Not nameable outside this crate.
352#[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    /// Whether this declaration came from a standalone [`Task`] rather than
361    /// a [`Workflow`]; standalone tasks may not have parents.
362    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    /// Every action this declaration serves, with its handler.
371    ///
372    /// Fails exactly when [`to_request`](Self::to_request) fails.
373    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    /// Every task this declaration serves, hooks included.
393    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    /// Whether anything here asks the engine for a `default` slot.
401    ///
402    /// The on-failure and on-success hooks count: declaring one of them
403    /// durable is allowed, and a worker that did not register the matching
404    /// slot pool would never be assigned it.
405    pub(crate) fn has_default(&self) -> bool {
406        self.declared_tasks().any(|task| !task.durable)
407    }
408
409    /// Whether anything here asks the engine for a `durable` slot.
410    pub(crate) fn has_durable(&self) -> bool {
411        self.declared_tasks().any(|task| task.durable)
412    }
413
414    /// Validates the declaration and maps it to the registration request.
415    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    /// Fails when this declaration asks for something `engine_version` does
460    /// not do. Checked once, at registration, because the alternative is the
461    /// engine silently ignoring the field.
462    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            // Checked before the worker exists rather than when a batch
472            // arrives, because on an older engine none ever will: the
473            // registration is taken, the batch config is dropped, and every run
474            // is assigned singly to a handler that expects a whole batch.
475            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                    // Its parents are the leaves the SDK will give it.
579                    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        // An eviction policy is worker-side only and never leaves this
616        // process, so nothing downstream would ever complain about one that
617        // cannot fire. Both of these are refused here rather than warned
618        // about, because both mean the declaration says something it cannot
619        // do.
620        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        // A batch task says things the rest of a declaration cannot
643        // contradict, and every contradiction is silent if it is let through:
644        // a config the engine reads as nothing buffers nothing, and `retries`
645        // is forced to zero without a word by both official SDKs
646        // (`sdks/go/batch_task_test.go:75-87`,
647        // `sdks/python/hatchet_sdk/runnables/workflow.py:1650`).
648        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    /// Kahn-style topological pass over task parents; errors naming a task
720    /// on the cycle when the parent graph is not a DAG.
721    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(|&(_, &degree)| 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(|&(_, &degree)| 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
771/// Why a workflow or task name cannot be sent to the engine, if any: names
772/// must be non-empty, not just whitespace, and must not contain `:` (which
773/// would corrupt the `workflow:task` action id).
774fn 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
784/// The tasks nothing else depends on, in declaration order.
785///
786/// Only the workflow's own tasks are considered: the on-failure task is not
787/// one of them, and the on-success task is the one whose parents are being
788/// computed.
789fn 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
801/// One task's three condition gates: `wait_for`, `skip_if`, `cancel_if`, in
802/// that order.
803fn 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
815/// Checks one task's conditions: the conditions themselves, and that every
816/// parent condition names a task this one really runs after.
817///
818/// `parents` is the task's own parents — for the on-success hook, the leaves
819/// the SDK will parent it on.
820fn 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        // One slot of the kind this task needs, as the official Python SDK
877        // sends it (`sdks/python/hatchet_sdk/runnables/task.py:183-185`): a
878        // durable task waits on the engine rather than on the worker, so it
879        // is charged to a pool of its own.
880        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        // The one field a batch task adds. Everything else about it is an
886        // ordinary task's registration, down to the single `default` slot: a
887        // batch is one unit of work for the worker however many runs it
888        // answers for (`sdks/python/hatchet_sdk/runnables/task.py:175-185`).
889        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    /// Criterion 1: a durable declaration says so on the wire, and asks for a
965    /// slot of its own kind — an ordinary one is untouched.
966    #[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    /// What the worker's `slot_config` is computed from, hooks included.
985    #[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        // A durable hook counts too: a worker that did not register the pool
1007        // would never be assigned it.
1008        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        // Keep handles to the source tasks' handlers before the tasks are
1278        // moved into the workflow, so we can prove the *pairing* below, not
1279        // just that the right ids come out.
1280        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    /// An eviction policy is worker-side only: the registration request must
1315    /// be the very same bytes it would have been without one.
1316    #[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        // The same declaration inside a workflow, and its on-failure hook.
1349        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        // The control: one millisecond more and it is a policy.
1372        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        // fetch → build → package, and fetch → lint. Leaves: package, lint.
1648        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    /// Criterion 1. The milestone wrote `sleep_for: "30s"`; this SDK sends
1813    /// whole milliseconds, as the official Go SDK does — see the plan's
1814    /// corrections and the spike findings.
1815    #[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    /// Criterion 2.
1843    #[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    /// Criterion 3: the event key is namespaced, the readable key is not.
1872    /// The `wait_for` is not decoration — a cancelling event condition on
1873    /// its own would never be reached, and is rejected.
1874    #[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    /// Criterion 4, second half: a duplicate readable key is an error, not
1897    /// a panic, and the message says how to fix it.
1898    #[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        // `b` never declares `a` as a parent.
1921        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    /// Readable ids reach the engine exactly as they were declared — they are
1933    /// not lowercased the way workflow and action names are — so a parent
1934    /// condition whose spelling differs only in case would never match, and
1935    /// is rejected rather than hanging.
1936    #[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    /// An event `skip_if` with nothing to queue on would leave the task
1977    /// waiting for ever, so the declaration is rejected, naming the task.
1978    #[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    /// Carry-over from P1: the Go SDK's on-failure dump never sends
1995    /// conditions (`sdks/go/internal/task/task.go:375-387`), so a condition
1996    /// there would be a silent no-op at best.
1997    #[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        // The point of taking `&Task`: the handles are still ours, so a
2137        // caller can read the run's output by task handle without having
2138        // cloned them first.
2139        assert_eq!(fetch.name(), "fetch");
2140        assert_eq!(build.name(), "build");
2141        assert_eq!(task_names(&workflow.definition().tasks), ["fetch", "build"]);
2142    }
2143}