124 lines
2.8 KiB
Markdown
124 lines
2.8 KiB
Markdown
# Supervisor Prototype
|
|
|
|
Supervisor je prvý funkčný prototyp ako jedna Go aplikácia s embednutým Vue frontendom.
|
|
|
|
## Čo projekt robí
|
|
|
|
- spúšťa paralelné externé konzolové procesy v PTY session
|
|
- session bežia ďalej nezávisle od pripojeného browsera
|
|
- streamuje live terminál výstup cez WebSocket
|
|
- prijíma input z klávesnice (xterm.js) aj programový input cez HTTP API
|
|
- drží metadata a scrollback output v in-memory store
|
|
- podporuje odstránenie ukončených session (status `stopped`, `exited`, `error`)
|
|
|
|
## Architektúra
|
|
|
|
- `cmd/supervisor/main.go`: entrypoint
|
|
- `internal/app`: zostavenie aplikácie, wiring komponentov
|
|
- `internal/httpserver`: čistý `net/http` router, middleware, API + WS handlery
|
|
- `internal/session`: PTY procesy, lifecycle session, output buffer, subscribe mechanizmus
|
|
- `internal/store/memory`: in-memory persistencia metadata session
|
|
- `internal/supervisor`: skeleton orchestration vrstvy pre budúce supervisor/worker rozšírenie
|
|
- `web/`: samostatný Vue 3 + Vite frontend
|
|
- `internal/static`: embedded statické assets servované zo zabudovaného FS
|
|
|
|
## API endpointy
|
|
|
|
- `GET /healthz`
|
|
- `GET /api/sessions`
|
|
- `POST /api/sessions`
|
|
- `GET /api/sessions/{id}`
|
|
- `POST /api/sessions/{id}/input`
|
|
- `POST /api/sessions/{id}/stop`
|
|
- `DELETE /api/sessions/{id}`
|
|
- `GET /ws/sessions/{id}`
|
|
|
|
Poznámka k mazaniu:
|
|
|
|
- bežiacu session (`running`) nie je možné odstrániť (`409 Conflict`)
|
|
- neexistujúca session vracia `404`
|
|
- úspešné odstránenie vracia `204 No Content`
|
|
|
|
### Session model
|
|
|
|
Každá session obsahuje:
|
|
|
|
- `id`
|
|
- `name`
|
|
- `agentId`
|
|
- `command`
|
|
- `status`
|
|
- `createdAt`
|
|
- `startedAt`
|
|
- `exitedAt`
|
|
- `exitCode`
|
|
|
|
## WebSocket protokol
|
|
|
|
JSON envelope:
|
|
|
|
```json
|
|
{
|
|
"type": "terminal.input | terminal.output | terminal.resize | session.status | error",
|
|
"session": "session-id",
|
|
"payload": {}
|
|
}
|
|
```
|
|
|
|
Použité payloady:
|
|
|
|
- `terminal.input`: `{ "data": "..." }`
|
|
- `terminal.output`: `{ "data": "..." }`
|
|
- `terminal.resize`: `{ "cols": 120, "rows": 30 }`
|
|
- `session.status`: `{ "status": "running", "exitCode": null }`
|
|
- `error`: `{ "message": "..." }`
|
|
|
|
## Frontend poznámky
|
|
|
|
- layout má globálny reset okrajov (`body { margin: 0; }`)
|
|
- v sidebare je pri ukončených session tlačidlo `Remove`
|
|
- pri odstránení aktuálne otvorenej session UI presmeruje na dashboard
|
|
|
|
## Build
|
|
|
|
Predpoklady:
|
|
|
|
- Go (1.23+)
|
|
- Node.js + npm
|
|
|
|
Frontend build do `web/dist` a následne sa skopíruje do `internal/static/dist` pre `go:embed`.
|
|
|
|
```bash
|
|
make frontend-build
|
|
make backend-build
|
|
make build
|
|
```
|
|
|
|
## Spustenie
|
|
|
|
```bash
|
|
make run
|
|
```
|
|
|
|
alebo:
|
|
|
|
```bash
|
|
./bin/supervisor
|
|
```
|
|
|
|
Default adresa: `:8080`.
|
|
|
|
Konfigurácia:
|
|
|
|
- `SUPERVISOR_ADDR` (napr. `:9090`)
|
|
|
|
## Budúce rozšírenie
|
|
|
|
Štruktúra je pripravená na doplnenie:
|
|
|
|
- supervisor orchestration manager
|
|
- worker agents
|
|
- workflow runs
|
|
- audit log
|
|
- persistent store (DB)
|