Skip to main content

Crate hatchet_rest

Crate hatchet_rest 

Source
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 APIErrors body ({"errors": [..]}) the engine sends when it rejects a request’s input.
CelApi
CEL debugging; from RestClient::cel.
CelDebugOutput
What an expression evaluated to (V1CELDebugResponse with no error).
CelDebugRequest
An expression and what to evaluate it against; for CelApi::debug.
Cron
A cron trigger (CronWorkflows).
CronListQuery
Which crons CronsApi::list returns. Only the settings given a value are sent.
CronsApi
Cron triggers; from RestClient::crons.
DurableBranch
The answer to RunsApi::branch_durable_task (V1BranchDurableTaskResponse).
Filter
A filter (V1Filter).
FilterListQuery
Which filters FiltersApi::list returns. Only the settings given a value are sent.
FilterSpec
A filter to create; for FiltersApi::create.
FilterUpdate
What to change in a filter; for FiltersApi::update. Only the fields given a value are sent, and at least one is required.
FiltersApi
Event filters; from RestClient::filters.
LogLine
One log line (V1LogLine).
LogListQuery
Which lines LogsApi::list returns. Only the settings given a value are sent, except since. The API pages logs by time and count, not by offset, and the engine reports all-zero pagination for them, so Page::has_next is always false here: to read on, ask again with since or until past the last line.
LogsApi
Log lines; from RestClient::logs.
MetricsApi
Metrics; from RestClient::metrics.
Page
One page of a list.
Pagination
The engine’s PaginationResponse. Pages count from 1; next_page keeps counting past the last page, so compare current_page with num_pages (as has_next does) rather than trusting it.
QueueMetrics
Counts of one queue (QueueMetrics).
QueueMetricsQuery
Which queues MetricsApi::queue counts. Only the settings given a value are sent.
RateLimit
A rate limit (RateLimit).
RateLimitListQuery
Which rate limits RateLimitsApi::list returns. Only the settings given a value are sent.
RateLimitsApi
The rate limit endpoint; from RestClient::rate_limits.
RegisteredWorkflow
A workflow a worker registered (RegisteredWorkflow).
ResourceMeta
The metadata every resource carries.
RestClient
A client for the Hatchet REST API. Cheap to clone; clones share one connection pool. Its Debug output never shows the token.
RestClientBuilder
Builds a RestClient. Anything not set here falls back to the HATCHET_CLIENT_* environment variable, then to the token’s claims. An environment variable set to the empty string counts as unset.
Route
What an Operation sends and expects, as the spec names it.
RunListQuery
Which runs RunsApi::list returns. Only the settings given a value are sent, except since and only_tasks, which are always sent.
RunSelector
Which task runs RunsApi::cancel and RunsApi::replay act on: named ones, or the ones a TaskFilter matches — never both.
RunsApi
Workflow runs and task runs; from RestClient::runs.
ScheduleListQuery
Which scheduled runs SchedulesApi::list returns. Only the settings given a value are sent.
ScheduledRun
A scheduled run (ScheduledWorkflows).
SchedulesApi
Scheduled runs; from RestClient::schedules.
SlotCapacity
One slot type’s capacity (WorkerSlotConfig).
TaskEvent
One event in a task run’s history (V1TaskEvent).
TaskFilter
The filter half of a RunSelector (V1TaskFilter). Every condition set here has to hold.
TaskQueueMetrics
The tenant’s task queue counts (TenantStepRunQueueMetrics), e.g. {"queues": {"greet:greet": 1}} as both supported engines answer. The spec gives queues no value schema, so it stays JSON.
TaskSummary
A task run (or a DAG run, in a list) as a list shows it (V1TaskSummary).
Tenant
A tenant (Tenant).
TenantApi
The tenant endpoint; from RestClient::tenant.
TenantQueueMetrics
The tenant’s queue counts (TenantQueueMetrics).
TriggerOpts
What a cron or a scheduled run triggers the workflow with. Every setter is optional; the API requires input and additionalMetadata in 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.
WebhookListQuery
Which webhooks WebhooksApi::list returns. Only the settings given a value are sent.
WebhookSpec
A webhook to create; for WebhooksApi::create. Its Debug output never shows the secret.
WebhookUpdate
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.
WebhooksApi
Incoming webhooks; from RestClient::webhooks.
Worker
A worker (Worker).
WorkerLabel
A worker label (WorkerLabel).
WorkerListQuery
Which workers WorkersApi::list returns. 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.
WorkerRuntime
What a worker reported about itself (WorkerRuntimeInfo).
WorkersApi
Workers; from RestClient::workers.
Workflow
A registered workflow (Workflow).
WorkflowListQuery
Which workflows WorkflowsApi::list returns. Only the settings given a value are sent.
WorkflowMetrics
A workflow’s concurrency-group counts (WorkflowMetrics).
WorkflowMetricsQuery
Which runs MetricsApi::workflow counts. Only the settings given a value are sent.
WorkflowRun
A workflow run (V1WorkflowRun).
WorkflowRunDetails
A workflow run with its tasks and history (V1WorkflowRunDetails).
WorkflowTag
A workflow’s tag (WorkflowTag).
WorkflowsApi
Registered workflows; from RestClient::workflows.

Enums§

CelDebugStatus
Whether the expression evaluated (V1CELDebugResponseStatus).
CronOrderBy
What CronListQuery::order_by sorts on (CronWorkflowsOrderByField).
Error
Errors returned by hatchet-rest. None of them ever contains the API token.
HmacAlgorithm
The HMAC hash (V1WebhookHMACAlgorithm).
HmacEncoding
How the HMAC signature is encoded (V1WebhookHMACEncoding).
LogLevel
A log line’s level (V1LogLineLevel).
MetadataOperator
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::ALL for the table and Operation::route for a row of it.
RateLimitOrderBy
What RateLimitListQuery::order_by sorts on.
RateLimitOrderDirection
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).
RunningFilter
Which running tasks a run list returns (V1RunningFilter).
ScheduleOrderBy
What ScheduleListQuery::order_by sorts on (ScheduledWorkflowsOrderByField).
ScheduledRunStatus
A scheduled run’s status, for ScheduleListQuery::statuses (ScheduledRunStatus).
SortDirection
Sort direction of the log, cron and scheduled-run lists.
TaskStatus
A run’s or task’s status (V1TaskStatus). Unlike hatchet-client’s gRPC RunStatus there is no EVICTED here — see TaskSummary::is_evicted.
TenantEnvironment
A tenant’s declared environment.
TenantVersion
Which engine generation a tenant runs on.
TriggerOrigin
Who made a cron or a scheduled run (CronWorkflowsMethod, ScheduledWorkflowsMethod).
WebhookAuth
How a webhook authenticates its sender: exactly one of the spec’s three shapes. Its Debug output never shows the secret.
WebhookAuthType
How a webhook authenticates its sender (V1WebhookAuthType).
WebhookSource
Who sends the webhook (V1WebhookSourceName).
WorkerKind
How a worker runs (WorkerType).
WorkerStatus
A worker’s state (WorkerStatus).
WorkflowRunStatus
The status of a workflow run in the older, v0 vocabulary the scheduled-run endpoints use (WorkflowRunStatus).

Type Aliases§

JsonObject
A JSON object as the engine sends it (inputs, outputs, metadata, payloads, fields this crate does not model).
Result
A Result whose error is this crate’s Error.