# Supervisor

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 API keys. API keys are scoped to grant one of three levels of access: Admin, Registrar (can register runners), User (can dispatch jobs).

Jobs contain scripts, environment variables, an identifier of the runner to execute the script, and signatures. The supervisor verifies the signatures, however access control based on who the signatories of a script is handled by the runner logic.

**Note:** Runners are expected to be started and managed externally. The supervisor only tracks which runners are registered and queues jobs to them via Redis.

## Usage

The supervisor needs an admin key to be configured to get started.
`cargo run -- --admin-secret <SECRET>`

You can also use the run script which uses the `.env` file to get the admin key.
`./scripts/run.sh`

The scripts directory also offers other scripts for building testing etc.

## Functionality

Beyond job dispatching, the supervisor provides:
- **API Key Management**: Create, list, and remove API keys with different permission scopes
- **Runner Registration**: Register runners so the supervisor knows which queues are available
- **Job Lifecycle**: Create, start, stop, and monitor jobs
- **Job Queuing**: Queue jobs to specific runners via Redis

Runner registration simply means the supervisor becomes aware that a certain runner is listening to its queue. The full API specification can be seen in `docs/openrpc.json`.

## OpenRPC

### Server

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


### 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
```