Skip to main content

Crate hatchet_client

Crate hatchet_client 

Source
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().await

From 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§

BatchConfig
How the engine buffers concurrent runs of one task into a batch.
BatchInput
The buffered inputs of one batch, keyed by BatchMemberId.
BatchItem
One member of a BatchInput: its input, and the workflow run it came from.
BatchOutput
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.
ClientBuilder
Builds a ClientConfig. Anything not set here falls back to the HATCHET_CLIENT_* environment variable, then to the token’s claims. An environment variable set to the empty string counts as unset.
ClientConfig
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.
ConditionSet
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.
DesiredLabel
A label a task wants its worker to have.
DurableContext
The context a durable task’s handler is given.
DurableEvent
One condition that was satisfied, and what satisfied it.
DurableRunHandle
A child run a durable handler started, and the result it is already waiting for.
EventInput
One event for EventsClient::bulk_push.
EventsClient
Pushes events to the engine, one at a time or in bulk.
EvictionPolicy
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.
IdempotencyCollision
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.
OutputStream
A run’s output stream: the chunks its handlers publish, in order.
PushOpts
Options for a pushed event.
PushedEvent
An event pushed to the engine.
RateLimit
How much of a rate limit one run of a task consumes.
RateLimitsClient
Creates and raises the tenant’s rate limits.
RunDetails
Everything GetRunDetails knows about one run.
RunHandle
A started run of a single task, and its output type.
RunOpts
Options for triggering a run of another workflow.
RunsClient
Cancels, replays and inspects runs the engine already knows about.
ShutdownHandle
Stops a Worker. Cloning it is cheap, and every clone stops the same worker; calling shutdown more than once is harmless.
StreamChunk
One chunk of a run’s output, as Context::put_stream published it.
Task
A declared task: register it on a worker by itself, or add it to a Workflow.
TaskBuilder
Configures a task before its handler is attached.
TaskError
Why a task run failed, and whether Hatchet should retry it.
TaskFailure
One task’s failure within a run, as the engine reported it.
TaskRunDetail
What the engine knows about one task of a run.
TasksFilter
Which runs a cancel_matching or replay_matching call acts on.
Worker
A registered worker: it runs the actions the engine assigns until it is asked to stop.
WorkerBuilder
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.
WorkflowResult
What a finished workflow run produced: one output per task that ran.
WorkflowRunHandle
A started run of a whole workflow.

Enums§

ConcurrencyLimitStrategy
What happens to runs beyond a concurrency limit.
Error
Errors returned by hatchet-client.
IdempotencyMethod
How long an idempotency key stays claimed.
LabelValue
A worker label value: a string or an integer.
Priority
Run priority; higher runs are scheduled first.
RateLimitDuration
The window a rate limit’s allowance refills over.
RunStatus
The state of a run, or of one task in it.
StickyStrategy
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 idempotency config.
MIN_ENGINE_VERSION
The oldest Hatchet engine this SDK works with.

Traits§

Register
Something a worker can register: a standalone Task or a Workflow.

Functions§

any_of
Satisfied as soon as any of conditions is.

Type Aliases§

BatchMemberId
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
Result with the SDK’s Error.