hatchet-client 0.1.0

Rust SDK for Hatchet: run workers and trigger tasks
Documentation
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
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
//! The entry point: one shared connection, handed to every generated client.

use std::fmt;
use std::pin::Pin;
use std::sync::Arc;

use hatchet_proto::root::dispatcher_client::DispatcherClient;
use hatchet_proto::root::events_service_client::EventsServiceClient;
use hatchet_proto::root::workflow_service_client::WorkflowServiceClient;
use hatchet_proto::root::{GetVersionRequest, WorkflowRunEvent};
use hatchet_proto::v1::admin_service_client::AdminServiceClient;
use tokio_stream::Stream;
use tokio_util::sync::{CancellationToken, DropGuard};
use tonic::Status;
use tonic::codec::CompressionEncoding;

use crate::events::EventsClient;
use crate::rate_limits::RateLimitsClient;
use crate::runs::client::RunsClient;
use crate::runs::listener::{RequestStream, RunListener};
use crate::transport::{self, GrpcService};
use crate::worker::WorkerBuilder;
use crate::{ClientBuilder, ClientConfig, Result, retry, version};

/// A connection to a Hatchet engine. Cheap to clone; clones share the
/// underlying gRPC channel.
///
/// One client is both sides of the SDK: it builds the [`Worker`](crate::Worker)
/// that runs declared tasks, and it triggers runs and pushes events. Hold on
/// to it for as long as anything might wait on a run — a
/// [`RunHandle`](crate::RunHandle) does not keep its client alive.
///
/// ```no_run
/// # use hatchet_client::{Client, RunOpts, TaskBuilder};
/// # async fn example() -> hatchet_client::Result<()> {
/// // Reads HATCHET_CLIENT_TOKEN and friends; see `ClientBuilder` to set
/// // them in code instead.
/// let client = Client::from_env()?;
///
/// let greet = TaskBuilder::<String, String>::new("greet")
///     .handler(|_ctx, name: String| async move { Ok(format!("Hello, {name}!")) });
///
/// // The worker side.
/// let worker = client.worker("greeter-1").register(&greet).build().await?;
/// let shutdown = worker.shutdown_handle();
/// let running = tokio::spawn(worker.run());
///
/// // The trigger side, from the same client.
/// let greeting = greet
///     .run(&client, &"Hatchet".to_string(), RunOpts::default())
///     .await?;
/// println!("{greeting}");
///
/// shutdown.shutdown();
/// running.await.expect("the worker task panicked")
/// # }
/// ```
#[derive(Clone)]
pub struct Client {
    inner: Arc<Inner>,
}

struct Inner {
    config: ClientConfig,
    service: GrpcService,
    /// Waits for run results on one shared subscription. It holds only a
    /// clone of the gRPC service, never a `Client`: a listener that kept its
    /// client alive would be a cycle no drop could break.
    runs: RunListener,
    /// Cancelled when the last clone of this client is dropped, which is what
    /// ends the listener's task. A clone of the service handle cannot tell
    /// the listener that: the channel it wraps stays perfectly usable.
    _stop: DropGuard,
    /// The REST client, built on first use by [`Client::rest`].
    #[cfg(feature = "rest")]
    rest: std::sync::OnceLock<hatchet_rest::RestClient>,
}

impl fmt::Debug for Client {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("Client")
            .field("config", &self.inner.config)
            .finish_non_exhaustive()
    }
}

impl Client {
    /// Starts configuring a client. Equivalent to [`ClientConfig::builder`].
    pub fn builder() -> ClientBuilder {
        ClientConfig::builder()
    }

    /// Configures a client from `HATCHET_CLIENT_*` environment variables.
    ///
    /// # Errors
    ///
    /// Those of [`ClientConfig::from_env`] and [`Client::new`]:
    /// [`Error::Config`](crate::Error::Config) when `HATCHET_CLIENT_TOKEN` is
    /// unset or a setting is contradictory,
    /// [`Error::InvalidToken`](crate::Error::InvalidToken) when the token
    /// carries neither the needed claims nor their environment overrides, and
    /// [`Error::Transport`](crate::Error::Transport) when the address or the
    /// TLS material will not make a channel.
    ///
    /// # Panics
    ///
    /// Panics if called outside a tokio runtime.
    pub fn from_env() -> Result<Self> {
        Self::new(ClientConfig::from_env()?)
    }

