Skip to main content

Workflow

Struct Workflow 

Source
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

Source

pub fn new(name: impl Into<String>) -> Self

Starts declaring a workflow.

Source

pub fn name(&self) -> &str

The workflow’s name as declared.

Source

pub fn description(self, description: impl Into<String>) -> Self

Describes the workflow.

Source

pub fn version(self, version: impl Into<String>) -> Self

Labels this version of the workflow.

Source

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.

Source

pub fn cron(self, expression: impl Into<String>) -> Self

Runs the workflow on a cron schedule. May be called repeatedly; cron expressions accumulate.

Source

pub fn cron_input(self, input: Value) -> Self

The input given to cron-triggered runs.

Source

pub fn default_priority(self, priority: Priority) -> Self

The priority of runs that do not specify one.

Source

pub fn concurrency(self, concurrency: Concurrency) -> Self

Adds a concurrency limit across runs of the whole workflow.

Source

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);
Source

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);
Source

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.

Source

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);
Source

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

Source

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.

Source

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.

Source

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 Clone for Workflow

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for Workflow

Names the workflow and its tasks; the tasks’ handlers are closures with nothing to print.

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl Register for Workflow

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> FutureExt for T

Source§

fn with_context(self, otel_cx: Context) -> WithContext<Self> ⓘ

Attaches the provided Context to this type, returning a WithContext wrapper. Read more
Source§

fn with_current_context(self) -> WithContext<Self> ⓘ

Attaches the current Context to this type, returning a WithContext wrapper. Read more
Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoRequest<T> for T

Source§

fn into_request(self) -> Request<T>

Wrap the input message T in a tonic::Request
Source§

impl<L> LayerExt<L> for L

Source§

fn named_layer<S>(&self, service: S) -> Layered<<L as Layer<S>>::Service, S>
where L: Layer<S>,

Applies the layer to a service and wraps it in Layered.
Source§

impl<T> PolicyExt for T
where T: ?Sized,

Source§

fn and<P, B, E>(self, other: P) -> And<T, P>
where T: Sized + Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns Action::Follow only if self and other return Action::Follow. Read more
Source§

fn or<P, B, E>(self, other: P) -> Or<T, P>
where T: Sized + Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns Action::Follow if either self or other returns Action::Follow. Read more
Source§

impl<T> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

Source§

fn vzip(self) -> V

Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more