Struct WorkflowRunner 

pub struct WorkflowRunner { /* private fields */ }

The main workflow runner that executes workflow definitions

Implementations

impl WorkflowRunner

pub fn new(workflow: WorkflowDefinition) -> WorkflowResult<Self>

Creates a new WorkflowRunner for the given workflow definition

pub fn with_secret_manager(self, manager: Arc<dyn SecretManager>) -> Self

Sets the secret manager for $secret expression variable

pub fn with_listener(self, listener: Arc<dyn WorkflowExecutionListener>) -> Self

Sets the execution listener for workflow/task events

pub fn with_event_bus(self, bus: SharedEventBus) -> Self

Sets the event bus for emit/listen tasks

pub fn with_sub_workflow(self, workflow: WorkflowDefinition) -> Self

Registers a sub-workflow that can be invoked via run: workflow Keyed by “namespace/name/version”

pub fn with_call_handler(self, handler: Box<dyn CallHandler>) -> Self

Registers a custom call handler for a specific call type (e.g., “grpc”, “openapi”, “asyncapi”, “a2a”)

pub fn with_run_handler(self, handler: Box<dyn RunHandler>) -> Self

Registers a custom run handler for a specific run type (e.g., “container”, “script”)

pub fn with_function(self, name: &str, task: TaskDefinition) -> Self

Registers a named function definition for call.function resolution

This allows registering external function definitions that can be referenced by call: <functionName> in workflows, similar to Java SDK’s cataloged function mechanism.

pub fn with_handler_registry(self, registry: HandlerRegistry) -> Self

Sets the entire handler registry (used for propagating handlers to child runners)

pub fn with_custom_task_handler( self, handler: Box<dyn CustomTaskHandler>, ) -> Self

Registers a custom task handler for a specific custom task type

pub fn with_expression_engine(self, engine: Arc<dyn ExpressionEngine>) -> Self

Registers a custom expression engine for a specific prefix (e.g., “cel”, “js”)

Expressions prefixed with engine_prefix: will be routed to this engine. Unprefixed expressions default to JQ.

pub fn with_expression_engine_registry( self, registry: ExpressionEngineRegistry, ) -> Self

Sets the expression engine registry (replaces all previously registered engines). Useful for propagating engines from a parent runner to a child runner.

pub fn with_variable(self, name: impl Into<String>, value: Value) -> Self

Injects a custom variable into the JQ expression context.

The variable will be available as $name in all expressions (input.from, output.as, switch conditions, etc.). This is useful for passing external configuration or environment information into the workflow.

Example

use swf_runtime::WorkflowRunner;
use serde_json::json;

let runner = WorkflowRunner::new(workflow)
    .expect("failed to create runner")
    .with_variable("config", json!({"base_url": "https://api.example.com"}))
    .with_variable("env", json!({"region": "us-east-1"}));

pub async fn run(&self, input: Value) -> WorkflowResult<Value>

Runs the workflow with the given input and returns the output

pub fn workflow(&self) -> &WorkflowDefinition

Returns a reference to the workflow definition

pub fn handle(&self) -> WorkflowHandle

Returns a WorkflowHandle that can suspend/resume the running workflow

Must be called before run(). The handle shares suspend/resume state with the workflow context via Arc.

pub fn schedule(self, input: Value) -> ScheduledWorkflow

Runs the workflow on a recurring schedule based on the workflow’s schedule.every or schedule.cron definition.

For every: runs the workflow at fixed intervals. For cron: runs the workflow according to the cron expression schedule.

Returns a ScheduledWorkflow that can be cancelled to stop the schedule. If no schedule is defined, runs once and returns a completed handle.