hatchet_client/declare/task.rs
1//! Declaring a task: options, a typed handler, and its type-erased form.
2
3use std::collections::BTreeMap;
4use std::fmt;
5use std::future::Future;
6use std::marker::PhantomData;
7use std::pin::Pin;
8use std::sync::Arc;
9use std::time::Duration;
10
11use serde::Serialize;
12use serde::de::DeserializeOwned;
13use serde_json::Value;
14
15use hatchet_proto::root::AssignedAction;
16
17use super::{
18 BatchConfig, Concurrency, ConditionSet, DesiredLabel, Idempotency, Priority, RateLimit,
19 StickyStrategy,
20};
21use crate::batch::{BatchInput, BatchMemberId, BatchOutput, BatchReport, reconcile};
22use crate::{Context, DurableContext, EvictionPolicy, TaskError};
23
24/// A handler with its input and output types erased at the JSON boundary,
25/// so the worker can run any task without knowing its types.
26// The function-pointer-like trait object is inherent to type erasure here;
27// splitting it up would not make it clearer.
28#[allow(clippy::type_complexity)]
29pub(crate) type ErasedHandler = Arc<
30 dyn Fn(Context, Value) -> Pin<Box<dyn Future<Output = Result<Value, TaskError>> + Send>>
31 + Send
32 + Sync,
33>;
34
35/// A batch handler with its types erased at the JSON boundary: it takes the
36/// `START_BATCH` action whole and answers with one outcome per member of it.
37///
38/// Taking the assignment rather than a parsed shape is what keeps the parsing
39/// next to the types it parses into: only this closure knows `I`.
40// Same reason as [`ErasedHandler`]: the trait object is the erasure.
41#[allow(clippy::type_complexity)]
42pub(crate) type ErasedBatchHandler = Arc<
43 dyn Fn(
44 Context,
45 AssignedAction,
46 ) -> Pin<Box<dyn Future<Output = Result<BatchReport, TaskError>> + Send>>
47 + Send
48 + Sync,
49>;
50
51/// What a batch task adds to a declaration.
52#[derive(Clone)]
53pub(crate) struct BatchDef {
54 pub(crate) config: BatchConfig,
55 /// Whether the handler answers with one value for the whole batch, which
56 /// is decided by which builder method attached it.
57 pub(crate) broadcast: bool,
58 pub(crate) handler: ErasedBatchHandler,
59}
60
61/// Per-task scheduling options.
62#[derive(Clone, Default)]
63pub(crate) struct TaskOptions {
64 pub(crate) retries: u32,
65 /// `(factor, max_seconds)`.
66 pub(crate) backoff: Option<(f32, u32)>,
67 pub(crate) execution_timeout: Option<Duration>,
68 pub(crate) schedule_timeout: Option<Duration>,
69 pub(crate) concurrency: Vec<Concurrency>,
70 pub(crate) rate_limits: Vec<RateLimit>,
71 pub(crate) worker_labels: BTreeMap<String, DesiredLabel>,
72 /// What holds the task back, what skips it and what cancels it. All
73 /// three leave as one `CreateTaskOpts.conditions`, told apart by the
74 /// engine's `Action`.
75 pub(crate) wait_for: ConditionSet,
76 pub(crate) skip_if: ConditionSet,
77 pub(crate) cancel_if: ConditionSet,
78 /// When a waiting run of this task may be handed back to the engine.
79 /// Worker-side only: it is never sent anywhere.
80 pub(crate) eviction_policy: Option<EvictionPolicy>,
81}
82
83/// Options that belong to a workflow as a whole: how it is triggered and
84/// described. A standalone task carries them for its implicit workflow.
85#[derive(Clone, Default)]
86pub(crate) struct WorkflowOptions {
87 pub(crate) description: Option<String>,
88 pub(crate) version: Option<String>,
89 pub(crate) on_events: Vec<String>,
90 pub(crate) on_crons: Vec<String>,
91 pub(crate) cron_input: Option<Value>,
92 pub(crate) default_priority: Option<Priority>,
93 pub(crate) concurrency: Vec<Concurrency>,
94 pub(crate) sticky: Option<StickyStrategy>,
95 pub(crate) idempotency: Option<Idempotency>,
96}
97
98impl WorkflowOptions {
99 pub(crate) fn is_empty(&self) -> bool {
100 self.description.is_none()
101 && self.version.is_none()
102 && self.on_events.is_empty()
103 && self.on_crons.is_empty()
104 && self.cron_input.is_none()
105 && self.default_priority.is_none()
106 && self.concurrency.is_empty()
107 && self.sticky.is_none()
108 && self.idempotency.is_none()
109 }
110}
111
112/// A task with its types erased: what a workflow and the worker hold.
113#[derive(Clone)]
114pub(crate) struct TaskDef {
115 pub(crate) name: String,
116 pub(crate) options: TaskOptions,
117 pub(crate) parents: Vec<String>,
118 pub(crate) handler: ErasedHandler,
119 /// Set by [`TaskBuilder::durable_handler`]: the engine sends this action a
120 /// durable invocation, and it asks for a `durable` slot rather than a
121 /// `default` one.
122 pub(crate) durable: bool,
123 /// Set by [`TaskBuilder::batch_handler`] or
124 /// [`TaskBuilder::batch_broadcast_handler`]: the engine buffers this task's
125 /// runs and assigns the whole group as one `START_BATCH`.
126 pub(crate) batch: Option<BatchDef>,
127}
128
129/// One action a worker serves: its handler, and whether the engine will send
130/// it a durable invocation.
131#[derive(Clone)]
132pub(crate) struct RegisteredAction {
133 pub(crate) handler: ErasedHandler,
134 pub(crate) durable: bool,
135 /// The policy the task declared, if any: the worker's eviction book reads
136 /// it when this action is assigned.
137 pub(crate) eviction_policy: Option<EvictionPolicy>,
138 /// The batch handler, when this action is a batch task: what a
139 /// `START_BATCH` assignment for it is run with.
140 pub(crate) batch: Option<ErasedBatchHandler>,
141}
142
143/// Configures a task before its handler is attached.
144///
145/// `I` is the input the handler receives and `O` the output it returns; both
146/// cross the wire as JSON. [`handler`](TaskBuilder::handler) finishes the
147/// declaration and hands back a [`Task`], which a worker registers and a
148/// client triggers.
149///
150/// The options set here are per task. The ones marked "standalone
151/// registration only" — [`on_events`](TaskBuilder::on_events),
152/// [`cron`](TaskBuilder::cron), [`cron_input`](TaskBuilder::cron_input),
153/// [`description`](TaskBuilder::description),
154/// [`version`](TaskBuilder::version),
155/// [`default_priority`](TaskBuilder::default_priority),
156/// [`workflow_concurrency`](TaskBuilder::workflow_concurrency),
157/// [`sticky`](TaskBuilder::sticky), [`idempotency`](TaskBuilder::idempotency)
158/// — belong to the
159/// workflow a standalone task implies; setting them on a task that is then
160/// added to a [`Workflow`](crate::Workflow) is an
161/// [`Error::InvalidDeclaration`](crate::Error::InvalidDeclaration) at
162/// registration.
163///
164/// ```
165/// use std::time::Duration;
166///
167/// use hatchet_client::{Concurrency, ConcurrencyLimitStrategy, DesiredLabel, TaskBuilder};
168///
169/// let agent_run = TaskBuilder::<String, String>::new("agent-run")
170/// .retries(1)
171/// .retry_backoff(2.0, 60)
172/// .execution_timeout(Duration::from_secs(2 * 3600))
173/// .concurrency(
174/// Concurrency::expr("input.device_id")
175/// .max_runs(1)
176/// .strategy(ConcurrencyLimitStrategy::GroupRoundRobin),
177/// )
178/// .worker_label("os", DesiredLabel::eq("macos").required())
179/// .on_events(["approval.granted"])
180/// .handler(|_ctx, repo: String| async move { Ok(format!("reviewed {repo}")) });
181///
182/// assert_eq!(agent_run.name(), "agent-run");
183/// ```
184#[must_use = "a task builder declares nothing until `handler` is called"]
185pub struct TaskBuilder<I, O> {
186 name: String,
187 options: TaskOptions,
188 standalone: WorkflowOptions,
189 _types: PhantomData<fn(I) -> O>,
190}
191
192/// Shows what a declaration is, not what it does: the handler is a closure
193/// with nothing to print, and the options are the caller's own values.
194impl<I, O> fmt::Debug for TaskBuilder<I, O> {
195 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
196 f.debug_struct("TaskBuilder")
197 .field("name", &self.name)
198 .field("retries", &self.options.retries)
199 .finish_non_exhaustive()
200 }
201}
202
203impl<I, O> TaskBuilder<I, O> {
204 /// Starts declaring a task. Registered on its own, the task name is also
205 /// the workflow name used to trigger it.
206 pub fn new(name: impl Into<String>) -> Self {
207 Self {
208 name: name.into(),
209 options: TaskOptions::default(),
210 standalone: WorkflowOptions::default(),
211 _types: PhantomData,
212 }
213 }
214
215 /// How many times Hatchet retries the task after a retryable failure.
216 pub fn retries(mut self, retries: u32) -> Self {
217 self.options.retries = retries;
218 self
219 }
220
221 /// Exponential backoff between retries: multiply the delay by `factor`
222 /// each time, up to `max_seconds`.
223 pub fn retry_backoff(mut self, factor: f32, max_seconds: u32) -> Self {
224 self.options.backoff = Some((factor, max_seconds));
225 self
226 }
227
228 /// How long a run may execute before the engine times it out.
229 pub fn execution_timeout(mut self, timeout: Duration) -> Self {
230 self.options.execution_timeout = Some(timeout);
231 self
232 }
233
234 /// How long a run may wait for a worker before the engine gives up.
235 pub fn schedule_timeout(mut self, timeout: Duration) -> Self {
236 self.options.schedule_timeout = Some(timeout);
237 self
238 }
239
240 /// Adds a concurrency limit on this task.
241 pub fn concurrency(mut self, concurrency: Concurrency) -> Self {
242 self.options.concurrency.push(concurrency);
243 self
244 }
245
246 /// Holds the task back until these conditions are satisfied.
247 ///
248 /// May be called repeatedly; everything given must be satisfied for the
249 /// task to start. Use [`any_of`](crate::any_of) for "whichever comes
250 /// first".
251 ///
252 /// A [`Condition::parent`](crate::Condition::parent) condition may only
253 /// name a task this one runs after — set the parents with
254 /// [`Task::parent`](crate::Task::parent) after the handler, as usual:
255 ///
256 /// ```
257 /// use std::time::Duration;
258 ///
259 /// use hatchet_client::{Condition, TaskBuilder, Workflow, any_of};
260 ///
261 /// let fetch = TaskBuilder::<(), u32>::new("fetch").handler(|_ctx, _input| async { Ok(1) });
262 /// let publish = TaskBuilder::<(), ()>::new("publish")
263 /// .wait_for(any_of([
264 /// Condition::on_event("publish.approved"),
265 /// Condition::sleep(Duration::from_secs(600)),
266 /// ]))
267 /// .skip_if(Condition::parent(&fetch).expression("output == 0"))
268 /// .handler(|_ctx, _input| async { Ok(()) })
269 /// .parent(&fetch);
270 ///
271 /// let pipeline = Workflow::new("pipeline").task(&fetch).task(&publish);
272 /// # let _ = pipeline;
273 /// ```
274 pub fn wait_for(mut self, conditions: impl Into<ConditionSet>) -> Self {
275 self.options.wait_for.extend(conditions.into());
276 self
277 }
278
279 /// Skips the task — without failing the workflow — when these
280 /// conditions are satisfied.
281 ///
282 /// A skipped task runs nothing and produces no output of its own: the
283 /// engine records `{"skipped": true}` for it instead, and skips
284 /// everything downstream of it too, including the
285 /// [`on_success`](crate::Workflow::on_success) task; the run itself
286 /// still succeeds. Read that marker rather than the output — a
287 /// downstream handler tells a skipped parent apart from one that ran with
288 /// [`Context::was_skipped`](crate::Context::was_skipped), and a caller
289 /// waiting on the run does the same with
290 /// [`WorkflowResult::was_skipped`](crate::WorkflowResult::was_skipped).
291 ///
292 /// A sleep or event condition here is weighed only while the task waits
293 /// to be queued, so it must be paired with a
294 /// [`wait_for`](TaskBuilder::wait_for) *on a sleep or an event* —
295 /// otherwise the task would wait for ever, and the declaration is
296 /// rejected. Neither having parents nor a `wait_for` made only of parent
297 /// conditions counts: a task in that shape was measured, on both
298 /// supported engines, never to start while an otherwise identical
299 /// sibling did. A parent condition needs no pairing at all: it is weighed
300 /// as soon as the parent finishes.
301 ///
302 /// May be called repeatedly; everything given must be satisfied.
303 ///
304 /// ```
305 /// use hatchet_client::{Condition, TaskBuilder, Workflow};
306 ///
307 /// let fetch = TaskBuilder::<(), u32>::new("fetch").handler(|_ctx, _input| async { Ok(0) });
308 /// let publish = TaskBuilder::<(), ()>::new("publish")
309 /// // Nothing was fetched, so there is nothing to publish.
310 /// .skip_if(Condition::parent(&fetch).expression("output == 0"))
311 /// .handler(|_ctx, _input| async { Ok(()) })
312 /// .parent(&fetch);
313 ///
314 /// let pipeline = Workflow::new("pipeline").task(&fetch).task(&publish);
315 /// # let _ = pipeline;
316 /// ```
317 pub fn skip_if(mut self, conditions: impl Into<ConditionSet>) -> Self {
318 self.options.skip_if.extend(conditions.into());
319 self
320 }
321
322 /// Cancels the task when these conditions are satisfied.
323 ///
324 /// What was measured, on both supported engines: the engine weighs the
325 /// condition while the task is *waiting to start*, and when it fired the
326 /// task was cancelled before its handler ever ran — so the handler's
327 /// [`Context::cancelled`](crate::Context::cancelled) token never
328 /// triggered either. A caller waiting on the run then gets
329 /// [`Error::RunCancelled`](crate::Error::RunCancelled).
330 ///
331 /// **This is a queuing gate, not a stop button.** A condition that
332 /// becomes true *after* the handler has started does not interrupt it:
333 /// measured on both supported engines, a task that had reported itself
334 /// started ran to completion and its run succeeded, with
335 /// `Context::cancelled` never triggering. For a handler that has to be
336 /// able to stop what it is doing, cancel the run —
337 /// [`RunHandle::cancel`](crate::RunHandle::cancel),
338 /// [`RunsClient::cancel`](crate::RunsClient::cancel), or the dashboard —
339 /// and watch `Context::cancelled`.
340 ///
341 /// The same pairing rule as [`skip_if`](TaskBuilder::skip_if) applies,
342 /// and for the same reason.
343 ///
344 /// The current official Go SDK exposes no equivalent option — only
345 /// `WithWaitFor` and `WithSkipIf`; a `CancelIf` field survives on the
346 /// deprecated `pkg/client/create` task struct. This follows the official
347 /// Python SDK.
348 ///
349 /// May be called repeatedly; everything given must be satisfied.
350 ///
351 /// ```
352 /// use std::time::Duration;
353 ///
354 /// use hatchet_client::{Condition, TaskBuilder};
355 ///
356 /// let deploy = TaskBuilder::<(), ()>::new("deploy")
357 /// // Deploy five minutes from now, unless someone calls it off.
358 /// .wait_for(Condition::sleep(Duration::from_secs(300)))
359 /// .cancel_if(Condition::on_event("deploy.aborted"))
360 /// .handler(|_ctx, _input| async { Ok(()) });
361 /// # let _ = deploy;
362 /// ```
363 pub fn cancel_if(mut self, conditions: impl Into<ConditionSet>) -> Self {
364 self.options.cancel_if.extend(conditions.into());
365 self
366 }
367
368 /// Adds a concurrency limit across *runs of this task as a workflow*,
369 /// rather than on the task itself — `CreateWorkflowVersionRequest`'s
370 /// `concurrency_arr` instead of `CreateTaskOpts.concurrency`. Standalone
371 /// registration only; inside a [`Workflow`](crate::Workflow), use
372 /// [`Workflow::concurrency`](crate::Workflow::concurrency).
373 ///
374 /// ```
375 /// use hatchet_client::{Concurrency, ConcurrencyLimitStrategy, TaskBuilder};
376 ///
377 /// // One run per tenant at a time; the rest wait their turn.
378 /// let agent_run = TaskBuilder::<(), ()>::new("agent-run")
379 /// .workflow_concurrency(
380 /// Concurrency::expr("input.tenant")
381 /// .max_runs(1)
382 /// .strategy(ConcurrencyLimitStrategy::GroupRoundRobin),
383 /// )
384 /// .handler(|_ctx, _input| async move { Ok(()) });
385 /// ```
386 pub fn workflow_concurrency(mut self, concurrency: Concurrency) -> Self {
387 self.standalone.concurrency.push(concurrency);
388 self
389 }
390
391 /// Makes each run consume units of a static rate limit.
392 pub fn rate_limit(mut self, rate_limit: RateLimit) -> Self {
393 self.options.rate_limits.push(rate_limit);
394 self
395 }
396
397 /// Asks for a worker whose label `key` satisfies `label`.
398 pub fn worker_label(mut self, key: impl Into<String>, label: DesiredLabel) -> Self {
399 self.options.worker_labels.insert(key.into(), label);
400 self
401 }
402
403 /// Describes the task. Standalone registration only.
404 pub fn description(mut self, description: impl Into<String>) -> Self {
405 self.standalone.description = Some(description.into());
406 self
407 }
408
409 /// Labels this version of the task. Standalone registration only.
410 pub fn version(mut self, version: impl Into<String>) -> Self {
411 self.standalone.version = Some(version.into());
412 self
413 }
414
415 /// Runs the task whenever one of these event keys is pushed. May be
416 /// called repeatedly; event keys accumulate. Standalone registration
417 /// only; inside a workflow, set triggers on the workflow.
418 pub fn on_events(mut self, keys: impl IntoIterator<Item = impl Into<String>>) -> Self {
419 self.standalone
420 .on_events
421 .extend(keys.into_iter().map(Into::into));
422 self
423 }
424
425 /// Runs the task on a cron schedule. May be called repeatedly; cron
426 /// expressions accumulate. Standalone registration only.
427 pub fn cron(mut self, expression: impl Into<String>) -> Self {
428 self.standalone.on_crons.push(expression.into());
429 self
430 }
431
432 /// The input given to cron-triggered runs. Standalone registration only.
433 pub fn cron_input(mut self, input: Value) -> Self {
434 self.standalone.cron_input = Some(input);
435 self
436 }
437
438 /// The priority of runs that do not specify one. Standalone registration only.
439 pub fn default_priority(mut self, priority: Priority) -> Self {
440 self.standalone.default_priority = Some(priority);
441 self
442 }
443
444 /// Pins this task's runs to one worker. Standalone registration only;
445 /// inside a [`Workflow`](crate::Workflow), use
446 /// [`Workflow::sticky`](crate::Workflow::sticky).
447 ///
448 /// ```
449 /// use hatchet_client::{StickyStrategy, TaskBuilder};
450 ///
451 /// let warm = TaskBuilder::<(), ()>::new("warm")
452 /// .sticky(StickyStrategy::Soft)
453 /// .handler(|_ctx, _input| async { Ok(()) });
454 /// # let _ = warm;
455 /// ```
456 pub fn sticky(mut self, strategy: StickyStrategy) -> Self {
457 self.standalone.sticky = Some(strategy);
458 self
459 }
460
461 /// Makes the engine refuse a second run whose key matches a claimed one.
462 /// Standalone registration only; inside a [`Workflow`](crate::Workflow),
463 /// use [`Workflow::idempotency`](crate::Workflow::idempotency).
464 ///
465 /// ```
466 /// use std::time::Duration;
467 ///
468 /// use hatchet_client::{Idempotency, TaskBuilder};
469 ///
470 /// let send = TaskBuilder::<(), ()>::new("send-receipt")
471 /// .idempotency(Idempotency::until_run_ends("input.order_id", Duration::from_secs(60)))
472 /// .handler(|_ctx, _input| async { Ok(()) });
473 /// # let _ = send;
474 /// ```
475 pub fn idempotency(mut self, idempotency: Idempotency) -> Self {
476 self.standalone.idempotency = Some(idempotency);
477 self
478 }
479
480 /// Lets this task's runs be handed back to the engine while they wait.
481 ///
482 /// **Durable tasks only.** A policy on an ordinary
483 /// [`handler`](Self::handler) is an
484 /// [`Error::InvalidDeclaration`](crate::Error::InvalidDeclaration) at
485 /// registration rather than a policy that silently never fires: an
486 /// ordinary run is never parked on the engine, so a policy on one nearly
487 /// always means the handler was meant to be a
488 /// [`durable_handler`](Self::durable_handler).
489 ///
490 /// Nothing about the policy is sent anywhere — the registration request is
491 /// byte for byte the one this task would send without it. See
492 /// [`EvictionPolicy`] for what the worker does with it.
493 ///
494 /// A [`ttl`](EvictionPolicy::ttl) of [`Duration::ZERO`] is refused for the
495 /// same reason: it would leave a policy that can only ever fire under
496 /// capacity pressure, which is not what a zero usually means.
497 ///
498 /// ```
499 /// use std::time::Duration;
500 ///
501 /// use hatchet_client::{EvictionPolicy, TaskBuilder};
502 ///
503 /// let approve = TaskBuilder::<(), ()>::new("approve")
504 /// .eviction_policy(EvictionPolicy::ttl(Duration::from_secs(60)))
505 /// .durable_handler(|ctx, _input| async move {
506 /// ctx.wait_for_event("approved").await?;
507 /// Ok(())
508 /// });
509 /// # let _ = approve;
510 /// ```
511 pub fn eviction_policy(mut self, policy: EvictionPolicy) -> Self {
512 self.options.eviction_policy = Some(policy);
513 self
514 }
515
516 /// Attaches the handler and finishes the declaration.
517 pub fn handler<F, Fut>(self, handler: F) -> Task<I, O>
518 where
519 F: Fn(Context, I) -> Fut + Send + Sync + 'static,
520 Fut: Future<Output = Result<O, TaskError>> + Send + 'static,
521 I: DeserializeOwned + Send + 'static,
522 O: Serialize + 'static,
523 {
524 let handler = Arc::new(handler);
525 let erased: ErasedHandler = Arc::new(move |context, input| {
526 let handler = Arc::clone(&handler);
527 Box::pin(async move {
528 let input: I = match serde_json::from_value(input) {
529 Ok(input) => input,
530 Err(e) => {
531 return Err(TaskError::non_retryable(format!(
532 "the input does not match the task's input type: {e}"
533 )));
534 }
535 };
536 let output = handler(context, input).await?;
537 serde_json::to_value(output).map_err(|e| {
538 TaskError::non_retryable(format!(
539 "the output could not be serialized to JSON: {e}"
540 ))
541 })
542 })
543 });
544 Task {
545 def: TaskDef {
546 name: self.name,
547 options: self.options,
548 parents: Vec::new(),
549 handler: erased,
550 durable: false,
551 batch: None,
552 },
553 standalone: self.standalone,
554 _types: PhantomData,
555 }
556 }
557
558 /// Attaches a **durable** handler and finishes the declaration.
559 ///
560 /// A durable task may pause on the engine rather than on the worker:
561 /// [`DurableContext::sleep_for`](crate::DurableContext::sleep_for) and
562 /// [`wait_for_event`](crate::DurableContext::wait_for_event) record the
563 /// wait in the engine's event log, so a worker that dies while waiting
564 /// does not lose it — the task is assigned again and the handler is run
565 /// **from the top**, with the waits that already finished answered at
566 /// once.
567 ///
568 /// That replay is what makes determinism a rule rather than a nicety: the
569 /// handler must reach the same durable operations in the same order on
570 /// every attempt, or the engine answers
571 /// [`Error::Nondeterminism`](crate::Error::Nondeterminism) and the run
572 /// fails without a retry. Anything that must not be recomputed goes
573 /// through [`memo`](crate::DurableContext::memo) or
574 /// [`now`](crate::DurableContext::now); see [`DurableContext`] for the
575 /// whole of the bargain.
576 ///
577 /// The task asks the engine for a `durable` slot rather than a `default`
578 /// one, and its worker registers a durable slot pool
579 /// ([`WorkerBuilder::durable_slots`](crate::WorkerBuilder::durable_slots),
580 /// 1000 by default) — a waiting durable task is not doing any work, so
581 /// those slots are cheap.
582 ///
583 /// ```
584 /// use std::time::Duration;
585 ///
586 /// use hatchet_client::TaskBuilder;
587 ///
588 /// let approve = TaskBuilder::<(), String>::new("approve")
589 /// .durable_handler(|ctx, _input| async move {
590 /// ctx.sleep_for(Duration::from_secs(60)).await?;
591 /// let event = ctx.wait_for_event("approved").await?;
592 /// Ok(event.key)
593 /// });
594 /// # let _ = approve;
595 /// ```
596 ///
597 /// [`DurableContext`]: crate::DurableContext
598 pub fn durable_handler<F, Fut>(self, handler: F) -> Task<I, O>
599 where
600 F: Fn(DurableContext, I) -> Fut + Send + Sync + 'static,
601 Fut: Future<Output = Result<O, TaskError>> + Send + 'static,
602 I: DeserializeOwned + Send + 'static,
603 O: Serialize + 'static,
604 {
605 let handler = Arc::new(handler);
606 let erased: ErasedHandler = Arc::new(move |context, input| {
607 let handler = Arc::clone(&handler);
608 Box::pin(async move {
609 // The only place a `DurableContext` is ever made, which is
610 // what keeps the durable operations out of an ordinary
611 // handler's reach. A durable action always arrives with a
612 // durable invocation attached; anything else is a worker bug,
613 // so it is reported rather than panicked on.
614 let context = DurableContext::attach(context)?;
615 let input: I = match serde_json::from_value(input) {
616 Ok(input) => input,
617 Err(e) => {
618 return Err(TaskError::non_retryable(format!(
619 "the input does not match the task's input type: {e}"
620 )));
621 }
622 };
623 let output = handler(context, input).await?;
624 serde_json::to_value(output).map_err(|e| {
625 TaskError::non_retryable(format!(
626 "the output could not be serialized to JSON: {e}"
627 ))
628 })
629 })
630 });
631 Task {
632 def: TaskDef {
633 name: self.name,
634 options: self.options,
635 parents: Vec::new(),
636 handler: erased,
637 durable: true,
638 batch: None,
639 },
640 standalone: self.standalone,
641 _types: PhantomData,
642 }
643 }
644
645 /// Attaches a **batch** handler and finishes the declaration.
646 ///
647 /// The engine buffers concurrent runs of this task and hands the whole
648 /// group to one worker at once: the handler is called **once** with every
649 /// buffered input, keyed by [`BatchMemberId`], and answers with one output
650 /// per input. Each member's output is reported separately, so the runs
651 /// behind them complete — or fail — independently.
652 ///
653 /// Three rules keep a member from waiting on an answer that never comes:
654 ///
655 /// - A member whose input does not deserialize into `I` fails on its own,
656 /// without being shown to the handler and without touching the rest.
657 /// - A member the handler leaves out of the [`BatchOutput`] is reported
658 /// **failed** rather than left alone. Measured against a real engine, an
659 /// unreported member stays `Running` until the task times out and is
660 /// never assigned again.
661 /// - A handler that returns `Err` fails **every** member of the batch with
662 /// that error, since there is no way to tell which member it was about.
663 ///
664 /// Both official SDKs instead fail the whole batch when a member is
665 /// missing, throwing away the outputs the handler did produce; this SDK
666 /// keeps them. A handler that panics fails every member the same way an
667 /// `Err` does.
668 ///
669 /// # How a batch runs on the worker
670 ///
671 /// A batch is **one** run of the worker, however many task runs it answers
672 /// for: it takes one `default` slot, and the STARTED naming every member is
673 /// reported before the handler is called. What comes back is at most two
674 /// reports — the members that succeeded, then the ones that failed —
675 /// because one event type covers a whole report.
676 ///
677 /// The [`Context`] the handler is given is the **batch's**: its per-run
678 /// accessors are empty, as [`Context`]'s own documentation sets out, and
679 /// everything about the batch is on [`BatchInput`]. Cancellation is the
680 /// batch's too: the worker shutting down cancels the whole batch and
681 /// nothing terminal is reported for any member, and there is no way to
682 /// cancel one member of a batch that is already running.
683 ///
684 /// # Rules a batch task is held to
685 ///
686 /// - It needs an engine of at least
687 /// [`BATCH_MIN_ENGINE_VERSION`](crate::BATCH_MIN_ENGINE_VERSION);
688 /// [`WorkerBuilder::build`](crate::WorkerBuilder::build) refuses an older
689 /// one, which would take the registration and then never batch anything.
690 /// - It cannot set [`retries`](Self::retries): the declaration is refused
691 /// with [`Error::InvalidDeclaration`](crate::Error::InvalidDeclaration)
692 /// rather than quietly forced to zero, as the official SDKs do. Failing a
693 /// member with a retryable [`TaskError`] still has the engine re-batch
694 /// that member on its own.
695 /// - It cannot be an [`on_failure`](crate::Workflow::on_failure) or
696 /// [`on_success`](crate::Workflow::on_success) hook: a hook runs because
697 /// one particular run ended, so there is nothing to batch it with.
698 /// - It cannot be durable — a durable handler is a different method, so
699 /// that one is a compile error rather than a rule.
700 ///
701 /// ```
702 /// use hatchet_client::{BatchConfig, BatchOutput, TaskBuilder, TaskError};
703 ///
704 /// let lengths = TaskBuilder::<String, usize>::new("lengths").batch_handler(
705 /// BatchConfig::max_size(16),
706 /// |_ctx, batch| async move {
707 /// let mut output = BatchOutput::new();
708 /// for (id, text) in batch.iter() {
709 /// if text.is_empty() {
710 /// output = output.fail(id.clone(), TaskError::non_retryable("empty"));
711 /// } else {
712 /// output = output.ok(id.clone(), text.len());
713 /// }
714 /// }
715 /// Ok(output)
716 /// },
717 /// );
718 /// # let _ = lengths;
719 /// ```
720 pub fn batch_handler<F, Fut>(self, config: BatchConfig, handler: F) -> Task<I, O>
721 where
722 F: Fn(Context, BatchInput<I>) -> Fut + Send + Sync + 'static,
723 Fut: Future<Output = Result<BatchOutput<O>, TaskError>> + Send + 'static,
724 I: DeserializeOwned + Send + 'static,
725 O: Serialize + Send + 'static,
726 {
727 let handler = Arc::new(handler);
728 let name = self.name.clone();
729 let erased: ErasedBatchHandler = Arc::new(move |context, action| {
730 let handler = Arc::clone(&handler);
731 let name = name.clone();
732 Box::pin(async move {
733 let (input, mut report) = BatchInput::<I>::decode(&action)?;
734 let members: Vec<BatchMemberId> = input.ids().cloned().collect();
735 // Called even when every input was rejected, so "the handler
736 // runs exactly once per batch" holds without exceptions.
737 let output = handler(context, input).await?;
738 reconcile(&name, &members, output.into_items(), &mut report);
739 Ok(report)
740 })
741 });
742 self.into_batch_task(config, false, erased)
743 }
744
745 /// Attaches a batch handler that answers with **one value for the whole
746 /// batch**, which every buffered run then receives as its own output.
747 ///
748 /// For work that is the same for every caller — a cache warm-up, a shared
749 /// lookup — where per-member outputs would be one value repeated. The
750 /// registration says so (`broadcast_output`), so the engine and the handler
751 /// can never disagree about the shape of the answer: which of the two
752 /// builder methods was called decides both.
753 ///
754 /// A member whose input does not deserialize into `I` still fails on its
755 /// own and does **not** receive the broadcast value. Everything else in
756 /// [`batch_handler`](Self::batch_handler) — the engine floor, no retries,
757 /// no hooks — applies here too.
758 ///
759 /// ```
760 /// use hatchet_client::{BatchConfig, TaskBuilder};
761 ///
762 /// let refresh = TaskBuilder::<String, String>::new("refresh").batch_broadcast_handler(
763 /// BatchConfig::max_size(64),
764 /// |_ctx, batch| async move { Ok(format!("refreshed for {} callers", batch.len())) },
765 /// );
766 /// # let _ = refresh;
767 /// ```
768 pub fn batch_broadcast_handler<F, Fut>(self, config: BatchConfig, handler: F) -> Task<I, O>
769 where
770 F: Fn(Context, BatchInput<I>) -> Fut + Send + Sync + 'static,
771 Fut: Future<Output = Result<O, TaskError>> + Send + 'static,
772 I: DeserializeOwned + Send + 'static,
773 O: Serialize + Send + 'static,
774 {
775 let handler = Arc::new(handler);
776 let name = self.name.clone();
777 let erased: ErasedBatchHandler = Arc::new(move |context, action| {
778 let handler = Arc::clone(&handler);
779 let name = name.clone();
780 Box::pin(async move {
781 let (input, mut report) = BatchInput::<I>::decode(&action)?;
782 let members: Vec<BatchMemberId> = input.ids().cloned().collect();
783 let output = handler(context, input).await?;
784 let value = serde_json::to_value(output).map_err(|e| {
785 TaskError::non_retryable(format!(
786 "the output could not be serialized to JSON: {e}"
787 ))
788 })?;
789 // Serialized once and copied, rather than left to `reconcile`
790 // to serialize per member: the value is the same for all of
791 // them, so a failure to serialize it is a failure of the whole
792 // batch and is raised above instead.
793 let answered = members
794 .iter()
795 .map(|id| (id.clone(), Ok(value.clone())))
796 .collect();
797 reconcile(&name, &members, answered, &mut report);
798 Ok(report)
799 })
800 });
801 self.into_batch_task(config, true, erased)
802 }
803
804 /// The half both batch handlers share: a [`Task`] whose ordinary handler
805 /// can only ever be reached by mistake.
806 fn into_batch_task(
807 self,
808 config: BatchConfig,
809 broadcast: bool,
810 handler: ErasedBatchHandler,
811 ) -> Task<I, O> {
812 let name = self.name;
813 // A batch task is assigned as `START_BATCH`, never as `START_STEP_RUN`
814 // — the engine even re-batches a failed member into a batch of one
815 // rather than assigning it singly. If an ordinary run arrives anyway,
816 // the engine took the registration and ignored the batch config, and
817 // saying so by name is far better than running a handler written for a
818 // whole batch against one input.
819 let stub_name = name.clone();
820 let stub: ErasedHandler = Arc::new(move |_context, _input| {
821 let name = stub_name.clone();
822 Box::pin(async move {
823 Err(TaskError::non_retryable(format!(
824 "`{name}` is a batch task, but this run was assigned as an ordinary task run; \
825 the engine this worker is connected to does not batch it"
826 )))
827 })
828 });
829 Task {
830 def: TaskDef {
831 name,
832 options: self.options,
833 parents: Vec::new(),
834 handler: stub,
835 durable: false,
836 batch: Some(BatchDef {
837 config,
838 broadcast,
839 handler,
840 }),
841 },
842 standalone: self.standalone,
843 _types: PhantomData,
844 }
845 }
846}
847
848/// A declared task: register it on a worker by itself, or add it to a
849/// [`Workflow`](crate::Workflow).
850#[must_use = "a declared task runs nothing until it is registered on a worker"]
851pub struct Task<I, O> {
852 pub(crate) def: TaskDef,
853 pub(crate) standalone: WorkflowOptions,
854 _types: PhantomData<fn(I) -> O>,
855}
856
857impl<I, O> fmt::Debug for Task<I, O> {
858 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
859 f.debug_struct("Task")
860 .field("name", &self.def.name)
861 .field("parents", &self.def.parents)
862 .finish_non_exhaustive()
863 }
864}
865
866impl<I, O> Clone for Task<I, O> {
867 fn clone(&self) -> Self {
868 Self {
869 def: self.def.clone(),
870 standalone: self.standalone.clone(),
871 _types: PhantomData,
872 }
873 }
874}
875
876impl<I, O> Task<I, O> {
877 /// The task's name as declared.
878 pub fn name(&self) -> &str {
879 &self.def.name
880 }
881
882 /// Makes this task run after `parent` within a workflow. Call once per
883 /// parent. The parent must be added to the same workflow.
884 ///
885 /// `parent` is taken by reference, so parents must be attached *before*
886 /// the parent task is moved into the workflow (or cloned first):
887 ///
888 /// ```
889 /// # use hatchet_client::{TaskBuilder, Workflow};
890 /// let fetch = TaskBuilder::<(), u32>::new("fetch").handler(|_ctx, _input| async { Ok(1) });
891 /// let report = TaskBuilder::<(), ()>::new("report")
892 /// .handler(|_ctx, _input| async { Ok(()) })
893 /// .parent(&fetch);
894 /// let workflow = Workflow::new("pipeline").task(&fetch).task(&report);
895 /// ```
896 pub fn parent<PI, PO>(mut self, parent: &Task<PI, PO>) -> Self {
897 self.def.parents.push(parent.def.name.clone());
898 self
899 }
900}
901
902#[cfg(test)]
903mod tests {
904 use super::super::Condition;
905 use super::*;
906 use serde::{Deserialize, Serialize};
907 use serde_json::json;
908 use std::time::Duration;
909
910 #[derive(Deserialize, Serialize)]
911 struct In {
912 repo: String,
913 }
914
915 #[derive(Deserialize, Serialize, Debug, PartialEq)]
916 struct Out {
917 pr: Option<String>,
918 }
919
920 fn echo_task(name: &str) -> Task<In, Out> {
921 TaskBuilder::<In, Out>::new(name).handler(|_ctx, input: In| async move {
922 Ok(Out {
923 pr: Some(input.repo),
924 })
925 })
926 }
927
928 #[test]
929 fn builder_collects_task_options() {
930 let task = TaskBuilder::<In, Out>::new("agent-run")
931 .retries(3)
932 .retry_backoff(2.0, 60)
933 .execution_timeout(Duration::from_secs(7200))
934 .schedule_timeout(Duration::from_secs(300))
935 .concurrency(Concurrency::expr("input.device_id").max_runs(1))
936 .rate_limit(RateLimit::new("github-api", 1))
937 .worker_label("os", DesiredLabel::eq("macos").required())
938 .handler(|_ctx, _input: In| async move { Ok(Out { pr: None }) });
939
940 assert_eq!(task.name(), "agent-run");
941 let options = &task.def.options;
942 assert_eq!(options.retries, 3);
943 assert_eq!(options.backoff, Some((2.0, 60)));
944 assert_eq!(options.execution_timeout, Some(Duration::from_secs(7200)));
945 assert_eq!(options.schedule_timeout, Some(Duration::from_secs(300)));
946 assert_eq!(
947 options.concurrency,
948 [Concurrency::expr("input.device_id").max_runs(1)]
949 );
950 assert_eq!(options.rate_limits, [RateLimit::new("github-api", 1)]);
951 assert_eq!(
952 options.worker_labels["os"],
953 DesiredLabel::eq("macos").required()
954 );
955 assert!(task.standalone.is_empty());
956 assert!(task.def.parents.is_empty());
957 }
958
959 #[test]
960 fn builder_collects_standalone_trigger_options() {
961 let task = TaskBuilder::<In, Out>::new("nightly")
962 .description("Nightly sweep")
963 .version("v2")
964 .on_events(["approval.granted", "approval.revoked"])
965 .cron("0 * * * *")
966 .cron("30 2 * * *")
967 .cron_input(json!({"repo": "hatchet-rs"}))
968 .default_priority(Priority::High)
969 .handler(|_ctx, _input: In| async move { Ok(Out { pr: None }) });
970
971 let standalone = &task.standalone;
972 assert!(!standalone.is_empty());
973 assert_eq!(standalone.description.as_deref(), Some("Nightly sweep"));
974 assert_eq!(standalone.version.as_deref(), Some("v2"));
975 assert_eq!(
976 standalone.on_events,
977 ["approval.granted", "approval.revoked"]
978 );
979 assert_eq!(standalone.on_crons, ["0 * * * *", "30 2 * * *"]);
980 assert_eq!(standalone.cron_input, Some(json!({"repo": "hatchet-rs"})));
981 assert_eq!(standalone.default_priority, Some(Priority::High));
982 }
983
984 #[test]
985 fn builder_collects_conditions_per_gate_and_accumulates() {
986 let task = TaskBuilder::<In, Out>::new("gated")
987 .wait_for(Condition::sleep(Duration::from_secs(5)))
988 .wait_for(Condition::on_event("go"))
989 .skip_if(Condition::on_event("skip"))
990 .cancel_if(Condition::on_event("stop"))
991 .handler(|_ctx, _input: In| async move { Ok(Out { pr: None }) });
992
993 let options = &task.def.options;
994 assert_eq!(
995 options.wait_for,
996 ConditionSet::from(Condition::sleep(Duration::from_secs(5)))
997 .and(Condition::on_event("go")),
998 "repeated calls accumulate rather than replace"
999 );
1000 assert_eq!(options.skip_if, Condition::on_event("skip").into());
1001 assert_eq!(options.cancel_if, Condition::on_event("stop").into());
1002 }
1003
1004 #[test]
1005 fn a_task_without_conditions_has_three_empty_gates() {
1006 let task = echo_task("plain");
1007 assert!(task.def.options.wait_for.is_empty());
1008 assert!(task.def.options.skip_if.is_empty());
1009 assert!(task.def.options.cancel_if.is_empty());
1010 }
1011
1012 #[test]
1013 fn parents_are_recorded_by_name_across_input_and_output_types() {
1014 let a = echo_task("fetch");
1015 let b =
1016 TaskBuilder::<(), u32>::new("count").handler(|_ctx, _input: ()| async move { Ok(1) });
1017 let c = echo_task("report").parent(&a).parent(&b);
1018 assert_eq!(c.def.parents, ["fetch", "count"]);
1019 }
1020
1021 #[tokio::test]
1022 async fn erased_handler_round_trips_json() {
1023 let task = echo_task("agent-run");
1024 let output = (task.def.handler)(Context::placeholder(), json!({"repo": "hatchet-rs"}))
1025 .await
1026 .unwrap();
1027 assert_eq!(output, json!({"pr": "hatchet-rs"}));
1028 }
1029
1030 #[tokio::test]
1031 async fn input_of_the_wrong_shape_is_a_non_retryable_error() {
1032 let task = echo_task("agent-run");
1033 let error = (task.def.handler)(Context::placeholder(), json!({"repo": 42}))
1034 .await
1035 .unwrap_err();
1036 assert!(!error.is_retryable());
1037 assert!(error.message().contains("input"), "{error}");
1038 }
1039
1040 #[tokio::test]
1041 async fn handler_errors_pass_through_unchanged() {
1042 let task = TaskBuilder::<In, Out>::new("fails")
1043 .handler(|_ctx, _input: In| async move { Err(TaskError::non_retryable("nope")) });
1044 let error = (task.def.handler)(Context::placeholder(), json!({"repo": "x"}))
1045 .await
1046 .unwrap_err();
1047 assert_eq!(error, TaskError::non_retryable("nope"));
1048 }
1049
1050 #[tokio::test]
1051 async fn output_that_cannot_be_serialized_is_a_non_retryable_error() {
1052 use std::collections::HashMap;
1053 // JSON object keys must be strings; a tuple key cannot be serialized.
1054 let task = TaskBuilder::<(), HashMap<(i32, i32), i32>>::new("bad-output")
1055 .handler(|_ctx, _input: ()| async move { Ok(HashMap::from([((1, 2), 3)])) });
1056 let error = (task.def.handler)(Context::placeholder(), json!(null))
1057 .await
1058 .unwrap_err();
1059 assert!(!error.is_retryable());
1060 assert!(error.message().contains("output"), "{error}");
1061 }
1062
1063 #[test]
1064 fn debug_names_the_declaration_and_says_it_is_not_all_of_it() {
1065 let builder = TaskBuilder::<In, Out>::new("agent-run").retries(3);
1066 let debug = format!("{builder:?}");
1067 assert!(debug.starts_with("TaskBuilder"), "{debug}");
1068 assert!(debug.contains("agent-run"), "{debug}");
1069 assert!(debug.contains(".."), "{debug}");
1070
1071 let task = echo_task("report").parent(&echo_task("fetch"));
1072 let debug = format!("{task:?}");
1073 assert!(debug.starts_with("Task"), "{debug}");
1074 assert!(debug.contains("report"), "{debug}");
1075 assert!(debug.contains("fetch"), "{debug}");
1076 assert!(debug.contains(".."), "{debug}");
1077 }
1078
1079 /// A `START_BATCH` for two members, shaped as a real engine sends one.
1080 fn batch_action(items: &[(&str, Value)]) -> AssignedAction {
1081 let payload: serde_json::Map<String, Value> = items
1082 .iter()
1083 .map(|(id, input)| {
1084 (
1085 (*id).to_string(),
1086 json!({"workflow_run_id": format!("{id}-run"), "payload": {"input": input}}),
1087 )
1088 })
1089 .collect();
1090 AssignedAction {
1091 action_payload: Value::Object(payload).to_string(),
1092 batch_id: Some("b-1".to_string()),
1093 ..AssignedAction::default()
1094 }
1095 }
1096
1097 async fn run_batch(task: &Task<u32, u32>, action: &AssignedAction) -> BTreeMap<String, Value> {
1098 let handler = task
1099 .def
1100 .batch
1101 .as_ref()
1102 .expect("a batch task")
1103 .handler
1104 .clone();
1105 let report = handler(Context::placeholder(), action.clone())
1106 .await
1107 .expect("the batch handler answered");
1108 report
1109 .into_iter()
1110 .map(|(id, result)| {
1111 (
1112 id,
1113 match result {
1114 Ok(value) => value,
1115 Err(error) => json!({"failed": error.message()}),
1116 },
1117 )
1118 })
1119 .collect()
1120 }
1121
1122 #[test]
1123 fn a_batch_task_carries_its_config_and_says_it_is_not_a_broadcast() {
1124 let task = TaskBuilder::<u32, u32>::new("double").batch_handler(
1125 BatchConfig::max_size(4).group_key("input.tenant"),
1126 |_ctx, _batch| async move { Ok(BatchOutput::new()) },
1127 );
1128 let batch = task.def.batch.as_ref().expect("a batch task");
1129 assert!(!batch.broadcast);
1130 assert_eq!(
1131 batch.config,
1132 BatchConfig::max_size(4).group_key("input.tenant")
1133 );
1134 assert!(!task.def.durable, "a batch task asks for a default slot");
1135 }
1136
1137 #[tokio::test]
1138 async fn a_batch_handler_is_called_once_and_answers_for_every_member() {
1139 let calls = Arc::new(std::sync::atomic::AtomicUsize::new(0));
1140 let seen = Arc::clone(&calls);
1141 let task = TaskBuilder::<u32, u32>::new("double").batch_handler(
1142 BatchConfig::max_size(4),
1143 move |_ctx, batch: BatchInput<u32>| {
1144 let seen = Arc::clone(&seen);
1145 async move {
1146 seen.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
1147 Ok(batch.iter().map(|(id, n)| (id.clone(), n * 2)).collect())
1148 }
1149 },
1150 );
1151
1152 let report = run_batch(&task, &batch_action(&[("a", json!(1)), ("b", json!(2))])).await;
1153
1154 assert_eq!(calls.load(std::sync::atomic::Ordering::SeqCst), 1);
1155 assert_eq!(
1156 report,
1157 BTreeMap::from([("a".to_string(), json!(2)), ("b".to_string(), json!(4))]),
1158 );
1159 }
1160
1161 /// The difference from both official SDKs: the members that were answered
1162 /// keep their outputs, and only the omitted one fails.
1163 #[tokio::test]
1164 async fn a_member_the_handler_leaves_out_fails_alone() {
1165 let task = TaskBuilder::<u32, u32>::new("double").batch_handler(
1166 BatchConfig::max_size(4),
1167 |_ctx, batch: BatchInput<u32>| async move {
1168 Ok(BatchOutput::new().ok(batch.ids().next().unwrap().clone(), 10))
1169 },
1170 );
1171
1172 let report = run_batch(&task, &batch_action(&[("a", json!(1)), ("b", json!(2))])).await;
1173
1174 assert_eq!(report["a"], json!(10));
1175 assert!(
1176 report["b"]["failed"]
1177 .as_str()
1178 .unwrap()
1179 .contains("no output"),
1180 "{report:?}"
1181 );
1182 }
1183
1184 #[tokio::test]
1185 async fn a_member_whose_input_is_of_the_wrong_type_never_reaches_the_handler() {
1186 let task = TaskBuilder::<u32, u32>::new("double").batch_handler(
1187 BatchConfig::max_size(4),
1188 |_ctx, batch: BatchInput<u32>| async move {
1189 assert_eq!(batch.len(), 1, "only the decodable member is shown");
1190 Ok(batch.iter().map(|(id, n)| (id.clone(), n * 2)).collect())
1191 },
1192 );
1193
1194 let report = run_batch(
1195 &task,
1196 &batch_action(&[("a", json!(1)), ("b", json!("not a number"))]),
1197 )
1198 .await;
1199
1200 assert_eq!(report["a"], json!(2));
1201 assert!(
1202 report["b"]["failed"]
1203 .as_str()
1204 .unwrap()
1205 .contains("input type"),
1206 "{report:?}"
1207 );
1208 }
1209
1210 #[tokio::test]
1211 async fn a_broadcast_handler_gives_every_member_the_same_value() {
1212 let task = TaskBuilder::<u32, u32>::new("warm").batch_broadcast_handler(
1213 BatchConfig::max_size(4),
1214 |_ctx, batch: BatchInput<u32>| async move { Ok(u32::try_from(batch.len()).unwrap()) },
1215 );
1216
1217 assert!(task.def.batch.as_ref().unwrap().broadcast);
1218 let report = run_batch(&task, &batch_action(&[("a", json!(1)), ("b", json!(2))])).await;
1219 assert_eq!(
1220 report,
1221 BTreeMap::from([("a".to_string(), json!(2)), ("b".to_string(), json!(2))]),
1222 );
1223 }
1224
1225 #[tokio::test]
1226 async fn a_batch_handler_that_fails_says_nothing_about_any_member() {
1227 let task = TaskBuilder::<u32, u32>::new("double").batch_handler(
1228 BatchConfig::max_size(4),
1229 |_ctx, _batch: BatchInput<u32>| async move { Err(TaskError::new("the api is down")) },
1230 );
1231
1232 let handler = task.def.batch.as_ref().unwrap().handler.clone();
1233 let error = handler(Context::placeholder(), batch_action(&[("a", json!(1))]))
1234 .await
1235 .unwrap_err();
1236
1237 // Whose failure it is cannot be told from here: the runner fails every
1238 // member with it.
1239 assert_eq!(error, TaskError::new("the api is down"));
1240 }
1241
1242 /// The stub: an engine that took the registration and ignored the batch
1243 /// config assigns ordinary runs, and they must fail loudly rather than
1244 /// running a whole-batch handler against one input.
1245 #[tokio::test]
1246 async fn a_batch_task_assigned_as_an_ordinary_run_fails_by_name() {
1247 let task = TaskBuilder::<u32, u32>::new("double").batch_handler(
1248 BatchConfig::max_size(4),
1249 |_ctx, _batch: BatchInput<u32>| async move { Ok(BatchOutput::new()) },
1250 );
1251
1252 let error = (task.def.handler)(Context::placeholder(), json!(1))
1253 .await
1254 .unwrap_err();
1255
1256 assert!(!error.is_retryable(), "{error}");
1257 assert!(error.message().contains("double"), "{error}");
1258 assert!(error.message().contains("batch task"), "{error}");
1259 }
1260
1261 #[test]
1262 fn tasks_are_cheap_to_clone_and_share_the_handler() {
1263 let task = echo_task("agent-run");
1264 let clone = task.clone();
1265 assert!(Arc::ptr_eq(&task.def.handler, &clone.def.handler));
1266 }
1267}