initial commit

clients/openrpc/README.md

@@ -0,0 +1,196 @@
+# Hero Supervisor OpenRPC Client
+
+A Rust client library for interacting with the Hero Supervisor OpenRPC server. This crate provides a simple, async interface for managing actors and jobs remotely.
+
+## Features
+
+- **Async API**: Built on `tokio` and `jsonrpsee` for high-performance async operations
+- **Type Safety**: Full Rust type safety with serde serialization/deserialization
+- **Job Builder**: Fluent API for creating jobs with validation
+- **Comprehensive Coverage**: All supervisor operations available via client
+- **Error Handling**: Detailed error types with proper error propagation
+
+## Installation
+
+Add this to your `Cargo.toml`:
+
+```toml
+[dependencies]
+hero-supervisor-openrpc-client = "0.1.0"
+tokio = { version = "1.0", features = ["full"] }
+```
+
+## Quick Start
+
+```rust
+use hero_supervisor_openrpc_client::{
+    SupervisorClient, RunnerConfig, RunnerType, ProcessManagerType, JobBuilder, JobType
+};
+use std::path::PathBuf;
+use std::time::Duration;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // Create a client
+    let client = SupervisorClient::new("http://127.0.0.1:3030")?;
+    
+    // Add a runner
+    let config = RunnerConfig {
+        actor_id: "my_actor".to_string(),
+        runner_type: RunnerType::OSISRunner,
+        binary_path: PathBuf::from("/path/to/actor/binary"),
+        db_path: "/path/to/db".to_string(),
+        redis_url: "redis://localhost:6379".to_string(),
+    };
+    
+    client.add_runner(config, ProcessManagerType::Simple).await?;
+    
+    // Start the runner
+    client.start_runner("my_actor").await?;
+    
+    // Create and queue a job
+    let job = JobBuilder::new()
+        .caller_id("my_client")
+        .context_id("example_context")
+        .payload("print('Hello from Hero Supervisor!');")
+        .job_type(JobType::OSIS)
+        .runner_name("my_actor")
+        .timeout(Duration::from_secs(60))
+        .build()?;
+    
+    client.queue_job_to_runner("my_actor", job).await?;
+    
+    // Check runner status
+    let status = client.get_runner_status("my_actor").await?;
+    println!("Runner status: {:?}", status);
+    
+    // List all runners
+    let runners = client.list_runners().await?;
+    println!("Active runners: {:?}", runners);
+    
+    Ok(())
+}
+```
+
+## API Reference
+
+### Client Creation
+
+```rust
+let client = SupervisorClient::new("http://127.0.0.1:3030")?;
+```
+
+### Runner Management
+
+```rust
+// Add a runner
+client.add_runner(config, ProcessManagerType::Simple).await?;
+
+// Remove a runner
+client.remove_runner("actor_id").await?;
+
+// List all runners
+let runners = client.list_runners().await?;
+
+// Start/stop runners
+client.start_runner("actor_id").await?;
+client.stop_runner("actor_id", false).await?; // force = false
+
+// Get runner status
+let status = client.get_runner_status("actor_id").await?;
+
+// Get runner logs
+let logs = client.get_runner_logs("actor_id", Some(100), false).await?;
+```
+
+### Job Management
+
+```rust
+// Create a job using the builder
+let job = JobBuilder::new()
+    .caller_id("client_id")
+    .context_id("context_id")
+    .payload("script_content")
+    .job_type(JobType::OSIS)
+    .runner_name("target_actor")
+    .timeout(Duration::from_secs(300))
+    .env_var("KEY", "value")
+    .build()?;
+
+// Queue the job
+client.queue_job_to_runner("actor_id", job).await?;
+```
+
+### Bulk Operations
+
+```rust
+// Start all runners
+let results = client.start_all().await?;
+
+// Stop all runners
+let results = client.stop_all(false).await?; // force = false
+
+// Get status of all runners
+let statuses = client.get_all_runner_status().await?;
+```
+
+## Types
+
+### RunnerType
+
+- `SALRunner` - System abstraction layer operations
+- `OSISRunner` - Operating system interface operations  
+- `VRunner` - Virtualization operations
+- `PyRunner` - Python-based actors
+
+### JobType
+
+- `SAL` - SAL job type
+- `OSIS` - OSIS job type
+- `V` - V job type
+- `Python` - Python job type
+
+### ProcessManagerType
+
+- `Simple` - Direct process spawning
+- `Tmux(String)` - Tmux session-based management
+
+### ProcessStatus
+
+- `Running` - Process is active
+- `Stopped` - Process is stopped
+- `Failed` - Process failed
+- `Unknown` - Status unknown
+
+## Error Handling
+
+The client uses the `ClientError` enum for error handling:
+
+```rust
+use hero_supervisor_openrpc_client::ClientError;
+
+match client.start_runner("actor_id").await {
+    Ok(()) => println!("Runner started successfully"),
+    Err(ClientError::JsonRpc(e)) => println!("JSON-RPC error: {}", e),
+    Err(ClientError::Server { message }) => println!("Server error: {}", message),
+    Err(e) => println!("Other error: {}", e),
+}
+```
+
+## Examples
+
+See the `examples/` directory for complete usage examples:
+
+- `basic_client.rs` - Basic client usage
+- `job_management.rs` - Job creation and management
+- `runner_lifecycle.rs` - Complete runner lifecycle management
+
+## Requirements
+
+- Rust 1.70+
+- Hero Supervisor server running with OpenRPC feature enabled
+- Network access to the supervisor server
+
+## License
+
+Licensed under either of Apache License, Version 2.0 or MIT license at your option.