/** * Suggested checks from the apps running in containers: which app an image is, which port to ask it on, what the check wants, and how that turns into suggestions and checks that * are added with the right settings. * * 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-appcatalog-")); 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, servers, integrations, endpointChecks } = await import("../src/db/schema.js"); const { runMigrations } = await import("../src/db/migrate.js"); const cat = await import("../src/services/appCatalog.js"); const { parsePorts } = await import("../src/integrations/dockhand/adapter.js"); const sug = await import("../src/services/endpointSuggestions.js"); const { endpointsRouter } = await import("../src/routes/endpoints.js"); const { isValuePath, valueProblem } = await import("../src/services/valueCheck.js"); const { eq } = await import("drizzle-orm"); await runMigrations(); describe("which app an image is", () => { test("the repository of an image, with registry, tag and digest left off", () => { assert.equal(cat.repoOf("ghcr.io/immich-app/immich-server:v3"), "immich-app/immich-server"); assert.equal(cat.repoOf("docker.n8n.io/n8nio/n8n"), "n8nio/n8n"); assert.equal(cat.repoOf("docker.gitea.com/gitea:latest"), "gitea"); assert.equal(cat.repoOf("docker.io/valkey/valkey:9@sha256:4963247afc4cd33c7d3b2d2816b9f7f8eeebab148d29056c2ca4d7cbc966f2d9"), "valkey/valkey"); assert.equal(cat.repoOf("localhost:5000/team/app:1"), "team/app"); assert.equal(cat.repoOf("adminer:latest"), "adminer"); assert.equal(cat.repoOf("louislam/dockge:latest"), "louislam/dockge", "a Docker Hub user is not a registry"); }); test("the apps in a real set of containers, and what is left alone", () => { const expected: Record = { "ghcr.io/immich-app/immich-server:v3": "immich", "ghcr.io/immich-app/immich-machine-learning:v3": null, "ghcr.io/paperless-ngx/paperless-ngx:latest": "paperless", "ghcr.io/nextcloud-releases/aio-apache:latest": "nextcloud", "ghcr.io/nextcloud-releases/aio-nextcloud:latest": null, "ghcr.io/nextcloud-releases/all-in-one:latest": null, "docker.gitea.com/gitea:latest": "gitea", "ghcr.io/goauthentik/server:2026.8.3": "authentik", "docker.n8n.io/n8nio/n8n": "n8n", "grafana/grafana:latest": "grafana", "prom/prometheus": "prometheus", "quay.io/prometheus/node-exporter:latest": null, "vaultwarden/server:latest": "vaultwarden", "ghcr.io/bitwarden/web:2026.9.0": null, "lscr.io/linuxserver/bookstack:latest": "bookstack", "ghcr.io/sysadminsmedia/homebox:latest": "homebox", "binwiederhier/ntfy": "ntfy", "gotify/server:latest": "gotify", "jc21/nginx-proxy-manager:latest": "npm", "jc21/mariadb-aria:latest": null, "ollama/ollama:latest": "ollama", "ghcr.io/open-webui/open-webui:main": "open-webui", "semaphoreui/semaphore:v2.20.16-beta1": "semaphore", "getmeili/meilisearch:v1.41.0": "meilisearch", "docker.io/technitium/dns-server:latest": "technitium", "ghcr.io/requarks/wiki:latest": "wikijs", "lscr.io/linuxserver/duplicati:latest": "duplicati", "docker.io/netboxcommunity/netbox:latest": "netbox", "gitea.labsconnect.se/bobban/homelab-manager-homelab-manager:latest": null, "sha256:117302266443aed6e3ea5da9ef815f96fbafe44be8fd992887636f46bbaa074f": null, "postgres:16-alpine": null, "alpine": null, }; for (const [image, id] of Object.entries(expected)) assert.equal(cat.appForImage(image)?.id ?? null, id, image); }); test("every catalog entry has a path, a port and, where it checks a value, a path the value check can read", () => { assert.ok(cat.APPS.length > 30); assert.equal(new Set(cat.APPS.map((a) => a.id)).size, cat.APPS.length, "ids are unique"); for (const a of cat.APPS) { assert.ok(a.path.startsWith("/") && a.ports.length > 0 && a.says, a.id); if (a.value) assert.equal(valueProblem(a.value.path, a.value.op, a.value.expected), null, `${a.id}: the value check is one the checks accept`); if (a.value) assert.ok(isValuePath(a.value.path), a.id); if (a.expectStatus) assert.match(a.expectStatus, /^\d{3}(-\d{3})?(, ?\d{3}(-\d{3})?)*$/, a.id); } }); }); describe("the ports of a container", () => { test("Docker's own list, strings, and inspect's map", () => { assert.deepEqual(parsePorts([{ IP: "0.0.0.0", PrivatePort: 80, PublicPort: 8080, Type: "tcp" }, { PrivatePort: 53, Type: "udp" }]), [ { privatePort: 80, publicPort: 8080, protocol: "tcp" }, { privatePort: 53, publicPort: null, protocol: "udp" }, ]); assert.deepEqual(parsePorts([{ privatePort: 3000, publicPort: 3001, type: "tcp" }]), [{ privatePort: 3000, publicPort: 3001, protocol: "tcp" }]); assert.deepEqual(parsePorts(["0.0.0.0:8080->80/tcp", "[::]:8443->443/tcp", "9000/tcp"]), [ { publicPort: 8080, privatePort: 80, protocol: "tcp" }, { publicPort: 8443, privatePort: 443, protocol: "tcp" }, { publicPort: null, privatePort: 9000, protocol: "tcp" }, ]); assert.deepEqual(parsePorts({ "80/tcp": [{ HostIp: "0.0.0.0", HostPort: "8081" }], "443/tcp": null }), [ { privatePort: 80, publicPort: 8081, protocol: "tcp" }, { privatePort: 443, publicPort: null, protocol: "tcp" }, ]); for (const nothing of [undefined, null, "", 5, [], {}, [{ nonsense: true }], ["not a port"]]) assert.deepEqual(parsePorts(nothing), []); }); test("the port to ask: the published one for what the app listens on, or the only one published", () => { const immich = cat.APPS.find((a) => a.id === "immich")!; assert.deepEqual(cat.portFor(immich, [{ privatePort: 2283, publicPort: 12283, protocol: "tcp" }, { privatePort: 22, publicPort: 2222, protocol: "tcp" }]), { port: 12283, inner: 2283 }); assert.deepEqual(cat.portFor(immich, [{ privatePort: 8000, publicPort: 8123, protocol: "tcp" }]), { port: 8123, inner: 8000 }, "remapped inside: the only one published"); assert.equal(cat.portFor(immich, [{ privatePort: 1, publicPort: 11, protocol: "tcp" }, { privatePort: 2, publicPort: 22, protocol: "tcp" }]), null, "two, and neither is the app's"); assert.equal(cat.portFor(immich, [{ privatePort: 53, publicPort: 53, protocol: "udp" }]), null, "udp is not web"); assert.equal(cat.portFor(immich, [{ privatePort: 2283, publicPort: null, protocol: "tcp" }]), null, "not published"); }); }); describe("what is suggested", () => { const S = (id: number, name: string, ips: string[], ports: number[] = []) => ({ id, name, hostname: null, ips, ports: ports.map((port) => ({ port, protocol: "tcp" })) }); const base = (): import("../src/services/endpointSuggestions.js").SuggestionInput => ({ servers: [S(1, "Jazz", ["10.0.0.7"]), S(2, "Jackie", ["10.0.0.5"]), S(3, "Nova", ["10.0.0.9"], [8000])], dns: [], secrets: [], existing: [], dismissed: new Set() }); const container = (environmentName: string, name: string, image: string, ports: { privatePort: number; publicPort: number | null; protocol?: string }[] = [], state = "running") => ({ environmentName, name, image, state, ports: ports.map((p) => ({ protocol: "tcp", ...p })) }); test("an app on a known Docker host is checked on its own health address, with what a good answer looks like", () => { const { suggestions } = sug.suggestChecks({ ...base(), containers: [container("Jazz", "immich_server", "ghcr.io/immich-app/immich-server:v3", [{ privatePort: 2283, publicPort: 2283 }])] }); assert.equal(suggestions.length, 1); const s = suggestions[0]; assert.deepEqual([s.key, s.name, s.target, s.serverName, s.kind], ["app|immich|10.0.0.7|2283", "Immich on Jazz", "http://10.0.0.7:2283/api/server/ping", "Jazz", "http"]); assert.deepEqual([s.valuePath, s.valueOp, s.valueExpected, s.checks], ["res", "=", "pong", "its ping answers “pong”"]); assert.match(s.reason, /immich_server runs Immich on Jazz/); }); test("the port is the one published; with no ports said, the one the host's agent sees listening; with neither, nothing", () => { const remapped = sug.suggestChecks({ ...base(), containers: [container("Jackie", "gitea", "docker.gitea.com/gitea:latest", [{ privatePort: 3000, publicPort: 3030 }, { privatePort: 22, publicPort: 222 }])] }); assert.equal(remapped.suggestions[0].target, "http://10.0.0.5:3030/api/healthz"); const viaAgent = sug.suggestChecks({ ...base(), containers: [container("Nova", "paperless-ngx-webserver-1", "ghcr.io/paperless-ngx/paperless-ngx:latest")] }); assert.deepEqual([viaAgent.suggestions[0]?.target, viaAgent.suggestions[0]?.expectStatus], ["http://10.0.0.9:8000/accounts/login/", "200"]); const neither = sug.suggestChecks({ ...base(), containers: [container("Jazz", "immich_server", "ghcr.io/immich-app/immich-server:v3")] }); assert.deepEqual(neither.suggestions, []); }); test("a TLS-only port is asked over https and accepts a certificate that is not trusted", () => { const s = sug.suggestChecks({ ...base(), containers: [container("Jazz", "authentik-server-1", "ghcr.io/goauthentik/server:2026.8.3", [{ privatePort: 9443, publicPort: 9443 }])] }).suggestions[0]; assert.deepEqual([s.target, s.insecure, s.expectStatus], ["https://10.0.0.7:9443/-/health/live/", true, "200-299"]); }); test("what is not offered: stopped containers, unknown images, hosts the app does not know, what a check already covers, and one app twice", () => { const containers = [ container("Jazz", "stopped-immich", "ghcr.io/immich-app/immich-server:v3", [{ privatePort: 2283, publicPort: 2283 }], "exited"), container("Jazz", "mystery", "ghcr.io/someone/thing:1", [{ privatePort: 80, publicPort: 80 }]), container("Elsewhere", "immich_server", "ghcr.io/immich-app/immich-server:v3", [{ privatePort: 2283, publicPort: 2283 }]), container("Jackie", "gitea", "docker.gitea.com/gitea:latest", [{ privatePort: 3000, publicPort: 3000 }]), container("Jazz", "grafana-grafana-1", "grafana/grafana:latest", [{ privatePort: 3000, publicPort: 3000 }]), container("Jazz", "grafana-again", "grafana/grafana:latest", [{ privatePort: 3000, publicPort: 3000 }]), ]; const input = { ...base(), containers, existing: [{ kind: "http", target: "http://10.0.0.5:3000/", port: null }] }; assert.deepEqual(sug.suggestChecks(input).suggestions.map((s) => s.key), ["app|grafana|10.0.0.7|3000"], "gitea is covered, grafana is offered once"); const dismissed = sug.suggestChecks({ ...input, dismissed: new Set(["app|grafana|10.0.0.7|3000"]) }); assert.deepEqual([dismissed.suggestions.length, dismissed.dismissed.length], [0, 1]); }); test("a web port the agent sees is not offered again as a bare port when an app is known to be there", () => { const withPort = { ...base(), servers: [S(1, "Jazz", ["10.0.0.7"], [8080])], dns: [{ name: "search.lab.example", type: "A", content: "10.0.0.7" }] }; const plain = sug.suggestChecks(withPort).suggestions; assert.deepEqual(plain.map((s) => s.target), ["http://search.lab.example:8080/"]); const both = sug.suggestChecks({ ...withPort, containers: [container("Jazz", "searxng", "docker.io/searxng/searxng:latest", [{ privatePort: 8080, publicPort: 8080 }])] }).suggestions; assert.deepEqual(both.map((s) => s.key), ["app|searxng|10.0.0.7|8080"], "the app's check replaces it"); }); }); describe("added through the route", () => { let dockhand: Server; let app: Server; let base = ""; let who = "admin"; before(async () => { await db.insert(users).values([ { oidcSub: "admin", name: "Ada", role: "admin" }, { oidcSub: "viewer", name: "Vic", role: "viewer" }, ]); await db.insert(servers).values({ name: "Jazz", apiTokenHash: "j", apiTokenPrefix: "j", ipAddresses: JSON.stringify(["10.0.0.7"]) }); dockhand = createHttpServer((req, res) => { const url = new URL(req.url ?? "", "http://x"); res.setHeader("content-type", "application/json"); if (url.pathname === "/api/environments") return void res.end(JSON.stringify([{ id: 1, name: "Jazz", connectionType: "hawser" }])); if (url.pathname === "/api/containers/pending-updates") return void res.end(JSON.stringify({ pendingUpdates: [] })); if (url.pathname === "/api/containers") return void res.end(JSON.stringify([{ id: "a", name: "immich_server", image: "ghcr.io/immich-app/immich-server:v3", state: "running", status: "Up 2 days", ports: [{ IP: "0.0.0.0", PrivatePort: 2283, PublicPort: 2283, Type: "tcp" }] }])); res.statusCode = 404; res.end("{}"); }); await new Promise((r) => dockhand.listen(0, "127.0.0.1", r)); await db.insert(integrations).values({ type: "dockhand", name: "Dockhand", baseUrl: "", config: JSON.stringify({ url: `http://127.0.0.1:${(dockhand.address() as AddressInfo).port}`, token: "t" }) }); const a = express(); a.use(express.json()); a.use((req, _res, next) => { (req as unknown as { session: unknown }).session = { user: { sub: who } }; next(); }); a.use("/api/endpoints", endpointsRouter); app = await new Promise((resolve) => { const s = a.listen(0, "127.0.0.1", () => resolve(s)); }); base = `http://127.0.0.1:${(app.address() as AddressInfo).port}/api/endpoints`; }); after(() => { dockhand.close(); app.close(); try { rmSync(dir, { recursive: true, force: true }); } catch { // Windows keeps the database file locked until the process exits. } }); const call = (method: string, path: string, body?: unknown) => fetch(`${base}${path}`, { method, headers: { "content-type": "application/json", connection: "close" }, body: body === undefined ? undefined : JSON.stringify(body) }); test("the app is offered, adding it makes a check that asks the right thing, and then it is no longer offered", async () => { sug.resetContainerCacheForTests(); const list = (await (await call("GET", "/suggestions")).json()) as { suggestions: { key: string; name: string; target: string; checks?: string }[] }; const s = list.suggestions.find((x) => x.key.startsWith("app|immich"))!; assert.deepEqual([s.name, s.target, s.checks], ["Immich on Jazz", "http://10.0.0.7:2283/api/server/ping", "its ping answers “pong”"]); const added = await call("POST", "/suggestions/add", { keys: [s.key] }); assert.equal(added.status, 201); const [check] = await db.select().from(endpointChecks).where(eq(endpointChecks.name, "Immich on Jazz")); assert.deepEqual([check.kind, check.target, check.valuePath, check.valueOp, check.valueExpected, check.serverId !== null], ["http", "http://10.0.0.7:2283/api/server/ping", "res", "=", "pong", true]); sug.resetContainerCacheForTests(); const again = (await (await call("GET", "/suggestions")).json()) as { suggestions: { key: string }[] }; assert.ok(!again.suggestions.some((x) => x.key.startsWith("app|immich")), "covered now"); }); test("only an administrator is offered them", async () => { who = "viewer"; assert.equal((await call("GET", "/suggestions")).status, 403); assert.equal((await call("POST", "/suggestions/add", { keys: ["app|immich|10.0.0.7|2283"] })).status, 403); who = "admin"; }); });