supervisor/examples/README.md

Hero Supervisor Examples

This directory contains examples demonstrating the new job API functionality and workflows.

Examples Overview

1. job_api_examples.rs - Comprehensive API Demo

Complete demonstration of all new job API methods:

• Fire-and-forget execution using job.run
• Asynchronous processing with jobs.create, job.start, job.status, job.result
• Batch job processing for multiple jobs
• Job listing with jobs.list

Run with:

cargo run --example job_api_examples

2. simple_job_workflow.rs - Basic Workflow

Simple example showing the basic job lifecycle:

1. Create job with jobs.create
2. Start job with job.start
3. Monitor with job.status
4. Get result with job.result

Run with:

cargo run --example simple_job_workflow

3. integration_test.rs - Integration Tests

Comprehensive integration tests validating:

• Complete job lifecycle
• Immediate job execution
• Job listing functionality
• Authentication error handling
• Nonexistent job operations

Run with:

cargo test --test integration_test

Prerequisites

Before running the examples, ensure:

1. Redis is running:

   docker run -d -p 6379:6379 redis:alpine
   

2. Supervisor is running:

   ./target/debug/supervisor --config examples/supervisor/config.toml
   

3. Runners are configured in your config.toml:

   [[actors]]
   id = "osis_runner_1"
   name = "osis_runner_1"
   binary_path = "/path/to/osis_runner"
   db_path = "/tmp/osis_db"
   redis_url = "redis://localhost:6379"
   process_manager = "simple"
   

API Convention Summary

The examples demonstrate the new job API convention:

General Operations (jobs.)

• jobs.create - Create a job without queuing it
• jobs.list - List all job IDs in the system

Specific Operations (job.)

• job.run - Run a job immediately and return result
• job.start - Start a previously created job
• job.status - Get current job status (non-blocking)
• job.result - Get job result (blocking until complete)

Workflow Patterns

Pattern 1: Fire-and-Forget

let result = client.job_run(secret, job).await?;
match result {
    JobResult::Success { success } => println!("Output: {}", success),
    JobResult::Error { error } => println!("Error: {}", error),
}

Pattern 2: Asynchronous Processing

// Create and start
let job_id = client.jobs_create(secret, job).await?;
client.job_start(secret, &job_id).await?;

// Monitor (non-blocking)
loop {
    let status = client.job_status(&job_id).await?;
    if status.status == "completed" { break; }
    sleep(Duration::from_secs(1)).await;
}

// Get result
let result = client.job_result(&job_id).await?;

Pattern 3: Batch Processing

// Create all jobs
let mut job_ids = Vec::new();
for job_spec in job_specs {
    let job_id = client.jobs_create(secret, job_spec).await?;
    job_ids.push(job_id);
}

// Start all jobs
for job_id in &job_ids {
    client.job_start(secret, job_id).await?;
}

// Collect results
for job_id in &job_ids {
    let result = client.job_result(job_id).await?;
    // Process result...
}

Error Handling

The examples demonstrate proper error handling for:

• Authentication errors - Invalid secrets
• Job not found errors - Nonexistent job IDs
• Connection errors - Supervisor not available
• Execution errors - Job failures

Authentication

Examples use different secret types:

• Admin secrets: Full system access
• User secrets: Job operations only (used in examples)
• Register secrets: Runner registration only

Configure secrets in your supervisor config:

admin_secrets = ["admin-secret-123"]
user_secrets = ["user-secret-456"]
register_secrets = ["register-secret-789"]

Troubleshooting

Common Issues

1. Connection refused

   • Ensure supervisor is running on localhost:3030
   • Check supervisor logs for errors

2. Authentication failed

   • Verify secret is configured in supervisor
   • Check secret type matches operation requirements

3. Job execution failed

   • Ensure runners are properly configured and running
   • Check runner logs for execution errors
   • Verify job payload is valid for the target runner

4. Redis connection failed

   • Ensure Redis is running on localhost:6379
   • Check Redis connectivity from supervisor

Debug Mode

Run examples with debug logging:

RUST_LOG=debug cargo run --example job_api_examples

This will show detailed API calls and responses for troubleshooting.