Hero Supervisor

A Rust-based actor management system for the Hero ecosystem that provides unified process management, job queuing, and optional OpenRPC server integration.

Repository Structure

supervisor/
├── core/              # Main supervisor library and binary
│   ├── src/
│   │   ├── bin/supervisor.rs  # Supervisor binary
│   │   └── lib.rs             # Library exports
│   ├── examples/              # Usage examples
│   └── tests/                 # Integration tests
├── client/            # OpenRPC client library (Rust + WASM)
├── ui/                # Admin UI (Yew WASM application)
└── docs/              # Documentation

## Features

The crate uses Rust's feature system to provide conditional compilation:

- **`default`**: Includes CLI functionality
- **`cli`**: Enables the supervisor binary (included in default)

All OpenRPC functionality is now included by default for simplified deployment.

## Architecture

The Hero Supervisor uses a clean, simplified architecture with centralized resource management:

### Core Components

#### `SupervisorBuilder` → `Supervisor` → `SupervisorApp`
- **`SupervisorBuilder`**: Configures Redis URL, namespace, secrets, runners, and process manager
- **`Supervisor`**: Core engine that owns Redis client and process manager, manages runners centrally
- **`SupervisorApp`**: Main application that wraps supervisor and provides `start()` method for complete lifecycle management

### Key Design Decisions

- **Centralized Resources**: Supervisor exclusively owns Redis client and process manager (no per-runner instances)
- **Builder Pattern**: Flexible configuration through `SupervisorBuilder` with method chaining
- **Direct OpenRPC Integration**: RPC trait implemented directly on `Arc<Mutex<Supervisor>>` (no wrapper layers)
- **Simplified App**: `SupervisorApp::start()` handles everything - runners, OpenRPC server, graceful shutdown


## Usage

### Running the Supervisor Binary

```bash
# Run with default (error) logging
cargo run --bin supervisor

# Run with info logging
RUST_LOG=info cargo run --bin supervisor

# Run with debug logging  
RUST_LOG=debug cargo run --bin supervisor

# Run with trace logging (very verbose)
RUST_LOG=trace cargo run --bin supervisor

# Run with specific module logging
RUST_LOG=hero_supervisor=debug cargo run --bin supervisor

Library Usage

use hero_supervisor::{SupervisorBuilder, SupervisorApp};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Build supervisor with configuration
    let supervisor = SupervisorBuilder::new()
        .redis_url("redis://localhost:6379")
        .namespace("hero")
        .build()
        .await?;
    
    // Create and start the complete application
    let mut app = SupervisorApp::new(supervisor);
    app.start().await?;
    
    Ok(())
}

As a Dependency

[dependencies]
hero-supervisor = "0.1.0"

OpenRPC Server

The supervisor automatically starts an OpenRPC server on 127.0.0.1:3030 that exposes all supervisor functionality via JSON-RPC.

Available Methods

• add_runner - Add a new actor/runner
• remove_runner - Remove an actor/runner
• list_runners - List all runner IDs
• start_runner - Start a specific runner
• stop_runner - Stop a specific runner
• get_runner_status - Get status of a specific runner
• get_runner_logs - Get logs for a specific runner
• queue_job_to_runner - Queue a job to a specific runner
• get_all_runner_status - Get status of all runners
• start_all - Start all runners
• stop_all - Stop all runners
• get_all_status - Get status summary for all runners

Example JSON-RPC Call

curl -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"list_runners","id":1}' \
  http://127.0.0.1:3030

Development

Building

# Build everything (default includes CLI and OpenRPC)
cargo build

# Library only (minimal build)
cargo build --no-default-features

# With CLI (same as default)
cargo build --features cli

Testing

cargo test --all-features

Running

# Start supervisor with OpenRPC server
RUST_LOG=info cargo run --features openrpc

Dependencies

Core Dependencies

• tokio - Async runtime
• redis - Redis client for job queuing
• serde - Serialization
• log - Logging
• sal-service-manager - Process management

Feature-Gated Dependencies

• jsonrpsee - JSON-RPC server (openrpc feature)
• anyhow - Error handling (openrpc feature)

Architecture Benefits

1. No Cyclic Dependencies: Library and OpenRPC server are in the same crate, eliminating dependency cycles
2. Feature-Gated: CLI and server functionality only compiled when needed
3. Clean Separation: Library can be used independently without CLI dependencies
4. Conditional Compilation: Rust's feature system ensures minimal dependencies for library users
5. Single Binary: One supervisor binary with optional OpenRPC server integration

Documentation

• Quick Start Guide - Get started with Hero Supervisor
• Authentication - Secret-based authentication system
• Job API Convention - Job submission and management API
• Mycelium Integration - Optional Mycelium network support
• Restructure Notes - Repository restructuring details
• Test Keypairs - Testing with authentication

License

MIT OR Apache-2.0