    /// Creates a client. The connection is established lazily, on the first
    /// call, so this succeeds even while the engine is unreachable. TLS
    /// material (system roots, certificate files) is loaded eagerly here, so
    /// TLS misconfiguration fails at construction rather than on the first
    /// call.
    ///
    /// The shared listener that waits for run results is built here but not
    /// started: a client that never waits for a run spawns no task and opens
    /// no stream.
    ///
    /// Nothing here checks the engine's version — a client that only triggers
    /// runs makes no call of its own. Call
    /// [`check_engine_version`](Client::check_engine_version) if you want that
    /// checked.
    ///
    /// # Errors
    ///
    /// [`Error::Transport`](crate::Error::Transport) when `host_port` is not a
    /// usable address or the TLS material is not accepted, and
    /// [`Error::Config`](crate::Error::Config) when the token cannot go in a
    /// header, a certificate or key file cannot be read, `mtls` was asked for
    /// without a certificate and key, or `tls`/`mtls` was asked for in a build
    /// with no crypto provider or no root store compiled in (see the crate's
    /// `tls-*` cargo features).
    ///
    /// # Panics
    ///
    /// Panics if called outside a tokio runtime.
    pub fn new(config: ClientConfig) -> Result<Self> {
        let gzip = config.gzip();
        let service = transport::connect(&config)?;
        let stop = CancellationToken::new();
        let runs = RunListener::new(subscribing(service.clone(), gzip), stop.clone());
        Ok(Self {
            inner: Arc::new(Inner {
                config,
                service,
                runs,
                _stop: stop.drop_guard(),
                #[cfg(feature = "rest")]
                rest: std::sync::OnceLock::new(),
            }),
        })
    }

    /// The resolved configuration.
    pub fn config(&self) -> &ClientConfig {
        &self.inner.config
    }

    /// The engine's version string, e.g. `"v0.107.0"`.
    ///
    /// # Errors
    ///
    /// [`Error::Grpc`](crate::Error::Grpc) when the call fails — including
    /// when the engine cannot be reached, since the connection is made
    /// lazily and this is often the first call to touch it.
    pub async fn engine_version(&self) -> Result<String> {
        let response = retry::unary(|| {
            let mut dispatcher = self.dispatcher_grpc();
            async move {
                dispatcher
                    .get_version(retry::timed(GetVersionRequest {}))
                    .await
            }
        })
        .await?;
        Ok(response.into_inner().version)
    }

    /// Asks the engine for its version and checks it against
    /// [`MIN_ENGINE_VERSION`](crate::MIN_ENGINE_VERSION).
    ///
    /// [`WorkerBuilder::build`](crate::WorkerBuilder::build) does this on its
    /// own; call it yourself in a process that only triggers runs and would
    /// otherwise never find out.
    ///
    /// # Errors
    ///
    /// [`Error::UnsupportedEngine`](crate::Error::UnsupportedEngine) when the
    /// engine is older than the minimum,
    /// [`Error::InvalidEngineVersion`](crate::Error::InvalidEngineVersion)
    /// when what it reported is not `vMAJOR.MINOR.PATCH`, and those of
    /// [`engine_version`](Client::engine_version).
    pub async fn check_engine_version(&self) -> Result<()> {
        version::ensure_supported(&self.engine_version().await?)
    }

    pub(crate) fn dispatcher_grpc(&self) -> DispatcherClient<GrpcService> {
        dispatcher_grpc(self.grpc_service(), self.inner.config.gzip())
    }

    /// The gRPC channel every generated client is built on, for the durable
    /// stream's own connect function.
    pub(crate) fn grpc_service(&self) -> GrpcService {
        self.inner.service.clone()
    }

    /// The listener every wait for a run result goes through. One per client,
    /// however many runs are waited for.
    ///
    /// Named `run_listener` rather than `runs` because [`Client::runs`] is
    /// the public run-control client.
    pub(crate) fn run_listener(&self) -> &RunListener {
        &self.inner.runs
    }

    pub(crate) fn admin_grpc(&self) -> AdminServiceClient<GrpcService> {
        let client = AdminServiceClient::new(self.inner.service.clone())
            .accept_compressed(CompressionEncoding::Gzip);
        if self.inner.config.gzip() {
            client.send_compressed(CompressionEncoding::Gzip)
        } else {
            client
        }
    }

