Expand description
Worker SDK for Kruxia Flow — run Rust activities in budgeted workflows with engine-enforced cost limits.
A Kruxia Flow worker polls the server for queued activities, executes registered handlers, and reports results (including LLM usage, so external activities count against workflow budgets with full fidelity). This crate provides the complete worker loop: registration, polling, bounded concurrency, heartbeats, timeout and panic containment, completion/failure reporting, OAuth2 client-credentials auth, and graceful drain on shutdown.
§Quickstart
Run a server locally (no auth needed in dev mode):
kruxiaflow serve --insecure-devThen a minimal worker:
use kruxiaflow_worker::{ActivityContext, ActivityResult, Worker};
use serde_json::json;
#[derive(serde::Deserialize)]
struct EchoParams {
message: String,
}
#[tokio::main]
async fn main() -> anyhow::Result<()> {
let worker = Worker::builder()
.worker("demo") // the workflow definition's `worker:` field
.register_fn("echo", |params: EchoParams, _ctx: ActivityContext| async move {
Ok(ActivityResult::value("echoed", json!(params.message)))
})
.build()?; // config from KRUXIAFLOW_* environment variables
worker.run_until_shutdown().await;
Ok(())
}A workflow activity with worker: demo and name: echo now executes on
this worker.
§Reporting cost and usage
Activities that call LLMs themselves report per-call usage so the engine records it exactly like built-in LLM activities — visible in cost history/analytics and counted against workflow budgets:
use kruxiaflow_worker::{ActivityResult, UsageEntry};
use serde_json::json;
ActivityResult::value("summary", json!("..."))
.push_usage(
UsageEntry::new("anthropic", "claude-sonnet-5")
.input_tokens(12034)
.output_tokens(512)
.cache_read_tokens(9800),
)The server prices entries from its model catalog unless an entry carries
an explicit cost_usd. Failures spend money too: attach usage to
ActivityError so failed attempts are budget-counted.
§Failure semantics
Handlers return Result<ActivityResult, ActivityError>. Construct errors
with ActivityError::retryable (transient: the orchestrator re-queues
up to the activity’s retry limit) or ActivityError::terminal (bad
input, business rejection: no retry). Panics and timeouts are caught and
reported as retryable; parameter deserialization failures are terminal.
§Shutdown
Worker::run_until_shutdown listens for SIGINT/SIGTERM;
Worker::handle gives a programmatic trigger. Shutdown stops polling
and drains in-flight activities up to the configured shutdown_timeout,
then fails the remainder as retryable so they re-queue — nothing is lost
or double-completed.
Re-exports§
pub use client::ReportAck;pub use client::WakeConnect;pub use client::WakeStream;pub use client::WorkerApiClient;pub use config::WakeMode;pub use config::WorkerConfig;pub use config::WorkerConfigBuilder;pub use context::ActivityContext;pub use error::ActivityError;pub use error::ClientError;pub use error::ConfigError;pub use poller::WorkerPoller;pub use registry::ActivityExecutor;pub use registry::ActivityImpl;pub use registry::ActivityRegistry;pub use registry::TypedActivity;pub use result::ActivityResult;pub use types::ActivityOutput;pub use types::OutputType;pub use types::PendingActivity;pub use types::PollActivitiesResponse;pub use types::PollOutcome;pub use types::UsageEntry;pub use worker::Worker;pub use worker::WorkerBuilder;pub use worker::WorkerHandle;
Modules§
- client
- HTTP client for the worker activity APIs.
- config
- Worker configuration from environment variables or a builder.
- context
- Activity execution context.
- error
- Error types for the worker SDK.
- poller
- Poll / lease / execute loop with semaphore-based concurrency.
- registry
- Activity handler registration and dispatch.
- result
- Activity execution result.
- types
- Protocol types shared between workers and the Kruxia Flow server.
- worker
- High-level worker: builder, run loop, graceful shutdown.