horus/lib/clients/supervisor/README.md

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:

[dependencies]
hero-supervisor-openrpc-client = "0.1.0"
tokio = { version = "1.0", features = ["full"] }

Quick Start

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

let client = SupervisorClient::new("http://127.0.0.1:3030")?;

Runner Management

// 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

// 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

// 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:

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.