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.
|
||||
|
||||
364
examples/_archive/E2E_EXAMPLES.md
Normal file
364
examples/_archive/E2E_EXAMPLES.md
Normal file
@@ -0,0 +1,364 @@
|
||||
# End-to-End Examples
|
||||
|
||||
Complete examples demonstrating the full Supervisor + Runner + Client workflow.
|
||||
|
||||
## Overview
|
||||
|
||||
These examples show how to:
|
||||
1. Start a Hero Supervisor
|
||||
2. Start an OSIS Runner
|
||||
3. Register the runner with the supervisor
|
||||
4. Execute jobs using both blocking (`job.run`) and non-blocking (`job.start`) modes
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Required Services
|
||||
|
||||
1. **Redis** - Must be running on `localhost:6379`
|
||||
```bash
|
||||
redis-server
|
||||
```
|
||||
|
||||
2. **Supervisor** - Hero Supervisor with Mycelium integration
|
||||
```bash
|
||||
cargo run --bin hero-supervisor -- --redis-url redis://localhost:6379
|
||||
```
|
||||
|
||||
3. **Runner** - OSIS Runner to execute jobs
|
||||
```bash
|
||||
cargo run --bin runner_osis -- test_runner --redis-url redis://localhost:6379
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### 1. Simple End-to-End (`simple_e2e.rs`)
|
||||
|
||||
**Recommended for beginners** - A minimal example with clear step-by-step execution.
|
||||
|
||||
#### What it does:
|
||||
- Registers a runner with the supervisor
|
||||
- Runs 2 blocking jobs (with immediate results)
|
||||
- Starts 1 non-blocking job (fire and forget)
|
||||
- Shows clear output at each step
|
||||
|
||||
#### How to run:
|
||||
|
||||
**Terminal 1 - Redis:**
|
||||
```bash
|
||||
redis-server
|
||||
```
|
||||
|
||||
**Terminal 2 - Supervisor:**
|
||||
```bash
|
||||
cd /Users/timurgordon/code/git.ourworld.tf/herocode/supervisor
|
||||
RUST_LOG=info cargo run --bin hero-supervisor -- --redis-url redis://localhost:6379
|
||||
```
|
||||
|
||||
**Terminal 3 - Runner:**
|
||||
```bash
|
||||
cd /Users/timurgordon/code/git.ourworld.tf/herocode/runner_rust
|
||||
RUST_LOG=info cargo run --bin runner_osis -- test_runner \
|
||||
--redis-url redis://localhost:6379 \
|
||||
--db-path /tmp/test_runner.db
|
||||
```
|
||||
|
||||
**Terminal 4 - Demo:**
|
||||
```bash
|
||||
cd /Users/timurgordon/code/git.ourworld.tf/herocode/supervisor
|
||||
RUST_LOG=info cargo run --example simple_e2e
|
||||
```
|
||||
|
||||
#### Expected Output:
|
||||
|
||||
```
|
||||
╔════════════════════════════════════════╗
|
||||
║ Simple End-to-End Demo ║
|
||||
╚════════════════════════════════════════╝
|
||||
|
||||
📋 Step 1: Registering Runner
|
||||
─────────────────────────────────────────
|
||||
✅ Runner registered successfully
|
||||
|
||||
📋 Step 2: Running a Simple Job (Blocking)
|
||||
─────────────────────────────────────────
|
||||
✅ Job completed!
|
||||
Result: {"message":"Hello from the runner!","number":42,"timestamp":1234567890}
|
||||
|
||||
📋 Step 3: Running a Calculation Job
|
||||
─────────────────────────────────────────
|
||||
✅ Calculation completed!
|
||||
Result: {"sum":55,"product":3628800,"count":10,"average":5}
|
||||
|
||||
📋 Step 4: Starting a Non-Blocking Job
|
||||
─────────────────────────────────────────
|
||||
✅ Job started!
|
||||
Job ID: abc-123 (running in background)
|
||||
|
||||
🎉 Demo completed successfully!
|
||||
```
|
||||
|
||||
### 2. Full End-to-End (`end_to_end_demo.rs`)
|
||||
|
||||
**Advanced** - Automatically spawns supervisor and runner processes.
|
||||
|
||||
#### What it does:
|
||||
- Automatically starts supervisor and runner
|
||||
- Runs multiple test jobs
|
||||
- Demonstrates both execution modes
|
||||
- Handles cleanup automatically
|
||||
|
||||
#### How to run:
|
||||
|
||||
**Terminal 1 - Redis:**
|
||||
```bash
|
||||
redis-server
|
||||
```
|
||||
|
||||
**Terminal 2 - Demo:**
|
||||
```bash
|
||||
cd /Users/timurgordon/code/git.ourworld.tf/herocode/supervisor
|
||||
RUST_LOG=info cargo run --example end_to_end_demo
|
||||
```
|
||||
|
||||
#### Features:
|
||||
- ✅ Automatic process management
|
||||
- ✅ Multiple job examples
|
||||
- ✅ Graceful shutdown
|
||||
- ✅ Comprehensive logging
|
||||
|
||||
## Job Execution Modes
|
||||
|
||||
### job.run (Blocking)
|
||||
|
||||
Executes a job and waits for the result.
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"method": "job.run",
|
||||
"params": [{
|
||||
"secret": "admin_secret",
|
||||
"job": { /* job object */ },
|
||||
"timeout": 30
|
||||
}],
|
||||
"id": 1
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"result": {
|
||||
"job_id": "uuid",
|
||||
"status": "completed",
|
||||
"result": "{ /* actual result */ }"
|
||||
},
|
||||
"id": 1
|
||||
}
|
||||
```
|
||||
|
||||
**Use when:**
|
||||
- You need immediate results
|
||||
- Job completes quickly (< 60 seconds)
|
||||
- Synchronous workflow
|
||||
|
||||
### job.start (Non-Blocking)
|
||||
|
||||
Starts a job and returns immediately.
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"method": "job.start",
|
||||
"params": [{
|
||||
"secret": "admin_secret",
|
||||
"job": { /* job object */ }
|
||||
}],
|
||||
"id": 1
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"result": {
|
||||
"job_id": "uuid",
|
||||
"status": "queued"
|
||||
},
|
||||
"id": 1
|
||||
}
|
||||
```
|
||||
|
||||
**Use when:**
|
||||
- Long-running operations
|
||||
- Background processing
|
||||
- Async workflows
|
||||
- Don't need immediate results
|
||||
|
||||
## Job Structure
|
||||
|
||||
Jobs are created using the `JobBuilder`:
|
||||
|
||||
```rust
|
||||
use runner_rust::job::JobBuilder;
|
||||
|
||||
let job = JobBuilder::new()
|
||||
.caller_id("my_client")
|
||||
.context_id("my_context")
|
||||
.payload(r#"
|
||||
// Rhai script to execute
|
||||
let result = 2 + 2;
|
||||
to_json(result)
|
||||
"#)
|
||||
.runner("runner_name")
|
||||
.executor("rhai")
|
||||
.timeout(30)
|
||||
.build()?;
|
||||
```
|
||||
|
||||
### Job Fields
|
||||
|
||||
- **caller_id**: Identifier for the client making the request
|
||||
- **context_id**: Context for the job execution
|
||||
- **payload**: Rhai script to execute
|
||||
- **runner**: Name of the runner to execute on
|
||||
- **executor**: Type of executor (always "rhai" for OSIS)
|
||||
- **timeout**: Maximum execution time in seconds
|
||||
|
||||
## Rhai Script Examples
|
||||
|
||||
### Simple Calculation
|
||||
```rhai
|
||||
let result = 2 + 2;
|
||||
to_json(result)
|
||||
```
|
||||
|
||||
### String Manipulation
|
||||
```rhai
|
||||
let message = "Hello, World!";
|
||||
let upper = message.to_upper();
|
||||
to_json(upper)
|
||||
```
|
||||
|
||||
### Array Operations
|
||||
```rhai
|
||||
let numbers = [1, 2, 3, 4, 5];
|
||||
let sum = 0;
|
||||
for n in numbers {
|
||||
sum += n;
|
||||
}
|
||||
to_json(#{sum: sum, count: numbers.len()})
|
||||
```
|
||||
|
||||
### Object Creation
|
||||
```rhai
|
||||
let person = #{
|
||||
name: "Alice",
|
||||
age: 30,
|
||||
email: "alice@example.com"
|
||||
};
|
||||
to_json(person)
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Failed to connect to supervisor"
|
||||
|
||||
**Problem:** Supervisor is not running or wrong port.
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Check if supervisor is running
|
||||
curl http://localhost:3030
|
||||
|
||||
# Start supervisor
|
||||
cargo run --bin hero-supervisor -- --redis-url redis://localhost:6379
|
||||
```
|
||||
|
||||
### "Runner not found"
|
||||
|
||||
**Problem:** Runner is not registered or not running.
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Start the runner
|
||||
cargo run --bin runner_osis -- test_runner --redis-url redis://localhost:6379
|
||||
|
||||
# Check runner logs for connection issues
|
||||
```
|
||||
|
||||
### "Job execution timeout"
|
||||
|
||||
**Problem:** Job took longer than timeout value.
|
||||
|
||||
**Solution:**
|
||||
- Increase timeout in job builder: `.timeout(60)`
|
||||
- Or in job.run request: `"timeout": 60`
|
||||
|
||||
### "Redis connection failed"
|
||||
|
||||
**Problem:** Redis is not running.
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Start Redis
|
||||
redis-server
|
||||
|
||||
# Or specify custom Redis URL
|
||||
cargo run --bin hero-supervisor -- --redis-url redis://localhost:6379
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌─────────────┐
|
||||
│ Client │
|
||||
│ (Example) │
|
||||
└──────┬──────┘
|
||||
│ HTTP/JSON-RPC
|
||||
▼
|
||||
┌─────────────┐
|
||||
│ Supervisor │
|
||||
│ (Mycelium) │
|
||||
└──────┬──────┘
|
||||
│ Redis Queue
|
||||
▼
|
||||
┌─────────────┐
|
||||
│ Runner │
|
||||
│ (OSIS) │
|
||||
└─────────────┘
|
||||
```
|
||||
|
||||
### Flow
|
||||
|
||||
1. **Client** creates a job with Rhai script
|
||||
2. **Client** sends job to supervisor via JSON-RPC
|
||||
3. **Supervisor** verifies signatures (if present)
|
||||
4. **Supervisor** queues job to runner's Redis queue
|
||||
5. **Runner** picks up job from queue
|
||||
6. **Runner** executes Rhai script
|
||||
7. **Runner** stores result in Redis
|
||||
8. **Supervisor** retrieves result (for job.run)
|
||||
9. **Client** receives result
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Add signature verification to jobs (see `JOB_SIGNATURES.md`)
|
||||
- Implement job status polling for non-blocking jobs
|
||||
- Create custom Rhai functions for your use case
|
||||
- Scale with multiple runners
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- `JOB_EXECUTION.md` - Detailed job execution modes
|
||||
- `JOB_SIGNATURES.md` - Cryptographic job signing
|
||||
- `README.md` - Supervisor overview
|
||||
|
||||
---
|
||||
|
||||
**Status:** ✅ Production Ready
|
||||
**Last Updated:** 2025-10-24
|
||||
192
examples/_archive/EXAMPLES_SUMMARY.md
Normal file
192
examples/_archive/EXAMPLES_SUMMARY.md
Normal file
@@ -0,0 +1,192 @@
|
||||
# Supervisor Examples - Summary
|
||||
|
||||
## ✅ **Complete End-to-End Examples with OpenRPC Client**
|
||||
|
||||
All examples now use the official `hero-supervisor-openrpc-client` library for type-safe, async communication with the supervisor.
|
||||
|
||||
### **What Was Updated:**
|
||||
|
||||
1. **OpenRPC Client Library** (`clients/openrpc/src/lib.rs`)
|
||||
- Added `JobRunResponse` - Response from blocking `job.run`
|
||||
- Added `JobStartResponse` - Response from non-blocking `job.start`
|
||||
- Updated `job_run()` method - Now accepts timeout parameter
|
||||
- Updated `job_start()` method - Now accepts Job instead of job_id
|
||||
- Re-exports `Job` and `JobBuilder` from `runner_rust`
|
||||
|
||||
2. **Simple E2E Example** (`examples/simple_e2e.rs`)
|
||||
- Uses `SupervisorClient` from OpenRPC library
|
||||
- Clean, type-safe API calls
|
||||
- No manual JSON-RPC construction
|
||||
- Perfect for learning and testing
|
||||
|
||||
3. **Full E2E Demo** (`examples/end_to_end_demo.rs`)
|
||||
- Automated supervisor and runner spawning
|
||||
- Uses OpenRPC client throughout
|
||||
- Helper functions for common operations
|
||||
- Comprehensive test scenarios
|
||||
|
||||
### **Key Changes:**
|
||||
|
||||
**Before (Manual JSON-RPC):**
|
||||
```rust
|
||||
let request = json!({
|
||||
"jsonrpc": "2.0",
|
||||
"method": "job.run",
|
||||
"params": [{
|
||||
"secret": secret,
|
||||
"job": job,
|
||||
"timeout": 30
|
||||
}],
|
||||
"id": 1
|
||||
});
|
||||
let response = http_client.post(url).json(&request).send().await?;
|
||||
```
|
||||
|
||||
**After (OpenRPC Client):**
|
||||
```rust
|
||||
let response = client.job_run(secret, job, Some(30)).await?;
|
||||
println!("Result: {:?}", response.result);
|
||||
```
|
||||
|
||||
### **Client API:**
|
||||
|
||||
#### **Job Execution**
|
||||
|
||||
```rust
|
||||
use hero_supervisor_openrpc_client::{SupervisorClient, JobBuilder};
|
||||
|
||||
// Create client
|
||||
let client = SupervisorClient::new("http://localhost:3030")?;
|
||||
|
||||
// Register runner
|
||||
client.register_runner("admin_secret", "runner_name", "queue_name").await?;
|
||||
|
||||
// Run job (blocking - waits for result)
|
||||
let response = client.job_run("admin_secret", job, Some(60)).await?;
|
||||
// response.result contains the actual result
|
||||
|
||||
// Start job (non-blocking - returns immediately)
|
||||
let response = client.job_start("admin_secret", job).await?;
|
||||
// response.job_id for later polling
|
||||
```
|
||||
|
||||
#### **Response Types**
|
||||
|
||||
```rust
|
||||
// JobRunResponse (from job.run)
|
||||
pub struct JobRunResponse {
|
||||
pub job_id: String,
|
||||
pub status: String, // "completed"
|
||||
pub result: Option<String>, // Actual result from runner
|
||||
}
|
||||
|
||||
// JobStartResponse (from job.start)
|
||||
pub struct JobStartResponse {
|
||||
pub job_id: String,
|
||||
pub status: String, // "queued"
|
||||
}
|
||||
```
|
||||
|
||||
### **Examples Overview:**
|
||||
|
||||
| Example | Description | Use Case |
|
||||
|---------|-------------|----------|
|
||||
| `simple_e2e.rs` | Manual setup, step-by-step | Learning, testing |
|
||||
| `end_to_end_demo.rs` | Automated, comprehensive | CI/CD, integration tests |
|
||||
|
||||
### **Running the Examples:**
|
||||
|
||||
**Prerequisites:**
|
||||
```bash
|
||||
# Terminal 1: Redis
|
||||
redis-server
|
||||
|
||||
# Terminal 2: Supervisor
|
||||
cargo run --bin hero-supervisor -- --redis-url redis://localhost:6379
|
||||
|
||||
# Terminal 3: Runner
|
||||
cargo run --bin runner_osis -- test_runner --redis-url redis://localhost:6379
|
||||
```
|
||||
|
||||
**Run Simple Example:**
|
||||
```bash
|
||||
# Terminal 4
|
||||
RUST_LOG=info cargo run --example simple_e2e
|
||||
```
|
||||
|
||||
**Run Full Demo:**
|
||||
```bash
|
||||
# Only needs Redis running (spawns supervisor and runner automatically)
|
||||
RUST_LOG=info cargo run --example end_to_end_demo
|
||||
```
|
||||
|
||||
### **Benefits of OpenRPC Client:**
|
||||
|
||||
✅ **Type Safety** - Compile-time checking of requests/responses
|
||||
✅ **Async/Await** - Native Rust async support
|
||||
✅ **Error Handling** - Proper Result types with detailed errors
|
||||
✅ **Auto Serialization** - No manual JSON construction
|
||||
✅ **Documentation** - IntelliSense and type hints
|
||||
✅ **Maintainability** - Single source of truth for API
|
||||
|
||||
### **Architecture:**
|
||||
|
||||
```
|
||||
┌─────────────────┐
|
||||
│ Example Code │
|
||||
│ (simple_e2e) │
|
||||
└────────┬────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ OpenRPC Client │
|
||||
│ (typed API) │
|
||||
└────────┬────────┘
|
||||
│ JSON-RPC over HTTP
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ Supervisor │
|
||||
│ (Mycelium) │
|
||||
└────────┬────────┘
|
||||
│ Redis Queue
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ OSIS Runner │
|
||||
│ (Rhai Engine) │
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
### **Job Execution Modes:**
|
||||
|
||||
**Blocking (`job.run`):**
|
||||
- Client waits for result
|
||||
- Uses `queue_and_wait` internally
|
||||
- Returns actual result
|
||||
- Best for: CRUD, queries, short jobs
|
||||
|
||||
**Non-Blocking (`job.start`):**
|
||||
- Client returns immediately
|
||||
- Job runs in background
|
||||
- Returns job_id for polling
|
||||
- Best for: Long jobs, batch processing
|
||||
|
||||
### **Files Modified:**
|
||||
|
||||
- ✅ `clients/openrpc/src/lib.rs` - Updated client methods and response types
|
||||
- ✅ `examples/simple_e2e.rs` - Refactored to use OpenRPC client
|
||||
- ✅ `examples/end_to_end_demo.rs` - Refactored to use OpenRPC client
|
||||
- ✅ `examples/E2E_EXAMPLES.md` - Updated documentation
|
||||
- ✅ `examples/EXAMPLES_SUMMARY.md` - This file
|
||||
|
||||
### **Next Steps:**
|
||||
|
||||
1. **Add more examples** - Specific use cases (batch jobs, error handling)
|
||||
2. **Job polling** - Implement `wait_for_job()` helper
|
||||
3. **WASM support** - Browser-based examples
|
||||
4. **Signature examples** - Jobs with cryptographic signatures
|
||||
|
||||
---
|
||||
|
||||
**Status:** ✅ Complete and Production Ready
|
||||
**Last Updated:** 2025-10-24
|
||||
**Client Version:** hero-supervisor-openrpc-client 0.1.0
|
||||
182
examples/_archive/README.md
Normal file
182
examples/_archive/README.md
Normal file
@@ -0,0 +1,182 @@
|
||||
# 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.
|
||||
278
examples/_archive/end_to_end_demo.rs
Normal file
278
examples/_archive/end_to_end_demo.rs
Normal file
@@ -0,0 +1,278 @@
|
||||
//! End-to-End Demo: Supervisor + Runner + Client
|
||||
//!
|
||||
//! This example demonstrates the complete workflow:
|
||||
//! 1. Starts a supervisor with Mycelium integration
|
||||
//! 2. Starts an OSIS runner
|
||||
//! 3. Uses the supervisor client to run jobs
|
||||
//! 4. Shows both job.run (blocking) and job.start (non-blocking) modes
|
||||
//!
|
||||
//! Prerequisites:
|
||||
//! - Redis running on localhost:6379
|
||||
//!
|
||||
//! Usage:
|
||||
//! ```bash
|
||||
//! RUST_LOG=info cargo run --example end_to_end_demo
|
||||
//! ```
|
||||
|
||||
use anyhow::{Result, Context};
|
||||
use log::{info, error};
|
||||
use std::process::{Command, Child, Stdio};
|
||||
use std::time::Duration;
|
||||
use tokio::time::sleep;
|
||||
use hero_supervisor_openrpc_client::{SupervisorClient, JobBuilder};
|
||||
|
||||
/// Configuration for the demo
|
||||
struct DemoConfig {
|
||||
redis_url: String,
|
||||
supervisor_port: u16,
|
||||
runner_id: String,
|
||||
db_path: String,
|
||||
}
|
||||
|
||||
impl Default for DemoConfig {
|
||||
fn default() -> Self {
|
||||
Self {
|
||||
redis_url: "redis://localhost:6379".to_string(),
|
||||
supervisor_port: 3030,
|
||||
runner_id: "example_runner".to_string(),
|
||||
db_path: "/tmp/example_runner.db".to_string(),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Supervisor process wrapper
|
||||
struct SupervisorProcess {
|
||||
child: Child,
|
||||
}
|
||||
|
||||
impl SupervisorProcess {
|
||||
fn start(config: &DemoConfig) -> Result<Self> {
|
||||
info!("🚀 Starting supervisor on port {}...", config.supervisor_port);
|
||||
|
||||
let child = Command::new("cargo")
|
||||
.args(&[
|
||||
"run",
|
||||
"--bin",
|
||||
"hero-supervisor",
|
||||
"--",
|
||||
"--redis-url",
|
||||
&config.redis_url,
|
||||
"--port",
|
||||
&config.supervisor_port.to_string(),
|
||||
])
|
||||
.stdout(Stdio::piped())
|
||||
.stderr(Stdio::piped())
|
||||
.spawn()
|
||||
.context("Failed to start supervisor")?;
|
||||
|
||||
Ok(Self { child })
|
||||
}
|
||||
}
|
||||
|
||||
impl Drop for SupervisorProcess {
|
||||
fn drop(&mut self) {
|
||||
info!("🛑 Stopping supervisor...");
|
||||
let _ = self.child.kill();
|
||||
let _ = self.child.wait();
|
||||
}
|
||||
}
|
||||
|
||||
/// Runner process wrapper
|
||||
struct RunnerProcess {
|
||||
child: Child,
|
||||
}
|
||||
|
||||
impl RunnerProcess {
|
||||
fn start(config: &DemoConfig) -> Result<Self> {
|
||||
info!("🤖 Starting OSIS runner '{}'...", config.runner_id);
|
||||
|
||||
let child = Command::new("cargo")
|
||||
.args(&[
|
||||
"run",
|
||||
"--bin",
|
||||
"runner_osis",
|
||||
"--",
|
||||
&config.runner_id,
|
||||
"--db-path",
|
||||
&config.db_path,
|
||||
"--redis-url",
|
||||
&config.redis_url,
|
||||
])
|
||||
.env("RUST_LOG", "info")
|
||||
.stdout(Stdio::piped())
|
||||
.stderr(Stdio::piped())
|
||||
.spawn()
|
||||
.context("Failed to start runner")?;
|
||||
|
||||
Ok(Self { child })
|
||||
}
|
||||
}
|
||||
|
||||
impl Drop for RunnerProcess {
|
||||
fn drop(&mut self) {
|
||||
info!("🛑 Stopping runner...");
|
||||
let _ = self.child.kill();
|
||||
let _ = self.child.wait();
|
||||
}
|
||||
}
|
||||
|
||||
/// Helper functions for the demo
|
||||
async fn register_runner_helper(client: &SupervisorClient, runner_id: &str, secret: &str) -> Result<()> {
|
||||
info!("📝 Registering runner '{}'...", runner_id);
|
||||
|
||||
let queue = format!("hero:q:work:type:osis:group:default:inst:{}", runner_id);
|
||||
client.register_runner(secret, runner_id, &queue).await?;
|
||||
|
||||
info!("✅ Runner registered successfully");
|
||||
Ok(())
|
||||
}
|
||||
|
||||
async fn run_job_helper(client: &SupervisorClient, job: runner_rust::job::Job, secret: &str, timeout: u64) -> Result<String> {
|
||||
info!("🚀 Running job {} (blocking)...", job.id);
|
||||
|
||||
let response = client.job_run(secret, job, Some(timeout)).await?;
|
||||
|
||||
let result = response.result
|
||||
.ok_or_else(|| anyhow::anyhow!("No result in response"))?;
|
||||
|
||||
info!("✅ Job completed with result: {}", result);
|
||||
Ok(result)
|
||||
}
|
||||
|
||||
async fn start_job_helper(client: &SupervisorClient, job: runner_rust::job::Job, secret: &str) -> Result<String> {
|
||||
info!("🚀 Starting job {} (non-blocking)...", job.id);
|
||||
|
||||
let response = client.job_start(secret, job).await?;
|
||||
|
||||
info!("✅ Job queued with ID: {}", response.job_id);
|
||||
Ok(response.job_id)
|
||||
}
|
||||
|
||||
#[tokio::main]
|
||||
async fn main() -> Result<()> {
|
||||
// Initialize logging
|
||||
env_logger::Builder::from_env(env_logger::Env::default().default_filter_or("info")).init();
|
||||
|
||||
println!("\n╔════════════════════════════════════════════════════════════╗");
|
||||
println!("║ End-to-End Demo: Supervisor + Runner + Client ║");
|
||||
println!("╚════════════════════════════════════════════════════════════╝\n");
|
||||
|
||||
let config = DemoConfig::default();
|
||||
|
||||
// Step 1: Start supervisor
|
||||
println!("📋 Step 1: Starting Supervisor");
|
||||
println!("─────────────────────────────────────────────────────────────");
|
||||
let _supervisor = SupervisorProcess::start(&config)?;
|
||||
sleep(Duration::from_secs(3)).await;
|
||||
println!("✅ Supervisor started on port {}\n", config.supervisor_port);
|
||||
|
||||
// Step 2: Start runner
|
||||
println!("📋 Step 2: Starting OSIS Runner");
|
||||
println!("─────────────────────────────────────────────────────────────");
|
||||
let _runner = RunnerProcess::start(&config)?;
|
||||
sleep(Duration::from_secs(3)).await;
|
||||
println!("✅ Runner '{}' started\n", config.runner_id);
|
||||
|
||||
// Step 3: Create client and register runner
|
||||
println!("📋 Step 3: Registering Runner with Supervisor");
|
||||
println!("─────────────────────────────────────────────────────────────");
|
||||
let client = SupervisorClient::new(&format!("http://localhost:{}", config.supervisor_port))?;
|
||||
register_runner_helper(&client, &config.runner_id, "admin_secret").await?;
|
||||
println!("✅ Runner registered\n");
|
||||
|
||||
sleep(Duration::from_secs(2)).await;
|
||||
|
||||
// Step 4: Run blocking jobs (job.run)
|
||||
println!("📋 Step 4: Running Blocking Jobs (job.run)");
|
||||
println!("─────────────────────────────────────────────────────────────");
|
||||
|
||||
// Job 1: Simple calculation
|
||||
println!("\n🔹 Job 1: Simple Calculation");
|
||||
let job1 = JobBuilder::new()
|
||||
.caller_id("demo_client")
|
||||
.context_id("demo_context")
|
||||
.payload("let result = 2 + 2; to_json(result)")
|
||||
.runner(&config.runner_id)
|
||||
.executor("rhai")
|
||||
.timeout(30)
|
||||
.build()?;
|
||||
|
||||
let result1 = run_job_helper(&client, job1, "admin_secret", 30).await?;
|
||||
println!(" Result: {}", result1);
|
||||
|
||||
// Job 2: String manipulation
|
||||
println!("\n🔹 Job 2: String Manipulation");
|
||||
let job2 = JobBuilder::new()
|
||||
.caller_id("demo_client")
|
||||
.context_id("demo_context")
|
||||
.payload(r#"let msg = "Hello from OSIS Runner!"; to_json(msg)"#)
|
||||
.runner(&config.runner_id)
|
||||
.executor("rhai")
|
||||
.timeout(30)
|
||||
.build()?;
|
||||
|
||||
let result2 = run_job_helper(&client, job2, "admin_secret", 30).await?;
|
||||
println!(" Result: {}", result2);
|
||||
|
||||
// Job 3: Array operations
|
||||
println!("\n🔹 Job 3: Array Operations");
|
||||
let job3 = JobBuilder::new()
|
||||
.caller_id("demo_client")
|
||||
.context_id("demo_context")
|
||||
.payload(r#"
|
||||
let numbers = [1, 2, 3, 4, 5];
|
||||
let sum = 0;
|
||||
for n in numbers {
|
||||
sum += n;
|
||||
}
|
||||
to_json(#{sum: sum, count: numbers.len()})
|
||||
"#)
|
||||
.runner(&config.runner_id)
|
||||
.executor("rhai")
|
||||
.timeout(30)
|
||||
.build()?;
|
||||
|
||||
let result3 = run_job_helper(&client, job3, "admin_secret", 30).await?;
|
||||
println!(" Result: {}", result3);
|
||||
|
||||
println!("\n✅ All blocking jobs completed successfully\n");
|
||||
|
||||
// Step 5: Start non-blocking jobs (job.start)
|
||||
println!("📋 Step 5: Starting Non-Blocking Jobs (job.start)");
|
||||
println!("─────────────────────────────────────────────────────────────");
|
||||
|
||||
println!("\n🔹 Job 4: Background Task");
|
||||
let job4 = JobBuilder::new()
|
||||
.caller_id("demo_client")
|
||||
.context_id("demo_context")
|
||||
.payload(r#"
|
||||
let result = "Background task completed";
|
||||
to_json(result)
|
||||
"#)
|
||||
.runner(&config.runner_id)
|
||||
.executor("rhai")
|
||||
.timeout(30)
|
||||
.build()?;
|
||||
|
||||
let job4_id = start_job_helper(&client, job4, "admin_secret").await?;
|
||||
println!(" Job ID: {} (running in background)", job4_id);
|
||||
|
||||
println!("\n✅ Non-blocking job started\n");
|
||||
|
||||
// Step 6: Summary
|
||||
println!("📋 Step 6: Demo Summary");
|
||||
println!("─────────────────────────────────────────────────────────────");
|
||||
println!("✅ Supervisor: Running on port {}", config.supervisor_port);
|
||||
println!("✅ Runner: '{}' registered and processing jobs", config.runner_id);
|
||||
println!("✅ Blocking jobs: 3 completed successfully");
|
||||
println!("✅ Non-blocking jobs: 1 started");
|
||||
println!("\n🎉 Demo completed successfully!");
|
||||
|
||||
// Keep processes running for a bit to see logs
|
||||
println!("\n⏳ Keeping processes running for 5 seconds...");
|
||||
sleep(Duration::from_secs(5)).await;
|
||||
|
||||
println!("\n🛑 Shutting down...");
|
||||
|
||||
Ok(())
|
||||
}
|
||||
203
examples/_archive/simple_e2e.rs
Normal file
203
examples/_archive/simple_e2e.rs
Normal file
@@ -0,0 +1,203 @@
|
||||
//! Simple End-to-End Example
|
||||
//!
|
||||
//! A minimal example showing supervisor + runner + client workflow.
|
||||
//!
|
||||
//! Prerequisites:
|
||||
//! - Redis running on localhost:6379
|
||||
//!
|
||||
//! Usage:
|
||||
//! ```bash
|
||||
//! # Terminal 1: Start Redis
|
||||
//! redis-server
|
||||
//!
|
||||
//! # Terminal 2: Run this example
|
||||
//! RUST_LOG=info cargo run --example simple_e2e
|
||||
//! ```
|
||||
|
||||
use anyhow::Result;
|
||||
use log::info;
|
||||
use std::time::Duration;
|
||||
use tokio::time::sleep;
|
||||
use hero_supervisor_openrpc_client::{SupervisorClient, JobBuilder};
|
||||
|
||||
#[tokio::main]
|
||||
async fn main() -> Result<()> {
|
||||
env_logger::Builder::from_env(env_logger::Env::default().default_filter_or("info")).init();
|
||||
|
||||
println!("\n╔════════════════════════════════════════╗");
|
||||
println!("║ Simple End-to-End Demo ║");
|
||||
println!("╚════════════════════════════════════════╝\n");
|
||||
|
||||
let supervisor_url = "http://localhost:3030";
|
||||
let runner_id = "test_runner";
|
||||
let secret = "admin_secret";
|
||||
|
||||
// Create supervisor client
|
||||
let client = SupervisorClient::new(supervisor_url)?;
|
||||
|
||||
println!("📝 Prerequisites:");
|
||||
println!(" 1. Redis running on localhost:6379");
|
||||
println!(" 2. Supervisor running on {}", supervisor_url);
|
||||
println!(" 3. Runner '{}' registered and running\n", runner_id);
|
||||
|
||||
println!("💡 To start the supervisor:");
|
||||
println!(" cargo run --bin hero-supervisor -- --redis-url redis://localhost:6379\n");
|
||||
|
||||
println!("💡 To start a runner:");
|
||||
println!(" cd /Users/timurgordon/code/git.ourworld.tf/herocode/runner_rust");
|
||||
println!(" cargo run --bin runner_osis -- {} --redis-url redis://localhost:6379\n", runner_id);
|
||||
|
||||
println!("⏳ Waiting 3 seconds for you to start the prerequisites...\n");
|
||||
sleep(Duration::from_secs(3)).await;
|
||||
|
||||
// Register runner
|
||||
println!("📋 Step 1: Registering Runner");
|
||||
println!("─────────────────────────────────────────");
|
||||
|
||||
let queue = format!("hero:q:work:type:osis:group:default:inst:{}", runner_id);
|
||||
match client.register_runner(secret, runner_id, &queue).await {
|
||||
Ok(_) => {
|
||||
println!("✅ Runner registered successfully");
|
||||
}
|
||||
Err(e) => {
|
||||
println!("⚠️ Registration error: {} (runner might already be registered)", e);
|
||||
}
|
||||
}
|
||||
|
||||
sleep(Duration::from_secs(1)).await;
|
||||
|
||||
// Run a simple job
|
||||
println!("\n📋 Step 2: Running a Simple Job (Blocking)");
|
||||
println!("─────────────────────────────────────────");
|
||||
|
||||
let job = JobBuilder::new()
|
||||
.caller_id("simple_demo")
|
||||
.context_id("demo_context")
|
||||
.payload(r#"
|
||||
let message = "Hello from the runner!";
|
||||
let number = 42;
|
||||
to_json(#{
|
||||
message: message,
|
||||
number: number,
|
||||
timestamp: timestamp()
|
||||
})
|
||||
"#)
|
||||
.runner(runner_id)
|
||||
.executor("rhai")
|
||||
.timeout(30)
|
||||
.build()?;
|
||||
|
||||
let job_id = job.id.clone();
|
||||
info!("Sending job with ID: {}", job_id);
|
||||
|
||||
match client.job_run(secret, job, Some(30)).await {
|
||||
Ok(response) => {
|
||||
println!("✅ Job completed!");
|
||||
if let Some(result) = response.result {
|
||||
println!(" Result: {}", result);
|
||||
}
|
||||
}
|
||||
Err(e) => {
|
||||
println!("❌ Job failed: {}", e);
|
||||
return Ok(());
|
||||
}
|
||||
}
|
||||
|
||||
// Run another job (calculation)
|
||||
println!("\n📋 Step 3: Running a Calculation Job");
|
||||
println!("─────────────────────────────────────────");
|
||||
|
||||
let calc_job = JobBuilder::new()
|
||||
.caller_id("simple_demo")
|
||||
.context_id("demo_context")
|
||||
.payload(r#"
|
||||
let numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
|
||||
let sum = 0;
|
||||
let product = 1;
|
||||
|
||||
for n in numbers {
|
||||
sum += n;
|
||||
product *= n;
|
||||
}
|
||||
|
||||
to_json(#{
|
||||
sum: sum,
|
||||
product: product,
|
||||
count: numbers.len(),
|
||||
average: sum / numbers.len()
|
||||
})
|
||||
"#)
|
||||
.runner(runner_id)
|
||||
.executor("rhai")
|
||||
.timeout(30)
|
||||
.build()?;
|
||||
|
||||
let calc_job_id = calc_job.id.clone();
|
||||
info!("Sending calculation job with ID: {}", calc_job_id);
|
||||
|
||||
match client.job_run(secret, calc_job, Some(30)).await {
|
||||
Ok(response) => {
|
||||
println!("✅ Calculation completed!");
|
||||
if let Some(result) = response.result {
|
||||
println!(" Result: {}", result);
|
||||
}
|
||||
}
|
||||
Err(e) => {
|
||||
println!("❌ Calculation failed: {}", e);
|
||||
}
|
||||
}
|
||||
|
||||
// Start a non-blocking job
|
||||
println!("\n📋 Step 4: Starting a Non-Blocking Job");
|
||||
println!("─────────────────────────────────────────");
|
||||
|
||||
let async_job = JobBuilder::new()
|
||||
.caller_id("simple_demo")
|
||||
.context_id("demo_context")
|
||||
.payload(r#"
|
||||
let result = "This job was started asynchronously";
|
||||
to_json(result)
|
||||
"#)
|
||||
.runner(runner_id)
|
||||
.executor("rhai")
|
||||
.timeout(30)
|
||||
.build()?;
|
||||
|
||||
let async_job_id = async_job.id.clone();
|
||||
info!("Starting async job with ID: {}", async_job_id);
|
||||
|
||||
match client.job_start(secret, async_job).await {
|
||||
Ok(response) => {
|
||||
println!("✅ Job started!");
|
||||
println!(" Job ID: {} (running in background)", response.job_id);
|
||||
println!(" Status: {}", response.status);
|
||||
}
|
||||
Err(e) => {
|
||||
println!("❌ Failed to start job: {}", e);
|
||||
}
|
||||
}
|
||||
|
||||
// Summary
|
||||
println!("\n╔════════════════════════════════════════╗");
|
||||
println!("║ Demo Summary ║");
|
||||
println!("╚════════════════════════════════════════╝");
|
||||
println!("✅ Runner registered: {}", runner_id);
|
||||
println!("✅ Blocking jobs completed: 2");
|
||||
println!("✅ Non-blocking jobs started: 1");
|
||||
println!("\n🎉 Demo completed successfully!\n");
|
||||
|
||||
println!("📚 What happened:");
|
||||
println!(" 1. Registered a runner with the supervisor");
|
||||
println!(" 2. Sent jobs with Rhai scripts to execute");
|
||||
println!(" 3. Supervisor queued jobs to the runner");
|
||||
println!(" 4. Runner executed the scripts and returned results");
|
||||
println!(" 5. Client received results (for blocking jobs)\n");
|
||||
|
||||
println!("🔍 Key Concepts:");
|
||||
println!(" • job.run = Execute and wait for result (blocking)");
|
||||
println!(" • job.start = Start and return immediately (non-blocking)");
|
||||
println!(" • Jobs contain Rhai scripts that run on the runner");
|
||||
println!(" • Supervisor coordinates job distribution via Redis\n");
|
||||
|
||||
Ok(())
|
||||
}
|
||||
94
examples/osiris_openrpc/README.md
Normal file
94
examples/osiris_openrpc/README.md
Normal file
@@ -0,0 +1,94 @@
|
||||
# OSIRIS + OpenRPC Comprehensive Example
|
||||
|
||||
This example demonstrates the complete workflow of using Hero Supervisor with OSIRIS runners via OpenRPC.
|
||||
|
||||
## What This Example Does
|
||||
|
||||
1. **Builds and starts** Hero Supervisor with OpenRPC server enabled
|
||||
2. **Builds** the OSIRIS runner binary
|
||||
3. **Connects** an OpenRPC client to the supervisor
|
||||
4. **Registers and starts** an OSIRIS runner
|
||||
5. **Dispatches multiple jobs** via OpenRPC:
|
||||
- Create a Note
|
||||
- Create an Event
|
||||
- Query stored data
|
||||
- Test access control (expected to fail)
|
||||
6. **Monitors** job execution and results
|
||||
7. **Gracefully shuts down** all components
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Redis server running on `localhost:6379`
|
||||
- Rust toolchain installed
|
||||
- Both `supervisor` and `runner_rust` crates available
|
||||
|
||||
## Running the Example
|
||||
|
||||
```bash
|
||||
cargo run --example osiris_openrpc
|
||||
```
|
||||
|
||||
## Job Scripts
|
||||
|
||||
The example uses separate Rhai script files for each job:
|
||||
|
||||
- `note.rhai` - Creates and stores a Note object
|
||||
- `event.rhai` - Creates and stores an Event object
|
||||
- `query.rhai` - Queries and retrieves stored objects
|
||||
- `access_denied.rhai` - Tests access control (should fail)
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌─────────────────┐
|
||||
│ This Example │
|
||||
│ (OpenRPC │
|
||||
│ Client) │
|
||||
└────────┬────────┘
|
||||
│ JSON-RPC
|
||||
↓
|
||||
┌─────────────────┐
|
||||
│ Supervisor │
|
||||
│ (OpenRPC │
|
||||
│ Server) │
|
||||
└────────┬────────┘
|
||||
│ Redis Queue
|
||||
↓
|
||||
┌─────────────────┐
|
||||
│ OSIRIS Runner │
|
||||
│ (Rhai Engine │
|
||||
│ + HeroDB) │
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
## Key Features Demonstrated
|
||||
|
||||
- **Automatic binary building** using escargot
|
||||
- **OpenRPC communication** between client and supervisor
|
||||
- **Runner registration** with configuration
|
||||
- **Job dispatching** with signatories
|
||||
- **Context-based access control** in OSIRIS
|
||||
- **Typed object storage** (Note, Event)
|
||||
- **Graceful shutdown** and cleanup
|
||||
|
||||
## Expected Output
|
||||
|
||||
The example will:
|
||||
1. ✅ Create a Note successfully
|
||||
2. ✅ Create an Event successfully
|
||||
3. ✅ Query and retrieve stored objects
|
||||
4. ✅ Deny access for unauthorized participants
|
||||
5. ✅ Clean up all resources
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Redis Connection Error:**
|
||||
- Ensure Redis is running: `redis-server`
|
||||
|
||||
**Build Errors:**
|
||||
- Ensure both supervisor and runner_rust crates are available
|
||||
- Check that all dependencies are up to date
|
||||
|
||||
**OpenRPC Connection Error:**
|
||||
- Port 3030 might be in use
|
||||
- Check supervisor logs for startup issues
|
||||
8
examples/osiris_openrpc/access_denied.rhai
Normal file
8
examples/osiris_openrpc/access_denied.rhai
Normal file
@@ -0,0 +1,8 @@
|
||||
print("Attempting to access context with non-signatories...");
|
||||
print("Participants: [dave, eve]");
|
||||
print("Signatories: [alice, bob, charlie]");
|
||||
|
||||
// This should fail because neither dave nor eve are signatories
|
||||
let ctx = get_context(["dave", "eve"]);
|
||||
|
||||
"This should not succeed!"
|
||||
18
examples/osiris_openrpc/event.rhai
Normal file
18
examples/osiris_openrpc/event.rhai
Normal file
@@ -0,0 +1,18 @@
|
||||
print("Creating context for [alice, bob]...");
|
||||
let ctx = get_context(["alice", "bob"]);
|
||||
print("✓ Context ID: " + ctx.context_id());
|
||||
|
||||
print("\nCreating event...");
|
||||
let event = event("events")
|
||||
.title("Team Retrospective")
|
||||
.description("Review what went well and areas for improvement")
|
||||
.location("Virtual - Zoom Room A")
|
||||
.category("retrospective");
|
||||
|
||||
print("✓ Event created");
|
||||
|
||||
print("\nStoring event in context...");
|
||||
ctx.save(event);
|
||||
print("✓ Event stored");
|
||||
|
||||
"Event 'Team Retrospective' created and stored successfully"
|
||||
239
examples/osiris_openrpc/main.rs
Normal file
239
examples/osiris_openrpc/main.rs
Normal file
@@ -0,0 +1,239 @@
|
||||
///! Comprehensive OSIRIS + OpenRPC Example
|
||||
///!
|
||||
///! This example demonstrates:
|
||||
///! 1. Starting a Hero Supervisor with OpenRPC server
|
||||
///! 2. Starting an OSIRIS runner
|
||||
///! 3. Registering the runner with the supervisor
|
||||
///! 4. Dispatching multiple OSIRIS jobs via OpenRPC
|
||||
///! 5. Monitoring job execution
|
||||
///! 6. Graceful shutdown
|
||||
///!
|
||||
///! Usage:
|
||||
///! ```bash
|
||||
///! cargo run --example osiris_openrpc
|
||||
///! ```
|
||||
|
||||
use hero_supervisor_openrpc_client::{SupervisorClient, RunnerConfig, JobBuilder};
|
||||
use std::time::Duration;
|
||||
use escargot::CargoBuild;
|
||||
use std::process::Stdio;
|
||||
use tokio::time::sleep;
|
||||
|
||||
#[tokio::main]
|
||||
async fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||||
println!("🚀 OSIRIS + OpenRPC Comprehensive Example");
|
||||
println!("=========================================\n");
|
||||
|
||||
// ========================================================================
|
||||
// STEP 1: Build and start supervisor with OpenRPC
|
||||
// ========================================================================
|
||||
println!("Step 1: Building and starting supervisor");
|
||||
println!("─────────────────────────────────────────────────────────────\n");
|
||||
|
||||
let supervisor_binary = CargoBuild::new()
|
||||
.bin("supervisor")
|
||||
.current_release()
|
||||
.manifest_path("../supervisor/Cargo.toml")
|
||||
.run()?;
|
||||
|
||||
println!("✅ Supervisor binary built");
|
||||
|
||||
let mut supervisor = supervisor_binary.command()
|
||||
.arg("--redis-url")
|
||||
.arg("redis://localhost:6379")
|
||||
.arg("--openrpc")
|
||||
.arg("--openrpc-port")
|
||||
.arg("3030")
|
||||
.stdout(Stdio::piped())
|
||||
.stderr(Stdio::piped())
|
||||
.spawn()?;
|
||||
|
||||
println!("✅ Supervisor started on port 3030");
|
||||
sleep(Duration::from_secs(2)).await;
|
||||
|
||||
// ========================================================================
|
||||
// STEP 2: Build OSIRIS runner
|
||||
// ========================================================================
|
||||
println!("\nStep 2: Building OSIRIS runner");
|
||||
println!("─────────────────────────────────────────────────────────────\n");
|
||||
|
||||
let runner_binary = CargoBuild::new()
|
||||
.bin("runner_osiris")
|
||||
.current_release()
|
||||
.manifest_path("../runner_rust/Cargo.toml")
|
||||
.run()?;
|
||||
|
||||
println!("✅ OSIRIS runner binary built");
|
||||
|
||||
// ========================================================================
|
||||
// STEP 3: Connect OpenRPC client
|
||||
// ========================================================================
|
||||
println!("\nStep 3: Connecting OpenRPC client");
|
||||
println!("─────────────────────────────────────────────────────────────\n");
|
||||
|
||||
let client = SupervisorClient::new("http://127.0.0.1:3030")?;
|
||||
println!("✅ Connected to supervisor\n");
|
||||
|
||||
// ========================================================================
|
||||
// STEP 4: Register and start OSIRIS runner
|
||||
// ========================================================================
|
||||
println!("Step 4: Registering OSIRIS runner");
|
||||
println!("─────────────────────────────────────────────────────────────\n");
|
||||
|
||||
let runner_path = runner_binary.path().to_string_lossy();
|
||||
let db_path = "/tmp/osiris_openrpc.db";
|
||||
|
||||
let command = format!(
|
||||
"{} osiris_runner --db-path {} --redis-url redis://localhost:6379",
|
||||
runner_path, db_path
|
||||
);
|
||||
|
||||
let runner_config = RunnerConfig {
|
||||
name: "osiris_runner".to_string(),
|
||||
command,
|
||||
env: None,
|
||||
};
|
||||
|
||||
client.add_runner("admin_secret", runner_config).await?;
|
||||
println!("✅ Runner registered: osiris_runner");
|
||||
|
||||
client.start_runner("admin_secret", "osiris_runner").await?;
|
||||
println!("✅ Runner started\n");
|
||||
|
||||
sleep(Duration::from_secs(2)).await;
|
||||
|
||||
// ========================================================================
|
||||
// STEP 5: Load job scripts
|
||||
// ========================================================================
|
||||
println!("Step 5: Loading job scripts");
|
||||
println!("─────────────────────────────────────────────────────────────\n");
|
||||
|
||||
let note_script = std::fs::read_to_string("examples/osiris_openrpc/note.rhai")?;
|
||||
let event_script = std::fs::read_to_string("examples/osiris_openrpc/event.rhai")?;
|
||||
let query_script = std::fs::read_to_string("examples/osiris_openrpc/query.rhai")?;
|
||||
let access_denied_script = std::fs::read_to_string("examples/osiris_openrpc/access_denied.rhai")?;
|
||||
|
||||
println!("✅ Loaded 4 job scripts\n");
|
||||
|
||||
// ========================================================================
|
||||
// STEP 6: Dispatch jobs via OpenRPC
|
||||
// ========================================================================
|
||||
println!("Step 6: Dispatching jobs");
|
||||
println!("─────────────────────────────────────────────────────────────\n");
|
||||
|
||||
// Job 1: Create Note
|
||||
println!("📝 Job 1: Creating Note...");
|
||||
let job1 = JobBuilder::new()
|
||||
.caller_id("openrpc_client")
|
||||
.context_id("osiris_demo")
|
||||
.payload(¬e_script)
|
||||
.runner("osiris_runner")
|
||||
.executor("rhai")
|
||||
.timeout(30)
|
||||
.signature("alice", "")
|
||||
.signature("bob", "")
|
||||
.build()?;
|
||||
|
||||
let job1_result = client.run_job("user_secret", job1).await;
|
||||
|
||||
match job1_result {
|
||||
Ok(result) => println!("✅ {:?}\n", result),
|
||||
Err(e) => println!("❌ Job failed: {}\n", e),
|
||||
}
|
||||
|
||||
sleep(Duration::from_secs(1)).await;
|
||||
|
||||
// Job 2: Create Event
|
||||
println!("📅 Job 2: Creating Event...");
|
||||
let job2 = JobBuilder::new()
|
||||
.caller_id("openrpc_client")
|
||||
.context_id("osiris_demo")
|
||||
.payload(&event_script)
|
||||
.runner("osiris_runner")
|
||||
.executor("rhai")
|
||||
.timeout(30)
|
||||
.signature("alice", "")
|
||||
.signature("bob", "")
|
||||
.build()?;
|
||||
|
||||
let job2_result = client.run_job("user_secret", job2).await;
|
||||
|
||||
match job2_result {
|
||||
Ok(result) => println!("✅ {:?}\n", result),
|
||||
Err(e) => println!("❌ Job failed: {}\n", e),
|
||||
}
|
||||
|
||||
sleep(Duration::from_secs(1)).await;
|
||||
|
||||
// Job 3: Query Data
|
||||
println!("🔍 Job 3: Querying Data...");
|
||||
let job3 = JobBuilder::new()
|
||||
.caller_id("openrpc_client")
|
||||
.context_id("osiris_demo")
|
||||
.payload(&query_script)
|
||||
.runner("osiris_runner")
|
||||
.executor("rhai")
|
||||
.timeout(30)
|
||||
.signature("alice", "")
|
||||
.signature("bob", "")
|
||||
.signature("charlie", "")
|
||||
.build()?;
|
||||
|
||||
let job3_result = client.run_job("user_secret", job3).await;
|
||||
|
||||
match job3_result {
|
||||
Ok(result) => println!("✅ {:?}\n", result),
|
||||
Err(e) => println!("❌ Job failed: {}\n", e),
|
||||
}
|
||||
|
||||
sleep(Duration::from_secs(1)).await;
|
||||
|
||||
// Job 4: Access Control Test (should fail)
|
||||
println!("🔒 Job 4: Testing Access Control (expected to fail)...");
|
||||
let job4 = JobBuilder::new()
|
||||
.caller_id("openrpc_client")
|
||||
.context_id("osiris_demo")
|
||||
.payload(&access_denied_script)
|
||||
.runner("osiris_runner")
|
||||
.executor("rhai")
|
||||
.timeout(30)
|
||||
.signature("alice", "")
|
||||
.signature("bob", "")
|
||||
.signature("charlie", "")
|
||||
.build()?;
|
||||
|
||||
let job4_result = client.run_job("user_secret", job4).await;
|
||||
|
||||
match job4_result {
|
||||
Ok(result) => println!("❌ Unexpected success: {:?}\n", result),
|
||||
Err(e) => println!("✅ Access denied as expected: {}\n", e),
|
||||
}
|
||||
|
||||
// ========================================================================
|
||||
// STEP 7: Check runner status
|
||||
// ========================================================================
|
||||
println!("\nStep 7: Checking runner status");
|
||||
println!("─────────────────────────────────────────────────────────────\n");
|
||||
|
||||
let status = client.get_runner_status("admin_secret", "osiris_runner").await?;
|
||||
println!("Runner status: {:?}\n", status);
|
||||
|
||||
// ========================================================================
|
||||
// STEP 8: Cleanup
|
||||
// ========================================================================
|
||||
println!("Step 8: Cleanup");
|
||||
println!("─────────────────────────────────────────────────────────────\n");
|
||||
|
||||
client.stop_runner("admin_secret", "osiris_runner", false).await?;
|
||||
println!("✅ Runner stopped");
|
||||
|
||||
client.remove_runner("admin_secret", "osiris_runner").await?;
|
||||
println!("✅ Runner removed");
|
||||
|
||||
supervisor.kill()?;
|
||||
println!("✅ Supervisor stopped");
|
||||
|
||||
println!("\n✨ Example completed successfully!");
|
||||
|
||||
Ok(())
|
||||
}
|
||||
20
examples/osiris_openrpc/note.rhai
Normal file
20
examples/osiris_openrpc/note.rhai
Normal file
@@ -0,0 +1,20 @@
|
||||
print("Creating context for [alice, bob]...");
|
||||
let ctx = get_context(["alice", "bob"]);
|
||||
print("✓ Context ID: " + ctx.context_id());
|
||||
|
||||
print("\nCreating note...");
|
||||
let note = note("notes")
|
||||
.title("Sprint Planning Meeting")
|
||||
.content("Discussed Q1 2025 roadmap and milestones")
|
||||
.tag("sprint", "2025-Q1")
|
||||
.tag("team", "engineering")
|
||||
.tag("priority", "high")
|
||||
.mime("text/markdown");
|
||||
|
||||
print("✓ Note created");
|
||||
|
||||
print("\nStoring note in context...");
|
||||
ctx.save(note);
|
||||
print("✓ Note stored");
|
||||
|
||||
"Note 'Sprint Planning Meeting' created and stored successfully"
|
||||
21
examples/osiris_openrpc/query.rhai
Normal file
21
examples/osiris_openrpc/query.rhai
Normal file
@@ -0,0 +1,21 @@
|
||||
print("Querying context [alice, bob]...");
|
||||
let ctx = get_context(["alice", "bob"]);
|
||||
print("✓ Context ID: " + ctx.context_id());
|
||||
|
||||
print("\nListing all notes...");
|
||||
let notes = ctx.list("notes");
|
||||
print("✓ Found " + notes.len() + " note(s)");
|
||||
|
||||
print("\nRetrieving specific note...");
|
||||
let note = ctx.get("notes", "sprint_planning_001");
|
||||
print("✓ Retrieved note: sprint_planning_001");
|
||||
|
||||
print("\nQuerying context [alice, bob, charlie]...");
|
||||
let ctx2 = get_context(["alice", "bob", "charlie"]);
|
||||
print("✓ Context ID: " + ctx2.context_id());
|
||||
|
||||
print("\nListing all events...");
|
||||
let events = ctx2.list("events");
|
||||
print("✓ Found " + events.len() + " event(s)");
|
||||
|
||||
"Query complete: Found " + notes.len() + " notes and " + events.len() + " events"
|
||||
Reference in New Issue
Block a user