pub struct Client { /* private fields */ }Expand description
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
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 does not keep its client alive.
// 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")Implementations§
Source§impl Client
impl Client
Sourcepub fn builder() -> ClientBuilder
pub fn builder() -> ClientBuilder
Starts configuring a client. Equivalent to ClientConfig::builder.
Sourcepub fn from_env() -> Result<Self>
pub fn from_env() -> Result<Self>
Configures a client from HATCHET_CLIENT_* environment variables.
§Errors
Those of ClientConfig::from_env and Client::new:
Error::Config when HATCHET_CLIENT_TOKEN is
unset or a setting is contradictory,
Error::InvalidToken when the token
carries neither the needed claims nor their environment overrides, and
Error::Transport when the address or the
TLS material will not make a channel.
§Panics
Panics if called outside a tokio runtime.
Sourcepub fn new(config: ClientConfig) -> Result<Self>
pub fn new(config: ClientConfig) -> Result<Self>
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 if you want that
checked.
§Errors
Error::Transport when host_port is not a
usable address or the TLS material is not accepted, and
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.
Sourcepub fn config(&self) -> &ClientConfig
pub fn config(&self) -> &ClientConfig
The resolved configuration.
Sourcepub async fn engine_version(&self) -> Result<String>
pub async fn engine_version(&self) -> Result<String>
The engine’s version string, e.g. "v0.107.0".
§Errors
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.
Sourcepub async fn check_engine_version(&self) -> Result<()>
pub async fn check_engine_version(&self) -> Result<()>
Asks the engine for its version and checks it against
MIN_ENGINE_VERSION.
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 when the
engine is older than the minimum,
Error::InvalidEngineVersion
when what it reported is not vMAJOR.MINOR.PATCH, and those of
engine_version.
Sourcepub fn events(&self) -> EventsClient
pub fn events(&self) -> EventsClient
Pushes events to the engine, one at a time or in bulk.
Sourcepub fn rate_limits(&self) -> RateLimitsClient
pub fn rate_limits(&self) -> RateLimitsClient
Creates and raises the tenant’s rate limits.
Sourcepub fn runs(&self) -> RunsClient
pub fn runs(&self) -> RunsClient
Cancels, replays and inspects runs the engine already knows about.
Sourcepub fn worker(&self, name: impl Into<String>) -> WorkerBuilder
pub fn worker(&self, name: impl Into<String>) -> WorkerBuilder
Starts configuring a worker named name. The name is how the engine’s
dashboard identifies it; it does not have to be unique.
Sourcepub fn task<I, O>(&self, name: impl Into<String>) -> TaskBuilder<I, O>
pub fn task<I, O>(&self, name: impl Into<String>) -> TaskBuilder<I, O>
Starts declaring a task with input I and output O. Shorthand for
TaskBuilder::new; the declaration is not
tied to this client.
Source§impl Client
impl Client
Sourcepub fn rest(&self) -> Result<RestClient>
pub fn rest(&self) -> Result<RestClient>
A client for Hatchet’s REST management API (the hatchet-rest
crate, re-exported as 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
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.
let workers = client.rest()?.workers().list(Default::default()).await?;
for worker in workers.rows {
println!("{} {:?}", worker.name, worker.status);
}§Errors
Those of 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.
Trait Implementations§
Auto Trait Implementations§
impl !RefUnwindSafe for Client
impl !UnwindSafe for Client
impl Forget for Client
impl Freeze for Client
impl Move for Client
impl Send for Client
impl Sync for Client
impl Unpin for Client
impl UnsafeUnpin for Client
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
Source§impl<T> FutureExt for T
impl<T> FutureExt for T
Source§fn with_context(self, otel_cx: Context) -> WithContext<Self> ⓘ
fn with_context(self, otel_cx: Context) -> WithContext<Self> ⓘ
Source§fn with_current_context(self) -> WithContext<Self> ⓘ
fn with_current_context(self) -> WithContext<Self> ⓘ
Source§impl<T> Instrument for T
impl<T> Instrument for T
Source§fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
Source§fn in_current_span(self) -> Instrumented<Self> ⓘ
fn in_current_span(self) -> Instrumented<Self> ⓘ
Source§impl<T> IntoRequest<T> for T
impl<T> IntoRequest<T> for T
Source§fn into_request(self) -> Request<T>
fn into_request(self) -> Request<T>
T in a tonic::Request