pub struct Workflow { /* private fields */ }Expand description
A named set of tasks, ordered into a DAG by their parents.
Every task in a workflow receives the workflow’s input; a task reads
what came before it with
Context::parent_output. Triggers
(events, crons), the description, the version and the default priority
belong to the workflow rather than to its tasks.
Parents are attached to a task before it is moved in, so declare them in dependency order:
use hatchet_client::{TaskBuilder, Workflow};
let fetch = TaskBuilder::<(), u32>::new("fetch").handler(|_ctx, _input| async { Ok(21) });
let summarize = TaskBuilder::<(), String>::new("summarize")
.handler({
let fetch = fetch.clone();
move |ctx: hatchet_client::Context, _input: ()| {
let fetch = fetch.clone();
async move {
let total: u32 = ctx.parent_output(&fetch)?;
Ok(format!("total {total}"))
}
}
})
.parent(&fetch);
let pipeline = Workflow::new("pipeline")
.cron("0 * * * *")
.task(&fetch)
.task(&summarize);
assert_eq!(pipeline.name(), "pipeline");Mistakes — duplicate task names, a parent that was never added, trigger
options set on a task instead of on the workflow — are reported as
Error::InvalidDeclaration when the workflow is registered.
Implementations§
Source§impl Workflow
impl Workflow
Sourcepub fn description(self, description: impl Into<String>) -> Self
pub fn description(self, description: impl Into<String>) -> Self
Describes the workflow.
Sourcepub fn on_events(
self,
keys: impl IntoIterator<Item = impl Into<String>>,
) -> Self
pub fn on_events( self, keys: impl IntoIterator<Item = impl Into<String>>, ) -> Self
Runs the workflow whenever one of these event keys is pushed. May be called repeatedly; event keys accumulate.
Sourcepub fn cron(self, expression: impl Into<String>) -> Self
pub fn cron(self, expression: impl Into<String>) -> Self
Runs the workflow on a cron schedule. May be called repeatedly; cron expressions accumulate.
Sourcepub fn cron_input(self, input: Value) -> Self
pub fn cron_input(self, input: Value) -> Self
The input given to cron-triggered runs.
Sourcepub fn default_priority(self, priority: Priority) -> Self
pub fn default_priority(self, priority: Priority) -> Self
The priority of runs that do not specify one.
Sourcepub fn concurrency(self, concurrency: Concurrency) -> Self
pub fn concurrency(self, concurrency: Concurrency) -> Self
Adds a concurrency limit across runs of the whole workflow.
Sourcepub fn sticky(self, strategy: StickyStrategy) -> Self
pub fn sticky(self, strategy: StickyStrategy) -> Self
Pins each run’s tasks to one worker.
use hatchet_client::{StickyStrategy, TaskBuilder, Workflow};
let load = TaskBuilder::<(), ()>::new("load").handler(|_ctx, _input| async { Ok(()) });
let build = Workflow::new("build").sticky(StickyStrategy::Hard).task(&load);Sourcepub fn idempotency(self, idempotency: Idempotency) -> Self
pub fn idempotency(self, idempotency: Idempotency) -> Self
Makes the engine refuse a second run whose key matches a claimed one.
use std::time::Duration;
use hatchet_client::{Idempotency, TaskBuilder, Workflow};
let charge = TaskBuilder::<(), ()>::new("charge").handler(|_ctx, _input| async { Ok(()) });
let checkout = Workflow::new("checkout")
.idempotency(Idempotency::until_run_ends("input.order_id", Duration::from_secs(600)))
.task(&charge);Sourcepub fn task<I, O>(self, task: &Task<I, O>) -> Self
pub fn task<I, O>(self, task: &Task<I, O>) -> Self
Adds a task. Its parents must be added to this workflow too.
The task is taken by reference and cloned in (a Task is a cheap
handle: an Arc around the handler plus its options), so the caller
keeps its own handle for Context::parent_output and
WorkflowResult::output.
Mistakes (duplicate names, unknown parents, trigger options set on the
task instead of the workflow) are reported as
Error::InvalidDeclaration when the workflow is registered.
Sourcepub fn on_failure<I, O>(self, task: &Task<I, O>) -> Self
pub fn on_failure<I, O>(self, task: &Task<I, O>) -> Self
Runs task once if the workflow fails, whatever failed in it.
The task receives the workflow’s input, and its output is
discarded. It reads what went wrong with
Context::step_run_errors. It is
not one of the workflow’s tasks — it has no parents, nothing depends
on it, and it never runs when the workflow succeeds.
Declaring it twice, giving it a parent, passing a task that is
already one of the workflow’s tasks, or setting standalone-only
options on it are all Error::InvalidDeclaration at registration.
It keeps the name it was declared with, which is a third behaviour:
the official Go SDK renames the on-failure task to on-failure, and
the official Python SDK appends -on-failure to the declared name.
Only a Workflow can have one — unlike Go, a standalone task
cannot; wrap it in a one-task workflow instead.
use hatchet_client::{Context, TaskBuilder, Workflow};
let charge = TaskBuilder::<(), ()>::new("charge")
.handler(|_ctx, _input| async { Ok(()) });
let alert = TaskBuilder::<(), ()>::new("alert").handler(|ctx: Context, _input: ()| async move {
for (task, error) in ctx.step_run_errors() {
eprintln!("{task} failed: {error}");
}
Ok(())
});
let checkout = Workflow::new("checkout")
.task(&charge)
.on_failure(&alert);Sourcepub fn on_success<I, O>(self, task: &Task<I, O>) -> Self
pub fn on_success<I, O>(self, task: &Task<I, O>) -> Self
Runs task once, after every other task in the workflow has
succeeded.
The engine has no field for this — CreateWorkflowVersionRequest
only carries on_failure_task. So this is registered as an ordinary
task whose parents are every leaf of the workflow (the tasks no
other task depends on), which is how the official Python SDK does
it. The Go SDK has no equivalent at all.
Being an ordinary task, it can read its parents’ outputs with
Context::parent_output, and a
failure anywhere upstream means it never runs.
Declaring it twice, giving it parents of its own, passing a task
that is already one of the workflow’s tasks or its on-failure task,
or setting standalone-only options on it are all
Error::InvalidDeclaration at registration.
It keeps the name it was declared with, where the official Python SDK
appends -on-success to it.
use hatchet_client::{TaskBuilder, Workflow};
let fetch = TaskBuilder::<(), u32>::new("fetch").handler(|_ctx, _input| async { Ok(1) });
let lint = TaskBuilder::<(), ()>::new("lint")
.handler(|_ctx, _input| async { Ok(()) })
.parent(&fetch);
let build = TaskBuilder::<(), ()>::new("build")
.handler(|_ctx, _input| async { Ok(()) })
.parent(&fetch);
let announce = TaskBuilder::<(), ()>::new("announce")
.handler(|_ctx, _input| async { Ok(()) });
// `announce` is registered with `lint` and `build` as its parents:
// they are the workflow's leaves, and `fetch` is not.
let pipeline = Workflow::new("pipeline")
.task(&fetch)
.task(&lint)
.task(&build)
.on_success(&announce);Source§impl Workflow
impl Workflow
Sourcepub async fn run_no_wait<I: Serialize>(
&self,
client: &Client,
input: &I,
opts: RunOpts,
) -> Result<WorkflowRunHandle>
pub async fn run_no_wait<I: Serialize>( &self, client: &Client, input: &I, opts: RunOpts, ) -> Result<WorkflowRunHandle>
Triggers a run of this workflow and hands back a handle to it, without waiting for it to finish. The input is the workflow’s own, which every task in it receives.
§Errors
The same as Task::run_no_wait.
Sourcepub async fn run<I: Serialize>(
&self,
client: &Client,
input: &I,
opts: RunOpts,
) -> Result<WorkflowResult>
pub async fn run<I: Serialize>( &self, client: &Client, input: &I, opts: RunOpts, ) -> Result<WorkflowResult>
Triggers a run of this workflow and waits for every task in it to finish.
Waits without a time limit, exactly like Task::run.
§Errors
Those of run_no_wait, plus those of
WorkflowRunHandle::result.
Sourcepub async fn run_many<I: Serialize>(
&self,
client: &Client,
inputs: impl IntoIterator<Item = (I, RunOpts)>,
) -> Result<Vec<WorkflowRunHandle>>
pub async fn run_many<I: Serialize>( &self, client: &Client, inputs: impl IntoIterator<Item = (I, RunOpts)>, ) -> Result<Vec<WorkflowRunHandle>>
Triggers a run of this workflow for every (input, opts) pair, the
same way as Task::run_many, and hands back handles in the same
order as inputs.
This is also the way to start many runs of a task that is declared inside a workflow: such a task is not addressable on its own, so it is its workflow that is triggered, with the workflow’s own input.
One RunOpts for the whole batch is a map over the inputs —
inputs.into_iter().map(|input| (input, opts.clone())) — as shown on
Task::run_many.
§Retries
The same as Task::run_many: a chunk the engine received but could
not answer in time is re-sent, so up to 1000 runs may be started twice.
§Errors
The same as Task::run_many.
Trait Implementations§
Source§impl Debug for Workflow
Names the workflow and its tasks; the tasks’ handlers are closures with
nothing to print.
impl Debug for Workflow
Names the workflow and its tasks; the tasks’ handlers are closures with nothing to print.
impl Register for Workflow
Auto Trait Implementations§
impl !RefUnwindSafe for Workflow
impl !UnwindSafe for Workflow
impl Forget for Workflow
impl Freeze for Workflow
impl Move for Workflow
impl Send for Workflow
impl Sync for Workflow
impl Unpin for Workflow
impl UnsafeUnpin for Workflow
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
Source§impl<T> FutureExt for T
impl<T> FutureExt for T
Source§fn with_context(self, otel_cx: Context) -> WithContext<Self> ⓘ
fn with_context(self, otel_cx: Context) -> WithContext<Self> ⓘ
Source§fn with_current_context(self) -> WithContext<Self> ⓘ
fn with_current_context(self) -> WithContext<Self> ⓘ
Source§impl<T> Instrument for T
impl<T> Instrument for T
Source§fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
Source§fn in_current_span(self) -> Instrumented<Self> ⓘ
fn in_current_span(self) -> Instrumented<Self> ⓘ
Source§impl<T> IntoRequest<T> for T
impl<T> IntoRequest<T> for T
Source§fn into_request(self) -> Request<T>
fn into_request(self) -> Request<T>
T in a tonic::Request