1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
//! Rust SDK for [Hatchet](https://hatchet.run): 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`](TaskBuilder::skip_if)
//! and [`cancel_if`](TaskBuilder::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 [`StreamChunk`]s, 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`](DurableContext::sleep_for),
//! [`wait_for_event`](DurableContext::wait_for_event),
//! [`wait_for`](DurableContext::wait_for)) and hold what must not be
//! recomputed ([`memo`](DurableContext::memo),
//! [`now`](DurableContext::now)), so a worker that dies while waiting loses
//! nothing. It can also start child runs through the same event log
//! ([`spawn`](DurableContext::spawn),
//! [`spawn_many`](DurableContext::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.
//!
//! ```no_run
//! 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",
//! })
//! }
//!
//! # async fn example() -> hatchet_client::Result<()> {
//! 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:
//!
//! ```no_run
//! # use hatchet_client::{Client, RunOpts, TaskBuilder};
//! # use serde::{Deserialize, Serialize};
//! # #[derive(Deserialize, Serialize)]
//! # struct Review { repo: String }
//! # #[derive(Deserialize, Serialize)]
//! # struct Verdict { approved: bool }
//! # async fn triggering(client: &Client) -> hatchet_client::Result<()> {
//! # let review = TaskBuilder::<Review, Verdict>::new("review")
//! # .handler(|_ctx, input: Review| async move { Ok(Verdict { approved: input.repo == "hatchet-rs" }) });
//! let verdict = review
//! .run(client, &Review { repo: "hatchet-rs".to_string() }, RunOpts::default())
//! .await?;
//! println!("approved: {}", verdict.approved);
//! # Ok(())
//! # }
//! ```
//!
//! …or pushes events that trigger every workflow registered with a matching
//! `on_events`:
//!
//! ```no_run
//! # use hatchet_client::{Client, PushOpts};
//! # async fn example(client: Client) -> hatchet_client::Result<()> {
//! client
//! .events()
//! .push("approval.granted", &serde_json::json!({"issue": "BLOG-12"}), PushOpts::default())
//! .await?;
//! # Ok(())
//! # }
//! ```
pub use ;
pub use Client;
pub use ;
pub use Context;
pub use ;
pub use ;
pub use ;
pub use ;
/// Re-exported so users can name the generated gRPC types that appear in
/// [`Error`].
pub use hatchet_proto;
/// Re-exported so users can name tonic's types (e.g. `tonic::Status`,
/// `tonic::Code`) that appear in [`Error`].
pub use tonic;
/// The REST management API client, re-exported so the types
/// [`Client::rest`] returns can be named. Needs the `rest` feature.
pub use hatchet_rest;
pub use RateLimitsClient;
pub use ;
pub use TaskError;
pub use RunOpts;
pub use ;
pub use ;