supervisor/README.md

# 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

```rust
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
```toml
[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

```bash
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
```bash
# 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
```bash
cargo test --all-features
```

### Running
```bash
# 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](docs/QUICK_START.md)** - Get started with Hero Supervisor
- **[Authentication](docs/AUTH.md)** - Secret-based authentication system
- **[Job API Convention](docs/job-api-convention.md)** - Job submission and management API
- **[Mycelium Integration](docs/MYCELIUM.md)** - Optional Mycelium network support
- **[Restructure Notes](docs/RESTRUCTURE.md)** - Repository restructuring details
- **[Test Keypairs](docs/test_keypairs.md)** - Testing with authentication

## License

MIT OR Apache-2.0