Skip to main content

Crate kruxiaflow_worker

Crate kruxiaflow_worker 

Source
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-dev

Then 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.

Attribute Macros§

async_trait