hatchet-client
Rust SDK for Hatchet: declare tasks and workflows, run them on a worker, and trigger runs from anywhere.
Status: pre-release. This crate has not been published to crates.io yet, and its API may still change. Until it is, depend on it from git:
[]
= { = "https://github.com/moreal/hatchet-rs" }
Requirements
- Rust 1.88 or newer.
- A Hatchet engine at v0.80.0 or newer.
Client::check_engine_version()asks the engine and returns a clear error on anything older.
Quick start
The worker side and the trigger side of one task, in one process. It needs
tokio (with macros and rt-multi-thread), serde (with derive) and, for
the log line, tracing-subscriber.
use ;
use ;
async
async
This is examples/standalone_task.rs verbatim; a test in the repository keeps
the two identical. Client::from_env() reads HATCHET_CLIENT_TOKEN and, for a
local engine, HATCHET_CLIENT_HOST_PORT and HATCHET_CLIENT_TLS_STRATEGY=none;
everything else it can take from the token's claims. The other examples
(conditions, dag_workflow, durable_approval, durable_fanout,
event_trigger, long_running, output_stream, rate_limits,
worker_labels) and how to start a local hatchet-lite engine are described
in examples/README.md.
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:
| Feature | Default | What it does |
|---|---|---|
tls-ring |
yes | ring as the rustls crypto provider |
tls-aws-lc |
no | aws-lc-rs as the crypto provider (needs a C toolchain and cmake) |
tls-native-roots |
yes | verify the engine against the platform's trust store |
tls-webpki-roots |
no | verify it against the bundled webpki roots |
rest |
no | Client::rest(): the REST management API through hatchet-rest (links reqwest); the tls-* features are forwarded to it |
otel |
no | the trace crosses the engine: a trigger (child spawns and event pushes included) writes its span's W3C traceparent into the additional metadata, and a worker's hatchet.start_step_run continues the traceparent it finds there, as the official SDKs do (links opentelemetry 0.32's API and tracing-opentelemetry 0.33, never the OpenTelemetry SDK) |
With no crypto provider the crate still builds, and plaintext
(HATCHET_CLIENT_TLS_STRATEGY=none) still works; tls and mtls then fail at
Client::new with an Error::Config that names the features to enable. Native
roots win when both root stores are compiled in, and
HATCHET_CLIENT_TLS_ROOT_CA_FILE overrides both. Without rest, this crate
links no HTTP client (a test in xtask checks the dependency graph). The
spans (triggers, event pushes, a worker's runs, batches and cancellations) are
tracing spans and exist without otel; the feature only writes and reads the
traceparent, and only when the application's subscriber has a
tracing-opentelemetry 0.33 layer.
License
MIT OR Apache-2.0, at your option. See LICENSE-MIT and LICENSE-APACHE.