Skip to main content

hatchet_client/runs/
mod.rs

1//! Triggering runs and waiting for their results.
2//!
3//! Triggering comes first and subscribing second, on purpose: the engine
4//! answers a subscription for a run that has already finished straight away,
5//! so there is no window to lose a result in — whereas subscribing to a run id
6//! that does not exist yet is not possible at all. The official SDKs order it
7//! the same way.
8
9use std::fmt;
10use std::marker::PhantomData;
11
12use hatchet_proto::root::{StepRunResult, WorkflowRunEvent};
13use serde::Serialize;
14use serde::de::DeserializeOwned;
15use tracing::{Instrument, Span};
16
17use crate::error::{Error, Result, TaskFailure};
18use crate::{Client, RunOpts, Task, Workflow, otel, retry, trigger};
19
20pub(crate) mod bulk;
21pub(crate) mod client;
22pub(crate) mod details;
23pub(crate) mod filter;
24pub(crate) mod listener;
25pub(crate) mod stream;
26
27pub use client::RunsClient;
28pub use details::{RunDetails, TaskRunDetail};
29pub use filter::{RunStatus, TasksFilter};
30pub use stream::{OutputStream, StreamChunk};
31
32impl<I, O> Task<I, O> {
33    /// Triggers a run of this task and hands back a handle to it, without
34    /// waiting for it to finish.
35    ///
36    /// What is triggered is the workflow named after the task, which is the
37    /// right thing for a task registered on its own — a standalone task *is* a
38    /// one-task workflow of the same name. A task declared inside a
39    /// [`Workflow`] is not addressable by itself; trigger its workflow with
40    /// [`Workflow::run_no_wait`] instead.
41    ///
42    /// Nothing here checks that the engine is a version this SDK supports; a
43    /// client that only triggers runs makes no other call. Call
44    /// [`Client::check_engine_version`] once at startup if you want that
45    /// checked.
46    ///
47    /// # Retries
48    ///
49    /// A `TriggerWorkflow` call the engine received but could not answer in
50    /// time is sent again under the SDK's retry policy, so a run can be
51    /// started twice — the handle then names only the second one. This is the
52    /// same exposure as the official Go SDK. A top-level run has no
53    /// deduplication key to hand the engine (the engine's own is for child
54    /// runs, see [`RunOpts::child_key`](crate::RunOpts::child_key)), so a task
55    /// that must not happen twice needs [`Workflow::idempotency`].
56    ///
57    /// # Errors
58    ///
59    /// [`Error::Json`] when `input` or a metadata value cannot be
60    /// serialized; [`Error::IdempotencyCollision`] when the workflow
61    /// declares [`idempotency`](crate::Workflow::idempotency) and the
62    /// computed key is already claimed by another run;
63    /// [`Error::InvalidArgument`] when `opts` asks for
64    /// [`RunOpts::sticky`](crate::RunOpts::sticky) outside a task handler
65    /// (there is no parent run to inherit a worker from); and
66    /// [`Error::Grpc`] when the call fails for any other reason.
67    pub async fn run_no_wait(
68        &self,
69        client: &Client,
70        input: &I,
71        opts: RunOpts,
72    ) -> Result<RunHandle<O>>
73    where
74        I: Serialize,
75    {
76        let span = otel::run_workflow(self.name());
77        let run_id = trigger(client, self.name(), input, &opts, &span)
78            .instrument(span.clone())
79            .await;
80        otel::record_result(&span, &run_id);
81        Ok(self.handle(client, run_id?))
82    }
83
84    /// Triggers a run of this task and waits for its output.
85    ///
86    /// Equivalent to [`run_no_wait`](Task::run_no_wait) followed by
87    /// [`RunHandle::result`], and waits just as long: for ever, if the run
88    /// never finishes. Wrap the call in [`tokio::time::timeout`] if that is
89    /// not acceptable.
90    ///
91    /// ```no_run
92    /// # use hatchet_client::{Client, RunOpts, TaskBuilder};
93    /// # use serde::{Deserialize, Serialize};
94    /// # #[derive(Deserialize, Serialize)]
95    /// # struct Review { repo: String }
96    /// # #[derive(Deserialize, Serialize)]
97    /// # struct Verdict { approved: bool }
98    /// # async fn example(client: &Client) -> hatchet_client::Result<()> {
99    /// // The same declaration the worker registers; triggering only needs
100    /// // its name and its types.
101    /// let review = TaskBuilder::<Review, Verdict>::new("review")
102    ///     .handler(|_ctx, input: Review| async move {
103    ///         Ok(Verdict { approved: input.repo == "hatchet-rs" })
104    ///     });
105    ///
106    /// let verdict = review
107    ///     .run(
108    ///         client,
109    ///         &Review { repo: "hatchet-rs".to_string() },
110    ///         RunOpts::default().metadata("customer", "acme"),
111    ///     )
112    ///     .await?;
113    /// println!("approved: {}", verdict.approved);
114    /// # Ok(())
115    /// # }
116    /// ```
117    ///
118    /// # Errors
119    ///
120    /// Those of [`run_no_wait`](Task::run_no_wait), plus those of
121    /// [`RunHandle::result`].
122    pub async fn run(&self, client: &Client, input: &I, opts: RunOpts) -> Result<O>
123    where
124        I: Serialize,
125        O: DeserializeOwned,
126    {
127        // One span from the trigger to the result, the way the official Go
128        // SDK's `Run` holds its `hatchet.run_workflow` open while it waits
129        // (`sdks/go/workflow.go:932-963`).
130        let span = otel::run_workflow(self.name());
131        let output = async {
132            let run_id = trigger(client, self.name(), input, &opts, &span).await?;
133            self.handle(client, run_id).result().await
134        }
135        .instrument(span.clone())
136        .await;
137        otel::record_result(&span, &output);
138        output
139    }
140
141    /// Triggers a run of this task for every `(input, opts)` pair, in as few
142    /// `BulkTriggerWorkflow` calls as the engine's own limits allow (1000
143    /// requests or 3 MiB of encoded requests per call, whichever comes
144    /// first), and hands back handles in the same order as `inputs`.
145    ///
146    /// What is triggered is the workflow named after the task, exactly as in
147    /// [`run_no_wait`](Task::run_no_wait): right for a standalone task, and
148    /// not possible for a task declared inside a [`Workflow`], which is not
149    /// addressable on its own — use [`Workflow::run_many`] for those.
150    ///
151    /// Every request is built and serialized *before* the first call goes
152    /// out, so a bad input aborts the whole batch rather than starting some
153    /// runs and then failing on a later one. An empty `inputs` makes no call
154    /// at all.
155    ///
156    /// One [`RunOpts`] for the whole batch is a `map` over the inputs, since
157    /// the pairs are what this takes:
158    ///
159    /// ```no_run
160    /// # use hatchet_client::{Client, RunOpts, TaskBuilder};
161    /// # async fn example(client: &Client, inputs: Vec<u32>) -> hatchet_client::Result<()> {
162    /// # let task = TaskBuilder::<u32, u32>::new("double")
163    /// #     .handler(|_ctx, input: u32| async move { Ok(input * 2) });
164    /// let opts = RunOpts::default().metadata("batch", "nightly");
165    /// let handles = task
166    ///     .run_many(client, inputs.into_iter().map(|input| (input, opts.clone())))
167    ///     .await?;
168    /// # let _ = handles;
169    /// # Ok(())
170    /// # }
171    /// ```
172    ///
173    /// # Retries
174    ///
175    /// A `BulkTriggerWorkflow` call the engine received but could not answer
176    /// in time is sent again under the SDK's retry policy, so a chunk of up to
177    /// 1000 runs can be started twice — the handles then name only the second
178    /// set. This is the same exposure as the official Go SDK; tasks that must
179    /// not happen twice need [`Workflow::idempotency`].
180    ///
181    /// # Errors
182    ///
183    /// [`Error::Json`] when an input or a metadata value cannot be
184    /// serialized (before anything is sent); [`Error::InvalidArgument`] when
185    /// any pair's `opts` asks for [`RunOpts::sticky`](crate::RunOpts::sticky)
186    /// (there is no parent run at this level to inherit a worker from), also
187    /// checked before anything is sent; [`Error::Grpc`] or
188    /// [`Error::IdempotencyCollision`]/[`Error::BulkIdempotencyCollision`]
189    /// when the first chunk fails outright; and [`Error::PartialBulkTrigger`]
190    /// when a later chunk fails (for any of those same reasons) after
191    /// earlier ones already started runs — its `run_ids` are the runs that
192    /// really were started, so they are not lost.
193    pub async fn run_many(
194        &self,
195        client: &Client,
196        inputs: impl IntoIterator<Item = (I, RunOpts)>,
197    ) -> Result<Vec<RunHandle<O>>>
198    where
199        I: Serialize,
200    {
201        let inputs: Vec<(I, RunOpts)> = inputs.into_iter().collect();
202        let span = otel::run_workflows(self.name(), inputs.len());
203        let run_ids = trigger_all(client, self.name(), &inputs, &span)
204            .instrument(span.clone())
205            .await;
206        otel::record_result(&span, &run_ids);
207        Ok(run_ids?
208            .into_iter()
209            .map(|run_id| self.handle(client, run_id))
210            .collect())
211    }
212
213    /// A handle on this task's run `run_id`.
214    fn handle(&self, client: &Client, run_id: String) -> RunHandle<O> {
215        RunHandle {
216            run_id,
217            task_name: self.name().to_string(),
218            client: client.clone(),
219            _output: PhantomData,
220        }
221    }
222}
223
224impl Workflow {
225    /// Triggers a run of this workflow and hands back a handle to it, without
226    /// waiting for it to finish. The input is the workflow's own, which every
227    /// task in it receives.
228    ///
229    /// # Errors
230    ///
231    /// The same as [`Task::run_no_wait`].
232    pub async fn run_no_wait<I: Serialize>(
233        &self,
234        client: &Client,
235        input: &I,
236        opts: RunOpts,
237    ) -> Result<WorkflowRunHandle> {
238        let span = otel::run_workflow(self.name());
239        let run_id = trigger(client, self.name(), input, &opts, &span)
240            .instrument(span.clone())
241            .await;
242        otel::record_result(&span, &run_id);
243        Ok(self.handle(client, run_id?))
244    }
245
246    /// Triggers a run of this workflow and waits for every task in it to
247    /// finish.
248    ///
249    /// Waits without a time limit, exactly like [`Task::run`].
250    ///
251    /// # Errors
252    ///
253    /// Those of [`run_no_wait`](Workflow::run_no_wait), plus those of
254    /// [`WorkflowRunHandle::result`].
255    pub async fn run<I: Serialize>(
256        &self,
257        client: &Client,
258        input: &I,
259        opts: RunOpts,
260    ) -> Result<WorkflowResult> {
261        // One span from the trigger to the result, as in `Task::run`.
262        let span = otel::run_workflow(self.name());
263        let result = async {
264            let run_id = trigger(client, self.name(), input, &opts, &span).await?;
265            self.handle(client, run_id).result().await
266        }
267        .instrument(span.clone())
268        .await;
269        otel::record_result(&span, &result);
270        result
271    }
272
273    /// Triggers a run of this workflow for every `(input, opts)` pair, the
274    /// same way as [`Task::run_many`], and hands back handles in the same
275    /// order as `inputs`.
276    ///
277    /// This is also the way to start many runs of a task that is *declared
278    /// inside* a workflow: such a task is not addressable on its own, so it is
279    /// its workflow that is triggered, with the workflow's own input.
280    ///
281    /// One [`RunOpts`] for the whole batch is a `map` over the inputs —
282    /// `inputs.into_iter().map(|input| (input, opts.clone()))` — as shown on
283    /// [`Task::run_many`].
284    ///
285    /// # Retries
286    ///
287    /// The same as [`Task::run_many`]: a chunk the engine received but could
288    /// not answer in time is re-sent, so up to 1000 runs may be started twice.
289    ///
290    /// # Errors
291    ///
292    /// The same as [`Task::run_many`].
293    pub async fn run_many<I: Serialize>(
294        &self,
295        client: &Client,
296        inputs: impl IntoIterator<Item = (I, RunOpts)>,
297    ) -> Result<Vec<WorkflowRunHandle>> {
298        let inputs: Vec<(I, RunOpts)> = inputs.into_iter().collect();
299        let span = otel::run_workflows(self.name(), inputs.len());
300        let run_ids = trigger_all(client, self.name(), &inputs, &span)
301            .instrument(span.clone())
302            .await;
303        otel::record_result(&span, &run_ids);
304        Ok(run_ids?
305            .into_iter()
306            .map(|run_id| self.handle(client, run_id))
307            .collect())
308    }
309
310    /// A handle on this workflow's run `run_id`.
311    fn handle(&self, client: &Client, run_id: String) -> WorkflowRunHandle {
312        WorkflowRunHandle {
313            run_id,
314            client: client.clone(),
315        }
316    }
317}
318
319/// A started run of a single task, and its output type.
320///
321/// Holding one does not hold a subscription open: the stream is opened when
322/// [`result`](RunHandle::result) is awaited, and closed again once nothing is
323/// waiting for anything.
324///
325/// It does keep a clone of the [`Client`] it was started from, which is what
326/// lets it wait ([`result`](RunHandle::result)) and cancel
327/// ([`cancel`](RunHandle::cancel)) on its own. A `Client` is one `Arc`, so
328/// that costs a reference — and it means a handle stays usable after the
329/// client it came from goes out of scope. There is no reference cycle: the
330/// client's result listener never holds a `Client` (see `client.rs`).
331#[must_use = "a run handle waits for nothing until `result` is awaited"]
332pub struct RunHandle<O> {
333    run_id: String,
334    task_name: String,
335    client: Client,
336    _output: PhantomData<fn() -> O>,
337}
338
339/// Cloning a handle costs two strings and a reference; both clones wait on the
340/// same run.
341impl<O> Clone for RunHandle<O> {
342    fn clone(&self) -> Self {
343        Self {
344            run_id: self.run_id.clone(),
345            task_name: self.task_name.clone(),
346            client: self.client.clone(),
347            _output: PhantomData,
348        }
349    }
350}
351
352impl<O> fmt::Debug for RunHandle<O> {
353    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
354        f.debug_struct("RunHandle")
355            .field("run_id", &self.run_id)
356            .field("task", &self.task_name)
357            .finish_non_exhaustive()
358    }
359}
360
361impl<O> RunHandle<O> {
362    /// The engine's id for this run. Runs are addressed by it in the
363    /// dashboard and in the REST API.
364    pub fn id(&self) -> &str {
365        &self.run_id
366    }
367
368    /// Stops this run.
369    ///
370    /// One `CancelTasks` call naming this run. Measured on both supported
371    /// engine versions: a workflow run id cancels every task of that run that
372    /// exists when the call arrives — a task the engine has not created yet
373    /// is *not* covered and will still run, so a run that fans out over time
374    /// may need cancelling more than once.
375    ///
376    /// Cancelling a run that is already over is not an error, and neither is
377    /// cancelling one the engine has never heard of: the engine answers both
378    /// by echoing the id back. There is therefore nothing to check — the
379    /// answer is not proof of effect — and this hands back nothing.
380    ///
381    /// The run's own handler sees the cancellation as
382    /// [`Context::cancelled`](crate::Context::cancelled); a waiter on
383    /// [`result`](RunHandle::result) sees [`Error::RunCancelled`].
384    ///
385    /// ```no_run
386    /// # use hatchet_client::{Client, RunOpts, TaskBuilder};
387    /// # async fn example(client: &Client) -> hatchet_client::Result<()> {
388    /// # let task = TaskBuilder::<(), u32>::new("count")
389    /// #     .handler(|_ctx, _input| async { Ok(1) });
390    /// let run = task.run_no_wait(client, &(), RunOpts::default()).await?;
391    /// run.cancel().await?;
392    /// # Ok(())
393    /// # }
394    /// ```
395    ///
396    /// # Errors
397    ///
398    /// [`Error::Grpc`] when the call fails.
399    pub async fn cancel(&self) -> Result<()> {
400        cancel_run(&self.client, &self.run_id).await
401    }
402
403    /// The output stream of this run: the chunks its handler publishes with
404    /// [`Context::put_stream`](crate::Context::put_stream).
405    ///
406    /// Exactly [`RunsClient::stream`] for this run's id, which documents what
407    /// a subscription opened after the trigger can miss, what ends the stream,
408    /// and the five seconds this can spend waiting for the engine to answer
409    /// before handing back a stream that is still being opened. Nothing can be
410    /// subscribed to before the trigger, so a handler that starts publishing
411    /// at once may be a chunk ahead of this; the race-free pattern is
412    /// [`RunsClient::stream_by_metadata`], opened *before* the run is
413    /// triggered.
414    ///
415    /// ```no_run
416    /// # use hatchet_client::{Client, RunOpts, TaskBuilder};
417    /// # async fn example(client: &Client) -> hatchet_client::Result<()> {
418    /// # let task = TaskBuilder::<(), u32>::new("count")
419    /// #     .handler(|_ctx, _input| async { Ok(1) });
420    /// let run = task.run_no_wait(client, &(), RunOpts::default()).await?;
421    /// let mut chunks = run.stream().await?;
422    /// while let Some(chunk) = chunks.next().await {
423    ///     println!("{}", chunk?.payload);
424    /// }
425    /// // The output is separate from the result: this still waits for it.
426    /// let count = run.result().await?;
427    /// # let _ = count;
428    /// # Ok(())
429    /// # }
430    /// ```
431    ///
432    /// # Errors
433    ///
434    /// Those of [`RunsClient::stream`].
435    pub async fn stream(&self) -> Result<OutputStream> {
436        self.client.runs().stream(&self.run_id).await
437    }
438}
439
440impl<O: DeserializeOwned> RunHandle<O> {
441    /// Waits for the run to finish and deserializes its output.
442    ///
443    /// **There is no time limit.** A run that never finishes is waited for for
444    /// ever, which is what the official SDKs do; wrap the call in
445    /// [`tokio::time::timeout`] if that is not what you want. The wait costs
446    /// nothing while it lasts — every wait on one client shares a single
447    /// subscription — and dropping the future stops waiting without affecting
448    /// the run.
449    ///
450    /// Awaiting it more than once waits again, and a run that has already
451    /// finished is answered straight away.
452    ///
453    /// The subscription is the client's, and a handle holds a clone of that
454    /// client, so this goes on working after the `Client` the run was started
455    /// from goes out of scope.
456    ///
457    /// ```no_run
458    /// # use std::time::Duration;
459    /// # use hatchet_client::{Client, RunOpts, TaskBuilder};
460    /// # async fn example(client: &Client) -> hatchet_client::Result<()> {
461    /// # let task = TaskBuilder::<(), u32>::new("count")
462    /// #     .handler(|_ctx, _input| async { Ok(1) });
463    /// let run = task.run_no_wait(client, &(), RunOpts::default()).await?;
464    /// println!("started {}", run.id());
465    ///
466    /// // An hour is this caller's own limit, not the SDK's.
467    /// let count = tokio::time::timeout(Duration::from_secs(3600), run.result())
468    ///     .await
469    ///     .expect("the run took more than an hour")?;
470    /// # let _ = count;
471    /// # Ok(())
472    /// # }
473    /// ```
474    ///
475    /// # Errors
476    ///
477    /// [`Error::RunFailed`] when a task of the run reported an error,
478    /// [`Error::RunCancelled`] when the run was cancelled before it finished
479    /// — by [`cancel`](RunHandle::cancel), by
480    /// [`RunsClient::cancel`], by a [`Concurrency`](crate::Concurrency) limit
481    /// that cancels rather than queues, or from the dashboard —
482    /// [`Error::RunOutput`] when the run produced no output for this task or
483    /// its output is not an `O`, and [`Error::ResultStream`] when the
484    /// subscription was given up on — the run itself is unaffected by that
485    /// last one, and waiting again opens a new subscription.
486    pub async fn result(&self) -> Result<O> {
487        let event = self.client.run_listener().wait(self.run_id.clone()).await?;
488        output_of(&event, &self.task_name)
489    }
490}
491
492/// A started run of a whole workflow.
493///
494/// Its tasks have their own output types, so the result is handed back
495/// untyped and each output is deserialized on the way out; see
496/// [`WorkflowResult`].
497///
498/// Like [`RunHandle`], it holds a clone of the [`Client`] it was started
499/// from, so it can wait and cancel after that client goes out of scope.
500#[must_use = "a run handle waits for nothing until `result` is awaited"]
501#[derive(Clone)]
502pub struct WorkflowRunHandle {
503    run_id: String,
504    client: Client,
505}
506
507impl fmt::Debug for WorkflowRunHandle {
508    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
509        f.debug_struct("WorkflowRunHandle")
510            .field("run_id", &self.run_id)
511            .finish_non_exhaustive()
512    }
513}
514
515impl WorkflowRunHandle {
516    /// The engine's id for this run.
517    pub fn id(&self) -> &str {
518        &self.run_id
519    }
520
521    /// Stops this run.
522    ///
523    /// Exactly [`RunHandle::cancel`], which documents what a run id does and
524    /// does not reach.
525    ///
526    /// ```no_run
527    /// # use hatchet_client::{Client, RunOpts, Workflow};
528    /// # async fn example(client: &Client) -> hatchet_client::Result<()> {
529    /// # let task = hatchet_client::TaskBuilder::<(), ()>::new("t")
530    /// #     .handler(|_ctx, _input| async { Ok(()) });
531    /// # let workflow = Workflow::new("pipeline").task(&task);
532    /// let run = workflow.run_no_wait(client, &(), RunOpts::default()).await?;
533    /// run.cancel().await?;
534    /// # Ok(())
535    /// # }
536    /// ```
537    ///
538    /// # Errors
539    ///
540    /// [`Error::Grpc`] when the call fails.
541    pub async fn cancel(&self) -> Result<()> {
542        cancel_run(&self.client, &self.run_id).await
543    }
544
545    /// The output stream of this run: the chunks its tasks publish with
546    /// [`Context::put_stream`](crate::Context::put_stream).
547    ///
548    /// Exactly [`RunsClient::stream`] for this run's id, which documents what
549    /// a subscription opened after the trigger can miss, what ends the stream,
550    /// and the five seconds this can spend waiting for the engine to answer
551    /// before handing back a stream that is still being opened. The race-free
552    /// pattern is [`RunsClient::stream_by_metadata`], opened *before* the run
553    /// is triggered.
554    ///
555    /// A workflow run has one chunk sequence per task, so
556    /// [`StreamChunk::task_run_id`](crate::StreamChunk::task_run_id) is what
557    /// tells two tasks' outputs apart when they stream at once.
558    ///
559    /// ```no_run
560    /// # use hatchet_client::{Client, RunOpts, TaskBuilder, Workflow};
561    /// # async fn example(client: &Client) -> hatchet_client::Result<()> {
562    /// # let emit = TaskBuilder::<(), ()>::new("emit")
563    /// #     .handler(|_ctx, _input| async { Ok(()) });
564    /// # let workflow = Workflow::new("pipeline").task(&emit);
565    /// let run = workflow.run_no_wait(client, &(), RunOpts::default()).await?;
566    /// let mut chunks = run.stream().await?;
567    /// while let Some(chunk) = chunks.next().await {
568    ///     let chunk = chunk?;
569    ///     println!("{}: {}", chunk.task_run_id, chunk.payload);
570    /// }
571    /// # Ok(())
572    /// # }
573    /// ```
574    ///
575    /// # Errors
576    ///
577    /// Those of [`RunsClient::stream`].
578    pub async fn stream(&self) -> Result<OutputStream> {
579        self.client.runs().stream(&self.run_id).await
580    }
581
582    /// Waits for every task of the run to finish.
583    ///
584    /// Waits without a time limit, exactly like [`RunHandle::result`], and
585    /// like it goes on working after the [`Client`] the run was started from
586    /// goes out of scope.
587    ///
588    /// # Errors
589    ///
590    /// [`Error::RunFailed`] when any task of the run reported an error,
591    /// [`Error::RunCancelled`] when the run was cancelled before it finished
592    /// (the same sources as for [`RunHandle::result`]), and
593    /// [`Error::ResultStream`] when the subscription was given up on. Reading
594    /// an output is what can fail with [`Error::RunOutput`], and that happens
595    /// in [`WorkflowResult::output`] rather than here.
596    pub async fn result(&self) -> Result<WorkflowResult> {
597        let event = self.client.run_listener().wait(self.run_id.clone()).await?;
598        succeeded(&event)?;
599        Ok(WorkflowResult {
600            run_id: event.workflow_run_id,
601            results: event.results,
602        })
603    }
604}
605
606/// What a finished workflow run produced: one output per task that ran.
607#[derive(Clone, Debug)]
608pub struct WorkflowResult {
609    run_id: String,
610    results: Vec<StepRunResult>,
611}
612
613impl WorkflowResult {
614    /// The engine's id for the run these outputs came from.
615    pub fn run_id(&self) -> &str {
616        &self.run_id
617    }
618
619    /// The output of `task`, deserialized into the type it was declared with.
620    ///
621    /// # Errors
622    ///
623    /// [`Error::RunOutput`] when the run has no output under that task's name,
624    /// or the output is not an `O`.
625    pub fn output<PI, O: DeserializeOwned>(&self, task: &Task<PI, O>) -> Result<O> {
626        self.output_by_name(task.name())
627    }
628
629    /// The output of the task called `name`, deserialized into `T`.
630    ///
631    /// The name is matched as declared first and without regard to case
632    /// afterwards, because the engine knows a task by the lowercased name it
633    /// was registered under.
634    ///
635    /// # Errors
636    ///
637    /// [`Error::RunOutput`] when the run has no output under that name, or
638    /// the output is not a `T`.
639    pub fn output_by_name<T: DeserializeOwned>(&self, name: &str) -> Result<T> {
640        let result = named(&self.results, name).ok_or_else(|| Error::RunOutput {
641            run_id: self.run_id.clone(),
642            reason: format!(
643                "the run produced no output for task {name:?}; it ran {}",
644                listed(&self.results)
645            ),
646        })?;
647        decode(&self.run_id, result)
648    }
649
650    /// Whether `task` was skipped by its
651    /// [`skip_if`](crate::TaskBuilder::skip_if) conditions rather than run.
652    ///
653    /// A skipped task does not fail the run; it simply produced nothing, so
654    /// [`output`](WorkflowResult::output) for it is an [`Error::RunOutput`]
655    /// that says it was skipped.
656    pub fn was_skipped<PI, O>(&self, task: &Task<PI, O>) -> bool {
657        self.was_skipped_by_name(task.name())
658    }
659
660    /// Like [`WorkflowResult::was_skipped`], but by name — matched the same
661    /// way [`output_by_name`](WorkflowResult::output_by_name) matches: as
662    /// declared first, then without regard to case.
663    pub fn was_skipped_by_name(&self, name: &str) -> bool {
664        named(&self.results, name).is_some_and(was_skipped)
665    }
666}
667
668/// The result `name` produced, matched as declared and then without regard to
669/// case: the engine knows a task by the lowercased name it was registered
670/// under.
671fn named<'a>(results: &'a [StepRunResult], name: &str) -> Option<&'a StepRunResult> {
672    results
673        .iter()
674        .find(|result| result.task_name == name)
675        .or_else(|| {
676            results
677                .iter()
678                .find(|result| result.task_name.eq_ignore_ascii_case(name))
679        })
680}
681
682/// The task names a run produced results for, for an error message.
683fn listed(results: &[StepRunResult]) -> String {
684    if results.is_empty() {
685        return "nothing".to_string();
686    }
687    results
688        .iter()
689        .map(|result| format!("{:?}", result.task_name))
690        .collect::<Vec<_>>()
691        .join(", ")
692}
693
694/// Cancels the run called `run_id`, whatever kind of handle asked.
695///
696/// One call, and the answer is discarded: the engine echoes back the ids it
697/// was given — a run that is already over, and even an id that names nothing
698/// at all, come back as "cancelled" (measured on v0.107.0) — so there is
699/// nothing in it a handle could report. Kept in one place so both handles
700/// cancel the same way.
701async fn cancel_run(client: &Client, run_id: &str) -> Result<()> {
702    client.runs().cancel([run_id]).await?;
703    Ok(())
704}
705
706/// Fails if any task of the run reported an error, and tells a cancellation
707/// apart from a failure.
708///
709/// One failed task fails the whole run, whatever the others did: a workflow
710/// whose last step could not run has not done what it was asked. A run with
711/// both a real failure and a cancelled task is reported as the failure — the
712/// cancellation is usually a consequence of it, and the failure is the part
713/// someone has to fix.
714fn succeeded(event: &WorkflowRunEvent) -> Result<()> {
715    let mut errors: Vec<TaskFailure> = Vec::new();
716    let mut cancelled: Vec<String> = Vec::new();
717    for result in &event.results {
718        match result.error.as_deref() {
719            // A message the engine did fill in is a failure, whatever else
720            // the row holds.
721            Some(message) if !message.trim().is_empty() => errors.push(TaskFailure {
722                task_name: result.task_name.clone(),
723                message: message.to_string(),
724            }),
725            _ if cancelled_shape(result) => cancelled.push(result.task_name.clone()),
726            // An empty error next to an output is neither: the engine fills
727            // `error` in with the empty string on rows that succeeded too.
728            _ => {}
729        }
730    }
731    if !errors.is_empty() {
732        return Err(Error::RunFailed {
733            run_id: event.workflow_run_id.clone(),
734            errors,
735        });
736    }
737    if !cancelled.is_empty() {
738        return Err(Error::RunCancelled {
739            run_id: event.workflow_run_id.clone(),
740            tasks: cancelled,
741        });
742    }
743    Ok(())
744}
745
746/// Whether one result records a task the engine **cancelled** rather than one
747/// that failed or succeeded.
748///
749/// The result stream gives nothing else to go on: `WorkflowRunEventType` has
750/// a single value (`FINISHED` —
751/// `api-contracts/dispatcher/dispatcher.proto:419-421`) and `StepRunResult`
752/// carries no status (`:434-444`). What is left is the shape of the row, and
753/// a cancelled task is recorded with an `error` the engine never filled in
754/// *and* no output — measured on both supported engine versions, for an
755/// explicit `CancelTasks` (by workflow run id and by task run id) and for a
756/// concurrency limit that cancels rather than queues.
757///
758/// Both halves are needed. Cancelling by workflow run id adds a blank-error
759/// row for a task that had already *succeeded*, next to that task's real
760/// success row, so "the error is blank" alone would report a finished run as
761/// cancelled; the success row carries its output, and the cancel row carries
762/// none.
763///
764/// This SDK's own worker cannot produce this shape by failing: it sends a
765/// failure message as a JSON string (`worker::events::failed`), so even an
766/// empty one goes out as `"\"\""` — two characters, not none.
767fn cancelled_shape(result: &StepRunResult) -> bool {
768    result.output.is_none()
769        && result
770            .error
771            .as_deref()
772            .is_some_and(|message| message.trim().is_empty())
773}
774
775/// The output a single-task run produced, as `O`.
776///
777/// The result is the one recorded under the task's name; a run that reported
778/// exactly one result reports it under whatever name the engine chose, so that
779/// one is taken as well.
780pub(crate) fn output_of<O: DeserializeOwned>(
781    event: &WorkflowRunEvent,
782    task_name: &str,
783) -> Result<O> {
784    succeeded(event)?;
785    let lone = match event.results.as_slice() {
786        [only] => Some(only),
787        _ => None,
788    };
789    let result = named(&event.results, task_name)
790        .or(lone)
791        .ok_or_else(|| Error::RunOutput {
792            run_id: event.workflow_run_id.clone(),
793            reason: format!(
794                "the run produced no output for task {task_name:?}; it ran {}",
795                listed(&event.results)
796            ),
797        })?;
798    decode(&event.workflow_run_id, result)
799}
800
801/// Whether one result records a task the engine skipped rather than ran: its
802/// output is the engine's `{"skipped": true}` marker, the same marker a
803/// child sees in its `parents` map (see `Context::was_skipped`).
804fn was_skipped(result: &StepRunResult) -> bool {
805    result.output.as_deref().is_some_and(|output| {
806        serde_json::from_str::<serde_json::Value>(output)
807            .ok()
808            .and_then(|value| value.get("skipped").cloned())
809            == Some(serde_json::Value::Bool(true))
810    })
811}
812
813/// Reads one task's output as a `T`.
814fn decode<T: DeserializeOwned>(run_id: &str, result: &StepRunResult) -> Result<T> {
815    if was_skipped(result) {
816        return Err(Error::RunOutput {
817            run_id: run_id.to_string(),
818            reason: format!(
819                "task {:?} was skipped, so it produced no output",
820                result.task_name
821            ),
822        });
823    }
824    // An output the engine did not record at all is not the same as a task
825    // that returned `null`, and only the first is a mistake worth reporting.
826    let output = result.output.as_deref().ok_or_else(|| Error::RunOutput {
827        run_id: run_id.to_string(),
828        reason: format!("task {:?} recorded no output", result.task_name),
829    })?;
830    serde_json::from_str(output).map_err(|error| Error::RunOutput {
831        run_id: run_id.to_string(),
832        reason: format!("task {:?}: {error}", result.task_name),
833    })
834}
835
836/// Triggers a run of the workflow declared as `name`, with no parent, under
837/// `span` — whose traceparent the request carries (with the `otel` feature)
838/// and on which the run's id is recorded — and hands back its run id.
839async fn trigger<I: Serialize>(
840    client: &Client,
841    name: &str,
842    input: &I,
843    opts: &RunOpts,
844    span: &Span,
845) -> Result<String> {
846    let mut request = trigger::request(client.config().namespace(), name, input, opts, None)?;
847    otel::inject(span, &mut request.additional_metadata);
848    let response = retry::unary(|| {
849        let mut workflows = client.workflows_grpc();
850        let request = retry::timed(request.clone());
851        async move { workflows.trigger_workflow(request).await }
852    })
853    .await
854    .map_err(|status| crate::collision::from_trigger(Error::from(status)))?;
855    let run_id = response.into_inner().workflow_run_id;
856    span.record("hatchet.child_workflow_run_id", run_id.as_str());
857    Ok(run_id)
858}
859
860/// Builds the request for every `(input, opts)` pair — each carrying
861/// `span`'s traceparent, as Go's `RunMany` puts its one
862/// `hatchet.run_workflows` span into every item (`sdks/go/workflow.go:1151`)
863/// — and sends them in as few `BulkTriggerWorkflow` calls as the engine
864/// allows. Every request is built before the first call.
865async fn trigger_all<I: Serialize>(
866    client: &Client,
867    name: &str,
868    inputs: &[(I, RunOpts)],
869    span: &Span,
870) -> Result<Vec<String>> {
871    let requests = inputs
872        .iter()
873        .map(|(input, opts)| {
874            let mut request =
875                trigger::request(client.config().namespace(), name, input, opts, None)?;
876            otel::inject(span, &mut request.additional_metadata);
877            Ok(request)
878        })
879        .collect::<Result<Vec<_>>>()?;
880    bulk::trigger_many(client, requests).await
881}
882
883#[cfg(test)]
884mod tests {
885    use super::*;
886    use hatchet_proto::root::WorkflowRunEventType;
887    use serde::Deserialize;
888    use serde_json::json;
889
890    #[derive(Debug, Deserialize, PartialEq)]
891    struct Out {
892        pr: Option<String>,
893    }
894
895    fn result(task_name: &str, output: Option<&str>, error: Option<&str>) -> StepRunResult {
896        StepRunResult {
897            task_name: task_name.to_string(),
898            output: output.map(str::to_string),
899            error: error.map(str::to_string),
900            ..StepRunResult::default()
901        }
902    }
903
904    fn event(results: Vec<StepRunResult>) -> WorkflowRunEvent {
905        WorkflowRunEvent {
906            workflow_run_id: "run-1".to_string(),
907            event_type: WorkflowRunEventType::Finished as i32,
908            results,
909            ..WorkflowRunEvent::default()
910        }
911    }
912
913    #[test]
914    fn the_output_of_the_named_task_is_the_one_that_is_read() {
915        let event = event(vec![
916            result("fetch", Some(r#"{"pr":"other"}"#), None),
917            result("agent-run", Some(r#"{"pr":null}"#), None),
918        ]);
919        let out: Out = output_of(&event, "agent-run").unwrap();
920        assert_eq!(out, Out { pr: None });
921    }
922
923    /// The engine knows a task by the lowercased name it was registered under,
924    /// so a declaration that was not written in lower case still finds it.
925    #[test]
926    fn a_name_is_matched_without_regard_to_case() {
927        let event = event(vec![result("agent-run", Some(r#"{"pr":null}"#), None)]);
928        let out: Out = output_of(&event, "Agent-Run").unwrap();
929        assert_eq!(out, Out { pr: None });
930    }
931
932    #[test]
933    fn a_skipped_task_is_reported_as_skipped_rather_than_as_a_missing_output() {
934        let event = event(vec![
935            result("fetch", Some(r#"{"pr":"ok"}"#), None),
936            result("maybe", Some(r#"{"skipped":true}"#), None),
937        ]);
938        let result = WorkflowResult {
939            run_id: event.workflow_run_id.clone(),
940            results: event.results.clone(),
941        };
942
943        assert!(result.was_skipped_by_name("maybe"));
944        assert!(!result.was_skipped_by_name("fetch"));
945        assert!(!result.was_skipped_by_name("never-ran"));
946
947        let error = result.output_by_name::<Out>("maybe").unwrap_err();
948        let Error::RunOutput { reason, .. } = &error else {
949            panic!("expected RunOutput: {error:?}");
950        };
951        assert!(reason.contains("skipped"), "{reason}");
952
953        // A skipped task is not a failed one.
954        assert!(succeeded(&event).is_ok());
955    }
956
957    #[test]
958    fn a_lone_result_is_the_output_whatever_it_is_called() {
959        let event = event(vec![result("step-one", Some(r#"{"pr":"x"}"#), None)]);
960        let out: Out = output_of(&event, "agent-run").unwrap();
961        assert_eq!(
962            out,
963            Out {
964                pr: Some("x".to_string())
965            }
966        );
967    }
968
969    #[test]
970    fn a_result_that_is_neither_named_nor_alone_is_a_run_output_error() {
971        let event = event(vec![
972            result("fetch", Some("1"), None),
973            result("report", Some("2"), None),
974        ]);
975        let error = output_of::<Out>(&event, "agent-run").unwrap_err();
976        let Error::RunOutput { run_id, reason } = &error else {
977            panic!("{error:?}")
978        };
979        assert_eq!(run_id, "run-1");
980        assert!(reason.contains("\"fetch\", \"report\""), "{reason}");
981    }
982
983    #[test]
984    fn an_output_of_the_wrong_shape_is_a_run_output_error() {
985        let event = event(vec![result("agent-run", Some(r#"{"pr":42}"#), None)]);
986        let error = output_of::<Out>(&event, "agent-run").unwrap_err();
987        assert!(matches!(error, Error::RunOutput { .. }), "{error:?}");
988    }
989
990    #[test]
991    fn a_missing_output_is_a_run_output_error() {
992        let event = event(vec![result("agent-run", None, None)]);
993        let error = output_of::<Out>(&event, "agent-run").unwrap_err();
994        let Error::RunOutput { reason, .. } = &error else {
995            panic!("{error:?}")
996        };
997        assert!(reason.contains("recorded no output"), "{reason}");
998    }
999
1000    #[test]
1001    fn a_reported_error_fails_the_run_before_any_output_is_read() {
1002        let event = event(vec![
1003            result("fetch", Some("1"), None),
1004            result("agent-run", None, Some("boom")),
1005        ]);
1006        let error = output_of::<Out>(&event, "agent-run").unwrap_err();
1007        let Error::RunFailed { run_id, errors } = &error else {
1008            panic!("{error:?}")
1009        };
1010        assert_eq!(run_id, "run-1");
1011        assert_eq!(
1012            errors,
1013            &[TaskFailure {
1014                task_name: "agent-run".to_string(),
1015                message: "boom".to_string(),
1016            }]
1017        );
1018    }
1019
1020    /// The shape a cancelled run arrives in, verbatim from what a real engine
1021    /// sent when a run was cancelled by its task run id.
1022    #[test]
1023    fn a_blank_error_with_no_output_is_a_cancellation() {
1024        let event = event(vec![
1025            result("lead", Some(r#"{"ok":true}"#), None),
1026            result("hold", None, Some("")),
1027        ]);
1028        let error = succeeded(&event).unwrap_err();
1029        let Error::RunCancelled { run_id, tasks } = &error else {
1030            panic!("expected a cancellation: {error:?}")
1031        };
1032        assert_eq!(run_id, "run-1");
1033        assert_eq!(tasks, &["hold".to_string()]);
1034    }
1035
1036    /// Cancelling by *workflow* run id adds a blank-error row for a task that
1037    /// had already succeeded, next to that task's own success row. The run is
1038    /// still a cancellation, and the task that really finished is not named
1039    /// twice for it.
1040    #[test]
1041    fn a_success_row_and_a_cancel_row_for_one_task_is_still_a_cancellation() {
1042        let event = event(vec![
1043            result("lead", Some(r#"{"ok":true}"#), None),
1044            result("lead", None, Some("")),
1045            result("hold", None, Some("")),
1046        ]);
1047        let error = succeeded(&event).unwrap_err();
1048        let Error::RunCancelled { tasks, .. } = &error else {
1049            panic!("expected a cancellation: {error:?}")
1050        };
1051        assert_eq!(tasks, &["lead".to_string(), "hold".to_string()]);
1052    }
1053
1054    /// A real failure outranks a cancellation: the run is reported as the
1055    /// failure, and only the task that really failed is named.
1056    #[test]
1057    fn a_real_failure_next_to_a_cancelled_task_is_a_failure() {
1058        let event = event(vec![
1059            result("fetch", None, Some("boom")),
1060            result("report", None, Some("")),
1061        ]);
1062        let error = succeeded(&event).unwrap_err();
1063        let Error::RunFailed { errors, .. } = &error else {
1064            panic!("expected a failure: {error:?}")
1065        };
1066        assert_eq!(
1067            errors,
1068            &[TaskFailure {
1069                task_name: "fetch".to_string(),
1070                message: "boom".to_string(),
1071            }]
1072        );
1073    }
1074
1075    /// What this SDK's own worker sends for a failure with nothing to say: an
1076    /// empty JSON string, which is not empty. A blank-message failure must not
1077    /// be reported to waiters as someone's decision to stop the run.
1078    #[test]
1079    fn a_json_encoded_empty_failure_message_is_a_failure_not_a_cancellation() {
1080        let event = event(vec![result("agent-run", None, Some("\"\""))]);
1081        let error = succeeded(&event).unwrap_err();
1082        let Error::RunFailed { errors, .. } = &error else {
1083            panic!("expected a failure: {error:?}")
1084        };
1085        assert_eq!(errors[0].message, "\"\"");
1086    }
1087
1088    /// The engine fills `error` in with the empty string on rows that
1089    /// succeeded, too — it is the missing output that makes a row a
1090    /// cancellation.
1091    #[test]
1092    fn a_blank_error_next_to_an_output_is_neither_a_failure_nor_a_cancellation() {
1093        let event = event(vec![result("agent-run", Some(r#"{"pr":null}"#), Some(""))]);
1094        succeeded(&event).expect("a row with an output is not a cancellation");
1095        let out: Out = output_of(&event, "agent-run").unwrap();
1096        assert_eq!(out, Out { pr: None });
1097    }
1098
1099    /// A single-task run's cancellation reaches the same waiter that would
1100    /// have read its output.
1101    #[test]
1102    fn a_cancelled_run_is_reported_before_any_output_is_read() {
1103        let event = event(vec![result("agent-run", None, Some(""))]);
1104        let error = output_of::<Out>(&event, "agent-run").unwrap_err();
1105        assert!(matches!(error, Error::RunCancelled { .. }), "{error:?}");
1106    }
1107
1108    #[test]
1109    fn a_workflow_result_reads_each_task_by_name() {
1110        let event = event(vec![
1111            result("fetch", Some(r#"{"n":1}"#), None),
1112            result("report", Some(r#""done""#), None),
1113        ]);
1114        succeeded(&event).unwrap();
1115        let workflow_result = WorkflowResult {
1116            run_id: event.workflow_run_id.clone(),
1117            results: event.results.clone(),
1118        };
1119        assert_eq!(workflow_result.run_id(), "run-1");
1120        assert_eq!(
1121            workflow_result
1122                .output_by_name::<serde_json::Value>("fetch")
1123                .unwrap(),
1124            json!({"n": 1})
1125        );
1126        assert_eq!(
1127            workflow_result.output_by_name::<String>("report").unwrap(),
1128            "done"
1129        );
1130        let error = workflow_result
1131            .output_by_name::<serde_json::Value>("missing")
1132            .unwrap_err();
1133        assert!(matches!(error, Error::RunOutput { .. }), "{error:?}");
1134    }
1135
1136    /// A single result is a *standalone task's* output whatever the engine
1137    /// called it; inside a workflow, names are how outputs are told apart, so
1138    /// asking for one that did not run is an error even when only one did.
1139    #[test]
1140    fn a_workflow_result_does_not_fall_back_to_a_lone_result() {
1141        let workflow_result = WorkflowResult {
1142            run_id: "run-1".to_string(),
1143            results: vec![result("fetch", Some("1"), None)],
1144        };
1145        let error = workflow_result.output_by_name::<u32>("report").unwrap_err();
1146        assert!(matches!(error, Error::RunOutput { .. }), "{error:?}");
1147    }
1148}