Expand description
A client for the Hatchet REST management API.
hatchet-client runs workers and triggers runs over gRPC; this crate is
the other half of what the official SDKs offer: listing and inspecting
runs, managing crons and scheduled runs, workers, workflows, filters and
webhooks, and reading logs, metrics, rate limits and the tenant. It is
built to call exactly the 37 REST operations the official Go SDK’s feature
clients call; Operation::ALL lists them.
Each one is sent by a method of a bundle RestClient hands out —
runs, logs,
crons, schedules,
workflows, workers,
metrics, rate_limits,
tenant, filters,
webhooks and cel.
// HATCHET_CLIENT_TOKEN, and optionally HATCHET_CLIENT_SERVER_URL /
// HATCHET_CLIENT_TENANT_ID (otherwise taken from the token's claims).
let rest = hatchet_rest::RestClient::from_env()?;
let tenant = rest.tenant().get().await?;
println!("{} ({})", tenant.name, tenant.metadata.id);§Requests
Every request carries Authorization: Bearer <token> and
Accept: application/json. Only a bodiless GET is retried — on a
transport error or a 429/502/503/504, five attempts in all, with
full-jitter backoff from 250 ms up to 5 s (or a Retry-After of at most
5 s) — which is the official Go SDK’s REST policy. A POST, PATCH or
DELETE is sent once. Each attempt may take 30 s
(RestClientBuilder::timeout). What an answer outside 2xx becomes is
tabled on Error.
§Configuration
RestClient::from_env resolves five settings — token, server URL,
tenant id, namespace, TLS root CA file — each an explicit builder value,
then a HATCHET_CLIENT_* environment variable, then (for server URL and
tenant id) a claim of the token. See RestClientBuilder for the full
table. HATCHET_CLIENT_TLS_STRATEGY and mTLS, which hatchet-client’s
gRPC side reads, do not apply here — the server URL’s scheme decides TLS.
§Errors
See Error for the full table from HTTP status to error variant. None
of them ever contain the API token or a webhook secret.
§Retries
Covered under Requests above; a GET that exhausts its five attempts, or
any request whose connection fails outright, becomes
Error::Transport. A real engine was not observed to answer 429 in
this crate’s integration tests, so the retry-then-succeed path is
verified against hatchet-testkit’s mock server only.
§Tracing
SchedulesApi::create opens a tracing span, hatchet.schedule_workflow,
named and attributed as the official Go SDK’s schedules client opens it:
instrumentor, hatchet.workflow_name (as the caller named it) and
hatchet.trigger_at (RFC 3339), with the otel.kind/otel.status_*
fields a tracing-opentelemetry layer turns into a producer span and its
status. Like Go, it puts no trace context into the scheduled run’s
metadata, and this crate links no OpenTelemetry crate. No other call opens
a span.
§Engine versions
v0.80.0 and v0.107.0 were both observed to serve all 37 operations, with
no per-operation version gate; smaller differences (an optional vs.
required since, ignored filters, absent response fields) are noted on
the affected types and methods.
§Relationship to hatchet-client
hatchet-client’s rest feature builds a cached RestClient from the
same configuration as its gRPC Client (Client::rest()). Cancel,
replay, a run’s details and status, and restoring an evicted task are
available over gRPC too; everything else this crate sends has no gRPC
equivalent.
Structs§
- ApiError
- One entry of the
APIErrorsbody ({"errors": [..]}) the engine sends when it rejects a request’s input. - CelApi
- CEL debugging; from
RestClient::cel. - CelDebug
Output - What an expression evaluated to (
V1CELDebugResponsewith no error). - CelDebug
Request - An expression and what to evaluate it against; for
CelApi::debug. - Cron
- A cron trigger (
CronWorkflows). - Cron
List Query - Which crons
CronsApi::listreturns. Only the settings given a value are sent. - Crons
Api - Cron triggers; from
RestClient::crons. - Durable
Branch - The answer to
RunsApi::branch_durable_task(V1BranchDurableTaskResponse). - Filter
- A filter (
V1Filter). - Filter
List Query - Which filters
FiltersApi::listreturns. Only the settings given a value are sent. - Filter
Spec - A filter to create; for
FiltersApi::create. - Filter
Update - What to change in a filter; for
FiltersApi::update. Only the fields given a value are sent, and at least one is required. - Filters
Api - Event filters; from
RestClient::filters. - LogLine
- One log line (
V1LogLine). - LogList
Query - Which lines
LogsApi::listreturns. Only the settings given a value are sent, exceptsince. The API pages logs by time and count, not by offset, and the engine reports all-zero pagination for them, soPage::has_nextis alwaysfalsehere: to read on, ask again withsinceoruntilpast the last line. - LogsApi
- Log lines; from
RestClient::logs. - Metrics
Api - Metrics; from
RestClient::metrics. - Page
- One page of a list.
- Pagination
- The engine’s
PaginationResponse. Pages count from 1;next_pagekeeps counting past the last page, so comparecurrent_pagewithnum_pages(ashas_nextdoes) rather than trusting it. - Queue
Metrics - Counts of one queue (
QueueMetrics). - Queue
Metrics Query - Which queues
MetricsApi::queuecounts. Only the settings given a value are sent. - Rate
Limit - A rate limit (
RateLimit). - Rate
Limit List Query - Which rate limits
RateLimitsApi::listreturns. Only the settings given a value are sent. - Rate
Limits Api - The rate limit endpoint; from
RestClient::rate_limits. - Registered
Workflow - A workflow a worker registered (
RegisteredWorkflow). - Resource
Meta - The
metadataevery resource carries. - Rest
Client - A client for the Hatchet REST API. Cheap to clone; clones share one
connection pool. Its
Debugoutput never shows the token. - Rest
Client Builder - Builds a
RestClient. Anything not set here falls back to theHATCHET_CLIENT_*environment variable, then to the token’s claims. An environment variable set to the empty string counts as unset. - Route
- What an
Operationsends and expects, as the spec names it. - RunList
Query - Which runs
RunsApi::listreturns. Only the settings given a value are sent, exceptsinceandonly_tasks, which are always sent. - RunSelector
- Which task runs
RunsApi::cancelandRunsApi::replayact on: named ones, or the ones aTaskFiltermatches — never both. - RunsApi
- Workflow runs and task runs; from
RestClient::runs. - Schedule
List Query - Which scheduled runs
SchedulesApi::listreturns. Only the settings given a value are sent. - Scheduled
Run - A scheduled run (
ScheduledWorkflows). - Schedules
Api - Scheduled runs; from
RestClient::schedules. - Slot
Capacity - One slot type’s capacity (
WorkerSlotConfig). - Task
Event - One event in a task run’s history (
V1TaskEvent). - Task
Filter - The filter half of a
RunSelector(V1TaskFilter). Every condition set here has to hold. - Task
Queue Metrics - The tenant’s task queue counts (
TenantStepRunQueueMetrics), e.g.{"queues": {"greet:greet": 1}}as both supported engines answer. The spec givesqueuesno value schema, so it stays JSON. - Task
Summary - A task run (or a DAG run, in a list) as a list shows it
(
V1TaskSummary). - Tenant
- A tenant (
Tenant). - Tenant
Api - The tenant endpoint; from
RestClient::tenant. - Tenant
Queue Metrics - The tenant’s queue counts (
TenantQueueMetrics). - Trigger
Opts - What a cron or a scheduled run triggers the workflow with. Every setter
is optional; the API requires
inputandadditionalMetadatain the body, so an unset one is sent as{}, as the official Go SDK does. - Webhook
- A webhook (
V1Webhook). The engine never sends the secret back. - Webhook
List Query - Which webhooks
WebhooksApi::listreturns. Only the settings given a value are sent. - Webhook
Spec - A webhook to create; for
WebhooksApi::create. ItsDebugoutput never shows the secret. - Webhook
Update - What to change in a webhook; for
WebhooksApi::update. Only the fields given a value are sent, and at least one is required. Neither the source nor the authentication can be changed. - Webhooks
Api - Incoming webhooks; from
RestClient::webhooks. - Worker
- A worker (
Worker). - Worker
Label - A worker label (
WorkerLabel). - Worker
List Query - Which workers
WorkersApi::listreturns. Only the settings given a value are sent — and none of these parameters is in the v0.80.0 spec, so a query with nothing set sends no query at all, which is what works on every supported engine. - Worker
Runtime - What a worker reported about itself (
WorkerRuntimeInfo). - Workers
Api - Workers; from
RestClient::workers. - Workflow
- A registered workflow (
Workflow). - Workflow
List Query - Which workflows
WorkflowsApi::listreturns. Only the settings given a value are sent. - Workflow
Metrics - A workflow’s concurrency-group counts (
WorkflowMetrics). - Workflow
Metrics Query - Which runs
MetricsApi::workflowcounts. Only the settings given a value are sent. - Workflow
Run - A workflow run (
V1WorkflowRun). - Workflow
RunDetails - A workflow run with its tasks and history (
V1WorkflowRunDetails). - Workflow
Tag - A workflow’s tag (
WorkflowTag). - Workflows
Api - Registered workflows; from
RestClient::workflows.
Enums§
- CelDebug
Status - Whether the expression evaluated (
V1CELDebugResponseStatus). - Cron
Order By - What
CronListQuery::order_bysorts on (CronWorkflowsOrderByField). - Error
- Errors returned by
hatchet-rest. None of them ever contains the API token. - Hmac
Algorithm - The HMAC hash (
V1WebhookHMACAlgorithm). - Hmac
Encoding - How the HMAC signature is encoded (
V1WebhookHMACEncoding). - LogLevel
- A log line’s level (
V1LogLineLevel). - Metadata
Operator - How several metadata pairs combine in a run list
(
V1AdditionalMetadataOperator; not in the v0.80.0 spec). - Method
- An HTTP method used by one of the
Operations. - Operation
- One of the REST operations this crate calls. See
Operation::ALLfor the table andOperation::routefor a row of it. - Rate
Limit Order By - What
RateLimitListQuery::order_bysorts on. - Rate
Limit Order Direction - Sort direction of the rate limit list (lower-case on this one list,
unlike every other list’s
ASC/DESC). - RunKind
- Whether a listed row is a whole DAG or a single task
(
V1WorkflowType). - Running
Filter - Which running tasks a run list returns (
V1RunningFilter). - Schedule
Order By - What
ScheduleListQuery::order_bysorts on (ScheduledWorkflowsOrderByField). - Scheduled
RunStatus - A scheduled run’s status, for
ScheduleListQuery::statuses(ScheduledRunStatus). - Sort
Direction - Sort direction of the log, cron and scheduled-run lists.
- Task
Status - A run’s or task’s status (
V1TaskStatus). Unlikehatchet-client’s gRPCRunStatusthere is noEVICTEDhere — seeTaskSummary::is_evicted. - Tenant
Environment - A tenant’s declared environment.
- Tenant
Version - Which engine generation a tenant runs on.
- Trigger
Origin - Who made a cron or a scheduled run (
CronWorkflowsMethod,ScheduledWorkflowsMethod). - Webhook
Auth - How a webhook authenticates its sender: exactly one of the spec’s three
shapes. Its
Debugoutput never shows the secret. - Webhook
Auth Type - How a webhook authenticates its sender (
V1WebhookAuthType). - Webhook
Source - Who sends the webhook (
V1WebhookSourceName). - Worker
Kind - How a worker runs (
WorkerType). - Worker
Status - A worker’s state (
WorkerStatus). - Workflow
RunStatus - The status of a workflow run in the older, v0 vocabulary the
scheduled-run endpoints use (
WorkflowRunStatus).
Type Aliases§
- Json
Object - A JSON object as the engine sends it (inputs, outputs, metadata, payloads, fields this crate does not model).
- Result
- A
Resultwhose error is this crate’sError.