    /// The v0 `EventsService`: where a running task's logs and stream events
    /// go.
    pub(crate) fn events_grpc(&self) -> EventsServiceClient<GrpcService> {
        let client = EventsServiceClient::new(self.inner.service.clone())
            .accept_compressed(CompressionEncoding::Gzip);
        if self.inner.config.gzip() {
            client.send_compressed(CompressionEncoding::Gzip)
        } else {
            client
        }
    }

    /// The v0 `WorkflowService`: where runs are triggered. Its
    /// `TriggerWorkflow` takes the *v1* request message.
    pub(crate) fn workflows_grpc(&self) -> WorkflowServiceClient<GrpcService> {
        let client = WorkflowServiceClient::new(self.inner.service.clone())
            .accept_compressed(CompressionEncoding::Gzip);
        if self.inner.config.gzip() {
            client.send_compressed(CompressionEncoding::Gzip)
        } else {
            client
        }
    }

    /// Pushes events to the engine, one at a time or in bulk.
    pub fn events(&self) -> EventsClient {
        EventsClient::new(self.clone())
    }

    /// Creates and raises the tenant's rate limits.
    pub fn rate_limits(&self) -> RateLimitsClient {
        RateLimitsClient::new(self.clone())
    }

    /// Cancels, replays and inspects runs the engine already knows about.
    pub fn runs(&self) -> RunsClient {
        RunsClient::new(self.clone())
    }

    /// Starts configuring a worker named `name`. The name is how the engine's
    /// dashboard identifies it; it does not have to be unique.
    pub fn worker(&self, name: impl Into<String>) -> WorkerBuilder {
        WorkerBuilder::new(self.clone(), name)
    }

    /// Starts declaring a task with input `I` and output `O`. Shorthand for
    /// [`TaskBuilder::new`](crate::TaskBuilder::new); the declaration is not
    /// tied to this client.
    pub fn task<I, O>(&self, name: impl Into<String>) -> crate::TaskBuilder<I, O> {
        crate::TaskBuilder::new(name)
    }

    /// Starts declaring a workflow. Shorthand for
    /// [`Workflow::new`](crate::Workflow::new).
    pub fn workflow(&self, name: impl Into<String>) -> crate::Workflow {
        crate::Workflow::new(name)
    }
}

fn dispatcher_grpc(service: GrpcService, gzip: bool) -> DispatcherClient<GrpcService> {
    let client = DispatcherClient::new(service).accept_compressed(CompressionEncoding::Gzip);
    if gzip {
        client.send_compressed(CompressionEncoding::Gzip)
    } else {
        client
    }
}

/// The run events one subscription is answered with.
type RunEventStream =
    Pin<Box<dyn Stream<Item = std::result::Result<WorkflowRunEvent, Status>> + Send>>;

/// The listener's connect function: opens one `SubscribeToWorkflowRuns`
/// stream, with `requests` as the ids it is asked about.
///
/// No `set_timeout` and no [`retry::unary`], for the same reasons as the
/// worker's action stream: a deadline would cut off a run that is simply
/// taking its time, and reconnecting is the listener's own job.
fn subscribing(
    service: GrpcService,
    gzip: bool,
) -> impl FnMut(
    RequestStream,
) -> Pin<Box<dyn Future<Output = std::result::Result<RunEventStream, Status>> + Send>> {
    move |requests| {
        let mut dispatcher = dispatcher_grpc(service.clone(), gzip);
        Box::pin(async move {
            let events = dispatcher
                .subscribe_to_workflow_runs(requests)
                .await?
                .into_inner();
            Ok(Box::pin(events) as RunEventStream)
        })
    }
}

