feat(integrations): add optional UniFi Site Manager client with 5min cache
Task 4 of the UniFi OS integration: an optional cloud client for Ubiquiti's Site Manager API that enriches the local console with ISP latency data. Instantiated only when a cloud API key is configured (Task 5). Every failure path (bad key, non-ok status, parse error, unmatched gateway MAC) returns null rather than throwing, since the cloud is a pure enrichment. Metrics are cached 5 minutes, keyed by gateway MAC, to respect the ~27 min publication lag and avoid rate limiting; the query window is 3 hours because a 15-minute window returns an empty array on the real API. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
1 parent
c17b863e3f
commit
ca1cc54623
2 files changed
+274
No files matched your search
@@ -0,0 +1,138 @@
|
||||
// @vitest-environment node
|
||||
import { Response } from "undici";
|
||||
import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
|
||||
|
||||
vi.hoisted(() => {
|
||||
process.env.SKIP_ENV_VALIDATION = "true";
|
||||
process.env.SECRET_ENCRYPTION_KEY = "ff3f4f7ce30e870c9630de9e5d244ffa81101a24ed0dfe5f064beb53a7e684f1";
|
||||
});
|
||||
|
||||
import { UnifiSmApi } from "../unifi-sm-api";
|
||||
|
||||
const GATEWAY_MAC = "aa:bb:cc:11:22:33";
|
||||
const OTHER_MAC = "dd:ee:ff:44:55:66";
|
||||
|
||||
const jsonResponse = (body: unknown, status = 200) =>
|
||||
new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } }) as never;
|
||||
|
||||
const sitesBody = {
|
||||
data: [
|
||||
{
|
||||
siteId: "mine",
|
||||
meta: { desc: "Mine", gatewayMac: GATEWAY_MAC },
|
||||
statistics: { wans: { WAN: { externalIp: "203.0.113.10" } } },
|
||||
},
|
||||
{ siteId: "theirs", meta: { desc: "Theirs", gatewayMac: OTHER_MAC } },
|
||||
],
|
||||
};
|
||||
|
||||
const metricsBody = (metricTime: string) => ({
|
||||
data: {
|
||||
metrics: [
|
||||
{
|
||||
periods: [
|
||||
{
|
||||
metricTime: "2026-09-08T08:00:00Z",
|
||||
data: { wan: { avgLatency: 99, maxLatency: 99, packetLoss: 5, uptime: 90, ispName: "Old" } },
|
||||
},
|
||||
{
|
||||
metricTime,
|
||||
data: { wan: { avgLatency: 11, maxLatency: 12, packetLoss: 0, uptime: 100, ispName: "Example ISP" } },
|
||||
},
|
||||
],
|
||||
},
|
||||
],
|
||||
},
|
||||
});
|
||||
|
||||
const createApi = () => {
|
||||
const fetchAsync = vi.fn(async (url: string) =>
|
||||
url.includes("isp-metrics") ? jsonResponse(metricsBody("2026-09-08T09:10:00Z")) : jsonResponse(sitesBody),
|
||||
);
|
||||
return { api: new UnifiSmApi("cloud-key", fetchAsync as never), fetchAsync };
|
||||
};
|
||||
|
||||
beforeEach(() => {
|
||||
UnifiSmApi.clearCache();
|
||||
vi.useFakeTimers();
|
||||
vi.setSystemTime(new Date("2026-09-08T09:37:00Z"));
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
vi.useRealTimers();
|
||||
});
|
||||
|
||||
describe("UnifiSmApi getIspMetricsAsync", () => {
|
||||
test("returns the newest period of the site matching the gateway MAC", async () => {
|
||||
const { api } = createApi();
|
||||
|
||||
const metrics = await api.getIspMetricsAsync(GATEWAY_MAC);
|
||||
|
||||
expect(metrics).toEqual({
|
||||
name: "Example ISP",
|
||||
externalIp: "203.0.113.10",
|
||||
latencyMs: 11,
|
||||
maxLatencyMs: 12,
|
||||
packetLossPct: 0,
|
||||
uptimePct: 100,
|
||||
measuredAt: new Date("2026-09-08T09:10:00Z"),
|
||||
});
|
||||
});
|
||||
|
||||
test("returns null when no cloud site matches, never another account site", async () => {
|
||||
const { api } = createApi();
|
||||
|
||||
expect(await api.getIspMetricsAsync("11:22:33:44:55:66")).toBeNull();
|
||||
});
|
||||
|
||||
test("returns null when the local gateway could not be identified", async () => {
|
||||
const { api, fetchAsync } = createApi();
|
||||
|
||||
expect(await api.getIspMetricsAsync(null)).toBeNull();
|
||||
expect(fetchAsync).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
test("queries a window wide enough for the cloud lag", async () => {
|
||||
const { api, fetchAsync } = createApi();
|
||||
|
||||
await api.getIspMetricsAsync(GATEWAY_MAC);
|
||||
|
||||
const body = JSON.parse(
|
||||
String(fetchAsync.mock.calls.find(([url]) => String(url).includes("isp-metrics"))?.[1]?.body),
|
||||
);
|
||||
const begin = new Date(body.sites[0].beginTimestamp).getTime();
|
||||
const end = new Date(body.sites[0].endTimestamp).getTime();
|
||||
|
||||
// Une fenêtre de 15 min renvoie un tableau vide sur l'API réelle.
|
||||
expect(end - begin).toBeGreaterThanOrEqual(3 * 60 * 60 * 1000);
|
||||
});
|
||||
|
||||
test("serves a second call from cache instead of hitting the cloud again", async () => {
|
||||
const { api, fetchAsync } = createApi();
|
||||
|
||||
await api.getIspMetricsAsync(GATEWAY_MAC);
|
||||
const callsAfterFirst = fetchAsync.mock.calls.length;
|
||||
await api.getIspMetricsAsync(GATEWAY_MAC);
|
||||
|
||||
expect(fetchAsync.mock.calls.length).toBe(callsAfterFirst);
|
||||
});
|
||||
|
||||
test("refetches once the cache entry has expired", async () => {
|
||||
const { api, fetchAsync } = createApi();
|
||||
|
||||
await api.getIspMetricsAsync(GATEWAY_MAC);
|
||||
const callsAfterFirst = fetchAsync.mock.calls.length;
|
||||
|
||||
vi.setSystemTime(new Date("2026-09-08T09:43:00Z"));
|
||||
await api.getIspMetricsAsync(GATEWAY_MAC);
|
||||
|
||||
expect(fetchAsync.mock.calls.length).toBeGreaterThan(callsAfterFirst);
|
||||
});
|
||||
|
||||
test("returns null when the cloud rejects the key rather than propagating", async () => {
|
||||
const fetchAsync = vi.fn(async () => jsonResponse({ message: "unauthorized" }, 401));
|
||||
const api = new UnifiSmApi("bad-key", fetchAsync as never);
|
||||
|
||||
expect(await api.getIspMetricsAsync(GATEWAY_MAC)).toBeNull();
|
||||
});
|
||||
});
|
||||
Reference in new issue
Block a user