herocode/supervisor
Archived
14
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update readme

Browse Source
This commit is contained in:
Timur Gordon
2025-11-12 12:15:46 +01:00
parent 285199edac
commit 4b516d9d7e
1 changed files with 14 additions and 156 deletions
Download Patch File Download Diff File Expand all files Collapse all files

170
README.md
View File

@@ -1,116 +1,29 @@
# Hero Supervisor # Supervisor
A Rust-based actor management system for the Hero ecosystem that provides unified process management, job queuing, and optional OpenRPC server integration. A job execution supervisor that queues jobs to runners over redis and returns their output. It provides an OpenRPC server for remote job dispatching. The openrpc server requires authorization via a shared secret key. Secret keys are scoped to grant one of three levels of access: Admin, Registrar (can register runners), User (can use supervisor).
## 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
Jobs contain scripts, some env vars, an identifier of the runner to execute the script and signatures. The supervisor also verifies the signatures, however access control based on who the signatories of a script is handled by the runner logic.
## Usage ## Usage
### Running the Supervisor Binary The supervisor needs an admin key to be configured to get started.
`cargo run -- --admin-secret <SECRET>`
```bash You can also use the run script which uses the `.env` file to get the admin key.
# Run with default (error) logging `./scripts/run.sh`
cargo run --bin supervisor
# Run with info logging The scripts directory also offers other scripts for building testing etc.
RUST_LOG=info cargo run --bin supervisor
# Run with debug logging ## Functionality
RUST_LOG=debug cargo run --bin supervisor
# Run with trace logging (very verbose) Beyond the job functionality, the supervisor also provides functionality for managing keys and registering runners. Runner registration simply means the supervisor becomes aware that a certain runner is being run and listening to it's queue. The The full spec can be seen in `openrpc.json`.
RUST_LOG=trace cargo run --bin supervisor
# Run with specific module logging ## OpenRPC
RUST_LOG=hero_supervisor=debug cargo run --bin supervisor
```
### Library Usage ### Server
```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. 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 ### Example JSON-RPC Call
@@ -120,61 +33,6 @@ curl -X POST -H "Content-Type: application/json" \
http://127.0.0.1:3030 http://127.0.0.1:3030
``` ```
## Development ### Client
### Building The repository also offers OpenRPC Client for supervisor compatible with WASM targets as well.
```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