Struct WorkerBuilder 

pub struct WorkerBuilder { /* private fields */ }

Builder for configuring and creating a Worker.

Examples

use std::sync::Arc;
use std::time::Duration;
use ironflow_worker::WorkerBuilder;
use ironflow_core::providers::claude::ClaudeCodeProvider;

let worker = WorkerBuilder::new("http://localhost:3000", "my-token")
    .provider(Arc::new(ClaudeCodeProvider::new()))
    .concurrency(4)
    .poll_interval(Duration::from_secs(2))
    .run_timeout(Duration::from_secs(600))
    .max_consecutive_panics(5)
    .build()?;

worker.run().await?;

Implementations

impl WorkerBuilder

pub fn new(api_url: &str, worker_token: &str) -> Self

Create a new builder targeting the given API server.

pub fn provider(self, provider: Arc<dyn AgentProvider>) -> Self

Set the agent provider for AI operations.

pub fn decision_provider(self, provider: Arc<dyn DecisionProvider>) -> Self

Set the DecisionProvider backend for ctx.decision(...) steps.

Every run executed by this worker gets it, like Engine::with_decision_provider. Optional: without it, a workflow that reaches a decision step fails with EngineError::NoDecisionProvider. A decision step already completed in the store is replayed without calling the provider again.

Examples

use std::sync::Arc;
use ironflow_core::providers::claude::ClaudeCodeProvider;
use ironflow_core::providers::record_replay_decision::RecordReplayDecisionProvider;
use ironflow_worker::WorkerBuilder;

let worker = WorkerBuilder::new("http://localhost:3000", "token")
    .provider(Arc::new(ClaudeCodeProvider::new()))
    .decision_provider(Arc::new(RecordReplayDecisionProvider::replay("tests/fixtures")))
    .build()?;

pub fn account_strategy(self, strategy: Arc<dyn AccountStrategy>) -> Self

Set the strategy picking a Provider Account for each agent step.

Defaults to LeastUtilized. Only used when Provider Accounts of the provider’s kind exist; otherwise agent steps run with the worker environment.

Examples

use std::sync::Arc;
use ironflow_core::account_strategy::Priority;
use ironflow_core::providers::claude::ClaudeCodeProvider;
use ironflow_worker::WorkerBuilder;

let worker = WorkerBuilder::new("http://localhost:3000", "token")
    .provider(Arc::new(ClaudeCodeProvider::new()))
    .account_strategy(Arc::new(Priority))
    .build()?;

pub fn max_capacity_wait(self, wait: Duration) -> Self

Set how long an agent step may wait for Provider Account capacity.

When every targeted account is rate limited, the run sleeps until the earliest reset if it falls within this bound, and fails with AgentError::NoCapacity otherwise. A step’s own AgentConfig::max_capacity_wait takes precedence. Defaults to DEFAULT_MAX_CAPACITY_WAIT (6 hours); Duration::ZERO fails fast.

Examples

use std::sync::Arc;
use std::time::Duration;
use ironflow_core::providers::claude::ClaudeCodeProvider;
use ironflow_worker::WorkerBuilder;

let worker = WorkerBuilder::new("http://localhost:3000", "token")
    .provider(Arc::new(ClaudeCodeProvider::new()))
    .max_capacity_wait(Duration::ZERO)
    .build()?;

pub fn register(self, handler: impl WorkflowHandler + 'static) -> Self

Register a workflow handler.

pub fn concurrency(self, n: usize) -> Self

Set the maximum number of concurrent workflow executions.

pub fn poll_interval(self, interval: Duration) -> Self

Set the interval between polls for new runs.

pub fn run_timeout(self, timeout: Duration) -> Self

Set the maximum execution time per run.

If a run exceeds this duration, it is cancelled and marked as Failed with a timeout error. Defaults to 30 minutes.

Examples

use std::time::Duration;
use ironflow_worker::WorkerBuilder;

let builder = WorkerBuilder::new("http://localhost:3000", "token")
    .run_timeout(Duration::from_secs(600));

pub fn max_consecutive_panics(self, n: u32) -> Self

Set the maximum number of consecutive panics per workflow before the worker stops picking runs for that workflow (poison pill guard).

When a workflow panics max_consecutive_panics times in a row without a single success, the worker skips it for a cooldown period (see panic_cooldown). Defaults to 3.

Examples

use ironflow_worker::WorkerBuilder;

let builder = WorkerBuilder::new("http://localhost:3000", "token")
    .max_consecutive_panics(5);

pub fn panic_cooldown(self, cooldown: Duration) -> Self

Set the cooldown duration after a workflow is flagged as a poison pill.

After max_consecutive_panics is reached, runs for that workflow are skipped until this duration elapses. Defaults to 5 minutes.

Examples

use std::time::Duration;
use ironflow_worker::WorkerBuilder;

let builder = WorkerBuilder::new("http://localhost:3000", "token")
    .panic_cooldown(Duration::from_secs(600));

pub fn worker_id(self, worker_id: &str) -> Self

Set the identifier this worker uses to claim runs.

Defaults to worker-<uuid>, regenerated at every start so two processes never share an identity. Override it only if you have a stable, unique name per process.

Examples

use ironflow_worker::WorkerBuilder;

let builder = WorkerBuilder::new("http://localhost:3000", "token")
    .worker_id("worker-eu-west-1a");

pub fn tags<I, S>(self, tags: I) -> Self

where I: IntoIterator<Item = S>, S: Into<String>,

Declare tags this worker carries, adding to any set before.

The worker only picks runs whose required tags (from WorkflowHandler::required_worker_tags and the run’s own worker_tags) are all in this list, and only runs of the workflows it registered. A run requiring a tag no worker carries stays pending. Defaults to no tag: the worker only takes runs that require none.

Each tag is 1 to 64 bytes of ASCII letters, digits and - _ . : / =, at most 32 tags; build rejects anything else. Surrounding whitespace and duplicates are dropped.

Examples

use ironflow_worker::WorkerBuilder;

let builder = WorkerBuilder::new("http://localhost:3000", "token")
    .tags(["gpu", "region:eu"]);

pub fn lease_ttl(self, ttl: Duration) -> Self

Set how long a lease stays valid without a refresh.

Once it expires, the API reaper requeues the run for another worker. Keep it at a few times lease_refresh_interval so a transient network blip does not hand the run over. Defaults to 90 s.

Examples

use std::time::Duration;
use ironflow_worker::WorkerBuilder;

let builder = WorkerBuilder::new("http://localhost:3000", "token")
    .lease_ttl(Duration::from_secs(120));

pub fn lease_refresh_interval(self, interval: Duration) -> Self

Set how often the lease of a running run is refreshed.

Defaults to 30 seconds. Must stay well below lease_ttl.

Examples

use std::time::Duration;
use ironflow_worker::WorkerBuilder;

let builder = WorkerBuilder::new("http://localhost:3000", "token")
    .lease_refresh_interval(Duration::from_secs(10));

pub fn build(self) -> Result<Worker, WorkerError>

Build the worker.

Errors

Returns WorkerError::Internal if no provider has been set. Returns WorkerError::Engine if a handler registration fails, or wrapping EngineError::InvalidWorkerTag if a tag set with tags is invalid.