#[cfg(feature = "rest")]
impl Client {
    /// A client for Hatchet's REST management API (the `hatchet-rest`
    /// crate, re-exported as [`hatchet_rest`](crate::hatchet_rest)), built
    /// from this client's resolved configuration: the same token, tenant,
    /// namespace, server URL (explicit, `HATCHET_CLIENT_SERVER_URL`, or the
    /// token's claim) and root CA file. The [`TlsStrategy`](crate::TlsStrategy)
    /// does not apply to it: the server URL's scheme decides, and the root CA
    /// file is used only for an `https://` URL. Needs the `rest` feature.
    ///
    /// Built on the first successful call and cached in this client (and its
    /// clones); later calls hand out a clone of it, which shares its
    /// connection pool.
    ///
    /// Part of what the REST API does, this crate already does over gRPC —
    /// [`Client::runs`]' cancel, replay and details, and
    /// [`Client::rate_limits`]' upsert. The REST client is for the rest:
    /// listing runs, logs, crons, scheduled runs, workers, workflows,
    /// filters, webhooks and metrics.
    ///
    /// ```no_run
    /// # async fn example(client: hatchet_client::Client) -> Result<(), Box<dyn std::error::Error>> {
    /// let workers = client.rest()?.workers().list(Default::default()).await?;
    /// for worker in workers.rows {
    ///     println!("{} {:?}", worker.name, worker.status);
    /// }
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// # Errors
    ///
    /// Those of [`RestClientBuilder::build`](hatchet_rest::RestClientBuilder::build).
    /// The gRPC configuration being complete does not make the REST one
    /// usable: a server URL that is not `http://` or `https://`, an
    /// `https://` one in a build with no crypto provider or root store, or
    /// an unreadable root CA file fail here, not at [`Client::new`]. A failed
    /// build is not cached; the next call tries again.
    pub fn rest(&self) -> hatchet_rest::Result<hatchet_rest::RestClient> {
        if let Some(rest) = self.inner.rest.get() {
            return Ok(rest.clone());
        }
        let config = &self.inner.config;
        let mut builder = hatchet_rest::RestClient::builder()
            .token(config.token())
            .server_url(config.server_url())
            .tenant_id(config.tenant_id())
            .namespace(config.namespace());
        if let Some(path) = config.tls_root_ca_file() {
            builder = builder.tls_root_ca_file(path);
        }
        let rest = builder.build()?;
        // Two first calls racing each build one; the first stored wins and
        // both hand out that one.
        Ok(self.inner.rest.get_or_init(|| rest).clone())
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::{Error, TlsStrategy};

    const TOKEN: &str = "e30.eyJzdWIiOiJ0Iiwic2VydmVyX3VybCI6Imh0dHA6Ly9sb2NhbGhvc3Q6ODg4OCIsImdycGNfYnJvYWRjYXN0X2FkZHJlc3MiOiJsb2NhbGhvc3Q6NzA3NyJ9.sig";

    #[tokio::test]
    async fn builder_builds_a_client_exposing_its_config() {
        let client = Client::builder()
            .token(TOKEN)
            .namespace("dev")
            .tls(TlsStrategy::None)
            .build()
            .unwrap();
        assert_eq!(client.config().host_port(), "localhost:7077");
        assert_eq!(client.config().namespace(), "dev_");
        let _cheap_clone = client.clone();
    }

    #[tokio::test]
    async fn debug_output_does_not_contain_the_token() {
        let client = Client::builder()
            .token(TOKEN)
            .tls(TlsStrategy::None)
            .build()
            .unwrap();
        assert!(!format!("{client:?}").contains(TOKEN));
    }

    #[tokio::test]
    async fn client_offers_the_declaration_entry_points() {
        let client = Client::builder()
            .token(TOKEN)
            .tls(TlsStrategy::None)
            .build()
            .unwrap();
        let task = client
            .task::<serde_json::Value, serde_json::Value>("agent-run")
            .handler(|_ctx, input| async move { Ok(input) });
        let workflow = client.workflow("pipeline").task(&task);
        assert_eq!(task.name(), "agent-run");
        assert_eq!(workflow.name(), "pipeline");
    }

    #[tokio::test(start_paused = true)]
    async fn engine_version_surfaces_a_grpc_error_when_nothing_listens() {
        let client = Client::builder()
            .token(TOKEN)
            .host_port("127.0.0.1:1")
            .tls(TlsStrategy::None)
            .build()
            .unwrap();
        let err = client.check_engine_version().await.unwrap_err();
        let Error::Grpc(status) = err else {
            panic!("{err:?}")
        };
        assert!(
            matches!(
                status.code(),
                tonic::Code::Unavailable | tonic::Code::DeadlineExceeded
            ),
            "{status:?}"
        );
    }
}