hatchet-client 0.1.0

Rust SDK for Hatchet: run workers and trigger tasks
Documentation

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:

[dependencies]
hatchet-client = { 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 hatchet_client::{Client, Context, RunOpts, TaskBuilder};
use serde::{Deserialize, Serialize};

#[derive(Deserialize, Serialize)]
struct Greeting {
    name: String,
}

#[derive(Deserialize, Serialize)]
struct Greeted {
    message: String,
}

async fn greet(_ctx: Context, input: Greeting) -> Result<Greeted, hatchet_client::TaskError> {
    Ok(Greeted {
        message: format!("Hello, {}!", input.name),
    })
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    tracing_subscriber::fmt::init();

    let client = Client::from_env()?;
    let greet_task = TaskBuilder::new("greet").handler(greet);

    let worker = client
        .worker("standalone-task-example")
        .register(&greet_task)
        .build()
        .await?;
    // Take the shutdown handle before `run`, which consumes the worker; run
    // it in the background so this process can trigger work against it.
    let shutdown = worker.shutdown_handle();
    let running = tokio::spawn(worker.run());

    let result = greet_task
        .run(
            &client,
            &Greeting {
                name: "Hatchet".to_string(),
            },
            RunOpts::default(),
        )
        .await;

    // Stop the worker whether the run succeeded or not, so this process
    // always terminates on its own.
    shutdown.shutdown();
    running.await??;

    let greeted = result?;
    println!("worker returned: {}", greeted.message);
    Ok(())
}

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.