Runtara Examples

Example applications demonstrating Runtara - a durable execution platform for crash-resilient workflows in Rust.

Quick Start

# Build all examples
cargo build --all

# Run a specific example
cargo run -p durable-example --bin basic_example

Project Structure

Crate	Description
durable-example	SDK examples demonstrating checkpoints, signals, sleep, and the #[durable] macro
durable-examples-embedded	Embedded mode with SQLite persistence (no server required)
workflows-example	JSON workflow DSL compilation to native Rust code

Examples Overview

durable-example

Examples that demonstrate the runtara-sdk for building durable workflows. These examples connect to runtara-core when available, or run in demo mode showing the patterns.

basic_example

SDK lifecycle fundamentals

Demonstrates the basic SDK workflow: initialization, connection, registration, heartbeat reporting, and completion.

cargo run -p durable-example --bin basic_example

Concepts covered:

• RuntaraSdk::localhost() - Create SDK for local development
• sdk.connect() - Establish QUIC connection to runtara-core
• sdk.register() - Register instance with the server
• sdk.heartbeat() - Simple "I'm alive" signals
• sdk.completed() - Signal successful completion with output

---

checkpoint_example

Durable state persistence

Shows how to save workflow state at checkpoints for crash recovery. If the process crashes, it can resume from the last checkpoint.

cargo run -p durable-example --bin checkpoint_example

Concepts covered:

• sdk.checkpoint() - Save serialized state to PostgreSQL
• Resume from existing checkpoint data
• Progress tracking through checkpoint IDs

---

sleep_example

Durable sleep for long-running tasks

Demonstrates durable sleep between workflow phases. Unlike tokio::sleep, durable sleep preserves state if the process crashes.

cargo run -p durable-example --bin sleep_example

Concepts covered:

• sdk.sleep() - Durable sleep with checkpoint
• Multi-phase workflows with delays
• State preservation across sleep periods

Use cases:

• Rate limit backoff
• Scheduled batch processing
• Throttling API calls

---

signal_example

Cancel, pause, and resume handling

Shows how to handle external control signals for graceful shutdown and pause/resume functionality.

cargo run -p durable-example --bin signal_example

Concepts covered:

• sdk.check_cancelled() - Simple cancellation check in loops
• sdk.poll_signal() - Manual signal polling for pause/resume
• sdk.acknowledge_signal() - Confirm signal handling
• sdk.suspended() - Report paused state
• SignalType::Cancel, SignalType::Pause, SignalType::Resume

---

error_example

Error handling and recovery patterns

Demonstrates different error handling strategies: retry with exponential backoff, unrecoverable errors, timeouts, and partial failure tolerance.

cargo run -p durable-example --bin error_example

Concepts covered:

• Exponential backoff retry pattern
• sdk.failed() - Report workflow failure
• tokio::timeout() - Operation timeouts
• Partial failure with continue (process remaining items)
• Checkpoint before risky operations

---

http_example

Real HTTP requests with checkpointing

Fetches URLs from runtara.com with checkpoint-based crash recovery. Demonstrates real-world I/O with durability.

cargo run -p durable-example --bin http_example

Concepts covered:

• Pre-fetch and post-fetch checkpoints
• HTTP client integration with reqwest
• Progress reporting during I/O operations
• Graceful handling of fetch failures

---

durable_macro_example

The #[durable] attribute macro

Demonstrates the #[durable] proc macro for transparent checkpoint-based caching. Functions decorated with #[durable] automatically cache their results.

cargo run -p durable-example --bin durable_macro_example

Concepts covered:

• #[durable] - Basic durable function with automatic caching
• #[durable(max_retries = 3, strategy = ExponentialBackoff, delay = 100)] - Retry configuration
• Idempotency keys for cache lookup
• Cached results on repeat calls

Example:

#[durable]
pub async fn get_order(key: &str, order_id: &str) -> Result<Order, AppError> {
    // First call executes, subsequent calls with same key return cached result
    db.fetch_order(order_id).await
}

---

durable_advanced_example

Complete order processing workflow

A realistic e-commerce order fulfillment pipeline with multiple durable steps: validation, inventory, payment, shipping, and notifications.

cargo run -p durable-example --bin durable_advanced_example

Concepts covered:

• Multi-step workflow orchestration
• Nested durable functions
• Service integration patterns (payment gateway, inventory, shipping)
• Complete workflow caching (entire workflow returns cached result on repeat)

Workflow steps:

1. Validate order
2. Reserve inventory
3. Capture payment
4. Create shipment
5. Send notifications

---

pauseable_example

Checkpoint-based pause/resume

Shows how to detect pause signals via checkpoint responses and cleanly exit for later resume.

cargo run -p durable-example --bin pauseable_example

# Resume with same instance ID
RUNTARA_INSTANCE_ID=<id> cargo run -p durable-example --bin pauseable_example

Concepts covered:

• result.should_pause() - Check for pause signal in checkpoint response
• result.should_cancel() - Check for cancel signal
• result.existing_state() - Resume from checkpoint
• Clean exit on pause for later restart

---

durable-examples-embedded

basic_embedded_example

SQLite persistence without a server

Demonstrates embedded mode where the SDK uses local SQLite for persistence instead of connecting to runtara-core. Ideal for development, testing, or single-node deployments.

cargo run -p durable-examples-embedded --bin basic_embedded_example

Concepts covered:

• RuntaraSdk::embedded() - Create SDK with local persistence
• SqlitePersistence - SQLite-backed checkpoint storage
• #[durable] macro with retry in embedded mode

Example:

let persistence: Arc<dyn Persistence> =
    Arc::new(SqlitePersistence::from_path(".data/example.db").await?);

RuntaraSdk::embedded(persistence, instance_id, tenant_id)
    .init(None)
    .await?;

---

workflows-example

workflows-example

JSON DSL to native Rust compilation

Demonstrates the workflow compilation system: load JSON workflow definitions, generate Rust code, and optionally compile to native binaries.

# Code generation only
cargo run -p workflows-example

# With compilation (requires pre-built stdlib)
cargo run -p workflows-example -- --compile

Concepts covered:

• ExecutionGraph - Workflow definition structure
• translate_scenario() - Generate Rust code from JSON
• compile_scenario() - Compile to native binary
• Workflow agents and step types

Included workflows:

File	Description
simple_passthrough.json	Passes input directly to output
transform_workflow.json	Uses transform agent with retry configuration
workflow_with_variables.json	Demonstrates scenario variables

---

Prerequisites

• Rust 1.75+ (Edition 2024)
• runtara-core running on localhost:8001 (for non-embedded examples)
  • Examples fall back to demo mode if server unavailable
• PostgreSQL (for runtara-core persistence)

Environment Variables

Variable	Default	Description
RUNTARA_SERVER_ADDR	127.0.0.1:8001	Core server address
RUNTARA_INSTANCE_ID	Auto-generated	Instance identifier (for resume)
RUNTARA_TENANT_ID	demo-tenant	Tenant identifier

Running with runtara-core

To run examples with full server integration:

# Terminal 1: Start runtara-core
cd ../runtara
RUNTARA_DATABASE_URL=postgres://user:pass@localhost/runtara cargo run -p runtara-core

# Terminal 2: Run examples
cd ../runtara-examples
cargo run -p durable-example --bin checkpoint_example

License

AGPL-3.0-or-later - See LICENSE for details.