182 lines
4.3 KiB
Markdown
182 lines
4.3 KiB
Markdown
# Hero Runner
|
|
|
|
A specialized runner for the Hero ecosystem that executes heroscripts using the `hero` CLI tool.
|
|
|
|
## Overview
|
|
|
|
The Hero runner executes heroscripts by piping the payload to `hero run -s` via stdin for each job. This makes it ideal for:
|
|
|
|
- Running heroscripts from job payloads
|
|
- Executing Hero automation tasks (e.g., `!!git.list`, `!!docker.start`)
|
|
- Integrating with the Hero CLI ecosystem
|
|
- Running scripted workflows
|
|
|
|
## Features
|
|
|
|
- **Heroscript Execution**: Pipes payload to `hero run -s` via stdin (no temp files)
|
|
- **Environment Variables**: Passes job environment variables to the hero command
|
|
- **Timeout Support**: Respects job timeout settings
|
|
- **Signature Verification**: Verifies job signatures before execution
|
|
- **Simple Integration**: No complex payload parsing - just pass the heroscript content
|
|
|
|
## Usage
|
|
|
|
### Starting the Runner
|
|
|
|
```bash
|
|
# Basic usage
|
|
herorunner my-hero-runner
|
|
|
|
# With custom Redis URL
|
|
herorunner my-hero-runner --redis-url redis://localhost:6379
|
|
```
|
|
|
|
### Command-line Options
|
|
|
|
- `runner_id`: Runner identifier (required, positional)
|
|
- `-r, --redis-url`: Redis URL (default: `redis://localhost:6379`)
|
|
|
|
## Job Payload Format
|
|
|
|
The job payload should contain the heroscript content. The runner will pipe it directly to `hero run -s` via stdin.
|
|
|
|
### Example Payloads
|
|
|
|
**Simple print:**
|
|
```
|
|
print("Hello from heroscript!")
|
|
```
|
|
|
|
**Hero actions:**
|
|
```
|
|
!!git.list
|
|
```
|
|
|
|
**Multi-line script:**
|
|
```
|
|
!!git.list
|
|
print("Repositories listed")
|
|
!!docker.ps
|
|
```
|
|
|
|
The runner executes: `echo "<payload>" | hero run -s`
|
|
|
|
## Examples
|
|
|
|
### Example 1: Simple Heroscript
|
|
|
|
Job payload:
|
|
```
|
|
print("Processing job...")
|
|
```
|
|
|
|
Executed as: `hero run -h 'print("Processing job...")'`
|
|
|
|
### Example 2: Multi-line Heroscript
|
|
|
|
Job payload:
|
|
```
|
|
print("Starting task...")
|
|
// Your heroscript logic here
|
|
print("Task completed!")
|
|
```
|
|
|
|
### Example 3: With Environment Variables
|
|
|
|
Job with env_vars:
|
|
```json
|
|
{
|
|
"payload": "print(env.MY_VAR)",
|
|
"env_vars": {
|
|
"MY_VAR": "Hello from Hero Runner"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Architecture
|
|
|
|
The Hero runner implements the `Runner` trait from `hero-runner` library:
|
|
|
|
```
|
|
┌─────────────────────┐
|
|
│ HeroExecutor │
|
|
│ │
|
|
│ - execute_command()│
|
|
│ - process_job() │
|
|
└─────────────────────┘
|
|
│
|
|
│ implements
|
|
▼
|
|
┌─────────────────────┐
|
|
│ Runner Trait │
|
|
│ │
|
|
│ - spawn() │
|
|
│ - process_job() │
|
|
│ - runner_type() │
|
|
└─────────────────────┘
|
|
│
|
|
│ executes
|
|
▼
|
|
┌─────────────────────┐
|
|
│ hero run -h │
|
|
│ <heroscript> │
|
|
└─────────────────────┘
|
|
```
|
|
|
|
## Security Considerations
|
|
|
|
1. **Heroscript Execution**: The runner executes heroscripts via the `hero` CLI. Ensure job payloads are from trusted sources.
|
|
2. **Signature Verification**: Always verify job signatures before execution.
|
|
3. **Environment Variables**: Be cautious with sensitive data in environment variables.
|
|
4. **Hero CLI Access**: Ensure the `hero` command is available in the system PATH.
|
|
|
|
## Error Handling
|
|
|
|
The runner handles various error scenarios:
|
|
|
|
- **Hero CLI Not Found**: Returns error if the `hero` command is not available
|
|
- **Timeout**: Kills the process if it exceeds the job timeout
|
|
- **Non-zero Exit**: Returns error if `hero run -h` exits with non-zero status
|
|
- **Heroscript Errors**: Returns error output from the hero CLI
|
|
|
|
## Logging
|
|
|
|
The runner logs to stdout/stderr with the following log levels:
|
|
|
|
- `INFO`: Job start/completion, runner lifecycle
|
|
- `DEBUG`: Command details, parsing information
|
|
- `ERROR`: Execution failures, timeout errors
|
|
|
|
## Integration with Supervisor
|
|
|
|
The Vlang runner integrates with the Hero Supervisor:
|
|
|
|
1. Register the runner with the supervisor
|
|
2. Supervisor queues jobs to the runner's Redis queue
|
|
3. Runner polls the queue and executes commands
|
|
4. Results are stored back in Redis
|
|
|
|
## Development
|
|
|
|
### Building
|
|
|
|
```bash
|
|
cargo build -p runner-hero
|
|
```
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
cargo test -p runner-hero
|
|
```
|
|
|
|
### Running Locally
|
|
|
|
```bash
|
|
cargo run -p runner-hero -- test-runner
|
|
```
|
|
|
|
## License
|
|
|
|
MIT OR Apache-2.0
|