211 lines
7.8 KiB
Markdown
211 lines
7.8 KiB
Markdown
# Protocol
|
||
|
||
Wire contract for PearData P2P RPC. Source of truth: `shared/protocol.js`, `shared/schema.js`, `shared/metrics.js`.
|
||
|
||
## Identity
|
||
|
||
| Constant | Value |
|
||
|----------|-------|
|
||
| Protocol id | `peardata/rpc` |
|
||
| Protocol version | `1` |
|
||
| Invite prefix | `pd1.` |
|
||
| Default role | `viewer` |
|
||
|
||
Bump `PROTOCOL_VERSION` on breaking argument/result shapes.
|
||
|
||
## Roles
|
||
|
||
| Role | Rank | Typical access |
|
||
|------|------|----------------|
|
||
| `viewer` | 1 | Read metrics, subscribe, list alerts |
|
||
| `operator` | 2 | Ack/silence alerts, run jobs, set alert config |
|
||
| `admin` | 3 | Mint invites, revoke peers, export snapshot |
|
||
|
||
Auth modes at handshake: public key (viewer), capability token / `pd1.` invite, admin seed proof, allowlist.
|
||
|
||
## Methods
|
||
|
||
### Session
|
||
|
||
| Method | Role | Notes |
|
||
|--------|------|-------|
|
||
| `handshake` | viewer | Negotiate version + elevate role |
|
||
| `ping` | viewer | Hot |
|
||
| `getServerInfo` | viewer | Agent metadata |
|
||
| `getAuthStatus` | viewer | Peer role / auth mode |
|
||
| `setDisplayName` | viewer | Label for audit / UI |
|
||
|
||
### Node
|
||
|
||
| Method | Role | Result |
|
||
|--------|------|--------|
|
||
| `getNodeInfo` | viewer | Hostname, CPUs, charts, sample interval |
|
||
| `getHealth` | viewer | `{ status, score, checks }` |
|
||
|
||
### Metrics discovery & query
|
||
|
||
| Method | Role | Args | Result |
|
||
|--------|------|------|--------|
|
||
| `listContexts` | viewer | — | Context catalog |
|
||
| `getContext` | viewer | `{ id }` | Charts in context |
|
||
| `listCharts` | viewer | — | agent-style chart map |
|
||
| `getChart` | viewer | `{ id }` | Chart summary |
|
||
| `queryData` | viewer | `{ chart, after, before, points, group, tier }` | Time series |
|
||
| `getWeights` | viewer | see below | Metric Correlations / alert weights |
|
||
| `queryLogs` | viewer* | see below | Anomaly / audit / journal lines |
|
||
| `listProcesses` | viewer | sort / filter / q / limit | Live Linux `/proc` process table |
|
||
| `getAllMetrics` | viewer | `{ format: json\|prometheus\|shell }` | Latest export |
|
||
|
||
\* `queryLogs` method role is viewer so anomaly search works for all dialers; **audit** and **journal** sources require **admin** inside the handler.
|
||
|
||
`after` / `before`: absolute unix seconds, or relative (negative = relative to `before`/`now`), agent-style.
|
||
|
||
#### `getWeights`
|
||
|
||
Scores charts for [Metric Correlations](../user-guide/metric-correlations.md) (or legacy alert weights when no highlight window).
|
||
|
||
| Arg | Notes |
|
||
|-----|--------|
|
||
| `method` | `volume` \| `ks2` \| `anomaly-rate` \| `value` \| `alerts` |
|
||
| `after` / `before` | Highlight window |
|
||
| `baseline_after` / `baseline_before` | Optional baseline (default 4× preceding highlight) |
|
||
| `points`, `time_group`, `contexts`, `charts`, `dimensions`, `limit`, `timeout` | Same as REST |
|
||
|
||
REST parity: `GET /api/v*/weights`. Engine: `server/services/weights.js`.
|
||
|
||
#### `queryLogs`
|
||
|
||
| Arg | Notes |
|
||
|-----|--------|
|
||
| `source` | `journal` (default) \| `anomaly` \| `audit` — desktop prefers journal for admins |
|
||
| `q` | Case-insensitive substring |
|
||
| `since` / `until` | Absolute ms/sec or relative (`-1h`) |
|
||
| `priority` / `unit` | Journal filters |
|
||
| `limit` / `cursor` | Cap (≤2000) + pagination offset |
|
||
|
||
Journal is **enabled by default** on Linux (`PEARDATA_JOURNAL=0` to disable). Installer grants `systemd-journal` to the agent user. REST: `GET /api/v*/logs`. Engine: `server/services/logs.js`. UI: [user-guide/logs.md](../user-guide/logs.md).
|
||
|
||
#### `listProcesses`
|
||
|
||
| Arg | Notes |
|
||
|-----|--------|
|
||
| `sort` | `cpu` (default) \| `rss` \| `pid` \| `name` \| `io` \| `threads` \| `age` \| `fds` \| `state` |
|
||
| `order` | `desc` (default) \| `asc` |
|
||
| `filter` | `all` \| `running` \| `sleeping` \| `zombie` \| `stopped` \| `highcpu` \| `highmem` \| `hasio` \| `kernel` \| `user` |
|
||
| `q` | Substring over pid / name / cmdline / user / cgroup |
|
||
| `limit` / `offset` | Cap ≤2000 |
|
||
| `pid` | Optional — return one process with detail fields (fds, exe, cwd, …) |
|
||
|
||
Linux `/proc` only. Rates need two samples (~450ms cache). REST: `GET /api/v*/processes`. UI: [user-guide/processes.md](../user-guide/processes.md).
|
||
|
||
### Live subscriptions
|
||
|
||
| Method | Role | Args |
|
||
|--------|------|------|
|
||
| `subscribeMetrics` | viewer | `{ charts: string[]\|['*'], intervalMs }` |
|
||
| `unsubscribeMetrics` | viewer | — |
|
||
| `subscribeAnomalies` | viewer | — |
|
||
| `unsubscribeAnomalies` | viewer | — |
|
||
|
||
### Anomalies & alerts
|
||
|
||
| Method | Role | Notes |
|
||
|--------|------|-------|
|
||
| `listAnomalies` | viewer | Recent events |
|
||
| `listAlerts` / `getAlert` | viewer | State + config |
|
||
| `setAlertConfig` | operator | Upsert threshold |
|
||
| `ackAlert` | operator | Clear until next breach |
|
||
| `silenceAlert` | operator | Disable temporarily |
|
||
|
||
### AI / QVAC tool composites
|
||
|
||
Lean read-only helpers for the desktop QVAC tab (and scripts). See [QVAC.md](./QVAC.md).
|
||
|
||
| Method | Role | Args | Notes |
|
||
|--------|------|------|-------|
|
||
| `getHostSnapshot` | viewer | — | Health, KPIs, recent anomalies/alerts, catalog + storage summary |
|
||
| `searchCharts` | viewer | `{ q?, limit? }` | Catalog free-text search (`limit` 1–100) |
|
||
| `summarizeChart` | viewer | `{ chart, after?, points?, group? }` | min/avg/max/last per dim for a window |
|
||
|
||
REST mirrors: `GET /api/v3/ai/snapshot`, `/api/v3/ai/charts`, `/api/v3/ai/chart/:id/summary`.
|
||
|
||
### Jobs
|
||
|
||
| Method | Role | Known jobs |
|
||
|--------|------|------------|
|
||
| `listJobs` | viewer | — |
|
||
| `runJob` | operator | `collectOnce`, `snapshot`, `gcBuffers` (prune) |
|
||
| `cancelJob` | operator | By job id |
|
||
|
||
### Data Manager (retention / storage)
|
||
|
||
| Method | Role | Notes |
|
||
|--------|------|-------|
|
||
| `getStorageInfo` | viewer | Disk usage, memory rings, warm sample stats, effective retention |
|
||
| `getRetentionConfig` | viewer | Current policy (`retention.json`; default warm age **3 months**, **1 GiB** disk budget) |
|
||
| `setRetentionConfig` | admin | Update hot/warm rings, age rotate, disk budget, auto-prune |
|
||
| `pruneHistory` | admin | `{ dryRun?, beforeMs?, gc? }` — delete warm points + physical reclaim (`clearUnlinked` + `compact`). Returns `bytesBefore` / `bytesAfter` / `bytesFreed`. |
|
||
|
||
UI: [user-guide/settings.md](../user-guide/settings.md) → **Data**. Job alias: `runJob({ name: 'gcBuffers' })` runs the same prune path.
|
||
|
||
### HyperDB / peer links
|
||
|
||
| Method | Role | Notes |
|
||
|--------|------|-------|
|
||
| `getDbInfo` | viewer | DB + discovery keys, swarm flag, remotes |
|
||
| `listPeerLinks` | viewer | Linked peers from HyperDB |
|
||
| `linkPeer` | admin | Upsert link; open remote bee + optional swarm join |
|
||
| `unlinkPeer` | admin | Remove link |
|
||
| `getFleetHealth` | viewer | Parent rollup (when `PEARDATA_PARENT=1`) |
|
||
| `listChildPeers` | viewer | Dialed child agents |
|
||
|
||
See [STORAGE-HYPERDB.md](./STORAGE-HYPERDB.md).
|
||
|
||
### Admin
|
||
|
||
| Method | Role |
|
||
|--------|------|
|
||
| `mintInvite` | admin |
|
||
| `listPeers` | admin |
|
||
| `revokePeer` | admin |
|
||
| `exportSnapshot` | admin |
|
||
|
||
## Pushes (server → client)
|
||
|
||
| Event | Payload |
|
||
|-------|---------|
|
||
| `push:metrics` | `{ samples: MetricSample[] }` |
|
||
| `push:anomaly` | `AnomalyEvent` |
|
||
| `push:alert` | Alert transition |
|
||
| `push:health` | `HealthSnapshot` |
|
||
| `push:job` | `JobRecord` |
|
||
| `push:system` | Generic notices |
|
||
|
||
## Errors
|
||
|
||
Handlers throw `Error` with `.code`:
|
||
|
||
| Code | Meaning |
|
||
|------|---------|
|
||
| `PERMISSION_DENIED` | Role too low |
|
||
| `RATE_LIMIT_EXCEEDED` | RPM exceeded |
|
||
| `INVALID_ARGS` | Schema failure |
|
||
| `NOT_CONNECTED` | Client-side |
|
||
| `CAPABILITY_*` | Invite/token issues |
|
||
|
||
## Versioning policy
|
||
|
||
1. Additive methods/fields: no version bump if old clients ignore unknowns.
|
||
2. Rename/remove/change meaning: bump `PROTOCOL_VERSION`; reject or compat-negotiate in handshake.
|
||
3. REST API versions (`v1`/`v2`/`v3`) are independent of RPC version but share the store.
|
||
|
||
## Example session
|
||
|
||
```text
|
||
client → handshake { clientName, clientVersion, capability? }
|
||
server → { role, protocolVersion, auth }
|
||
client → subscribeMetrics { charts: ['*'], intervalMs: 1000 }
|
||
server → push:metrics { samples: [...] } # ~1 Hz
|
||
client → queryData { chart: 'system.cpu', after: -300, points: 300 }
|
||
```
|