Compare commits
1
Commits
dev
..
194cd3c175
| Author | SHA1 | Date | |
|---|---|---|---|
 josh
|
194cd3c175 |
@@ -37,7 +37,176 @@ Open [http://localhost:3000](http://localhost:3000).
|
||||
|
||||
## REST API
|
||||
|
||||
See **[docs/api.md](docs/api.md)** for the full API reference.
|
||||
All endpoints are under `/api`. Request and response bodies are JSON.
|
||||
|
||||
### Instances
|
||||
|
||||
#### `GET /api/instances`
|
||||
|
||||
Returns all instances sorted by name. All query parameters are optional.
|
||||
|
||||
| Parameter | Type | Description |
|
||||
|---|---|---|
|
||||
| `search` | string | Partial match on `name`, `vmid`, or `stack` |
|
||||
| `state` | string | Exact match: `deployed`, `testing`, `degraded` |
|
||||
| `stack` | string | Exact match: `production`, `development` |
|
||||
|
||||
```
|
||||
GET /api/instances?search=plex&state=deployed
|
||||
```
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"vmid": 117,
|
||||
"name": "plex",
|
||||
"state": "deployed",
|
||||
"stack": "production",
|
||||
"tailscale_ip": "100.64.0.1",
|
||||
"atlas": 1, "argus": 1, "semaphore": 0,
|
||||
"patchmon": 1, "tailscale": 1, "andromeda": 0,
|
||||
"hardware_acceleration": 1,
|
||||
"created_at": "2024-01-15T10:30:00",
|
||||
"updated_at": "2024-03-10T14:22:00"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### `GET /api/instances/stacks`
|
||||
|
||||
Returns a sorted array of distinct stack names present in the registry.
|
||||
|
||||
```
|
||||
GET /api/instances/stacks
|
||||
→ ["development", "production"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### `GET /api/instances/:vmid`
|
||||
|
||||
Returns a single instance by VMID.
|
||||
|
||||
| Status | Condition |
|
||||
|---|---|
|
||||
| `200` | Instance found |
|
||||
| `400` | VMID is not a valid integer |
|
||||
| `404` | No instance with that VMID |
|
||||
|
||||
---
|
||||
|
||||
#### `GET /api/instances/:vmid/history`
|
||||
|
||||
Returns the audit log for an instance — newest events first.
|
||||
|
||||
| Status | Condition |
|
||||
|---|---|
|
||||
| `200` | History returned (may be empty array) |
|
||||
| `400` | VMID is not a valid integer |
|
||||
| `404` | No instance with that VMID |
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": 3,
|
||||
"vmid": 117,
|
||||
"field": "state",
|
||||
"old_value": "testing",
|
||||
"new_value": "deployed",
|
||||
"changed_at": "2024-03-10T14:22:00"
|
||||
},
|
||||
{
|
||||
"id": 1,
|
||||
"vmid": 117,
|
||||
"field": "created",
|
||||
"old_value": null,
|
||||
"new_value": null,
|
||||
"changed_at": "2024-01-15T10:30:00"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### `POST /api/instances`
|
||||
|
||||
Creates a new instance. Returns the created record.
|
||||
|
||||
| Status | Condition |
|
||||
|---|---|
|
||||
| `201` | Created successfully |
|
||||
| `400` | Validation error — see `errors` array in response |
|
||||
| `409` | VMID already exists |
|
||||
|
||||
**Request body:**
|
||||
|
||||
| Field | Type | Required | Notes |
|
||||
|---|---|---|---|
|
||||
| `name` | string | yes | |
|
||||
| `vmid` | integer | yes | Must be > 0 and unique |
|
||||
| `state` | string | yes | `deployed`, `testing`, or `degraded` |
|
||||
| `stack` | string | yes | `production` or `development` |
|
||||
| `tailscale_ip` | string | no | Valid IPv4 or empty string |
|
||||
| `atlas` | 0\|1 | no | |
|
||||
| `argus` | 0\|1 | no | |
|
||||
| `semaphore` | 0\|1 | no | |
|
||||
| `patchmon` | 0\|1 | no | |
|
||||
| `tailscale` | 0\|1 | no | |
|
||||
| `andromeda` | 0\|1 | no | |
|
||||
| `hardware_acceleration` | 0\|1 | no | |
|
||||
|
||||
---
|
||||
|
||||
#### `PUT /api/instances/:vmid`
|
||||
|
||||
Replaces all fields on an existing instance. Accepts the same body shape as `POST`. The `vmid` in the body may differ from the URL — this is how you change a VMID.
|
||||
|
||||
| Status | Condition |
|
||||
|---|---|
|
||||
| `200` | Updated successfully |
|
||||
| `400` | Validation error |
|
||||
| `404` | No instance with that VMID |
|
||||
| `409` | New VMID conflicts with an existing instance |
|
||||
|
||||
---
|
||||
|
||||
#### `DELETE /api/instances/:vmid`
|
||||
|
||||
Deletes an instance. Only instances on the `development` stack may be deleted.
|
||||
|
||||
| Status | Condition |
|
||||
|---|---|
|
||||
| `204` | Deleted successfully |
|
||||
| `400` | VMID is not a valid integer |
|
||||
| `404` | No instance with that VMID |
|
||||
| `422` | Instance is on the `production` stack |
|
||||
|
||||
---
|
||||
|
||||
### Backup
|
||||
|
||||
#### `GET /api/export`
|
||||
|
||||
Downloads a JSON backup of all instances as a file attachment.
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 1,
|
||||
"exported_at": "2024-03-10T14:22:00.000Z",
|
||||
"instances": [ ... ]
|
||||
}
|
||||
```
|
||||
|
||||
#### `POST /api/import`
|
||||
|
||||
Replaces all instances from a JSON backup. Validates every row before committing — if any row is invalid the entire import is rejected.
|
||||
|
||||
| Status | Condition |
|
||||
|---|---|
|
||||
| `200` | Import successful — returns `{ "imported": N }` |
|
||||
| `400` | Body missing `instances` array, or validation errors |
|
||||
|
||||
---
|
||||
|
||||
|
||||
-283
@@ -1,283 +0,0 @@
|
||||
# Catalyst API Reference
|
||||
|
||||
All endpoints are under `/api`. Request and response bodies are JSON.
|
||||
|
||||
---
|
||||
|
||||
## Instances
|
||||
|
||||
#### `GET /api/instances`
|
||||
|
||||
Returns all instances sorted by name. All query parameters are optional.
|
||||
|
||||
| Parameter | Type | Description |
|
||||
|---|---|---|
|
||||
| `search` | string | Partial match on `name`, `vmid`, or `stack` |
|
||||
| `state` | string | Exact match: `deployed`, `testing`, `degraded` |
|
||||
| `stack` | string | Exact match: `production`, `development` |
|
||||
|
||||
```
|
||||
GET /api/instances?search=plex&state=deployed
|
||||
```
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"vmid": 117,
|
||||
"name": "plex",
|
||||
"state": "deployed",
|
||||
"stack": "production",
|
||||
"tailscale_ip": "100.64.0.1",
|
||||
"atlas": 1, "argus": 1, "semaphore": 0,
|
||||
"patchmon": 1, "tailscale": 1, "andromeda": 0,
|
||||
"hardware_acceleration": 1,
|
||||
"created_at": "2024-01-15T10:30:00",
|
||||
"updated_at": "2024-03-10T14:22:00"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### `GET /api/instances/stacks`
|
||||
|
||||
Returns a sorted array of distinct stack names present in the registry.
|
||||
|
||||
```
|
||||
GET /api/instances/stacks
|
||||
→ ["development", "production"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### `GET /api/instances/:vmid`
|
||||
|
||||
Returns a single instance by VMID.
|
||||
|
||||
| Status | Condition |
|
||||
|---|---|
|
||||
| `200` | Instance found |
|
||||
| `400` | VMID is not a valid integer |
|
||||
| `404` | No instance with that VMID |
|
||||
|
||||
---
|
||||
|
||||
#### `GET /api/instances/:vmid/history`
|
||||
|
||||
Returns the audit log for an instance — newest events first.
|
||||
|
||||
| Status | Condition |
|
||||
|---|---|
|
||||
| `200` | History returned (may be empty array) |
|
||||
| `400` | VMID is not a valid integer |
|
||||
| `404` | No instance with that VMID |
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": 3,
|
||||
"vmid": 117,
|
||||
"field": "state",
|
||||
"old_value": "testing",
|
||||
"new_value": "deployed",
|
||||
"changed_at": "2024-03-10T14:22:00"
|
||||
},
|
||||
{
|
||||
"id": 1,
|
||||
"vmid": 117,
|
||||
"field": "created",
|
||||
"old_value": null,
|
||||
"new_value": null,
|
||||
"changed_at": "2024-01-15T10:30:00"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### `POST /api/instances`
|
||||
|
||||
Creates a new instance. Returns the created record.
|
||||
|
||||
| Status | Condition |
|
||||
|---|---|
|
||||
| `201` | Created successfully |
|
||||
| `400` | Validation error — see `errors` array in response |
|
||||
| `409` | VMID already exists |
|
||||
|
||||
**Request body:**
|
||||
|
||||
| Field | Type | Required | Notes |
|
||||
|---|---|---|---|
|
||||
| `name` | string | yes | |
|
||||
| `vmid` | integer | yes | Must be > 0 and unique |
|
||||
| `state` | string | yes | `deployed`, `testing`, or `degraded` |
|
||||
| `stack` | string | yes | `production` or `development` |
|
||||
| `tailscale_ip` | string | no | Valid IPv4 or empty string |
|
||||
| `atlas` | 0\|1 | no | |
|
||||
| `argus` | 0\|1 | no | |
|
||||
| `semaphore` | 0\|1 | no | |
|
||||
| `patchmon` | 0\|1 | no | |
|
||||
| `tailscale` | 0\|1 | no | |
|
||||
| `andromeda` | 0\|1 | no | |
|
||||
| `hardware_acceleration` | 0\|1 | no | |
|
||||
|
||||
---
|
||||
|
||||
#### `PUT /api/instances/:vmid`
|
||||
|
||||
Replaces all fields on an existing instance. Accepts the same body shape as `POST`. The `vmid` in the body may differ from the URL — this is how you change a VMID.
|
||||
|
||||
| Status | Condition |
|
||||
|---|---|
|
||||
| `200` | Updated successfully |
|
||||
| `400` | Validation error |
|
||||
| `404` | No instance with that VMID |
|
||||
| `409` | New VMID conflicts with an existing instance |
|
||||
|
||||
---
|
||||
|
||||
#### `DELETE /api/instances/:vmid`
|
||||
|
||||
Deletes an instance. Only instances on the `development` stack may be deleted.
|
||||
|
||||
| Status | Condition |
|
||||
|---|---|
|
||||
| `204` | Deleted successfully |
|
||||
| `400` | VMID is not a valid integer |
|
||||
| `404` | No instance with that VMID |
|
||||
| `422` | Instance is on the `production` stack |
|
||||
|
||||
---
|
||||
|
||||
## Jobs
|
||||
|
||||
Jobs are background sync tasks that keep instance data up to date by pulling from external services (Tailscale, Patchmon, Semaphore). Each job runs on a configurable interval and can also be triggered on demand.
|
||||
|
||||
Sensitive config fields (`api_key`, `api_token`) are always returned as `**REDACTED**`. Send `**REDACTED**` back in a `PUT` to preserve the stored value unchanged.
|
||||
|
||||
#### `GET /api/jobs`
|
||||
|
||||
Returns all jobs.
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": 1,
|
||||
"key": "tailscale_sync",
|
||||
"name": "Tailscale Sync",
|
||||
"description": "Syncs Tailscale device status and IPs",
|
||||
"enabled": 1,
|
||||
"schedule": 15,
|
||||
"config": { "api_key": "**REDACTED**", "tailnet": "example.com" },
|
||||
"last_run_at": "2024-03-10T14:22:00",
|
||||
"last_status": "success"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### `GET /api/jobs/:id`
|
||||
|
||||
Returns a single job and its last 10 run records, newest first.
|
||||
|
||||
| Status | Condition |
|
||||
|---|---|
|
||||
| `200` | Job found |
|
||||
| `400` | ID is not a valid integer |
|
||||
| `404` | No job with that ID |
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 1,
|
||||
"key": "tailscale_sync",
|
||||
"name": "Tailscale Sync",
|
||||
"enabled": 1,
|
||||
"schedule": 15,
|
||||
"config": { "api_key": "**REDACTED**", "tailnet": "example.com" },
|
||||
"runs": [
|
||||
{
|
||||
"id": 42,
|
||||
"started_at": "2024-03-10T14:22:00",
|
||||
"ended_at": "2024-03-10T14:22:01",
|
||||
"status": "success",
|
||||
"result": "3 updated of 12"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### `PUT /api/jobs/:id`
|
||||
|
||||
Updates a job's enabled state, schedule interval, or configuration. All fields are optional — omitted fields are left unchanged. Config is merged with the existing config (partial updates are safe).
|
||||
|
||||
| Status | Condition |
|
||||
|---|---|
|
||||
| `200` | Updated successfully — returns the updated job |
|
||||
| `400` | ID is not a valid integer |
|
||||
| `404` | No job with that ID |
|
||||
|
||||
**Request body:**
|
||||
|
||||
| Field | Type | Notes |
|
||||
|---|---|---|
|
||||
| `enabled` | boolean | `true` to enable, `false` to disable |
|
||||
| `schedule` | integer | Interval in minutes (default: 15) |
|
||||
| `config` | object | Merged with existing config — see per-job fields below |
|
||||
|
||||
**Config fields by job key:**
|
||||
|
||||
| Key | Field | Notes |
|
||||
|---|---|---|
|
||||
| `tailscale_sync` | `api_key` | Tailscale API key |
|
||||
| `tailscale_sync` | `tailnet` | Tailnet name (e.g. `example.com`) |
|
||||
| `tailscale_sync` | `run_on_create` | `true` to also run when a new instance is created |
|
||||
| `patchmon_sync` | `api_url` | Full URL to the Patchmon hosts endpoint |
|
||||
| `patchmon_sync` | `api_token` | `key:secret` credential or pre-encoded base64 |
|
||||
| `semaphore_sync` | `api_url` | Full URL to the Semaphore inventory endpoint |
|
||||
| `semaphore_sync` | `api_token` | Semaphore API token |
|
||||
|
||||
---
|
||||
|
||||
#### `POST /api/jobs/:id/run`
|
||||
|
||||
Triggers a job to run immediately. Blocks until the job completes and returns the result. The run is recorded in the job's history regardless of outcome.
|
||||
|
||||
| Status | Condition |
|
||||
|---|---|
|
||||
| `200` | Job completed successfully |
|
||||
| `400` | ID is not a valid integer |
|
||||
| `404` | No job with that ID |
|
||||
| `500` | Job handler threw an error (run is logged with `status: "error"`) |
|
||||
|
||||
```json
|
||||
{ "summary": "3 updated of 12" }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Backup
|
||||
|
||||
#### `GET /api/export`
|
||||
|
||||
Downloads a JSON backup of all instances as a file attachment.
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 1,
|
||||
"exported_at": "2024-03-10T14:22:00.000Z",
|
||||
"instances": [ ... ]
|
||||
}
|
||||
```
|
||||
|
||||
#### `POST /api/import`
|
||||
|
||||
Replaces all instances from a JSON backup. Validates every row before committing — if any row is invalid the entire import is rejected.
|
||||
|
||||
| Status | Condition |
|
||||
|---|---|
|
||||
| `200` | Import successful — returns `{ "imported": N }` |
|
||||
| `400` | Body missing `instances` array, or validation errors |
|
||||
+1
-1
@@ -1 +1 @@
|
||||
const VERSION = "1.7.2";
|
||||
const VERSION = "1.7.1";
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "catalyst",
|
||||
"version": "1.7.2",
|
||||
"version": "1.7.1",
|
||||
"type": "module",
|
||||
"scripts": {
|
||||
"start": "node server/server.js",
|
||||
|
||||
+2
-23
@@ -6,8 +6,6 @@ import { fileURLToPath } from 'url';
|
||||
const __dirname = dirname(fileURLToPath(import.meta.url));
|
||||
const DEFAULT_PATH = join(__dirname, '../data/catalyst.db');
|
||||
|
||||
const JOB_RUN_LIMIT = 10;
|
||||
|
||||
let db;
|
||||
|
||||
function init(path) {
|
||||
@@ -19,7 +17,7 @@ function init(path) {
|
||||
db.exec('PRAGMA foreign_keys = ON');
|
||||
db.exec('PRAGMA synchronous = NORMAL');
|
||||
createSchema();
|
||||
if (path !== ':memory:') { seed(); seedJobs(); pruneAllJobRuns(); }
|
||||
if (path !== ':memory:') { seed(); seedJobs(); }
|
||||
}
|
||||
|
||||
function createSchema() {
|
||||
@@ -269,7 +267,6 @@ export function importJobs(jobRows, jobRunRows = []) {
|
||||
`);
|
||||
for (const r of jobRunRows) insertRun.run(r);
|
||||
}
|
||||
pruneAllJobRuns();
|
||||
db.exec('COMMIT');
|
||||
}
|
||||
|
||||
@@ -329,28 +326,10 @@ export function completeJobRun(runId, status, result) {
|
||||
db.prepare(`
|
||||
UPDATE job_runs SET ended_at=strftime('%Y-%m-%dT%H:%M:%f', 'now'), status=@status, result=@result WHERE id=@id
|
||||
`).run({ id: runId, status, result });
|
||||
const row = db.prepare('SELECT job_id FROM job_runs WHERE id = ?').get(runId);
|
||||
if (row) pruneJobRuns(row.job_id);
|
||||
}
|
||||
|
||||
export function getJobRuns(jobId) {
|
||||
return db.prepare(`SELECT * FROM job_runs WHERE job_id = ? ORDER BY id DESC LIMIT ${JOB_RUN_LIMIT}`).all(jobId);
|
||||
}
|
||||
|
||||
function pruneJobRuns(jobId) {
|
||||
db.prepare(`
|
||||
DELETE FROM job_runs
|
||||
WHERE job_id = ?
|
||||
AND id NOT IN (
|
||||
SELECT id FROM job_runs WHERE job_id = ? ORDER BY id DESC LIMIT ?
|
||||
)
|
||||
`).run(jobId, jobId, JOB_RUN_LIMIT);
|
||||
}
|
||||
|
||||
function pruneAllJobRuns() {
|
||||
for (const j of db.prepare('SELECT id FROM jobs').all()) {
|
||||
pruneJobRuns(j.id);
|
||||
}
|
||||
return db.prepare('SELECT * FROM job_runs WHERE job_id = ? ORDER BY id DESC').all(jobId);
|
||||
}
|
||||
|
||||
// ── Test helpers ──────────────────────────────────────────────────────────────
|
||||
|
||||
@@ -450,17 +450,4 @@ describe('job_runs', () => {
|
||||
expect(runs[0].id).toBe(r2);
|
||||
expect(runs[1].id).toBe(r1);
|
||||
});
|
||||
|
||||
it('caps history at the last 10 runs per job', () => {
|
||||
createJob(baseJob);
|
||||
const id = getJobs()[0].id;
|
||||
for (let i = 0; i < 15; i++) {
|
||||
const runId = createJobRun(id);
|
||||
completeJobRun(runId, 'success', `run ${i}`);
|
||||
}
|
||||
const runs = getJobRuns(id);
|
||||
expect(runs).toHaveLength(10);
|
||||
expect(runs[0].result).toBe('run 14');
|
||||
expect(runs[9].result).toBe('run 5');
|
||||
});
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user