113 lines
3.2 KiB
Markdown
113 lines
3.2 KiB
Markdown
# HarborForge OpenClaw Server Connector Plugin — Project Plan
|
||
|
||
## 1) Goal
|
||
Provide a secure, lightweight plugin/agent that connects servers to HarborForge Monitor, streams telemetry in real time, and falls back to HTTP heartbeat when WebSocket is unavailable.
|
||
|
||
## 2) Scope
|
||
- **Handshake + auth** using backend-issued challenge + RSA-OAEP encrypted payload.
|
||
- **WebSocket telemetry** to `/monitor/server/ws`.
|
||
- **HTTP heartbeat** to `/monitor/server/heartbeat` as fallback.
|
||
- **System metrics**: CPU/Mem/Disk/Swap/Uptime/OpenClaw version/Agents list.
|
||
- **Retry & backoff**, offline handling, and minimal local state.
|
||
|
||
## 3) Non-Goals
|
||
- No UI in the plugin.
|
||
- No provider billing calls from plugin.
|
||
- No multi-tenant auth beyond challenge + server identifier.
|
||
|
||
## 4) Architecture
|
||
```
|
||
plugin/
|
||
config/ # load config & secrets
|
||
crypto/ # RSA-OAEP encrypt/decrypt helpers
|
||
collector/ # system + openclaw metrics
|
||
transport/ # ws + http heartbeat
|
||
state/ # retry/backoff, last sent, cache
|
||
main.ts|py # entry
|
||
```
|
||
|
||
### 4.1 Config
|
||
- `backend_url`
|
||
- `identifier`
|
||
- `challenge_uuid`
|
||
- `report_interval_sec` (default: 20-30s)
|
||
- `http_fallback_interval_sec` (default: 60s)
|
||
- `log_level`
|
||
|
||
### 4.2 Security
|
||
- Fetch public key: `GET /monitor/public/server-public-key`
|
||
- Encrypt payload with RSA-OAEP
|
||
- Include `nonce` + `ts` (UTC) to prevent replay
|
||
- **Challenge valid**: 10 minutes
|
||
- **Offline threshold**: 7 minutes
|
||
|
||
## 5) Communication Flow
|
||
### 5.1 Handshake (WS)
|
||
1. Plugin reads `identifier + challenge_uuid`.
|
||
2. Fetch RSA public key.
|
||
3. Encrypt payload: `{identifier, challenge_uuid, nonce, ts}`.
|
||
4. Connect WS `/monitor/server/ws` and send `encrypted_payload`.
|
||
5. On success: begin periodic telemetry push.
|
||
|
||
### 5.2 Fallback (HTTP)
|
||
If WS fails:
|
||
- POST telemetry to `/monitor/server/heartbeat` with same payload fields.
|
||
- Retry with exponential backoff (cap 5–10 min).
|
||
|
||
## 6) Telemetry Schema (example)
|
||
```
|
||
{
|
||
identifier: "vps.t1",
|
||
openclaw_version: "x.y.z",
|
||
cpu_pct: 12.5,
|
||
mem_pct: 41.2,
|
||
disk_pct: 62.0,
|
||
swap_pct: 0.0,
|
||
agents: [ { id: "a1", name: "agent", status: "running" } ],
|
||
last_seen_at: "2026-03-11T21:00:00Z"
|
||
}
|
||
```
|
||
|
||
## 7) Reliability
|
||
- Automatic reconnect on WS drop
|
||
- HTTP fallback if WS unavailable > 2 intervals
|
||
- Exponential backoff on failures
|
||
- Local cache for last successful payload
|
||
|
||
## 8) Deployment Options
|
||
- **Systemd service** (preferred for VPS)
|
||
- **Docker container** (optional)
|
||
- Single-binary build if using Go/Rust
|
||
|
||
## 9) Milestones
|
||
**M1 – POC (2–3 days)**
|
||
- CLI config loader + HTTP heartbeat
|
||
- See online + metrics in Monitor
|
||
|
||
**M2 – WS realtime (2–3 days)**
|
||
- Full handshake + WS streaming
|
||
- Reconnect & fallback logic
|
||
|
||
**M3 – Packaging (1–2 days)**
|
||
- systemd unit + sample config
|
||
- installation script
|
||
|
||
**M4 – Hardening & Docs (1–2 days)**
|
||
- logging, metrics, docs
|
||
- troubleshooting guide
|
||
|
||
## 10) Deliverables
|
||
- Plugin source
|
||
- Config template + systemd unit
|
||
- Integration docs
|
||
- Test script + example payloads
|
||
|
||
## 11) Open Questions
|
||
- Preferred language (Go/Python/Node/Rust)?
|
||
- How to read OpenClaw agent list (API vs local state)?
|
||
- Required log format / retention?
|
||
|
||
---
|
||
|
||
**Next step:** confirm preferred runtime (Go/Python/Node) and I will scaffold the project structure + first heartbeat implementation.
|