diff --git a/packages/definitions/src/integration.ts b/packages/definitions/src/integration.ts index f43d821bf..2984a2519 100644 --- a/packages/definitions/src/integration.ts +++ b/packages/definitions/src/integration.ts @@ -364,7 +364,7 @@ export const integrationDefs = { }, truenas: { name: "TrueNAS", - secretKinds: [["username", "password"]], + secretKinds: [["username", "password"], ["apiKey"]], iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/truenas.svg", category: ["healthMonitoring"], documentationUrl: createDocumentationLink("/docs/integrations/truenas"), diff --git a/packages/integrations/package.json b/packages/integrations/package.json index 88ea6892a..6e0c81039 100644 --- a/packages/integrations/package.json +++ b/packages/integrations/package.json @@ -47,12 +47,14 @@ "timezones-ical-library": "catalog:", "tsdav": "catalog:", "undici": "catalog:", + "ws": "catalog:", "xml2js": "catalog:", "zod": "catalog:" }, "devDependencies": { "@homarr/tsconfig": "workspace:^0.1.0", "@types/node-unifi": "catalog:", + "@types/ws": "catalog:", "@types/xml2js": "catalog:", "typescript": "catalog:" } diff --git a/packages/integrations/src/base/integration.ts b/packages/integrations/src/base/integration.ts index 22ad8b1ea..e129ca283 100644 --- a/packages/integrations/src/base/integration.ts +++ b/packages/integrations/src/base/integration.ts @@ -85,6 +85,16 @@ export abstract class Integration { return this.createUrl(this.integration.externalUrl ?? this.integration.url, path, queryParams); } + protected webSocketUrl( + path: `/${string}`, + queryParams?: Record, + ) { + const url = this.url(path, queryParams); + // http -> ws, https -> wss + url.protocol = url.protocol.replace("http", "ws"); + return url; + } + public async testConnectionAsync(): Promise { try { const url = new URL(this.integration.url); diff --git a/packages/integrations/src/truenas/test/truenas-api.spec.ts b/packages/integrations/src/truenas/test/truenas-api.spec.ts new file mode 100644 index 000000000..cc75bcc07 --- /dev/null +++ b/packages/integrations/src/truenas/test/truenas-api.spec.ts @@ -0,0 +1,79 @@ +import { describe, expect, test } from "vitest"; + +import { trueNasApis } from "../truenas-api"; + +describe("trueNasApis descriptors", () => { + test("expose the expected endpoints and handshake requirements", () => { + expect(trueNasApis.jsonRpc).toMatchObject({ + kind: "jsonRpc", + path: "/api/current", + requiresSessionHandshake: false, + }); + expect(trueNasApis.legacy).toMatchObject({ + kind: "legacy", + path: "/websocket", + requiresSessionHandshake: true, + }); + }); +}); + +describe("jsonRpc api", () => { + const { buildRequest, matchResponse } = trueNasApis.jsonRpc; + + test("builds a JSON-RPC 2.0 envelope", () => { + expect(buildRequest("id-1", "system.info", [])).toStrictEqual({ + jsonrpc: "2.0", + id: "id-1", + method: "system.info", + params: [], + }); + }); + + test("matches a result for the requested id", () => { + const result = matchResponse({ jsonrpc: "2.0", id: "id-1", result: true }, "id-1"); + expect(result).toStrictEqual({ result: true }); + }); + + test("returns the error when the response carries one", () => { + const error = { code: -32001, message: "Not authenticated" }; + expect(matchResponse({ jsonrpc: "2.0", id: "id-1", error }, "id-1")).toStrictEqual({ error }); + }); + + test("ignores responses for a different id", () => { + expect(matchResponse({ jsonrpc: "2.0", id: "other", result: true }, "id-1")).toBeUndefined(); + }); + + test("ignores non JSON-RPC messages", () => { + expect(matchResponse({ msg: "result", id: "id-1", result: true }, "id-1")).toBeUndefined(); + }); +}); + +describe("legacy api", () => { + const { buildRequest, matchResponse } = trueNasApis.legacy; + + test("builds a DDP method envelope", () => { + expect(buildRequest("id-1", "auth.login", ["user", "pass"])).toStrictEqual({ + id: "id-1", + msg: "method", + method: "auth.login", + params: ["user", "pass"], + }); + }); + + test("matches a result message for the requested id", () => { + expect(matchResponse({ msg: "result", id: "id-1", result: false }, "id-1")).toStrictEqual({ result: false }); + }); + + test("returns the error when the result message carries one", () => { + const error = { error: 13, reason: "boom" }; + expect(matchResponse({ msg: "result", id: "id-1", error }, "id-1")).toStrictEqual({ error }); + }); + + test("ignores responses for a different id", () => { + expect(matchResponse({ msg: "result", id: "other", result: true }, "id-1")).toBeUndefined(); + }); + + test("ignores non-result messages such as the session handshake", () => { + expect(matchResponse({ msg: "connected", session: "abc" }, "id-1")).toBeUndefined(); + }); +}); diff --git a/packages/integrations/src/truenas/test/truenas-integration.spec.ts b/packages/integrations/src/truenas/test/truenas-integration.spec.ts new file mode 100644 index 000000000..28ff3b8d1 --- /dev/null +++ b/packages/integrations/src/truenas/test/truenas-integration.spec.ts @@ -0,0 +1,264 @@ +import { beforeEach, describe, expect, test, vi } from "vitest"; + +import { IntegrationRequestError } from "../../base/errors/http/integration-request-error"; +import type { IntegrationSecret } from "../../base/types"; + +const ws = vi.hoisted(() => { + const sentPayloads: Record[] = []; + const constructedUrls: string[] = []; + // A failure with a `code` emits a coded TLS-style error; without one it mimics a missing endpoint (HTTP 404). + const failures: { path: string; code?: string }[] = []; + let responder: (method: string, params: unknown[]) => unknown = () => undefined; + + type Listener = (...args: unknown[]) => void; + + class FakeWebSocket { + static readonly OPEN = 1; + public readyState = FakeWebSocket.OPEN; + private readonly listeners: Record = {}; + + constructor(url: URL | string) { + constructedUrls.push(url.toString()); + setTimeout(() => { + const failure = failures.find((candidate) => url.toString().includes(candidate.path)); + if (failure) { + const error: Error & { code?: string } = new Error(failure.code ?? "Unexpected server response: 404"); + if (failure.code) error.code = failure.code; + this.dispatch("error", error); + } else { + this.dispatch("open"); + } + }, 0); + } + + on(event: string, listener: Listener) { + (this.listeners[event] ??= []).push(listener); + return this; + } + + once(event: string, listener: Listener) { + const wrapper: Listener = (...args) => { + this.off(event, wrapper); + listener(...args); + }; + return this.on(event, wrapper); + } + + off(event: string, listener: Listener) { + this.listeners[event] = (this.listeners[event] ?? []).filter((candidate) => candidate !== listener); + return this; + } + + send(raw: string) { + const payload = JSON.parse(raw) as Record; + sentPayloads.push(payload); + + if (payload.msg === "connect") { + this.respond(JSON.stringify({ msg: "connected", session: "test-session" })); + return; + } + + const result = responder(payload.method as string, (payload.params as unknown[] | undefined) ?? []); + const envelope = + payload.jsonrpc === "2.0" + ? { jsonrpc: "2.0", id: payload.id, result } + : { msg: "result", id: payload.id, result }; + this.respond(JSON.stringify(envelope)); + } + + close() { + this.readyState = 3; + } + + private respond(message: string) { + setTimeout(() => this.dispatch("message", message), 0); + } + + private dispatch(event: string, ...args: unknown[]) { + // `off` replaces the array rather than mutating it, so iterating it directly is safe. + for (const listener of this.listeners[event] ?? []) listener(...args); + } + } + + return { + FakeWebSocket, + sentPayloads, + constructedUrls, + failures, + setResponder: (fn: (method: string, params: unknown[]) => unknown) => { + responder = fn; + }, + }; +}); + +vi.mock("ws", () => ({ WebSocket: ws.FakeWebSocket })); +vi.mock("@homarr/core/infrastructure/certificates", () => ({ + getAllTrustedCertificatesAsync: vi.fn().mockResolvedValue([]), + getTrustedCertificateHostnamesAsync: vi.fn().mockResolvedValue([]), +})); +vi.mock("@homarr/core/infrastructure/http", () => ({ + createCustomCheckServerIdentity: () => () => undefined, +})); + +import { TrueNasIntegration } from "../truenas-integration"; + +const happyResponder = (method: string) => { + switch (method) { + case "auth.login": + case "auth.login_with_api_key": + return true; + case "system.info": + return { + version: "TrueNAS-SCALE-24.10", + hostname: "nas", + physmem: 16_000_000_000, + model: "Intel Xeon", + uptime_seconds: 3600, + }; + case "reporting.get_data": + return [ + { + name: "cpu", + identifier: "cpu", + aggregations: emptyAggregations(), + start: 0, + end: 1, + legend: [], + data: [[1000, 12]], + }, + { + name: "memory", + identifier: "memory", + aggregations: emptyAggregations(), + start: 0, + end: 1, + legend: [], + data: [[1000, 8_000_000_000]], + }, + { + name: "cputemp", + identifier: "cputemp", + aggregations: emptyAggregations(), + start: 0, + end: 1, + legend: [], + data: [[1000, 45]], + }, + ]; + case "pool.query": + return [{ name: "tank", status: "ONLINE", healthy: true, free: 500, size: 1000, allocated: 500 }]; + case "interface.query": + return [{ id: "eth0", name: "eth0" }]; + case "reporting.netdata_get_data": + return [{ name: "interface", identifier: "eth0", data: [[1000, 100, 200]] }]; + default: + return null; + } +}; + +const emptyAggregations = () => ({ min: {}, mean: {}, max: {} }); + +let integrationCounter = 0; +const createIntegration = (decryptedSecrets: IntegrationSecret[]) => + new TrueNasIntegration({ + id: `truenas-${(integrationCounter += 1)}`, + name: "TrueNAS Test", + url: "https://truenas.local", + externalUrl: null, + decryptedSecrets, + }); + +const credentials: IntegrationSecret[] = [ + { kind: "username", value: "root" }, + { kind: "password", value: "secret" }, +]; + +describe("TrueNasIntegration", () => { + beforeEach(() => { + ws.sentPayloads.length = 0; + ws.constructedUrls.length = 0; + ws.failures.length = 0; + ws.setResponder(happyResponder); + }); + + test("fetches and maps system info over the JSON-RPC API", async () => { + const integration = createIntegration(credentials); + + const result = await integration.getSystemInfoAsync(); + + expect(ws.constructedUrls).toContain("wss://truenas.local/api/current"); + // JSON-RPC does not use the legacy "connect" session handshake. + expect(ws.sentPayloads.some((payload) => payload.msg === "connect")).toBe(false); + + expect(result).toMatchObject({ + version: "TrueNAS-SCALE-24.10", + cpuModelName: "Intel Xeon", + cpuTemp: 45, + memAvailableInBytes: 16_000_000_000, + memUsedInBytes: 8_000_000_000, + uptime: 3600, + rebootRequired: false, + availablePkgUpdates: 0, + loadAverage: null, + gpu: [], + network: { up: 20_000, down: 10_000 }, + fileSystem: [{ deviceName: "tank", available: "1000", used: "500", percentage: 50 }], + smart: [{ deviceName: "tank", healthy: true, overallStatus: "ONLINE", temperature: null }], + }); + }); + + test("authenticates with an API key when one is configured", async () => { + const integration = createIntegration([{ kind: "apiKey", value: "api-key-123" }]); + + await integration.getSystemInfoAsync(); + + const authPayload = ws.sentPayloads.find((payload) => String(payload.method).startsWith("auth.")); + expect(authPayload).toMatchObject({ method: "auth.login_with_api_key", params: ["api-key-123"] }); + }); + + test("authenticates with username and password when no API key is configured", async () => { + const integration = createIntegration(credentials); + + await integration.getSystemInfoAsync(); + + const authPayload = ws.sentPayloads.find((payload) => String(payload.method).startsWith("auth.")); + expect(authPayload).toMatchObject({ method: "auth.login", params: ["root", "secret"] }); + }); + + test("falls back to the legacy websocket API when the JSON-RPC endpoint is unavailable", async () => { + ws.failures.push({ path: "/api/current" }); + const integration = createIntegration(credentials); + + const result = await integration.getSystemInfoAsync(); + + expect(ws.constructedUrls).toContain("wss://truenas.local/api/current"); + expect(ws.constructedUrls).toContain("wss://truenas.local/websocket"); + // The legacy API requires the "connect" session handshake before authenticating. + expect(ws.sentPayloads[0]).toMatchObject({ msg: "connect" }); + expect(ws.sentPayloads.find((payload) => String(payload.method).startsWith("auth."))).toMatchObject({ + msg: "method", + method: "auth.login", + }); + expect(result.version).toBe("TrueNAS-SCALE-24.10"); + }); + + test("rejects when authentication is not successful", async () => { + ws.setResponder((method) => (method.startsWith("auth.") ? false : happyResponder(method))); + const integration = createIntegration(credentials); + + await expect(integration.getSystemInfoAsync()).rejects.toThrow(); + }); + + test("surfaces a self-signed certificate as a certificate request error without falling back", async () => { + ws.failures.push({ path: "/api/current", code: "DEPTH_ZERO_SELF_SIGNED_CERT" }); + ws.failures.push({ path: "/websocket", code: "DEPTH_ZERO_SELF_SIGNED_CERT" }); + const integration = createIntegration(credentials); + + const error = await integration.getSystemInfoAsync().catch((caught: unknown) => caught); + + expect(error).toBeInstanceOf(IntegrationRequestError); + expect((error as IntegrationRequestError).cause).toMatchObject({ type: "certificate", reason: "untrusted" }); + // A certificate failure is endpoint-independent, so the legacy API must not be tried. + expect(ws.constructedUrls).not.toContain("wss://truenas.local/websocket"); + }); +}); diff --git a/packages/integrations/src/truenas/truenas-api.ts b/packages/integrations/src/truenas/truenas-api.ts new file mode 100644 index 000000000..322c3e856 --- /dev/null +++ b/packages/integrations/src/truenas/truenas-api.ts @@ -0,0 +1,50 @@ +export type TrueNasApiKind = "jsonRpc" | "legacy"; + +export type TrueNasResponse = { result: unknown } | { error: unknown }; + +export interface TrueNasApi { + kind: TrueNasApiKind; + /** Websocket path appended to the integration URL. */ + path: `/${string}`; + /** The legacy DDP API requires a "connect" handshake before authentication, the JSON-RPC API does not. */ + requiresSessionHandshake: boolean; + /** Builds the request envelope for a method call. */ + buildRequest: (id: string, method: string, params: unknown[]) => Record; + /** + * Returns the response payload when `message` is the reply to `id`, + * otherwise `undefined` so the caller keeps waiting for a later message. + */ + matchResponse: (message: Record, id: string) => TrueNasResponse | undefined; +} + +/** + * JSON-RPC 2.0 API introduced in TrueNAS SCALE 24.10 (Electric Eel) and the + * legacy DDP-style websocket API used before it. Both expose the same + * middleware methods, so only the transport envelope differs. + * @see https://www.truenas.com/docs/api/scale_rest_api.html + * @see https://www.truenas.com/docs/api/scale_websocket_api.html#websocket_protocol + */ +export const trueNasApis = { + jsonRpc: { + kind: "jsonRpc", + path: "/api/current", + requiresSessionHandshake: false, + buildRequest: (id: string, method: string, params: unknown[]) => ({ jsonrpc: "2.0", id, method, params }), + matchResponse: (message: Record, id: string) => { + if (message.id !== id || message.jsonrpc !== "2.0") return undefined; + if (message.error != null) return { error: message.error }; + return { result: message.result }; + }, + }, + legacy: { + kind: "legacy", + path: "/websocket", + requiresSessionHandshake: true, + buildRequest: (id: string, method: string, params: unknown[]) => ({ id, msg: "method", method, params }), + matchResponse: (message: Record, id: string) => { + if (message.id !== id || message.msg !== "result") return undefined; + if (message.error != null) return { error: message.error }; + return { result: message.result }; + }, + }, +} satisfies Record; diff --git a/packages/integrations/src/truenas/truenas-client.ts b/packages/integrations/src/truenas/truenas-client.ts new file mode 100644 index 000000000..e0f04f447 --- /dev/null +++ b/packages/integrations/src/truenas/truenas-client.ts @@ -0,0 +1,315 @@ +import type { RawData } from "ws"; +import { WebSocket } from "ws"; +import z from "zod"; + +import { createId } from "@homarr/common"; +import { matchErrorCode, RequestError, ResponseError } from "@homarr/common/server"; +import { + getAllTrustedCertificatesAsync, + getTrustedCertificateHostnamesAsync, +} from "@homarr/core/infrastructure/certificates"; +import { createCustomCheckServerIdentity } from "@homarr/core/infrastructure/http"; +import { createLogger } from "@homarr/core/infrastructure/logs"; + +import type { IntegrationTestingInput } from "../base/integration"; +import type { TrueNasApi } from "./truenas-api"; +import { trueNasApis } from "./truenas-api"; + +const logger = createLogger({ module: "trueNasClient" }); + +const REQUEST_TIMEOUT_MS = 5000; + +type CertificateOptions = IntegrationTestingInput["options"]; + +export type TrueNasCredentials = { apiKey: string } | { username: string; password: string }; + +/** + * Handles talking to a TrueNAS server: opening a websocket with Homarr's + * trusted certificates, negotiating the API variant, authenticating, and + * sending method requests. Connections are reused across the per-request + * integration instances and reconnected transparently when the server drops + * an idle socket. + */ +export class TrueNasClient { + // Keyed by integration id. The value is the in-flight connection promise so concurrent + // callers reuse a single socket instead of racing to open duplicates. + private static readonly connectionMap = new Map>(); + private static readonly apiMap = new Map(); + + constructor( + private readonly id: string, + private readonly webSocketUrl: (path: `/${string}`) => URL, + private readonly credentials: TrueNasCredentials, + ) {} + + /** Sends an authenticated request, reusing the cached connection while it is open. */ + public async requestAsync(method: string, params: unknown[] = []): Promise { + const socket = await this.getSocketAsync(); + return socket.requestAsync(method, params); + } + + /** + * Opens a connection with the provided certificate options, authenticates, + * and closes it. Used by the connection test, which may run with updated + * credentials, so any cached connection is dropped and the API re-detected. + */ + public async testAsync(certificate: CertificateOptions): Promise { + this.evictConnection(); + TrueNasClient.apiMap.delete(this.id); + + const socket = await this.openSocketAsync(certificate); + try { + await this.authenticateAsync(socket); + } finally { + socket.close(); + } + } + + private getSocketAsync(): Promise { + let connection = TrueNasClient.connectionMap.get(this.id); + if (!connection) { + connection = this.connectAndAuthenticateAsync(); + TrueNasClient.connectionMap.set(this.id, connection); + + const evict = () => { + if (TrueNasClient.connectionMap.get(this.id) === connection) { + TrueNasClient.connectionMap.delete(this.id); + } + }; + // Reconnect on the next request once this attempt fails or the server drops the socket. + connection.then((socket) => socket.onClose(evict), evict); + } + + return connection; + } + + private async connectAndAuthenticateAsync(): Promise { + const socket = await this.openSocketAsync(await resolveCertificateOptionsAsync()); + try { + await this.authenticateAsync(socket); + } catch (error) { + // Never keep an unauthenticated socket, it would be reused without re-authenticating. + socket.close(); + throw error; + } + return socket; + } + + private evictConnection() { + const connection = TrueNasClient.connectionMap.get(this.id); + if (!connection) return; + + TrueNasClient.connectionMap.delete(this.id); + connection.then((socket) => socket.close()).catch(() => undefined); + } + + /** + * Connects using the JSON-RPC API (TrueNAS 24.10+) when available and falls + * back to the legacy websocket API otherwise. A missing JSON-RPC endpoint + * surfaces as a plain protocol error; certificate, connection, DNS and + * timeout errors are endpoint-independent and are never retried. + */ + private async openSocketAsync(certificate: CertificateOptions): Promise { + const cachedApi = TrueNasClient.apiMap.get(this.id); + if (cachedApi) { + return openTrueNasSocketAsync(this.webSocketUrl(cachedApi.path), cachedApi, certificate); + } + + try { + const socket = await openTrueNasSocketAsync( + this.webSocketUrl(trueNasApis.jsonRpc.path), + trueNasApis.jsonRpc, + certificate, + ); + TrueNasClient.apiMap.set(this.id, trueNasApis.jsonRpc); + return socket; + } catch (error) { + if (error instanceof RequestError) throw error; + + logger.debug("JSON-RPC API unavailable, falling back to the legacy websocket API", { + error: error instanceof Error ? error.message : undefined, + }); + const socket = await openTrueNasSocketAsync( + this.webSocketUrl(trueNasApis.legacy.path), + trueNasApis.legacy, + certificate, + ); + TrueNasClient.apiMap.set(this.id, trueNasApis.legacy); + return socket; + } + } + + /** + * Authenticates with an API key when one is configured, otherwise with the + * username and password. Both methods work on either API. + * @see https://www.truenas.com/docs/api/scale_websocket_api.html#websocket_protocol + */ + private async authenticateAsync(socket: TrueNasSocket): Promise { + const response = + "apiKey" in this.credentials + ? await socket.requestAsync("auth.login_with_api_key", [this.credentials.apiKey]) + : await socket.requestAsync("auth.login", [this.credentials.username, this.credentials.password]); + + const success = await z.boolean().parseAsync(response); + if (!success) throw new ResponseError({ status: 401 }); + } +} + +/** + * Wraps a single websocket connection and speaks whichever TrueNAS API + * ({@link trueNasApis}) was negotiated when it was opened. + */ +class TrueNasSocket { + constructor( + private readonly webSocket: WebSocket, + private readonly api: TrueNasApi, + ) {} + + public close() { + this.webSocket.close(); + } + + public onClose(listener: () => void) { + this.webSocket.once("close", listener); + } + + /** + * The legacy DDP API requires a "connect" handshake to obtain a session + * before any method can be called. + * @see https://www.truenas.com/docs/api/scale_websocket_api.html#websocket_protocol + */ + public registerSessionAsync(): Promise { + return new Promise((resolve, reject) => { + const handler = (raw: RawData) => { + const message = parseMessage(raw); + if (message?.msg === "connected") { + this.webSocket.off("message", handler); + resolve(); + } else if (message?.msg === "failed") { + this.webSocket.off("message", handler); + reject(new Error("Unable to establish TrueNAS session")); + } + }; + + this.webSocket.on("message", handler); + this.webSocket.send(JSON.stringify({ msg: "connect", version: "1", support: ["1"] })); + }); + } + + /** + * Sends a method request and resolves with its result. Rejects after + * {@link REQUEST_TIMEOUT_MS} when no matching response was received. + */ + public requestAsync(method: string, params: unknown[] = []): Promise { + return new Promise((resolve, reject) => { + const id = createId(); + + const cleanup = () => { + clearTimeout(timeoutId); + this.webSocket.off("message", handler); + this.webSocket.off("close", onClose); + this.webSocket.off("error", onError); + }; + + const handler = (raw: RawData) => { + const message = parseMessage(raw); + if (!message) return; + + const response = this.api.matchResponse(message, id); + if (!response) return; + + cleanup(); + if ("error" in response) { + reject(new Error(`TrueNAS method "${method}" failed: ${JSON.stringify(response.error)}`)); + return; + } + logger.debug("Received method response", { id, method, api: this.api.kind }); + resolve(response.result); + }; + + // A dropped connection would otherwise leave the request hanging until the timeout below. + const onClose = () => { + cleanup(); + reject( + new RequestError( + { type: "connection", reason: "reset", code: "ECONNRESET" }, + { cause: new Error("Connection closed before a response was received") }, + ), + ); + }; + const onError = (error: Error) => { + cleanup(); + reject(error); + }; + + const timeoutId = setTimeout(() => { + cleanup(); + reject( + new RequestError( + { + type: "timeout", + reason: "aborted", + code: "ECONNABORTED", + }, + { cause: new Error("Canceled request after 5 seconds") }, + ), + ); + }, REQUEST_TIMEOUT_MS); + + this.webSocket.on("message", handler); + this.webSocket.once("close", onClose); + this.webSocket.once("error", onError); + logger.debug("Sending method request", { id, method, api: this.api.kind }); + this.webSocket.send(JSON.stringify(this.api.buildRequest(id, method, params))); + }); + } +} + +/** + * Opens a websocket using Homarr's trusted certificates and performs the + * session handshake when the API requires it. TLS, connection, DNS and timeout + * failures are translated into {@link RequestError}s so the connection test can + * offer to trust a self-signed certificate, exactly like the HTTP integrations. + */ +const openTrueNasSocketAsync = async ( + url: URL, + api: TrueNasApi, + certificate: CertificateOptions, +): Promise => { + logger.debug("Connecting to TrueNAS websocket", { url: url.toString(), api: api.kind }); + + const webSocket = await new Promise((resolve, reject) => { + const socket = new WebSocket(url, { + ca: certificate.ca, + // The @types/ws contract types this as returning a boolean, but ws forwards it to + // tls.connect which uses Node's `Error | undefined` contract that our helper follows. + checkServerIdentity: certificate.checkServerIdentity as never, + }); + + socket.once("open", () => resolve(socket)); + socket.once("error", (error: Error & { code?: string }) => { + const matched = error.code ? matchErrorCode(error.code) : undefined; + reject(matched ? new RequestError(matched, { cause: error }) : error); + }); + }); + + const socket = new TrueNasSocket(webSocket, api); + if (api.requiresSessionHandshake) await socket.registerSessionAsync(); + return socket; +}; + +const resolveCertificateOptionsAsync = async (): Promise => ({ + ca: await getAllTrustedCertificatesAsync(), + checkServerIdentity: createCustomCheckServerIdentity(await getTrustedCertificateHostnamesAsync()), +}); + +const parseMessage = (raw: RawData): Record | undefined => { + try { + const parsed: unknown = JSON.parse(raw.toString()); + return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) + ? (parsed as Record) + : undefined; + } catch { + return undefined; + } +}; diff --git a/packages/integrations/src/truenas/truenas-integration.ts b/packages/integrations/src/truenas/truenas-integration.ts index 8d64f848c..adbe32b3b 100644 --- a/packages/integrations/src/truenas/truenas-integration.ts +++ b/packages/integrations/src/truenas/truenas-integration.ts @@ -1,8 +1,6 @@ import dayjs from "dayjs"; import z from "zod"; -import { createId } from "@homarr/common"; -import { RequestError, ResponseError } from "@homarr/common/server"; import { createLogger } from "@homarr/core/infrastructure/logs"; import type { IntegrationTestingInput } from "../base/integration"; @@ -10,252 +8,21 @@ import { Integration } from "../base/integration"; import type { TestingResult } from "../base/test-connection/test-connection-service"; import type { ISystemHealthMonitoringIntegration } from "../interfaces/health-monitoring/health-monitoring-integration"; import type { SystemHealthMonitoring } from "../interfaces/health-monitoring/health-monitoring-types"; +import type { TrueNasCredentials } from "./truenas-client"; +import { TrueNasClient } from "./truenas-client"; const logger = createLogger({ module: "trueNasIntegration" }); const NETWORK_MULTIPLIER = 100; export class TrueNasIntegration extends Integration implements ISystemHealthMonitoringIntegration { - private static webSocketMap = new Map(); - - private wsUrl() { - const url = super.url("/websocket"); - url.protocol = url.protocol.replace("http", "ws"); - return url; - } - - private get webSocket() { - return TrueNasIntegration.webSocketMap.get(this.integration.id) ?? null; - } - - protected async testingAsync(_input: IntegrationTestingInput): Promise { - const webSocket = await this.connectWebSocketAsync(); - await this.registerSessionAsync(webSocket); - await this.authenticateWebSocketAsync(webSocket); - - // Remove current socket connection so we can authenticate with updated credentials - TrueNasIntegration.webSocketMap.delete(this.integration.id); + private client?: TrueNasClient; + protected async testingAsync(input: IntegrationTestingInput): Promise { + await this.getClient().testAsync(input.options); return { success: true }; } - /** - * TrueNAS API uses WebSocket. This function connects to the socket - * and resolves the promise if the connection was successful. - * @see https://www.truenas.com/docs/api/scale_websocket_api.html - */ - private async connectWebSocketAsync(): Promise { - logger.debug("Connecting to websocket server", { - url: this.wsUrl(), - }); - const webSocket = new WebSocket(this.wsUrl()); - - return new Promise((resolve, reject) => { - webSocket.onopen = () => { - logger.debug("Connected to websocket server", { - url: this.wsUrl(), - }); - resolve(webSocket); - }; - - webSocket.onerror = () => { - reject(new Error("Failed to connect")); - }; - }); - } - - /** - * Before authentication, a session must be obtained from the server using the "connect" event. - * @see https://www.truenas.com/docs/api/scale_websocket_api.html#websocket_protocol - */ - private async registerSessionAsync(webSocket: WebSocket): Promise { - return new Promise((resolve, reject) => { - const subscribe = (event: MessageEvent) => { - const data = JSON.parse(event.data) as { msg: string }; - if (data.msg === "connected") { - webSocket.removeEventListener("message", subscribe); - resolve(); - } else if (data.msg === "failed") { - webSocket.removeEventListener("message", subscribe); - reject(new Error("Unable to establish connection")); - } - }; - - webSocket.addEventListener("message", subscribe); - webSocket.send( - JSON.stringify({ - msg: "connect", - version: "1", // this must be number, not string - support: ["1"], // this must be number, not string - }), - ); - }); - } - - /** - * After a session was obtained, the session can be authenticated. - * @see https://www.truenas.com/docs/api/scale_websocket_api.html#websocket_protocol - */ - private async authenticateWebSocketAsync(webSocket?: WebSocket): Promise { - logger.debug("Authenticating with username and password", { - url: this.wsUrl(), - }); - const response = await this.requestAsync( - "auth.login", - [this.getSecretValue("username"), this.getSecretValue("password")], - webSocket, - ); - const result = await z.boolean().parseAsync(response); - if (!result) throw new ResponseError({ status: 401 }); - logger.debug("Authenticated successfully with username and password", { - url: this.wsUrl(), - }); - } - - private async getPoolsAsync() { - logger.debug("Retrieving pools", { - url: this.wsUrl(), - }); - - const response = await this.requestAsync("pool.query", [ - [], - { - extra: { - is_upgraded: true, - }, - }, - ]); - const result = await poolSchema.parseAsync(response); - // Offline / exported pools have null values for allocated, size and free, so we filter them out - // See https://github.com/homarr-labs/homarr/issues/5194 - const activePools = result - .map((pool) => { - if (pool.allocated !== null && pool.size !== null && pool.free !== null) { - return { - ...pool, - allocated: pool.allocated, - size: pool.size, - free: pool.free, - }; - } - - return null; - }) - .filter((pool) => pool !== null); - logger.debug("Retrieved pools", { - url: this.wsUrl(), - totalCount: result.length, - activeCount: activePools.length, - }); - return activePools; - } - - /** - * Retrieves data using the reporting method - * @see https://www.truenas.com/docs/api/scale_websocket_api.html#reporting - */ - private async getReportingAsync(): Promise { - logger.debug("Retrieving reporting data", { - url: this.wsUrl(), - }); - - const response = await this.requestAsync("reporting.get_data", [ - [ - { - name: "cpu", - }, - { - name: "memory", - }, - { - name: "cputemp", - }, - ], - { - aggregate: true, - start: dayjs().add(-5, "minutes").unix(), - end: dayjs().unix(), - }, - ]); - const result = await z.array(reportingItemSchema).parseAsync(response); - - logger.debug("Retrieved reporting data", { - url: this.wsUrl(), - count: result.length, - }); - return result; - } - - /** - * Retrieves a list of all available network interfaces - * @see https://www.truenas.com/docs/core/13.0/api/core_websocket_api.html#interface - */ - private async getNetworkInterfacesAsync(): Promise> { - logger.debug("Retrieving available network-interfaces", { - url: this.wsUrl(), - }); - - const response = await this.requestAsync("interface.query", [ - [], // no filters - {}, - ]); - const result = await networkInterfaceSchema.parseAsync(response); - - logger.debug("Retrieved available network-interfaces", { - url: this.wsUrl(), - count: result.length, - }); - return result; - } - - /** - * Retrieves reporting network data of the last 5 minutes - * @see https://www.truenas.com/docs/api/scale_websocket_api.html#reporting - */ - private async getReportingNetdataAsync(): Promise> { - const networkInterfaces = await this.getNetworkInterfacesAsync(); - - logger.debug("Retrieving reporting network data", { - url: this.wsUrl(), - }); - - const response = await this.requestAsync("reporting.netdata_get_data", [ - networkInterfaces.map((networkInterface) => ({ - name: "interface", - identifier: networkInterface.id, - })), - { - start: dayjs().add(-5, "minutes").unix(), - end: dayjs().unix(), - }, - ]); - const result = await reportingNetDataSchema.parseAsync(response); - - logger.debug("Retrieved reporting-network-data", { - url: this.wsUrl(), - count: result.length, - }); - return result; - } - - /** - * Retrieves information about the system - * @see https://www.truenas.com/docs/api/scale_websocket_api.html#system - */ - private async getSystemInformationAsync(): Promise> { - logger.debug("Retrieving system-information", { - url: this.wsUrl(), - }); - - const response = await this.requestAsync("system.info"); - const result = await systemInfoSchema.parseAsync(response); - - logger.debug("Retrieved system-information", { - url: this.wsUrl(), - }); - return result; - } - public async getSystemInfoAsync(): Promise { const systemInformation = await this.getSystemInformationAsync(); const reporting = await this.getReportingAsync(); @@ -272,7 +39,7 @@ export class TrueNasIntegration extends Integration implements ISystemHealthMoni return { cpuUtilization: cpuData.reduce((acc, item) => acc + (item > 100 ? 0 : item), 0) / cpuData.length, - cpuTemp: Math.max(...cpuTempData.filter((_item, i) => i > 0)), + cpuTemp: Math.max(...cpuTempData.filter((_item, index) => index > 0)), memAvailableInBytes: systemInformation.physmem, memUsedInBytes: memoryData[1] ?? 0, // Index 0 is UNIX timestamp, Index 1 is free space in bytes fileSystem: datasets.map((dataset) => ({ @@ -301,87 +68,164 @@ export class TrueNasIntegration extends Integration implements ISystemHealthMoni }; } - /** - * Send a request through websocket and return response - * Times out after 5 seconds when no response was received. - * @param method json-rpc method to call - * @param params array of parameters - * @param webSocketOverride override of webSocket, helpful for not storing the connection - * @returns result of json-rpc call - */ - private async requestAsync(method: string, params: unknown[] = [], webSocketOverride?: WebSocket) { - let webSocket = webSocketOverride ?? this.webSocket; - if (webSocket?.readyState !== WebSocket.OPEN) { - logger.debug("Connecting to websocket", { - url: this.wsUrl(), - }); - // We can only land here with static webSocket - webSocket = await this.connectWebSocketAsync(); - await this.registerSessionAsync(webSocket); - - TrueNasIntegration.webSocketMap.set(this.integration.id, webSocket); - await this.authenticateWebSocketAsync(); - } - - return await new Promise((resolve, reject) => { - const id = createId(); - const handler = (event: MessageEvent) => { - const data = JSON.parse(event.data) as Record; - if (data.msg !== "result") return; - if (data.id !== id) return; - - clearTimeout(timeoutId); - webSocket.removeEventListener("message", handler); - logger.debug("Received method response", { - id, - method, - url: this.wsUrl(), - }); - resolve(data.result); - }; - const timeoutId = setTimeout(() => { - webSocket.removeEventListener("message", handler); - reject( - new RequestError( - { - type: "timeout", - reason: "aborted", - code: "ECONNABORTED", - }, - { cause: new Error("Canceled request after 5 seconds") }, - ), - ); - }, 5000); - - webSocket.addEventListener("message", handler); - - logger.debug("Sending method request", { - id, - method, - url: this.wsUrl(), - }); - - webSocket.send( - JSON.stringify({ - id, - msg: "method", - method, - params, - }), - ); - }); + private getClient(): TrueNasClient { + return (this.client ??= this.createClient()); } - private extractNetworkTrafficData = (data: z.infer, index = 1 | 2) => { + private createClient(): TrueNasClient { + const credentials: TrueNasCredentials = this.hasSecretValue("apiKey") + ? { apiKey: this.getSecretValue("apiKey") } + : { username: this.getSecretValue("username"), password: this.getSecretValue("password") }; + + return new TrueNasClient(this.integration.id, (path) => this.webSocketUrl(path), credentials); + } + + private async requestAsync(method: string, params: unknown[] = []): Promise { + return this.getClient().requestAsync(method, params); + } + + private async getPoolsAsync() { + logger.debug("Retrieving pools", { url: this.integration.url }); + + const response = await this.requestAsync("pool.query", [ + [], + { + extra: { + is_upgraded: true, + }, + }, + ]); + const result = await poolSchema.parseAsync(response); + // Offline / exported pools have null values for allocated, size and free, so we filter them out + // See https://github.com/homarr-labs/homarr/issues/5194 + const activePools = result + .map((pool) => { + if (pool.allocated !== null && pool.size !== null && pool.free !== null) { + return { + ...pool, + allocated: pool.allocated, + size: pool.size, + free: pool.free, + }; + } + + return null; + }) + .filter((pool) => pool !== null); + logger.debug("Retrieved pools", { + url: this.integration.url, + totalCount: result.length, + activeCount: activePools.length, + }); + return activePools; + } + + /** + * Retrieves data using the reporting method + * @see https://www.truenas.com/docs/api/scale_websocket_api.html#reporting + */ + private async getReportingAsync(): Promise { + logger.debug("Retrieving reporting data", { url: this.integration.url }); + + const response = await this.requestAsync("reporting.get_data", [ + [ + { + name: "cpu", + }, + { + name: "memory", + }, + { + name: "cputemp", + }, + ], + { + aggregate: true, + start: dayjs().add(-5, "minutes").unix(), + end: dayjs().unix(), + }, + ]); + const result = await z.array(reportingItemSchema).parseAsync(response); + + logger.debug("Retrieved reporting data", { + url: this.integration.url, + count: result.length, + }); + return result; + } + + /** + * Retrieves a list of all available network interfaces + * @see https://www.truenas.com/docs/core/13.0/api/core_websocket_api.html#interface + */ + private async getNetworkInterfacesAsync(): Promise> { + logger.debug("Retrieving available network-interfaces", { url: this.integration.url }); + + const response = await this.requestAsync("interface.query", [ + [], // no filters + {}, + ]); + const result = await networkInterfaceSchema.parseAsync(response); + + logger.debug("Retrieved available network-interfaces", { + url: this.integration.url, + count: result.length, + }); + return result; + } + + /** + * Retrieves reporting network data of the last 5 minutes + * @see https://www.truenas.com/docs/api/scale_websocket_api.html#reporting + */ + private async getReportingNetdataAsync(): Promise> { + const networkInterfaces = await this.getNetworkInterfacesAsync(); + + logger.debug("Retrieving reporting network data", { url: this.integration.url }); + + const response = await this.requestAsync("reporting.netdata_get_data", [ + networkInterfaces.map((networkInterface) => ({ + name: "interface", + identifier: networkInterface.id, + })), + { + start: dayjs().add(-5, "minutes").unix(), + end: dayjs().unix(), + }, + ]); + const result = await reportingNetDataSchema.parseAsync(response); + + logger.debug("Retrieved reporting-network-data", { + url: this.integration.url, + count: result.length, + }); + return result; + } + + /** + * Retrieves information about the system + * @see https://www.truenas.com/docs/api/scale_websocket_api.html#system + */ + private async getSystemInformationAsync(): Promise> { + logger.debug("Retrieving system-information", { url: this.integration.url }); + + const response = await this.requestAsync("system.info"); + const result = await systemInfoSchema.parseAsync(response); + + logger.debug("Retrieved system-information", { url: this.integration.url }); + return result; + } + + private extractNetworkTrafficData = (data: z.infer, index: 1 | 2) => { return data.reduce((acc, current) => acc + (current.data.at(-1)?.at(index) ?? 0), 0); }; - private extractLatestReportingData(data: ReportingItem[], key: ReportingItem["identifier"]) { - // eslint-disable-next-line @typescript-eslint/no-non-null-assertion - const dataObject = data.find((item) => item.identifier === key)!; - // TODO: check why the below sorting is done, because right now it compares number[] with number[]? - // eslint-disable-next-line @typescript-eslint/no-non-null-assertion - return dataObject.data.sort((item1, item2) => (item1 > item2 ? -1 : 1))[0]!; + private extractLatestReportingData(data: ReportingItem[], identifier: ReportingItem["identifier"]) { + const item = data.find((reportingItem) => reportingItem.identifier === identifier); + // Reporting rows are [timestamp, ...values] in ascending time order, so the last row is the most recent reading. + const latest = item?.data.at(-1); + if (!latest) throw new Error(`TrueNAS returned no "${identifier}" reporting data`); + return latest; } } diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 332b04178..ad1813458 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -1773,6 +1773,9 @@ importers: undici: specifier: 'catalog:' version: 7.24.6 + ws: + specifier: 'catalog:' + version: 8.21.0 xml2js: specifier: 'catalog:' version: 0.6.2 @@ -1786,6 +1789,9 @@ importers: '@types/node-unifi': specifier: 'catalog:' version: 2.5.1(patch_hash=5e6ae51e2a17a7f9729bfa30b0eb3d0842a5810ac6db47603ab4a6efa1ed84c5) + '@types/ws': + specifier: 'catalog:' + version: 8.18.1 '@types/xml2js': specifier: 'catalog:' version: 0.4.14 @@ -10573,7 +10579,7 @@ snapshots: eventemitter2: 6.4.9 http-cookie-agent: 6.0.8(tough-cookie@5.1.2)(undici@7.24.6) tough-cookie: 5.1.2 - ws: 8.20.1 + ws: 8.21.0 transitivePeerDependencies: - bufferutil - debug