Skip to main content

Client

Struct Client 

Source
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

Source

pub fn builder() -> ClientBuilder

Starts configuring a client. Equivalent to ClientConfig::builder.

Source

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.

Source

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.

Source

pub fn config(&self) -> &ClientConfig

The resolved configuration.

Source

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.

Source

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.

Source

pub fn events(&self) -> EventsClient

Pushes events to the engine, one at a time or in bulk.

Source

pub fn rate_limits(&self) -> RateLimitsClient

Creates and raises the tenant’s rate limits.

Source

pub fn runs(&self) -> RunsClient

Cancels, replays and inspects runs the engine already knows about.

Source

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.

Source

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

pub fn workflow(&self, name: impl Into<String>) -> Workflow

Starts declaring a workflow. Shorthand for Workflow::new.

Source§

impl Client

Source

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§

Source§

impl Clone for Client

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for Client

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

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> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> FutureExt for T

Source§

fn with_context(self, otel_cx: Context) -> WithContext<Self> ⓘ

Attaches the provided Context to this type, returning a WithContext wrapper. Read more
Source§

fn with_current_context(self) -> WithContext<Self> ⓘ

Attaches the current Context to this type, returning a WithContext wrapper. Read more
Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoRequest<T> for T

Source§

fn into_request(self) -> Request<T>

Wrap the input message T in a tonic::Request
Source§

impl<L> LayerExt<L> for L

Source§

fn named_layer<S>(&self, service: S) -> Layered<<L as Layer<S>>::Service, S>
where L: Layer<S>,

Applies the layer to a service and wraps it in Layered.
Source§

impl<T> PolicyExt for T
where T: ?Sized,

Source§

fn and<P, B, E>(self, other: P) -> And<T, P>
where T: Sized + Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns Action::Follow only if self and other return Action::Follow. Read more
Source§

fn or<P, B, E>(self, other: P) -> Or<T, P>
where T: Sized + Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns Action::Follow if either self or other returns Action::Follow. Read more
Source§

impl<T> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

Source§

fn vzip(self) -> V

Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more