# 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, JobBuilder};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a client with admin secret
    let client = SupervisorClient::new("http://127.0.0.1:3030", "your-admin-secret")?;
    
    // Register a runner (runner must be started externally)
    client.register_runner("admin-secret", "my_runner").await?;
    
    // Create and run a job
    let job = JobBuilder::new()
        .caller_id("my_client")
        .context_id("example_context")
        .payload("echo 'Hello from Hero Supervisor!'")
        .executor("bash")
        .runner("my_runner")
        .timeout(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
// Register a runner
client.register_runner("admin-secret", "my_runner").await?;

// Remove a runner
client.remove_runner("admin-secret", "my_runner").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("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

### Runner Management

Runners are expected to be started and managed externally. The supervisor only tracks which runners are registered and queues jobs to them via Redis.

### 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.