hatchet_client/lib.rs
1//! Rust SDK for [Hatchet](https://hatchet.run): run workers and trigger tasks.
2//!
3//! Pre-release, and not yet published to crates.io. What is here:
4//! configuration, connection, task/workflow declaration, the worker that runs
5//! them, the [`Context`] a handler gets, and triggering runs and pushing
6//! events from the client side, with [`Workflow::on_failure`] and
7//! [`Workflow::on_success`] handlers around a workflow and conditions on the
8//! tasks in it ([`TaskBuilder::wait_for`], [`skip_if`](TaskBuilder::skip_if)
9//! and [`cancel_if`](TaskBuilder::cancel_if)), and pinning a workflow's runs
10//! to one worker ([`StickyStrategy`]). Also here: idempotency keys
11//! ([`Idempotency`]), static and dynamic (CEL) rate limits ([`RateLimit`])
12//! including upserting a tenant-wide limit ([`Client::rate_limits`]), sticky
13//! child runs ([`RunOpts::sticky`]), and a switch to turn gzip
14//! compression off ([`ClientBuilder::gzip`]). Also here: run control over
15//! gRPC — [`Client::runs`] cancels, replays and inspects a run by id or by
16//! [`TasksFilter`], and [`RunHandle::cancel`]/[`WorkflowRunHandle::cancel`]
17//! stop the run a handle names, with a cancelled run reported to a waiter as
18//! its own error ([`Error::RunCancelled`]) rather than an empty-message
19//! failure. Also here: reading a run's output back — [`Client::runs`]
20//! subscribes to the chunks a handler publishes with
21//! [`Context::put_stream`], by run id ([`RunsClient::stream`]) or, to be
22//! sure of catching the first one, by a metadata pair opened before the
23//! trigger ([`RunsClient::stream_by_metadata`]); the chunks come back in
24//! order as [`StreamChunk`]s, with a skipped one reported rather than
25//! hidden ([`Error::StreamGap`]). Also here: durable tasks —
26//! [`TaskBuilder::durable_handler`] declares one and hands its handler a
27//! [`DurableContext`], which can pause on the *engine* rather than on the
28//! worker ([`sleep_for`](DurableContext::sleep_for),
29//! [`wait_for_event`](DurableContext::wait_for_event),
30//! [`wait_for`](DurableContext::wait_for)) and hold what must not be
31//! recomputed ([`memo`](DurableContext::memo),
32//! [`now`](DurableContext::now)), so a worker that dies while waiting loses
33//! nothing. It can also start child runs through the same event log
34//! ([`spawn`](DurableContext::spawn),
35//! [`spawn_many`](DurableContext::spawn_many)), so a replayed attempt is
36//! handed the runs the first one started rather than starting new ones — that
37//! one needs an engine of at least
38//! [`DURABLE_SPAWN_MIN_ENGINE_VERSION`]. A durable task that is only *waiting*
39//! need not hold one of the worker's slots either: declare an
40//! [`EvictionPolicy`] ([`TaskBuilder::eviction_policy`]) and the worker hands
41//! such a run back to the engine, which assigns it again — replaying its log —
42//! when what it was waiting for happens, or at once on
43//! [`RunsClient::restore_evicted`]. Also here: batch tasks —
44//! [`TaskBuilder::batch_handler`] declares one whose concurrent runs the
45//! engine buffers and hands to one worker as a single call, answered with one
46//! output per member ([`BatchInput`], [`BatchOutput`]);
47//! [`TaskBuilder::batch_broadcast_handler`] is the shape where one value goes
48//! to every member instead. Needs an engine of at least
49//! [`BATCH_MIN_ENGINE_VERSION`]. The REST management API — listing runs,
50//! logs, crons, scheduled runs, workers, workflows, filters, webhooks and
51//! metrics — is the `hatchet-rest` crate, reached from here through
52//! `Client::rest()` with the `rest` feature (see below). Run control does not
53//! need it, since cancelling, replaying and inspecting a run are all gRPC
54//! here; the repository's README lists the whole roadmap and the differences
55//! from the official Go SDK.
56//!
57//! The oldest engine this SDK works with is [`MIN_ENGINE_VERSION`].
58//!
59//! # Cargo features
60//!
61//! TLS is assembled from a rustls crypto provider and a root store, each
62//! behind a feature that forwards to tonic's feature of the same name:
63//! `tls-ring` (default) or `tls-aws-lc` for the provider, `tls-native-roots`
64//! (default) or `tls-webpki-roots` for the roots. With no provider the crate
65//! still builds and [`TlsStrategy::None`] still works, while
66//! [`TlsStrategy::Tls`] and [`TlsStrategy::Mtls`] fail at [`Client::new`]
67//! with an [`Error::Config`] naming what to enable.
68//!
69//! With the `rest` feature (off by default), `Client::rest()` returns a
70//! `hatchet_rest::RestClient` for the REST management API, built from the
71//! client's own configuration, and `hatchet_client::hatchet_rest` re-exports
72//! that crate. The `tls-*` features are forwarded to it, so one TLS stack is
73//! linked. Without the feature, this crate links no HTTP client.
74//!
75//! With the `otel` feature (off by default), a trigger writes its span's W3C
76//! `traceparent` into the run's additional metadata and a worker continues
77//! the trace from the value it finds there — see "Tracing" below. It links
78//! OpenTelemetry's API (`opentelemetry` 0.32) and `tracing-opentelemetry`
79//! 0.33, never its SDK or an exporter.
80//!
81//! # Tracing
82//!
83//! Triggering a run opens a `tracing` span named the way the official Go SDK
84//! names its own: `hatchet.run_workflow` around [`Task::run_no_wait`],
85//! [`Task::run`], their [`Workflow`] counterparts and [`Context::spawn`],
86//! [`Context::spawn_workflow`], [`Context::run`] and
87//! [`DurableContext::spawn`] (for `run`, until the result arrives), and one
88//! `hatchet.run_workflows` around a `run_many` or
89//! [`DurableContext::spawn_many`]. They are producer spans with the
90//! attributes `instrumentor`, `hatchet.workflow_name` (as declared),
91//! `hatchet.child_workflow_run_id` or `hatchet.num_workflows`. Pushing events
92//! opens `hatchet.push_event` (`hatchet.event_key`, the key as given) or one
93//! `hatchet.bulk_push_event` (`hatchet.num_events`).
94//!
95//! A worker runs each action inside `hatchet.start_step_run`, a consumer span
96//! with the attributes Go's middleware sets (tenant, worker, workflow run,
97//! step run, step id, action and step names, retry count; workflow, workflow
98//! version, parent run, child index and child key when the action has them);
99//! the handler runs inside it, so what the handler opens — a child's trigger
100//! above all — is its child. A batch is one such span for the whole batch
101//! (with `hatchet.batch_id` and `hatchet.batch_size`, this SDK's own). An
102//! engine-sent cancellation opens `hatchet.cancel_step_run`, as the official
103//! Python SDK does (Go opens nothing there). A failed or panicking handler
104//! marks the run's span as an error; a cancelled run's status is left unset.
105//!
106//! All of these are `INFO` spans carrying the `otel.kind`/`otel.status_*`
107//! fields a `tracing-opentelemetry` layer turns into a span kind and status.
108//! They exist with or without any feature, and never record a run's input,
109//! output or metadata.
110//!
111//! With the `otel` feature (off by default), the trace crosses the engine. A
112//! trigger — a child spawned from a handler and a pushed event included —
113//! writes its span's W3C `traceparent` (version `00`) into the run's or
114//! event's additional metadata under the key `"traceparent"`, the key the
115//! official SDKs use, replacing a value already there, as they do; a
116//! `run_many` or `spawn_many` writes its one span's value into every run. A
117//! worker makes `hatchet.start_step_run` a child of the `traceparent` in the
118//! action's metadata; a value that is not a valid version-`00` (or later)
119//! W3C `traceparent` — missing, not a string, the wrong length, uppercase,
120//! version `ff`, all-zero ids — is rejected by this SDK's own parser and the
121//! run starts a trace of its own, unless the *engine* has already replaced
122//! that value with a `traceparent` it derived itself (v0.107.0 does this for
123//! some malformed shapes; see the root README's "Tracing" section for which
124//! ones, per engine version), in which case the handler continues the
125//! engine's trace instead. Only `traceparent` is written or read; a `tracestate` in the
126//! metadata is passed through untouched. All of that happens only when the
127//! subscriber has a `tracing-opentelemetry` 0.33 layer (built on
128//! `opentelemetry` 0.32, the pair this crate links) and the span is enabled;
129//! otherwise the metadata is sent as given and runs are roots. No
130//! OpenTelemetry type appears in this crate's API, and the OpenTelemetry SDK
131//! and exporters are the application's own choice.
132//!
133//! Declare a task, register it on a worker, and let the engine hand it work.
134//! The handler's [`Context`] is how it talks back: logging, asking for more
135//! time, streaming partial results, spawning child runs.
136//!
137//! ```no_run
138//! use std::time::Duration;
139//!
140//! use hatchet_client::{Client, Context, TaskError, TaskBuilder};
141//! use serde::{Deserialize, Serialize};
142//!
143//! #[derive(Deserialize)]
144//! struct Review {
145//! repo: String,
146//! }
147//!
148//! #[derive(Serialize)]
149//! struct Verdict {
150//! approved: bool,
151//! }
152//!
153//! async fn review(ctx: Context, input: Review) -> Result<Verdict, TaskError> {
154//! // A log line that does not reach the engine is not worth failing —
155//! // and retrying — the whole task over.
156//! if let Err(error) = ctx.log(format!("reviewing {}", input.repo)).await {
157//! tracing::warn!(%error, "the log line was not delivered");
158//! }
159//! // Cloning a repository may take longer than the task's timeout allows.
160//! ctx.refresh_timeout(Duration::from_secs(5 * 60)).await?;
161//! if ctx.is_cancelled() {
162//! return Err(TaskError::new("asked to stop"));
163//! }
164//! Ok(Verdict {
165//! approved: input.repo == "hatchet-rs",
166//! })
167//! }
168//!
169//! # async fn example() -> hatchet_client::Result<()> {
170//! let client = Client::from_env()?;
171//! let worker = client
172//! .worker("mac-studio-1")
173//! .slots(8)
174//! .register(&TaskBuilder::new("review").handler(review))
175//! .build()
176//! .await?;
177//!
178//! // Runs until SIGINT or SIGTERM, then waits for the runs in flight.
179//! worker.run_until_shutdown().await
180//! # }
181//! ```
182//!
183//! From the other side, a client triggers runs of the same declaration and
184//! waits for what they produced — every wait on one client shares a single
185//! subscription, which is opened when something waits and closed when nothing
186//! does:
187//!
188//! ```no_run
189//! # use hatchet_client::{Client, RunOpts, TaskBuilder};
190//! # use serde::{Deserialize, Serialize};
191//! # #[derive(Deserialize, Serialize)]
192//! # struct Review { repo: String }
193//! # #[derive(Deserialize, Serialize)]
194//! # struct Verdict { approved: bool }
195//! # async fn triggering(client: &Client) -> hatchet_client::Result<()> {
196//! # let review = TaskBuilder::<Review, Verdict>::new("review")
197//! # .handler(|_ctx, input: Review| async move { Ok(Verdict { approved: input.repo == "hatchet-rs" }) });
198//! let verdict = review
199//! .run(client, &Review { repo: "hatchet-rs".to_string() }, RunOpts::default())
200//! .await?;
201//! println!("approved: {}", verdict.approved);
202//! # Ok(())
203//! # }
204//! ```
205//!
206//! …or pushes events that trigger every workflow registered with a matching
207//! `on_events`:
208//!
209//! ```no_run
210//! # use hatchet_client::{Client, PushOpts};
211//! # async fn example(client: Client) -> hatchet_client::Result<()> {
212//! client
213//! .events()
214//! .push("approval.granted", &serde_json::json!({"issue": "BLOG-12"}), PushOpts::default())
215//! .await?;
216//! # Ok(())
217//! # }
218//! ```
219
220#![warn(missing_docs)]
221
222mod batch;
223mod client;
224mod collision;
225mod config;
226mod context;
227mod declare;
228mod durable;
229mod error;
230mod events;
231mod otel;
232mod rate_limits;
233mod retry;
234mod runs;
235mod task_error;
236mod transport;
237mod trigger;
238mod version;
239mod worker;
240
241pub use batch::{BatchInput, BatchItem, BatchMemberId, BatchOutput};
242pub use client::Client;
243pub use config::{ClientBuilder, ClientConfig, TlsStrategy};
244pub use context::Context;
245pub use declare::{
246 BatchConfig, Concurrency, ConcurrencyLimitStrategy, Condition, ConditionSet, DesiredLabel,
247 Idempotency, IdempotencyMethod, LabelValue, OrGroup, Priority, RateLimit, RateLimitDuration,
248 Register, StickyStrategy, Task, TaskBuilder, Workflow, any_of,
249};
250pub use durable::{DurableContext, DurableEvent, DurableRunHandle, EvictionPolicy};
251pub use error::{Error, IdempotencyCollision, Result, TaskFailure};
252pub use events::{EventInput, EventsClient, PushOpts, PushedEvent};
253/// Re-exported so users can name the generated gRPC types that appear in
254/// [`Error`].
255pub use hatchet_proto;
256/// Re-exported so users can name tonic's types (e.g. `tonic::Status`,
257/// `tonic::Code`) that appear in [`Error`].
258pub use hatchet_proto::tonic;
259/// The REST management API client, re-exported so the types
260/// [`Client::rest`] returns can be named. Needs the `rest` feature.
261#[cfg(feature = "rest")]
262pub use hatchet_rest;
263pub use rate_limits::RateLimitsClient;
264pub use runs::{
265 OutputStream, RunDetails, RunHandle, RunStatus, RunsClient, StreamChunk, TaskRunDetail,
266 TasksFilter, WorkflowResult, WorkflowRunHandle,
267};
268pub use task_error::TaskError;
269pub use trigger::RunOpts;
270pub use version::{
271 BATCH_MIN_ENGINE_VERSION, DURABLE_SPAWN_MIN_ENGINE_VERSION, IDEMPOTENCY_MIN_ENGINE_VERSION,
272 MIN_ENGINE_VERSION,
273};
274pub use worker::{ShutdownHandle, Worker, WorkerBuilder};