Expand description
Rust SDK for Hatchet: run workers and trigger tasks.
Pre-release, and not yet published to crates.io. What is here:
configuration, connection, task/workflow declaration, the worker that runs
them, the Context a handler gets, and triggering runs and pushing
events from the client side, with Workflow::on_failure and
Workflow::on_success handlers around a workflow and conditions on the
tasks in it (TaskBuilder::wait_for, skip_if
and cancel_if), and pinning a workflow’s runs
to one worker (StickyStrategy). Also here: idempotency keys
(Idempotency), static and dynamic (CEL) rate limits (RateLimit)
including upserting a tenant-wide limit (Client::rate_limits), sticky
child runs (RunOpts::sticky), and a switch to turn gzip
compression off (ClientBuilder::gzip). Also here: run control over
gRPC — Client::runs cancels, replays and inspects a run by id or by
TasksFilter, and RunHandle::cancel/WorkflowRunHandle::cancel
stop the run a handle names, with a cancelled run reported to a waiter as
its own error (Error::RunCancelled) rather than an empty-message
failure. Also here: reading a run’s output back — Client::runs
subscribes to the chunks a handler publishes with
Context::put_stream, by run id (RunsClient::stream) or, to be
sure of catching the first one, by a metadata pair opened before the
trigger (RunsClient::stream_by_metadata); the chunks come back in
order as StreamChunks, with a skipped one reported rather than
hidden (Error::StreamGap). Also here: durable tasks —
TaskBuilder::durable_handler declares one and hands its handler a
DurableContext, which can pause on the engine rather than on the
worker (sleep_for,
wait_for_event,
wait_for) and hold what must not be
recomputed (memo,
now), so a worker that dies while waiting loses
nothing. It can also start child runs through the same event log
(spawn,
spawn_many), so a replayed attempt is
handed the runs the first one started rather than starting new ones — that
one needs an engine of at least
DURABLE_SPAWN_MIN_ENGINE_VERSION. A durable task that is only waiting
need not hold one of the worker’s slots either: declare an
EvictionPolicy (TaskBuilder::eviction_policy) and the worker hands
such a run back to the engine, which assigns it again — replaying its log —
when what it was waiting for happens, or at once on
RunsClient::restore_evicted. Also here: batch tasks —
TaskBuilder::batch_handler declares one whose concurrent runs the
engine buffers and hands to one worker as a single call, answered with one
output per member (BatchInput, BatchOutput);
TaskBuilder::batch_broadcast_handler is the shape where one value goes
to every member instead. Needs an engine of at least
BATCH_MIN_ENGINE_VERSION. The REST management API — listing runs,
logs, crons, scheduled runs, workers, workflows, filters, webhooks and
metrics — is the hatchet-rest crate, reached from here through
Client::rest() with the rest feature (see below). Run control does not
need it, since cancelling, replaying and inspecting a run are all gRPC
here; the repository’s README lists the whole roadmap and the differences
from the official Go SDK.
The oldest engine this SDK works with is MIN_ENGINE_VERSION.
§Cargo features
TLS is assembled from a rustls crypto provider and a root store, each
behind a feature that forwards to tonic’s feature of the same name:
tls-ring (default) or tls-aws-lc for the provider, tls-native-roots
(default) or tls-webpki-roots for the roots. With no provider the crate
still builds and TlsStrategy::None still works, while
TlsStrategy::Tls and TlsStrategy::Mtls fail at Client::new
with an Error::Config naming what to enable.
With the rest feature (off by default), Client::rest() returns a
hatchet_rest::RestClient for the REST management API, built from the
client’s own configuration, and hatchet_client::hatchet_rest re-exports
that crate. The tls-* features are forwarded to it, so one TLS stack is
linked. Without the feature, this crate links no HTTP client.
With the otel feature (off by default), a trigger writes its span’s W3C
traceparent into the run’s additional metadata and a worker continues
the trace from the value it finds there — see “Tracing” below. It links
OpenTelemetry’s API (opentelemetry 0.32) and tracing-opentelemetry
0.33, never its SDK or an exporter.
§Tracing
Triggering a run opens a tracing span named the way the official Go SDK
names its own: hatchet.run_workflow around Task::run_no_wait,
Task::run, their Workflow counterparts and Context::spawn,
Context::spawn_workflow, Context::run and
DurableContext::spawn (for run, until the result arrives), and one
hatchet.run_workflows around a run_many or
DurableContext::spawn_many. They are producer spans with the
attributes instrumentor, hatchet.workflow_name (as declared),
hatchet.child_workflow_run_id or hatchet.num_workflows. Pushing events
opens hatchet.push_event (hatchet.event_key, the key as given) or one
hatchet.bulk_push_event (hatchet.num_events).
A worker runs each action inside hatchet.start_step_run, a consumer span
with the attributes Go’s middleware sets (tenant, worker, workflow run,
step run, step id, action and step names, retry count; workflow, workflow
version, parent run, child index and child key when the action has them);
the handler runs inside it, so what the handler opens — a child’s trigger
above all — is its child. A batch is one such span for the whole batch
(with hatchet.batch_id and hatchet.batch_size, this SDK’s own). An
engine-sent cancellation opens hatchet.cancel_step_run, as the official
Python SDK does (Go opens nothing there). A failed or panicking handler
marks the run’s span as an error; a cancelled run’s status is left unset.
All of these are INFO spans carrying the otel.kind/otel.status_*
fields a tracing-opentelemetry layer turns into a span kind and status.
They exist with or without any feature, and never record a run’s input,
output or metadata.
With the otel feature (off by default), the trace crosses the engine. A
trigger — a child spawned from a handler and a pushed event included —
writes its span’s W3C traceparent (version 00) into the run’s or
event’s additional metadata under the key "traceparent", the key the
official SDKs use, replacing a value already there, as they do; a
run_many or spawn_many writes its one span’s value into every run. A
worker makes hatchet.start_step_run a child of the traceparent in the
action’s metadata; a value that is not a valid version-00 (or later)
W3C traceparent — missing, not a string, the wrong length, uppercase,
version ff, all-zero ids — is rejected by this SDK’s own parser and the
run starts a trace of its own, unless the engine has already replaced
that value with a traceparent it derived itself (v0.107.0 does this for
some malformed shapes; see the root README’s “Tracing” section for which
ones, per engine version), in which case the handler continues the
engine’s trace instead. Only traceparent is written or read; a tracestate in the
metadata is passed through untouched. All of that happens only when the
subscriber has a tracing-opentelemetry 0.33 layer (built on
opentelemetry 0.32, the pair this crate links) and the span is enabled;
otherwise the metadata is sent as given and runs are roots. No
OpenTelemetry type appears in this crate’s API, and the OpenTelemetry SDK
and exporters are the application’s own choice.
Declare a task, register it on a worker, and let the engine hand it work.
The handler’s Context is how it talks back: logging, asking for more
time, streaming partial results, spawning child runs.
use std::time::Duration;
use hatchet_client::{Client, Context, TaskError, TaskBuilder};
use serde::{Deserialize, Serialize};
#[derive(Deserialize)]
struct Review {
repo: String,
}
#[derive(Serialize)]
struct Verdict {
approved: bool,
}
async fn review(ctx: Context, input: Review) -> Result<Verdict, TaskError> {
// A log line that does not reach the engine is not worth failing —
// and retrying — the whole task over.
if let Err(error) = ctx.log(format!("reviewing {}", input.repo)).await {
tracing::warn!(%error, "the log line was not delivered");
}
// Cloning a repository may take longer than the task's timeout allows.
ctx.refresh_timeout(Duration::from_secs(5 * 60)).await?;
if ctx.is_cancelled() {
return Err(TaskError::new("asked to stop"));
}
Ok(Verdict {
approved: input.repo == "hatchet-rs",
})
}
let client = Client::from_env()?;
let worker = client
.worker("mac-studio-1")
.slots(8)
.register(&TaskBuilder::new("review").handler(review))
.build()
.await?;
// Runs until SIGINT or SIGTERM, then waits for the runs in flight.
worker.run_until_shutdown().awaitFrom the other side, a client triggers runs of the same declaration and waits for what they produced — every wait on one client shares a single subscription, which is opened when something waits and closed when nothing does:
let verdict = review
.run(client, &Review { repo: "hatchet-rs".to_string() }, RunOpts::default())
.await?;
println!("approved: {}", verdict.approved);…or pushes events that trigger every workflow registered with a matching
on_events:
client
.events()
.push("approval.granted", &serde_json::json!({"issue": "BLOG-12"}), PushOpts::default())
.await?;Re-exports§
pub use hatchet_proto;pub use hatchet_proto::tonic;pub use hatchet_rest;
Structs§
- Batch
Config - How the engine buffers concurrent runs of one task into a batch.
- Batch
Input - The buffered inputs of one batch, keyed by
BatchMemberId. - Batch
Item - One member of a
BatchInput: its input, and the workflow run it came from. - Batch
Output - One output per batch member, as a batch handler answers.
- Client
- A connection to a Hatchet engine. Cheap to clone; clones share the underlying gRPC channel.
- Client
Builder - Builds a
ClientConfig. Anything not set here falls back to theHATCHET_CLIENT_*environment variable, then to the token’s claims. An environment variable set to the empty string counts as unset. - Client
Config - Resolved, immutable client configuration.
- Concurrency
- A concurrency limit keyed by a CEL expression over the run’s input.
- Condition
- One thing a task can wait on, be skipped by, or be cancelled by.
- Condition
Set - What one gate waits on: or-groups that must all be satisfied.
- Context
- What a running task knows about itself and can ask of the engine.
- Desired
Label - A label a task wants its worker to have.
- Durable
Context - The context a durable task’s handler is given.
- Durable
Event - One condition that was satisfied, and what satisfied it.
- Durable
RunHandle - A child run a durable handler started, and the result it is already waiting for.
- Event
Input - One event for
EventsClient::bulk_push. - Events
Client - Pushes events to the engine, one at a time or in bulk.
- Eviction
Policy - When a durable run that is waiting may be taken off this worker.
- Idempotency
- Makes the engine compute a key from each run’s input and refuse a second run that computes the same one.
- Idempotency
Collision - One idempotency-key collision, as the engine reported it.
- OrGroup
- A group of conditions of which any one satisfies the gate. Made by
any_of. - Output
Stream - A run’s output stream: the chunks its handlers publish, in order.
- Push
Opts - Options for a pushed event.
- Pushed
Event - An event pushed to the engine.
- Rate
Limit - How much of a rate limit one run of a task consumes.
- Rate
Limits Client - Creates and raises the tenant’s rate limits.
- RunDetails
- Everything
GetRunDetailsknows about one run. - RunHandle
- A started run of a single task, and its output type.
- RunOpts
- Options for triggering a run of another workflow.
- Runs
Client - Cancels, replays and inspects runs the engine already knows about.
- Shutdown
Handle - Stops a
Worker. Cloning it is cheap, and every clone stops the same worker; callingshutdownmore than once is harmless. - Stream
Chunk - One chunk of a run’s output, as
Context::put_streampublished it. - Task
- A declared task: register it on a worker by itself, or add it to a
Workflow. - Task
Builder - Configures a task before its handler is attached.
- Task
Error - Why a task run failed, and whether Hatchet should retry it.
- Task
Failure - One task’s failure within a run, as the engine reported it.
- Task
RunDetail - What the engine knows about one task of a run.
- Tasks
Filter - Which runs a
cancel_matchingorreplay_matchingcall acts on. - Worker
- A registered worker: it runs the actions the engine assigns until it is asked to stop.
- Worker
Builder - Configures a worker: what it can run, how much of it at once, and how it describes itself to the engine.
- Workflow
- A named set of tasks, ordered into a DAG by their parents.
- Workflow
Result - What a finished workflow run produced: one output per task that ran.
- Workflow
RunHandle - A started run of a whole workflow.
Enums§
- Concurrency
Limit Strategy - What happens to runs beyond a concurrency limit.
- Error
- Errors returned by
hatchet-client. - Idempotency
Method - How long an idempotency key stays claimed.
- Label
Value - A worker label value: a string or an integer.
- Priority
- Run priority; higher runs are scheduled first.
- Rate
Limit Duration - The window a rate limit’s allowance refills over.
- RunStatus
- The state of a run, or of one task in it.
- Sticky
Strategy - How a workflow’s runs are pinned to the worker that started them.
- TlsStrategy
- How the gRPC connection is secured.
Constants§
- BATCH_
MIN_ ENGINE_ VERSION - The oldest engine that really batches a batch task’s runs.
- DURABLE_
SPAWN_ MIN_ ENGINE_ VERSION - The oldest engine a durable handler may spawn a child run on with
DurableContext::spawn. - IDEMPOTENCY_
MIN_ ENGINE_ VERSION - The oldest engine that honours a workflow’s
idempotencyconfig. - MIN_
ENGINE_ VERSION - The oldest Hatchet engine this SDK works with.
Traits§
Functions§
- any_of
- Satisfied as soon as any of
conditionsis.
Type Aliases§
- Batch
Member Id - Identifies one buffered run inside a batch: the task run external id of that run, which is how the engine keys the items it sends.
- Result
Resultwith the SDK’sError.