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}