Skip to main content

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}