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:
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
|
||||
Reference in New Issue
Block a user