feat: simplify OpenRPC API and reorganize examples
- Simplified RunnerConfig to just name, command, and optional env - Removed RunnerType and ProcessManagerType enums - Removed db_path, redis_url, binary_path from config - Made runner name also serve as queue name (no separate queue param) - Added secret-based authentication to all runner management methods - Created comprehensive osiris_openrpc example - Archived old examples to _archive/ - Updated client API to match simplified supervisor interface
This commit is contained in:
Timur Gordon
@@ -1,182 +1,74 @@
|
||||
# Hero Supervisor Examples
|
||||
|
||||
This directory contains examples demonstrating the new job API functionality and workflows.
|
||||
This directory contains examples demonstrating Hero Supervisor functionality.
|
||||
|
||||
## Examples Overview
|
||||
## Available Examples
|
||||
|
||||
### 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`
|
||||
### osiris_openrpc
|
||||
|
||||
**Run with:**
|
||||
Comprehensive example showing the complete workflow of using Hero Supervisor with OSIRIS runners via OpenRPC.
|
||||
|
||||
**Features:**
|
||||
- Automatic supervisor and runner startup
|
||||
- OpenRPC client communication
|
||||
- Runner registration and management
|
||||
- Job dispatching with multiple scripts
|
||||
- Context-based access control
|
||||
- Graceful shutdown
|
||||
|
||||
**Run:**
|
||||
```bash
|
||||
cargo run --example job_api_examples
|
||||
cargo run --example osiris_openrpc
|
||||
```
|
||||
|
||||
### 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
|
||||
```
|
||||
See [osiris_openrpc/README.md](osiris_openrpc/README.md) for details.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before running the examples, ensure:
|
||||
All examples require:
|
||||
- Redis server running on `localhost:6379`
|
||||
- Rust toolchain installed
|
||||
|
||||
1. **Redis is running:**
|
||||
```bash
|
||||
docker run -d -p 6379:6379 redis:alpine
|
||||
```
|
||||
## Example Structure
|
||||
|
||||
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),
|
||||
}
|
||||
```
|
||||
examples/
|
||||
├── README.md # This file
|
||||
├── osiris_openrpc/ # OSIRIS + OpenRPC example
|
||||
│ ├── main.rs # Main example code
|
||||
│ ├── README.md # Detailed documentation
|
||||
│ ├── note.rhai # Note creation script
|
||||
│ ├── event.rhai # Event creation script
|
||||
│ ├── query.rhai # Query script
|
||||
│ └── access_denied.rhai # Access control test script
|
||||
└── _archive/ # Archived old examples
|
||||
```
|
||||
|
||||
### Pattern 2: Asynchronous Processing
|
||||
```rust
|
||||
// Create and start
|
||||
let job_id = client.jobs_create(secret, job).await?;
|
||||
client.job_start(secret, &job_id).await?;
|
||||
## Architecture Overview
|
||||
|
||||
// Monitor (non-blocking)
|
||||
loop {
|
||||
let status = client.job_status(&job_id).await?;
|
||||
if status.status == "completed" { break; }
|
||||
sleep(Duration::from_secs(1)).await;
|
||||
}
|
||||
The examples demonstrate the Hero Supervisor architecture:
|
||||
|
||||
// Get result
|
||||
let result = client.job_result(&job_id).await?;
|
||||
```
|
||||
Client (OpenRPC)
|
||||
↓
|
||||
Supervisor (OpenRPC Server)
|
||||
↓
|
||||
Redis Queue
|
||||
↓
|
||||
Runners (OSIRIS, SAL, etc.)
|
||||
```
|
||||
|
||||
### 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);
|
||||
}
|
||||
## Development
|
||||
|
||||
// Start all jobs
|
||||
for job_id in &job_ids {
|
||||
client.job_start(secret, job_id).await?;
|
||||
}
|
||||
To add a new example:
|
||||
|
||||
// Collect results
|
||||
for job_id in &job_ids {
|
||||
let result = client.job_result(job_id).await?;
|
||||
// Process result...
|
||||
}
|
||||
```
|
||||
1. Create a new directory under `examples/`
|
||||
2. Add `main.rs` with your example code
|
||||
3. Add any required script files (`.rhai`)
|
||||
4. Add a `README.md` documenting the example
|
||||
5. Update `Cargo.toml` to register the example
|
||||
6. Update this README with a link
|
||||
|
||||
## Error Handling
|
||||
## Archived Examples
|
||||
|
||||
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.
|
||||
Previous examples have been moved to `_archive/` for reference. These may be outdated but can provide useful patterns for specific use cases.
|
||||
|
||||
Reference in New Issue
Block a user