supervisor/examples/_archive/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:**
```bash
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:**
```bash
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:**
```bash
cargo test --test integration_test
```

## Prerequisites

Before running the examples, ensure:

1. **Redis is running:**
   ```bash
   docker run -d -p 6379:6379 redis:alpine
   ```

2. **Supervisor is running:**
   ```bash
   ./target/debug/supervisor --config examples/supervisor/config.toml
   ```

3. **Runners are configured** in your config.toml:
   ```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
```rust
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
```rust
// 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
```rust
// 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:
```toml
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:
```bash
RUST_LOG=debug cargo run --example job_api_examples
```

This will show detailed API calls and responses for troubleshooting.