Nextcloud, NetBox and n8n integrations

Three read-only integrations, each with a monitoring page, alerts, maintenance
silencing and held-when-unreadable handling.

Nextcloud: database needing upgrade (critical), maintenance mode, and the data
disk running low; users, files and app updates with an admin app password.
NetBox: no background worker running, counts, and a list of the servers this
app manages that have no address in NetBox (a list, not an alert).
n8n: an active workflow whose last run failed, clearing when it next succeeds.

Disk messages for Immich, Paperless and Nextcloud now use the same units as
the pages that show them.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
bobbanandClaude Sonnet 5.5 committed 2026-10-24 23:13:13 +02:00
1 parent a16996d975
commit 4ff0b44943
46 files changed
+10137 -10

No files matched your search

+262
View File
@@ -0,0 +1,262 @@
/**
* n8n: reading what its API says (workflows in pages, the latest runs), working out each workflow's last outcome, what is stored, what is wrong, the health pass, the alerts, the
* page's route and /metrics.
*
* Run with: npm test --workspace server
*/
import { test, describe, before, after } from "node:test";
import assert from "node:assert/strict";
import { createServer as createHttpServer, type Server } from "node:http";
import { mkdtempSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import type { AddressInfo } from "node:net";
const dir = mkdtempSync(join(tmpdir(), "hm-n8n-"));
process.env.DATABASE_PATH = join(dir, "test.sqlite");
process.env.SESSION_DIR = join(dir, "sessions");
process.env.CREDENTIALS_ENCRYPTION_KEY = "ab".repeat(32);
process.env.HEALTH_STARTUP_GRACE_MS = "0";
const express = (await import("express")).default;
const { db } = await import("../src/db/client.js");
const { users, integrations, n8nState } = await import("../src/db/schema.js");
const { runMigrations } = await import("../src/db/migrate.js");
const adapter = await import("../src/integrations/n8n/adapter.js");
const n8 = await import("../src/services/n8nSync.js");
const { evaluateHealth, collectSnapshot } = await import("../src/services/healthMonitor.js");
const { subjectOfConditionKey } = await import("../src/services/maintenance.js");
const { getAlerts, invalidateAlertsCache } = await import("../src/services/alerts.js");
const { n8nRouter } = await import("../src/routes/n8n.js");
const { buildMetrics } = await import("../src/services/metrics.js");
const { setInternalFlag } = await import("../src/services/settingsStore.js");
const { eq } = await import("drizzle-orm");
await runMigrations();
const MIN = 60_000;
const DAY = 86_400_000;
const NOW = new Date("2026-10-20T12:00:00Z");
const ago = (min: number, from: Date = NOW) => new Date(from.getTime() - min * MIN).toISOString();
type Read = import("../src/integrations/n8n/adapter.js").N8nRead;
type Workflow = import("../src/integrations/n8n/adapter.js").N8nWorkflow;
const wf = (id: string, name: string, extra: Partial<Workflow> = {}): Workflow => ({ id, name, active: true, lastStatus: "success", lastAt: ago(30), failed24h: 0, ...extra });
const read = (workflows: Workflow[] = [wf("1", "Backup notifier")], extra: Partial<Read> = {}): Read => ({ workflows, executionsKnown: true, ...extra });
describe("what n8n's API says", () => {
test("workflows: id, name and whether it is switched on; ones without an id are left out", () => {
const w = adapter.parseWorkflows({ data: [{ id: "a1", name: "Notify", active: true }, { id: 7, name: "Old", active: false }, { name: "no id" }] });
assert.deepEqual(w, [{ id: "a1", name: "Notify", active: true }, { id: "7", name: "Old", active: false }]);
assert.deepEqual(adapter.parseWorkflows(null), []);
});
test("each workflow's last outcome is the newest finished run; a run still going is not an outcome; failures are counted for the last day", () => {
const workflows = [{ id: "1", name: "A", active: true }, { id: "2", name: "B", active: true }, { id: "3", name: "C", active: false }];
const runs = {
data: [
{ workflowId: "1", status: "running", startedAt: ago(1) }, // still going: the one before it counts
{ workflowId: "1", status: "error", stoppedAt: ago(20) },
{ workflowId: "1", status: "success", stoppedAt: ago(200) },
{ workflowId: "1", status: "crashed", stoppedAt: ago(300) },
{ workflowId: "1", status: "error", stoppedAt: new Date(NOW.getTime() - 2 * DAY).toISOString() }, // older than a day
{ workflowId: "2", status: "success", stoppedAt: ago(50) },
{ workflowId: "9", status: "error", stoppedAt: ago(10) }, // a workflow that is not in the list
],
};
const s = adapter.summariseRuns(workflows, runs, NOW);
assert.deepEqual(s.map((x) => [x.id, x.lastStatus, x.failed24h]), [["1", "error", 2], ["2", "success", 0], ["3", null, 0]]);
assert.equal(s[0].lastAt, ago(20));
assert.equal(s[2].lastAt, null);
});
test("order does not matter: the newest wins whichever way the list comes", () => {
const w = [{ id: "1", name: "A", active: true }];
const runs = [{ workflowId: "1", status: "success", stoppedAt: ago(5) }, { workflowId: "1", status: "error", stoppedAt: ago(60) }];
assert.equal(adapter.summariseRuns(w, { data: runs }, NOW)[0].lastStatus, "success");
assert.equal(adapter.summariseRuns(w, { data: [...runs].reverse() }, NOW)[0].lastStatus, "success");
});
describe("the adapter against an n8n that answers", () => {
let server: Server;
let url = "";
let executionsStatus = 200;
const seen: { path: string; key: string | undefined; cursor: string | null }[] = [];
before(async () => {
server = createHttpServer((req, res) => {
const u = new URL(req.url ?? "", "http://x");
seen.push({ path: u.pathname, key: req.headers["x-n8n-api-key"] as string | undefined, cursor: u.searchParams.get("cursor") });
const send = (code: number, body: unknown) => {
res.writeHead(code, { "content-type": "application/json" });
res.end(JSON.stringify(body));
};
if (req.headers["x-n8n-api-key"] !== "key") return send(401, {});
if (u.pathname === "/api/v1/workflows") {
return u.searchParams.get("cursor") === "page2"
? send(200, { data: [{ id: "3", name: "Third", active: true }], nextCursor: null })
: send(200, { data: [{ id: "1", name: "First", active: true }, { id: "2", name: "Second", active: false }], nextCursor: "page2" });
}
if (u.pathname === "/api/v1/executions") {
if (executionsStatus !== 200) return send(executionsStatus, {});
return send(200, { data: [{ workflowId: "1", status: "error", stoppedAt: new Date(Date.now() - 5 * MIN).toISOString() }, { workflowId: "3", status: "success", stoppedAt: new Date(Date.now() - 9 * MIN).toISOString() }] });
}
send(404, {});
});
await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
url = `http://127.0.0.1:${(server.address() as AddressInfo).port}`;
});
after(() => server.close());
test("it follows the cursor through every workflow, sends the key, and works out each one's last run", async () => {
const r = await adapter.createN8nAdapter({ url: `${url}/`, apiKey: "key" }).read();
assert.deepEqual(r.workflows.map((w) => [w.id, w.active, w.lastStatus, w.failed24h]), [["1", true, "error", 1], ["2", false, null, 0], ["3", true, "success", 0]]);
assert.equal(r.executionsKnown, true);
assert.deepEqual(seen.filter((s) => s.path === "/api/v1/workflows").map((s) => s.cursor), [null, "page2"]);
assert.ok(seen.every((s) => s.key === "key"));
});
test("when the runs cannot be read the workflows are still there, and their last runs are unknown, not fine", async () => {
executionsStatus = 500;
const r = await adapter.createN8nAdapter({ url, apiKey: "key" }).read();
assert.equal(r.executionsKnown, false);
assert.equal(r.workflows.length, 3);
assert.ok(r.workflows.every((w) => w.lastStatus === null));
executionsStatus = 200;
});
test("a refused key and a dead address are said plainly", async () => {
const bad = await adapter.createN8nAdapter({ url, apiKey: "nope" }).ping();
assert.equal(bad.ok, false);
assert.match(bad.error ?? "", /did not accept the API key/);
assert.equal((await adapter.createN8nAdapter({ url, apiKey: "key" }).ping()).ok, true);
assert.equal((await adapter.createN8nAdapter({ url: "http://127.0.0.1:1", apiKey: "key" }).ping()).ok, false);
});
});
});
describe("what is stored", () => {
let id = 0;
before(async () => {
id = (await db.insert(integrations).values({ type: "n8n", name: "Flows", baseUrl: "http://10.9.6.1:5678", config: JSON.stringify({ url: "http://10.9.6.1:5678", apiKey: "key" }) }).returning({ id: integrations.id }))[0].id;
});
const state = async () => (await db.select().from(n8nState).where(eq(n8nState.integrationId, id)))[0];
test("the state is replaced at each read", async () => {
await n8.storeRead(id, read([wf("1", "A"), wf("2", "B")]), new Date());
assert.deepEqual(n8.workflowsOf(await state()).map((w) => w.name), ["A", "B"]);
await n8.storeRead(id, read([wf("3", "C")], { executionsKnown: false }), new Date());
const s = await state();
assert.deepEqual([n8.workflowsOf(s).map((w) => w.name), s.executionsKnown], [["C"], false]);
});
test("a read that failed is said, and what was stored is left alone", async () => {
const ok = await n8.syncN8n(id, new Date(), async () => read([wf("1", "Kept")]));
assert.equal(ok.ok, true);
const failed = await n8.syncN8n(id, new Date(), async () => {
throw new Error("connection refused");
});
assert.deepEqual([failed.ok, failed.error], [false, "connection refused"]);
assert.equal(failed.at, ok.at);
assert.deepEqual(n8.workflowsOf(await state()).map((w) => w.name), ["Kept"]);
assert.equal(n8.isN8nFresh((await n8.n8nSyncStatuses())[id], Date.now()), false);
});
});
describe("what is wrong", () => {
const row = (workflows: Workflow[], executionsKnown = true) => ({ workflows: JSON.stringify(workflows), executionsKnown });
const keys = (r: ReturnType<typeof row>) => n8.n8nProblems(1, "Flows", r, NOW).map((p) => `${p.key}=${p.severity}`);
test("an active workflow whose last run failed is a warning, one alert for each; it says when, and if it crashed or failed more than once", () => {
const p = n8.n8nProblems(1, "Flows", row([wf("a", "Backup notifier", { lastStatus: "error", lastAt: ago(20), failed24h: 3 }), wf("b", "Mailer", { lastStatus: "crashed", lastAt: ago(300), failed24h: 1 })]), NOW);
assert.deepEqual(p.map((x) => [x.key, x.severity]), [["n8n-failed:1:a", "warning"], ["n8n-failed:1:b", "warning"]]);
assert.equal(p[0].message, "Flows: the workflow “Backup notifier” failed on its last run (20 min ago), and 3 runs failed in the last day");
assert.match(p[1].message, /“Mailer” failed on its last run \(5 h ago, crashed\)$/);
});
test("one that succeeded since, one that is switched off, one whose failure is over a week old and one never seen run say nothing", () => {
assert.deepEqual(
keys(row([wf("a", "A", { lastStatus: "success" }), wf("b", "B", { active: false, lastStatus: "error", lastAt: ago(10) }), wf("c", "C", { lastStatus: "error", lastAt: new Date(NOW.getTime() - 8 * DAY).toISOString() }), wf("d", "D", { lastStatus: null, lastAt: null })])),
[],
);
});
test("when the runs could not be read nothing is claimed", () => {
assert.deepEqual(keys(row([wf("a", "A", { lastStatus: "error", lastAt: ago(5) })], false)), []);
});
});
describe("the health pass, the page and /metrics", () => {
let nId = 0;
let app: Server;
let base = "";
const fresh = () => setInternalFlag("n8nSync", JSON.stringify({ [nId]: { at: new Date().toISOString(), ok: true, error: null } }));
const stale = () => setInternalFlag("n8nSync", JSON.stringify({ [nId]: { at: new Date(Date.now() - 30 * MIN).toISOString(), ok: true, error: null } }));
before(async () => {
await db.insert(users).values([{ oidcSub: "viewer", name: "Vic", role: "viewer" }]);
nId = (await db.insert(integrations).values({ type: "n8n", name: "Automations", baseUrl: "http://10.9.6.2:5678", config: JSON.stringify({ url: "http://10.9.6.2:5678", apiKey: "key" }) }).returning({ id: integrations.id }))[0].id;
const t = new Date();
await n8.storeRead(nId, read([wf("a", "Backup notifier", { lastStatus: "error", lastAt: ago(20, t), failed24h: 2 }), wf("b", "Fine", { lastAt: ago(5, t) }), wf("c", "Off", { active: false })]), t);
await fresh();
const a = express();
a.use((req, _res, next) => {
(req as unknown as { session: unknown }).session = { user: { sub: "viewer" } };
next();
});
a.use("/api/n8n", n8nRouter);
app = await new Promise<Server>((resolve) => {
const s = a.listen(0, "127.0.0.1", () => resolve(s));
});
base = `http://127.0.0.1:${(app.address() as AddressInfo).port}/api/n8n`;
});
after(() => {
app.close();
try {
rmSync(dir, { recursive: true, force: true });
} catch {
// Windows keeps the database file locked until the process exits.
}
});
test("the health pass judges it from what is stored, and holds it when the last read is old", async () => {
let { snapshot, held } = await collectSnapshot();
assert.deepEqual(snapshot.n8n?.map((n) => n.integrationId), [nId]);
const list = evaluateHealth(snapshot, { serverOfflineMinutes: 60, diskUsagePercent: 90 }, Date.now(), { skipServers: true });
const c = list.find((x) => x.key === `n8n-failed:${nId}:a`)!;
assert.deepEqual([c.severity, c.source], ["warning", `n8n:${nId}`]);
assert.equal(subjectOfConditionKey(c.key), `integration:${nId}`, "maintenance on it silences its alerts");
assert.equal(list.some((x) => x.key.startsWith(`n8n-failed:${nId}:b`) || x.key.startsWith(`n8n-failed:${nId}:c`)), false);
await stale();
({ snapshot, held } = await collectSnapshot());
assert.deepEqual([snapshot.n8n ?? [], held.has(`n8n:${nId}`)], [[], true]);
await fresh();
});
test("the Alerts page shows it in the Automation kind, with where to look", async () => {
invalidateAlertsCache();
const report = await getAlerts(true);
const a = report.alerts.find((x) => x.id === `automation:n8n-failed:${nId}:a`)!;
assert.deepEqual([a.severity, a.category, a.source, a.link, a.target?.type, a.target?.id], ["warning", "automation", "n8n", "/n8n", "integration", nId]);
});
test("anyone signed in sees each n8n and its workflows; an old reading says nothing is wrong", async () => {
const body = (await (await fetch(base)).json()) as { n8ns: { id: number; fresh: boolean; state: { workflows: { name: string; lastStatus: string | null }[]; executionsKnown: boolean } | null; problems: unknown[] }[] };
const n = body.n8ns.find((x) => x.id === nId)!;
assert.deepEqual([n.fresh, n.state?.executionsKnown, n.state?.workflows.map((w) => [w.name, w.lastStatus])], [true, true, [["Backup notifier", "error"], ["Fine", "success"], ["Off", "success"]]]);
assert.equal(n.problems.length, 1);
await stale();
const old = (await (await fetch(base)).json()) as typeof body;
assert.deepEqual(old.n8ns.find((x) => x.id === nId)!.problems, []);
await fresh();
});
test("/metrics has the workflows, those switched on and those failing — only while the reading is recent", async () => {
let text = await buildMetrics(new Date());
assert.match(text, /homelab_n8n_workflows\{name="Automations"\} 3/);
assert.match(text, /homelab_n8n_workflows_active\{name="Automations"\} 2/);
assert.match(text, /homelab_n8n_workflows_failing\{name="Automations"\} 1/);
await stale();
text = await buildMetrics(new Date());
assert.doesNotMatch(text, /homelab_n8n/);
});
});