feat(integrations): add UnifiOsIntegration with optional cloud enrichment
Introduces UnifiOsIntegration, orchestrating UnifiOsApi (local) and UnifiSmApi (optional cloud) to build the UnifiOsSummary. Local endpoint calls degrade independently via Promise.allSettled; the cloud client is never instantiated without a configured siteManagerApiKey secret. Registers the unifiOs kind in the integration creator, index, and types barrels, resolving the previously-failing typecheck. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
1 parent
2de3063dc1
commit
0abde13101
6 files changed
+323
No files matched your search
@@ -0,0 +1,197 @@
|
||||
// @vitest-environment node
|
||||
import { Response } from "undici";
|
||||
import { beforeEach, describe, expect, test, vi } from "vitest";
|
||||
|
||||
vi.hoisted(() => {
|
||||
process.env.SKIP_ENV_VALIDATION = "true";
|
||||
process.env.SECRET_ENCRYPTION_KEY = "ff3f4f7ce30e870c9630de9e5d244ffa81101a24ed0dfe5f064beb53a7e684f1";
|
||||
});
|
||||
|
||||
import { fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/http";
|
||||
|
||||
import type { IntegrationSecret } from "../../base/types";
|
||||
import { UnifiSmApi } from "../unifi-sm-api";
|
||||
import { UnifiOsIntegration } from "../unifi-os-integration";
|
||||
|
||||
vi.mock("@homarr/core/infrastructure/http", () => ({
|
||||
fetchWithTrustedCertificatesAsync: vi.fn(),
|
||||
}));
|
||||
|
||||
const mockFetch = vi.mocked(fetchWithTrustedCertificatesAsync);
|
||||
|
||||
const GATEWAY_MAC = "aa:bb:cc:11:22:33";
|
||||
|
||||
const jsonResponse = (body: unknown, status = 200) =>
|
||||
new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } }) as never;
|
||||
|
||||
const page = (data: unknown[]) => ({ offset: 0, limit: 200, count: data.length, totalCount: data.length, data });
|
||||
|
||||
const localRoutes: Record<string, unknown> = {
|
||||
"/info": { applicationVersion: "10.6.102" },
|
||||
"/sites": page([{ id: "site-1", name: "Example site", internalReference: "default" }]),
|
||||
"/sites/site-1/clients": page([
|
||||
{ id: "c1", name: "a", type: "WIRED", access: { type: "DEFAULT" } },
|
||||
{ id: "c2", name: "b", type: "WIRELESS", access: { type: "DEFAULT" } },
|
||||
]),
|
||||
"/sites/site-1/devices": page([
|
||||
{
|
||||
id: "gw",
|
||||
name: "Gateway",
|
||||
model: "UXG Pro",
|
||||
macAddress: GATEWAY_MAC,
|
||||
state: "ONLINE",
|
||||
firmwareUpdatable: true,
|
||||
features: ["gateway"],
|
||||
},
|
||||
{
|
||||
id: "sw",
|
||||
name: "Switch",
|
||||
model: "USW Lite 8",
|
||||
macAddress: "aa:bb:cc:99:88:77",
|
||||
state: "OFFLINE",
|
||||
firmwareUpdatable: false,
|
||||
features: ["switching"],
|
||||
},
|
||||
]),
|
||||
"/sites/site-1/devices/gw/statistics/latest": {
|
||||
uptimeSec: 1009049,
|
||||
cpuUtilizationPct: 19.1,
|
||||
memoryUtilizationPct: 63.1,
|
||||
uplink: { txRateBps: 14140912, rxRateBps: 3346784 },
|
||||
},
|
||||
"/sites/site-1/vpn/servers": page([{ id: "v1", name: "vpn", enabled: true }]),
|
||||
};
|
||||
|
||||
const routeLocal = (rawUrl: string): Response | null => {
|
||||
const path = new URL(rawUrl).pathname.replace("/proxy/network/integration/v1", "");
|
||||
const body = localRoutes[path];
|
||||
return body === undefined ? null : jsonResponse(body);
|
||||
};
|
||||
|
||||
const createIntegration = (decryptedSecrets: IntegrationSecret[]) =>
|
||||
new UnifiOsIntegration({
|
||||
id: "test-unifi-os",
|
||||
name: "Test UniFi OS",
|
||||
url: "https://console.example.test",
|
||||
externalUrl: null,
|
||||
decryptedSecrets,
|
||||
});
|
||||
|
||||
const localOnlySecrets: IntegrationSecret[] = [{ kind: "apiKey", value: "local-key" }];
|
||||
const hybridSecrets: IntegrationSecret[] = [
|
||||
{ kind: "apiKey", value: "local-key" },
|
||||
{ kind: "siteManagerApiKey", value: "cloud-key" },
|
||||
];
|
||||
|
||||
beforeEach(() => {
|
||||
mockFetch.mockReset();
|
||||
UnifiSmApi.clearCache();
|
||||
});
|
||||
|
||||
describe("UnifiOsIntegration getUnifiOsSummaryAsync", () => {
|
||||
test("builds the summary from the local API alone", async () => {
|
||||
mockFetch.mockImplementation(async (url) => routeLocal(String(url)) ?? jsonResponse({}, 404));
|
||||
|
||||
const summary = await createIntegration(localOnlySecrets).getUnifiOsSummaryAsync();
|
||||
|
||||
expect(summary.site).toEqual({ id: "site-1", name: "Example site", applicationVersion: "10.6.102" });
|
||||
expect(summary.clients).toEqual({ total: 2, wired: 1, wireless: 1, vpn: 0, guests: 0 });
|
||||
expect(summary.devices).toEqual({ total: 2, online: 1, offline: 1, firmwareUpdatable: 1 });
|
||||
expect(summary.wan.state).toBe("online");
|
||||
expect(summary.wan.throughput).toEqual({ txBps: 14140912, rxBps: 3346784 });
|
||||
expect(summary.gateway).toMatchObject({ name: "Gateway", uptimeSec: 1009049, cpuPct: 19.1 });
|
||||
});
|
||||
|
||||
test("leaves the ISP block null when no Site Manager key is configured", async () => {
|
||||
mockFetch.mockImplementation(async (url) => routeLocal(String(url)) ?? jsonResponse({}, 404));
|
||||
|
||||
const summary = await createIntegration(localOnlySecrets).getUnifiOsSummaryAsync();
|
||||
|
||||
expect(summary.wan.isp).toBeNull();
|
||||
expect(mockFetch.mock.calls.every(([url]) => !String(url).startsWith("https://api.ui.com"))).toBe(true);
|
||||
});
|
||||
|
||||
test("fills the ISP block when a Site Manager key is configured", async () => {
|
||||
mockFetch.mockImplementation(async (url) => {
|
||||
const raw = String(url);
|
||||
if (raw.startsWith("https://api.ui.com/v1/sites")) {
|
||||
return jsonResponse({
|
||||
data: [
|
||||
{
|
||||
siteId: "cloud-1",
|
||||
hostId: "host-1",
|
||||
meta: { gatewayMac: GATEWAY_MAC },
|
||||
statistics: { wans: { WAN: { externalIp: "203.0.113.10" } } },
|
||||
},
|
||||
],
|
||||
});
|
||||
}
|
||||
if (raw.includes("isp-metrics")) {
|
||||
return jsonResponse({
|
||||
data: {
|
||||
metrics: [
|
||||
{
|
||||
periods: [
|
||||
{
|
||||
metricTime: "2026-09-08T09:10:00Z",
|
||||
data: {
|
||||
wan: { avgLatency: 11, maxLatency: 12, packetLoss: 0, uptime: 100, ispName: "Example ISP" },
|
||||
},
|
||||
},
|
||||
],
|
||||
},
|
||||
],
|
||||
},
|
||||
});
|
||||
}
|
||||
return routeLocal(raw) ?? jsonResponse({}, 404);
|
||||
});
|
||||
|
||||
const summary = await createIntegration(hybridSecrets).getUnifiOsSummaryAsync();
|
||||
|
||||
expect(summary.wan.isp).toMatchObject({ name: "Example ISP", latencyMs: 11, externalIp: "203.0.113.10" });
|
||||
expect(summary.wan.isp?.measuredAt).toEqual(new Date("2026-09-08T09:10:00Z"));
|
||||
});
|
||||
|
||||
test("degrades only the affected block when one local endpoint fails", async () => {
|
||||
mockFetch.mockImplementation(async (url) => {
|
||||
const raw = String(url);
|
||||
if (raw.includes("/vpn/servers")) return jsonResponse({ error: "boom" }, 500);
|
||||
return routeLocal(raw) ?? jsonResponse({}, 404);
|
||||
});
|
||||
|
||||
const summary = await createIntegration(localOnlySecrets).getUnifiOsSummaryAsync();
|
||||
|
||||
expect(summary.clients.total).toBe(2);
|
||||
expect(summary.devices.total).toBe(2);
|
||||
});
|
||||
|
||||
test("keeps clients and devices when the gateway cannot be identified", async () => {
|
||||
mockFetch.mockImplementation(async (url) => {
|
||||
const raw = String(url);
|
||||
if (raw.endsWith("/devices?limit=200")) {
|
||||
return jsonResponse(
|
||||
page([
|
||||
{
|
||||
id: "sw",
|
||||
name: "Switch",
|
||||
model: "USW Lite 8",
|
||||
macAddress: "aa:bb:cc:99:88:77",
|
||||
state: "ONLINE",
|
||||
firmwareUpdatable: false,
|
||||
features: ["switching"],
|
||||
},
|
||||
]),
|
||||
);
|
||||
}
|
||||
return routeLocal(raw) ?? jsonResponse({}, 404);
|
||||
});
|
||||
|
||||
const summary = await createIntegration(localOnlySecrets).getUnifiOsSummaryAsync();
|
||||
|
||||
expect(summary.gateway).toBeNull();
|
||||
expect(summary.wan.throughput).toBeNull();
|
||||
expect(summary.wan.state).toBe("unknown");
|
||||
expect(summary.clients.total).toBe(2);
|
||||
});
|
||||
});
|
||||
Reference in new issue
Block a user