hatchet-client 0.1.0

Rust SDK for Hatchet: run workers and trigger tasks
Documentation
//! 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(())
//! # }
//! ```

#![warn(missing_docs)]

mod batch;
mod client;
mod collision;
mod config;
mod context;
mod declare;
mod durable;
mod error;
mod events;
mod otel;
mod rate_limits;
mod retry;
mod runs;
mod task_error;
mod transport;
mod trigger;
mod version;
mod worker;

pub use batch::{BatchInput, BatchItem, BatchMemberId, BatchOutput};
pub use client::Client;
pub use config::{ClientBuilder, ClientConfig, TlsStrategy};
pub use context::Context;
pub use declare::{
    BatchConfig, Concurrency, ConcurrencyLimitStrategy, Condition, ConditionSet, DesiredLabel,
    Idempotency, IdempotencyMethod, LabelValue, OrGroup, Priority, RateLimit, RateLimitDuration,
    Register, StickyStrategy, Task, TaskBuilder, Workflow, any_of,
};
pub use durable::{DurableContext, DurableEvent, DurableRunHandle, EvictionPolicy};
pub use error::{Error, IdempotencyCollision, Result, TaskFailure};
pub use events::{EventInput, EventsClient, PushOpts, PushedEvent};
/// 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 hatchet_proto::tonic;
/// The REST management API client, re-exported so the types
/// [`Client::rest`] returns can be named. Needs the `rest` feature.
#[cfg(feature = "rest")]
pub use hatchet_rest;
pub use rate_limits::RateLimitsClient;
pub use runs::{
    OutputStream, RunDetails, RunHandle, RunStatus, RunsClient, StreamChunk, TaskRunDetail,
    TasksFilter, WorkflowResult, WorkflowRunHandle,
};
pub use task_error::TaskError;
pub use trigger::RunOpts;
pub use version::{
    BATCH_MIN_ENGINE_VERSION, DURABLE_SPAWN_MIN_ENGINE_VERSION, IDEMPOTENCY_MIN_ENGINE_VERSION,
    MIN_ENGINE_VERSION,
};
pub use worker::{ShutdownHandle, Worker, WorkerBuilder};