added live redoc and slight refactors to tokens

This commit is contained in:
ari committed 2026-10-20 22:53:09 -04:00
1 parent 435a54a02d
commit b38c66bcc8
19 files changed
+836 -157

No files matched your search

+33 -17
View File
@@ -7,6 +7,7 @@ Full endpoint and MCP client reference. The short version is in the [README](../
[`openapi.json`](openapi.json) is a committed OpenAPI 3.1 description of everything this binary serves: every REST route with its parameters and response schemas, the error shape, the MCP endpoint (`POST`, the standalone `GET` stream and the session `DELETE`), and an `x-mcp-tools` extension listing each MCP tool with the description and input JSON Schema the tool router reports (eight tools, or ten with `[peers] enabled = true`). `tests/openapi.rs` keeps it true: it fails if a route of the real router is undocumented, if a tool is missing from `x-mcp-tools`, or if the file is stale.
- `GET /api/v1/openapi.json` returns the document for the running instance, behind the same bearer token as the rest of `/api/v1`. Peer routes appear only when peers are enabled.
- `GET /docs` renders it with Redoc. The page (`/docs`) and the Redoc 2.5.4 bundle (`/docs/redoc.standalone.js`, embedded in the binary) are public, static and hold no host data; the page asks for a bearer token, keeps it in `sessionStorage` and sends it only to `GET /api/v1/openapi.json`, so the spec itself stays behind auth. With `[auth] enabled = false` it loads without asking. The page answers with a strict `Content-Security-Policy` (no external origins), so nothing is fetched from a CDN. Redoc shows REST operations; the MCP tools in `x-mcp-tools` are in the JSON, not in the rendered page.
- `slinuxm openapi [--peers]` prints the same document offline: no config file, no token, no server, no port. `--peers` describes a consolidator; without it you get the peer-less instance.
- Regenerate after changing a route, a tool, a response type or the crate version:
@@ -18,21 +19,22 @@ cargo run -- openapi --peers > docs/openapi.json
Base: `http://127.0.0.1:1984`. Errors are `{"error":{"code","message"}}`.
| Route | Notes |
|---|---|
| `GET /healthz` | public, `{"status":"ok","version":...}` |
| `GET /api/v1/systemd/units?state=failed` | `state` is an active state (`failed`, `active`, ...) |
| `GET /api/v1/systemd/units/{name}` | one unit with details; read-only, so only units systemd has loaded (unloaded or unknown is 404) |
| `GET /api/v1/systemd/timers` | |
| `GET /api/v1/journal?unit=&priority=err&lines=100` | priority by name or number |
| `GET /api/v1/journal/follow?unit=&priority=` | SSE, event `journal` |
| `GET /api/v1/docker/ps` | `503` when Docker is unavailable |
| `GET /api/v1/docker/containers/{name}` | |
| `GET /api/v1/docker/containers/{name}/logs?tail=&since=&follow=0\|1` | JSON, or SSE with events `stdout`/`stderr` |
| `GET /api/v1/peers` | consolidator only; sorted status list; absent when peers are disabled |
| `GET /api/v1/peers/{peer}` | one peer's status object; unknown name is 404 |
| `GET /api/v1/peers/{peer}/...` | GET-only pass-through of that peer's documented routes |
| `GET /api/v1/openapi.json` | this document, OpenAPI 3.1 (see [Generated reference](#generated-reference-openapi)) |
| Route | Notes |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `GET /healthz` | public, `{"status":"ok","version":...}` |
| `GET /docs`, `GET /docs/redoc.standalone.js` | public static Redoc viewer for the OpenAPI document, see [Generated reference](#generated-reference-openapi) |
| `GET /api/v1/systemd/units?state=failed` | `state` is an active state (`failed`, `active`, ...) |
| `GET /api/v1/systemd/units/{name}` | one unit with details; read-only, so only units systemd has loaded (unloaded or unknown is 404) |
| `GET /api/v1/systemd/timers` | |
| `GET /api/v1/journal?unit=&priority=err&lines=100` | priority by name or number |
| `GET /api/v1/journal/follow?unit=&priority=` | SSE, event `journal` |
| `GET /api/v1/docker/ps` | `503` when Docker is unavailable |
| `GET /api/v1/docker/containers/{name}` | |
| `GET /api/v1/docker/containers/{name}/logs?tail=&since=&follow=0\|1` | JSON, or SSE with events `stdout`/`stderr` |
| `GET /api/v1/peers` | consolidator only; sorted status list; absent when peers are disabled |
| `GET /api/v1/peers/{peer}` | one peer's status object; unknown name is 404 |
| `GET /api/v1/peers/{peer}/...` | GET-only pass-through of that peer's documented routes |
| `GET /api/v1/openapi.json` | this document, OpenAPI 3.1 (see [Generated reference](#generated-reference-openapi)) |
```sh
TOKEN=slinuxm_...
@@ -49,8 +51,22 @@ Present only when `[peers] enabled = true`. The same inbound token as the rest o
"name": "beta",
"enabled": true,
"url": "http://beta:1984",
"server": { "up": true, "since": "2026-10-19T10:00:00Z", "last_checked": "2026-10-19T10:00:09Z", "last_error": null, "latency_ms": 1 },
"api": { "up": true, "since": "2026-10-19T10:00:00Z", "last_checked": "2026-10-19T10:00:05Z", "last_error": null, "latency_ms": 7, "auth": "ok", "peer_version": "0.1.0" }
"server": {
"up": true,
"since": "2026-10-19T10:00:00Z",
"last_checked": "2026-10-19T10:00:09Z",
"last_error": null,
"latency_ms": 1
},
"api": {
"up": true,
"since": "2026-10-19T10:00:00Z",
"last_checked": "2026-10-19T10:00:05Z",
"last_error": null,
"latency_ms": 7,
"auth": "ok",
"peer_version": "0.1.0"
}
}
```