kruxiaflow-worker
Worker SDK for Kruxia Flow — run Rust activities in budgeted workflows with hard cost limits enforced in the engine.
A Kruxia Flow worker polls the server for queued activities, executes your
registered handlers, and reports results — including per-LLM-call usage, so
activities running in your own process count against workflow budgets with
the same fidelity as built-in activities. This crate is the complete worker
loop: registration, polling, bounded concurrency, heartbeats, timeout and
panic containment, OAuth2 client-credentials auth, and graceful drain on
shutdown. The same crate powers Kruxia Flow's own built-in std worker.
Quickstart
Start a server locally (5-minute quickstart), or in dev mode with no auth:
Add the SDK to a binary crate:
Register a handler and run:
use ;
use json;
async
KRUXIAFLOW_API_URL=http://localhost:8080
Any workflow activity declaring worker: demo / name: echo now executes
on your worker:
name: hello-sdk
activities:
greet:
worker: demo
name: echo
parameters:
message: "hello from Rust"
Reporting cost and usage
Cost governance is the point: budgets live in the engine, and what your
activity reports is what the engine enforces. An activity that calls an LLM
itself attaches one UsageEntry per call — the server prices it from its
model catalog, records it exactly like a built-in LLM activity (visible in
/cost/history and /cost/analytics), and counts it against the workflow's
budget:
use ;
use json;
#
UsageEntry::cost_usd(...)overrides catalog pricing for a single call — use it for costs the catalog can't model (e.g., time-based cache-storage billing).ActivityResult::with_cost(...)reports spend not covered by usage entries (a paid non-LLM API). Never repeat entry costs there.- Failures spend money too:
ActivityError::with_usage(...)/.with_cost(...)make failed attempts budget-counted.
Failure semantics
Handlers return Result<ActivityResult, ActivityError>:
| Failure | Reported as |
|---|---|
ActivityError::retryable(code, msg) |
re-queued up to the retry limit |
ActivityError::terminal(code, msg) |
no retry |
| parameter deserialization failure | terminal INVALID_PARAMETERS |
| handler panic | retryable PANIC (worker survives) |
timeout (settings.timeout or worker default) |
retryable TIMEOUT |
Configuration
Environment variables (matching the Python SDK), overridable via
WorkerConfig::builder():
| Variable | Required | Default |
|---|---|---|
KRUXIAFLOW_API_URL |
yes | — |
KRUXIAFLOW_CLIENT_ID |
yes* | — |
KRUXIAFLOW_CLIENT_SECRET |
yes* | — |
KRUXIAFLOW_WORKER |
no | inferred from registered activities |
KRUXIAFLOW_WORKER_ID |
no | auto-generated |
KRUXIAFLOW_WORKER_POLL_MAX_ACTIVITIES |
no | 10 |
KRUXIAFLOW_WORKER_POLL_INTERVAL |
no | 0.1 (seconds) |
KRUXIAFLOW_WORKER_MAX_ACTIVITIES |
no | 16 |
KRUXIAFLOW_WORKER_ACTIVITY_TIMEOUT |
no | 300 (seconds) |
KRUXIAFLOW_WORKER_HEARTBEAT_INTERVAL |
no | 30 (seconds) |
KRUXIAFLOW_WORKER_SHUTDOWN_TIMEOUT |
no | 30 (seconds) |
* not required against a dev-mode server (kruxiaflow serve --insecure-dev).
Graceful shutdown
run_until_shutdown() listens for SIGINT/SIGTERM; worker.handle() gives a
programmatic trigger (k8s preStop, tests). On shutdown the worker stops
polling, drains in-flight activities up to shutdown_timeout, then fails
whatever remains as retryable so it re-queues on another worker — nothing is
lost or double-completed.
Examples
echo_worker— minimal worker, one typed handlerllm_usage_worker— reporting per-call LLM usage and extra costsgraceful_drain— SIGTERM drain behavior with a slow activity
Run one against a local dev-mode server:
KRUXIAFLOW_API_URL=http://localhost:8080
License
Licensed under either of Apache License, Version 2.0 or MIT license at your option.