183 lines
4.5 KiB
Markdown
183 lines
4.5 KiB
Markdown
# 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.
|