75 KiB
Plan d'implémentation — Intégration UniFi OS
For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (
- [ ]) syntax for tracking.
Goal : Ajouter à Homarr une intégration unifiOs lisant l'API d'intégration officielle d'UniFi OS (clé X-API-KEY), enrichie optionnellement par l'API cloud Site Manager, et un widget dédié pour l'afficher.
Architecture : Quatre modules aux responsabilités disjointes dans packages/integrations/src/unifi-os/ — un client HTTP local, un client HTTP cloud optionnel à cache interne, un module de schémas et de mappers purs, et une classe Integration qui orchestre. Le tout branché sur les cinq points d'attache habituels du monorepo (definitions, request-handler, api, widgets, translation).
Tech Stack : TypeScript, zod v4 (zod/v4), vitest, undici fetch, Mantine v9, tRPC, Turbo/pnpm.
Spec : docs/superpowers/specs/2026-09-08-unifi-os-integration-design.md
Global Constraints
- Branche de travail :
feat/unifi-os-integration. Ne jamais committer surdevnimain. - Lint / format : oxlint et oxfmt, pas ESLint ni Prettier.
pnpm lintetpnpm format. - UI : Mantine v9, pas Tailwind. Icônes
@tabler/icons-react. - zod : importer
{ z } from "zod/v4"(convention de l'intégrationpatchmon, la plus récente). Objets tolérants aux champs inconnus viaz.looseObject. - Tests : vitest. Fichiers
*.spec.tssouspackages/integrations/src/unifi-os/test/. En-tête// @vitest-environment nodepour les tests d'intégration. Lancement :pnpm test. - Erreurs :
ParseErroretResponseErrordepuis@homarr/common/server;TestConnectionErrordepuis../base/test-connection/test-connection-error. - Base d'URL locale : l'utilisateur saisit l'origine de la console. Le client préfixe
/proxy/network/integration/v1. Ce préfixe n'est jamais exposé à la configuration. - Base d'URL cloud :
https://api.ui.com, en dur, jamais configurable. limitde l'API locale est plafonné à 200. Mesuré. Toute pagination doit en tenir compte.- Syntaxe de filtrage locale : préfixe.
and(type.eq('WIRED'),access.type.eq('DEFAULT')). Les formes infixes renvoient400 api.request.invalid-filter. - Aucun secret, MAC réel, IP publique ou nom de client réel dans le dépôt. Fixtures anonymisées.
NetworkControllerSummaryne doit pas être modifié. Aucun fichier deunifi-controller/ni d'opnsense/ne doit apparaître dans un diff.- Nommer la catégorie
unifiOs, jamaisnetworkController(voir §5.3 de la spec : la catégorie est un mécanisme de câblage, pas une étiquette).
Structure des fichiers
Créés :
| Fichier | Responsabilité |
|---|---|
packages/integrations/src/unifi-os/unifi-os-types.ts |
Schémas zod et fonctions pures de mapping. Aucun accès réseau. |
packages/integrations/src/unifi-os/unifi-os-api.ts |
Client HTTP de la console locale. Ne connaît pas Homarr. |
packages/integrations/src/unifi-os/unifi-sm-api.ts |
Client HTTP du cloud Site Manager. Cache interne. Optionnel. |
packages/integrations/src/unifi-os/unifi-os-integration.ts |
Classe Integration. Orchestration et dégradation. |
packages/integrations/src/interfaces/unifi-os-summary/unifi-os-summary-integration.ts |
Interface consommée par le request-handler. |
packages/integrations/src/unifi-os/test/unifi-os-types.spec.ts |
Tests des mappers, sans réseau. |
packages/integrations/src/unifi-os/test/unifi-os-api.spec.ts |
Tests du client local, fetch injecté. |
packages/integrations/src/unifi-os/test/unifi-sm-api.spec.ts |
Tests du client cloud et du cache. |
packages/integrations/src/unifi-os/test/unifi-os-integration.spec.ts |
Tests d'orchestration et de dégradation. |
packages/request-handler/src/unifi-os.ts |
Handler de cache. |
packages/api/src/router/widgets/unifi-os.ts |
Routeur tRPC. |
packages/widgets/src/unifi-os/index.ts |
Définition du widget. |
packages/widgets/src/unifi-os/component.tsx |
Composant Mantine. |
Modifiés :
| Fichier | Modification |
|---|---|
packages/definitions/src/integration.ts |
secret siteManagerApiKey, catégorie unifiOs, kind unifiOs |
packages/definitions/src/widget.ts |
WidgetKind unifiOs |
packages/definitions/src/widget-integration-map.ts |
unifiOs: ["unifiOs"] |
packages/integrations/src/base/creator.ts |
import + entrée unifiOs |
packages/integrations/src/index.ts |
export de la classe |
packages/integrations/src/types.ts |
export des types |
packages/api/src/router/widgets/index.ts |
entrée unifiOs |
packages/widgets/src/manifest.ts |
deux entrées (module + composant) |
packages/widgets/src/index.tsx |
import + entrée |
packages/widgets/src/catalog.ts |
icône — vérifié par manifest.spec.ts |
packages/widgets/src/refetch-intervals.ts |
intervalle 60 s |
packages/translation/src/lang/en.json |
libellés + integration.category.unifiOs |
Task 1 : Déclarations dans @homarr/definitions
Poser le vocabulaire avant tout le reste. Sans ces déclarations, rien d'autre ne compile.
Files:
- Modify:
packages/definitions/src/integration.ts - Modify:
packages/definitions/src/widget.ts - Modify:
packages/definitions/src/widget-integration-map.ts - Modify:
packages/translation/src/lang/en.json
Interfaces:
-
Consumes: rien.
-
Produces: le kind d'intégration
"unifiOs", la catégorie"unifiOs", le secret"siteManagerApiKey", leWidgetKind"unifiOs". Toutes les tâches suivantes en dépendent. -
Step 1 : Ajouter le secret
Dans packages/definitions/src/integration.ts, dans integrationSecretKindObject, juste après la ligne apiKey, ajouter :
siteManagerApiKey: { isPublic: false, multiline: false },
- Step 2 : Ajouter la catégorie
Dans le même fichier, dans le tableau integrationCategories, avant la ligne ] as const;, ajouter :
"unifiOs",
- Step 3 : Ajouter le kind d'intégration
Toujours dans le même fichier, dans integrationDefs, immédiatement après le bloc unifiController (qui se termine par defaultPort: 8443, puis },), ajouter :
unifiOs: {
name: "UniFi OS",
secretKinds: [["apiKey"], ["apiKey", "siteManagerApiKey"]],
iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/png/unifi.png",
category: ["unifiOs"],
documentationUrl: null,
defaultPort: 443,
},
documentationUrl: null est volontaire : la décision D1 de la spec exclut la documentation Docusaurus. Le champ accepte string | null.
secretKinds déclare deux jeux alternatifs. Le premier — ["apiKey"] — rend la clé cloud facultative. Motif identique à ntfy.
- Step 4 : Ajouter le WidgetKind
Dans packages/definitions/src/widget.ts, dans le tableau widgetKinds, après "networkControllerStatus", ajouter :
"unifiOs",
- Step 5 : Câbler la carte widget → intégrations
Dans packages/definitions/src/widget-integration-map.ts, dans widgetIntegrationSupport, après la ligne networkControllerStatus: getIntegrationKindsByCategory("networkController"), ajouter :
unifiOs: ["unifiOs"],
Liste littérale et non getIntegrationKindsByCategory("unifiOs") : le widget ne supporte qu'une intégration, et l'écrire en clair rend la relation évidente à la lecture. C'est ce que fait déjà coolify: ["coolify"].
- Step 6 : Ajouter la traduction de catégorie
Dans packages/translation/src/lang/en.json, dans l'objet integration.category, à côté de "networkController": "Network", ajouter :
"unifiOs": "UniFi OS",
- Step 7 : Vérifier que le typage tient
Run: pnpm turbo typecheck --filter=@homarr/definitions
Expected: PASS.
Si @homarr/widgets est aussi typé à ce stade, il échouera — c'est attendu : le WidgetKind unifiOs n'a pas encore d'entrée dans le manifeste. La Task 7 le corrige. Ne pas contourner en retirant le kind.
- Step 8 : Committer
git add packages/definitions/src/integration.ts packages/definitions/src/widget.ts packages/definitions/src/widget-integration-map.ts packages/translation/src/lang/en.json
git commit -m "feat(definitions): declare unifiOs integration kind, category and widget kind"
Task 2 : Schémas et mappers purs
Le cœur testable de l'intégration. Aucun réseau, donc aucun mock : ces tests restent valables même si Ubiquiti change ses endpoints.
Files:
- Create:
packages/integrations/src/unifi-os/unifi-os-types.ts - Test:
packages/integrations/src/unifi-os/test/unifi-os-types.spec.ts
Interfaces:
-
Consumes: rien.
-
Produces :
UnifiOsSummary,UnifiOsIspMetrics,UnifiOsClientCounts,UnifiOsDeviceCounts,UnifiOsGatewayunifiOsInfoSchema,unifiOsSiteSchema,unifiOsClientSchema,unifiOsDeviceSchema,unifiOsDeviceStatisticsSchema,unifiOsVpnServerSchema,createUnifiOsPageSchemaunifiSmSiteSchema,unifiSmIspMetricsResponseSchemaparseUnifiOsAsync<T>(value: unknown, schema: z.ZodType<T>, message: string): Promise<T>normalizeMacAddress(mac: string): stringcountClients(clients: UnifiOsClient[]): UnifiOsClientCountssummarizeDevices(devices: UnifiOsDevice[]): UnifiOsDeviceCountsfindGateway(devices: UnifiOsDevice[]): UnifiOsDevice | nullmatchCloudSite<T extends { meta: { gatewayMac?: string } }>(gatewayMac: string | null, sites: T[]): T | null
-
Step 1 : Écrire les tests qui échouent
Créer packages/integrations/src/unifi-os/test/unifi-os-types.spec.ts :
import { describe, expect, test } from "vitest";
import type { UnifiOsClient, UnifiOsDevice } from "../unifi-os-types";
import {
countClients,
findGateway,
matchCloudSite,
normalizeMacAddress,
summarizeDevices,
unifiOsClientSchema,
} from "../unifi-os-types";
const client = (type: string, accessType = "DEFAULT"): UnifiOsClient => ({
id: `client-${type}-${accessType}-${Math.random()}`,
name: "client",
type,
access: { type: accessType },
});
const device = (overrides: Partial<UnifiOsDevice> = {}): UnifiOsDevice => ({
id: "device-1",
name: "device",
model: "USW Lite 8",
macAddress: "aa:bb:cc:11:22:33",
state: "ONLINE",
firmwareUpdatable: false,
features: ["switching"],
...overrides,
});
describe("normalizeMacAddress", () => {
test("lowercases and strips separators so both APIs compare equal", () => {
expect(normalizeMacAddress("AA:BB:CC:11:22:33")).toBe("aabbcc112233");
expect(normalizeMacAddress("aa-bb-cc-11-22-33")).toBe("aabbcc112233");
expect(normalizeMacAddress("AABBCC112233")).toBe("aabbcc112233");
});
});
describe("countClients", () => {
test("counts each connection type separately", () => {
const counts = countClients([
client("WIRED"),
client("WIRED"),
client("WIRELESS"),
client("VPN"),
client("TELEPORT"),
]);
expect(counts).toEqual({ total: 5, wired: 2, wireless: 1, vpn: 2, guests: 0 });
});
test("folds TELEPORT into vpn because both are remote access", () => {
expect(countClients([client("TELEPORT")]).vpn).toBe(1);
});
test("counts guests across every connection type", () => {
const counts = countClients([client("WIRELESS", "GUEST"), client("WIRED", "GUEST"), client("WIRED")]);
expect(counts.guests).toBe(2);
expect(counts.wired).toBe(2);
});
test("treats an unknown connection type as counted but unclassified", () => {
const counts = countClients([client("SOMETHING_NEW")]);
expect(counts.total).toBe(1);
expect(counts.wired + counts.wireless + counts.vpn).toBe(0);
});
test("tolerates a client without an access block", () => {
const counts = countClients([{ id: "x", name: "x", type: "WIRED" }]);
expect(counts).toEqual({ total: 1, wired: 1, wireless: 0, vpn: 0, guests: 0 });
});
});
describe("summarizeDevices", () => {
test("splits online from everything else and counts pending firmware", () => {
const counts = summarizeDevices([
device({ id: "a", state: "ONLINE", firmwareUpdatable: true }),
device({ id: "b", state: "OFFLINE" }),
device({ id: "c", state: "UPDATING", firmwareUpdatable: true }),
]);
expect(counts).toEqual({ total: 3, online: 1, offline: 2, firmwareUpdatable: 2 });
});
test("returns zeroes for an empty site rather than throwing", () => {
expect(summarizeDevices([])).toEqual({ total: 0, online: 0, offline: 0, firmwareUpdatable: 0 });
});
});
describe("findGateway", () => {
test("prefers the device advertising the gateway feature", () => {
const gateway = device({ id: "gw", features: ["gateway"], model: "UXG Pro" });
expect(findGateway([device(), gateway])?.id).toBe("gw");
});
test("falls back to a gateway-looking model when features are empty", () => {
const gateway = device({ id: "gw", features: [], model: "Gateway Pro" });
expect(findGateway([device(), gateway])?.id).toBe("gw");
});
test("returns null when no gateway is present instead of picking any device", () => {
expect(findGateway([device()])).toBeNull();
});
});
describe("matchCloudSite", () => {
const siteA = { siteId: "a", meta: { gatewayMac: "AA:BB:CC:11:22:33" } };
const siteB = { siteId: "b", meta: { gatewayMac: "dd:ee:ff:44:55:66" } };
test("matches on the gateway MAC regardless of formatting", () => {
expect(matchCloudSite("aa-bb-cc-11-22-33", [siteB, siteA])?.siteId).toBe("a");
});
test("returns null rather than another account site when nothing matches", () => {
expect(matchCloudSite("11:22:33:44:55:66", [siteA, siteB])).toBeNull();
});
test("returns null when the local gateway is unknown", () => {
expect(matchCloudSite(null, [siteA, siteB])).toBeNull();
});
});
describe("unifiOsClientSchema", () => {
test("keeps fields the published OpenAPI does not document", () => {
const parsed = unifiOsClientSchema.parse({
id: "1",
name: "n",
type: "WIRED",
access: { type: "DEFAULT" },
macAddress: "aa:bb:cc:11:22:33",
uplinkDeviceId: "u1",
});
expect(parsed).toMatchObject({ macAddress: "aa:bb:cc:11:22:33", uplinkDeviceId: "u1" });
});
});
- Step 2 : Lancer les tests pour vérifier qu'ils échouent
Run: pnpm test packages/integrations/src/unifi-os/test/unifi-os-types.spec.ts
Expected: FAIL — Cannot find module '../unifi-os-types'.
- Step 3 : Écrire l'implémentation
Créer packages/integrations/src/unifi-os/unifi-os-types.ts :
import { ParseError } from "@homarr/common/server";
import { z } from "zod/v4";
/**
* Ubiquiti ne publie l'OpenAPI que pour la 10.4.57 alors que les consoles sont
* en 10.6.x et renvoient déjà des champs absents du spec. Tous les objets sont
* donc « loose » : un champ inattendu ne doit jamais faire échouer un widget.
*/
export const unifiOsInfoSchema = z.looseObject({
applicationVersion: z.string(),
});
export const unifiOsSiteSchema = z.looseObject({
id: z.string(),
name: z.string(),
internalReference: z.string().optional(),
});
export const unifiOsClientSchema = z.looseObject({
id: z.string(),
name: z.string(),
type: z.string(),
access: z.looseObject({ type: z.string() }).optional(),
});
export const unifiOsDeviceSchema = z.looseObject({
id: z.string(),
name: z.string(),
model: z.string(),
macAddress: z.string(),
state: z.string(),
firmwareUpdatable: z.boolean().optional(),
features: z.array(z.string()).default([]),
});
export const unifiOsDeviceStatisticsSchema = z.looseObject({
uptimeSec: z.number().optional(),
cpuUtilizationPct: z.number().optional(),
memoryUtilizationPct: z.number().optional(),
uplink: z.looseObject({ txRateBps: z.number(), rxRateBps: z.number() }).optional(),
});
export const unifiOsVpnServerSchema = z.looseObject({
id: z.string(),
name: z.string().optional(),
enabled: z.boolean(),
});
/** Enveloppe de pagination commune à tous les endpoints de liste. */
export const createUnifiOsPageSchema = <TItem extends z.ZodType>(item: TItem) =>
z.looseObject({
offset: z.number(),
limit: z.number(),
count: z.number(),
totalCount: z.number(),
data: z.array(item),
});
export const unifiSmSiteSchema = z.looseObject({
siteId: z.string(),
hostId: z.string().optional(),
meta: z.looseObject({
desc: z.string().optional(),
name: z.string().optional(),
gatewayMac: z.string().optional(),
}),
statistics: z
.looseObject({
ispInfo: z.looseObject({ name: z.string().optional() }).optional(),
percentages: z.looseObject({ wanUptime: z.number().optional() }).optional(),
wans: z.record(z.string(), z.looseObject({ externalIp: z.string().optional() })).optional(),
})
.optional(),
});
const unifiSmWanMetricsSchema = z.looseObject({
avgLatency: z.number().optional(),
maxLatency: z.number().optional(),
packetLoss: z.number().optional(),
uptime: z.number().optional(),
ispName: z.string().optional(),
});
export const unifiSmIspMetricsResponseSchema = z.looseObject({
data: z.looseObject({
metrics: z.array(
z.looseObject({
periods: z.array(
z.looseObject({
metricTime: z.string(),
data: z.looseObject({ wan: unifiSmWanMetricsSchema.optional() }),
}),
),
}),
),
}),
});
export type UnifiOsClient = z.infer<typeof unifiOsClientSchema>;
export type UnifiOsDevice = z.infer<typeof unifiOsDeviceSchema>;
export type UnifiOsSite = z.infer<typeof unifiOsSiteSchema>;
export type UnifiOsDeviceStatistics = z.infer<typeof unifiOsDeviceStatisticsSchema>;
export interface UnifiOsClientCounts {
total: number;
wired: number;
wireless: number;
vpn: number;
guests: number;
}
export interface UnifiOsDeviceCounts {
total: number;
online: number;
offline: number;
firmwareUpdatable: number;
}
export interface UnifiOsGateway {
name: string;
model: string;
macAddress: string;
uptimeSec: number | null;
cpuPct: number | null;
memoryPct: number | null;
}
export interface UnifiOsIspMetrics {
name: string;
externalIp: string | null;
latencyMs: number;
maxLatencyMs: number;
packetLossPct: number;
uptimePct: number;
/** Horodatage de la mesure : la donnée cloud accuse ~27 min de retard. */
measuredAt: Date;
}
export interface UnifiOsSummary {
site: {
id: string;
name: string;
applicationVersion: string;
};
wan: {
state: "online" | "offline" | "unknown";
throughput: { txBps: number; rxBps: number } | null;
isp: UnifiOsIspMetrics | null;
};
clients: UnifiOsClientCounts;
devices: UnifiOsDeviceCounts;
gateway: UnifiOsGateway | null;
}
export const parseUnifiOsAsync = async <TOutput>(
value: unknown,
schema: z.ZodType<TOutput>,
message: string,
): Promise<TOutput> => {
const result = await schema.safeParseAsync(value);
if (!result.success) {
throw new ParseError(message, { cause: result.error });
}
return result.data;
};
/**
* L'API locale renvoie `aa:bb:cc:11:22:33`, le cloud peut renvoyer une autre
* casse ou d'autres séparateurs. La comparaison se fait sur une forme canonique.
*/
export const normalizeMacAddress = (mac: string): string => mac.toLowerCase().replace(/[^0-9a-f]/g, "");
const VPN_CLIENT_TYPES = new Set(["VPN", "TELEPORT"]);
export const countClients = (clients: UnifiOsClient[]): UnifiOsClientCounts => {
const counts: UnifiOsClientCounts = { total: 0, wired: 0, wireless: 0, vpn: 0, guests: 0 };
for (const client of clients) {
counts.total += 1;
if (client.type === "WIRED") counts.wired += 1;
else if (client.type === "WIRELESS") counts.wireless += 1;
else if (VPN_CLIENT_TYPES.has(client.type)) counts.vpn += 1;
if (client.access?.type === "GUEST") counts.guests += 1;
}
return counts;
};
export const summarizeDevices = (devices: UnifiOsDevice[]): UnifiOsDeviceCounts => {
const online = devices.filter((device) => device.state === "ONLINE").length;
return {
total: devices.length,
online,
// Tout ce qui n'est pas ONLINE est indisponible du point de vue du dashboard,
// qu'il s'agisse d'OFFLINE, d'UPDATING ou d'un état futur inconnu.
offline: devices.length - online,
firmwareUpdatable: devices.filter((device) => device.firmwareUpdatable === true).length,
};
};
const GATEWAY_MODEL_HINT = /gateway|udm|uxg|ucg|usg/i;
export const findGateway = (devices: UnifiOsDevice[]): UnifiOsDevice | null =>
devices.find((device) => device.features.includes("gateway")) ??
devices.find((device) => GATEWAY_MODEL_HINT.test(device.model)) ??
null;
/**
* Une clé Site Manager voit tous les sites du compte, y compris ceux d'autres
* consoles. Sans correspondance stricte sur le MAC du gateway, on afficherait
* la latence d'un autre réseau. Renvoyer null est le seul comportement sûr.
*/
export const matchCloudSite = <TSite extends { meta: { gatewayMac?: string } }>(
gatewayMac: string | null,
sites: TSite[],
): TSite | null => {
if (gatewayMac === null) return null;
const normalized = normalizeMacAddress(gatewayMac);
return sites.find((site) => site.meta.gatewayMac !== undefined && normalizeMacAddress(site.meta.gatewayMac) === normalized) ?? null;
};
- Step 4 : Lancer les tests pour vérifier qu'ils passent
Run: pnpm test packages/integrations/src/unifi-os/test/unifi-os-types.spec.ts
Expected: PASS, 15 tests.
- Step 5 : Formater et committer
pnpm format
git add packages/integrations/src/unifi-os/
git commit -m "feat(integrations): add UniFi OS schemas and pure mappers"
Task 3 : Client HTTP local
Files:
- Create:
packages/integrations/src/unifi-os/unifi-os-api.ts - Test:
packages/integrations/src/unifi-os/test/unifi-os-api.spec.ts
Interfaces:
- Consumes: tout ce que produit la Task 2.
- Produces :
type UnifiOsFetch = (url: string, init?: RequestInit & { timeout?: number }) => Promise<Response>class UnifiOsApi— constructeur(origin: string, apiKey: string, fetchAsync: UnifiOsFetch)getInfoAsync(): Promise<{ applicationVersion: string }>getFirstSiteAsync(): Promise<UnifiOsSite | null>getClientCountsAsync(siteId: string): Promise<UnifiOsClientCounts>getDevicesAsync(siteId: string): Promise<UnifiOsDevice[]>getDeviceStatisticsAsync(siteId, deviceId): Promise<UnifiOsDeviceStatistics>getVpnServersAsync(siteId: string): Promise<{ enabled: boolean }[]>
Le fetchAsync est injecté plutôt que mocké au niveau du module : les tests
deviennent lisibles et n'ont pas besoin de vi.mock.
- Step 1 : Écrire les tests qui échouent
Créer packages/integrations/src/unifi-os/test/unifi-os-api.spec.ts :
import { Response } from "undici";
import { describe, expect, test, vi } from "vitest";
import { ResponseError } from "@homarr/common/server";
import { UnifiOsApi } from "../unifi-os-api";
const ORIGIN = "https://console.example.test";
const API_KEY = "test-key";
const jsonResponse = (body: unknown, status = 200) =>
new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } }) as never;
const page = (data: unknown[], totalCount = data.length, limit = 200) => ({
offset: 0,
limit,
count: data.length,
totalCount,
data,
});
const createApi = (handler: (url: string) => Promise<Response>) => {
const fetchAsync = vi.fn(async (url: string) => await handler(url));
return { api: new UnifiOsApi(ORIGIN, API_KEY, fetchAsync as never), fetchAsync };
};
describe("UnifiOsApi request shape", () => {
test("prefixes the integration path and sends the API key header", async () => {
const fetchAsync = vi.fn(async () => jsonResponse({ applicationVersion: "10.6.102" }));
const api = new UnifiOsApi(ORIGIN, API_KEY, fetchAsync as never);
await api.getInfoAsync();
expect(fetchAsync).toHaveBeenCalledWith(
`${ORIGIN}/proxy/network/integration/v1/info`,
expect.objectContaining({ headers: expect.objectContaining({ "X-API-KEY": API_KEY }) }),
);
});
test("does not double a slash when the origin has a trailing one", async () => {
const fetchAsync = vi.fn(async () => jsonResponse({ applicationVersion: "10.6.102" }));
const api = new UnifiOsApi(`${ORIGIN}/`, API_KEY, fetchAsync as never);
await api.getInfoAsync();
expect(fetchAsync.mock.calls[0]?.[0]).toBe(`${ORIGIN}/proxy/network/integration/v1/info`);
});
test("throws ResponseError on a non-ok status instead of parsing the body", async () => {
const { api } = createApi(async () => jsonResponse({ error: { code: 401 } }, 401));
await expect(api.getInfoAsync()).rejects.toBeInstanceOf(ResponseError);
});
});
describe("UnifiOsApi getClientCountsAsync", () => {
test("counts from a single page when totalCount fits under the API limit", async () => {
const { api, fetchAsync } = createApi(async () =>
jsonResponse(
page([
{ id: "1", name: "a", type: "WIRED", access: { type: "DEFAULT" } },
{ id: "2", name: "b", type: "WIRELESS", access: { type: "GUEST" } },
]),
),
);
const counts = await api.getClientCountsAsync("site-1");
expect(counts).toEqual({ total: 2, wired: 1, wireless: 1, vpn: 0, guests: 1 });
expect(fetchAsync).toHaveBeenCalledTimes(1);
});
test("switches to filtered count queries when the site exceeds the 200 limit", async () => {
const requested: string[] = [];
const { api } = createApi(async (url) => {
requested.push(url);
if (!url.includes("filter=")) return jsonResponse(page([], 512));
if (url.includes("WIRED")) return jsonResponse(page([], 400, 1));
if (url.includes("WIRELESS")) return jsonResponse(page([], 100, 1));
if (url.includes("TELEPORT")) return jsonResponse(page([], 2, 1));
if (url.includes("VPN")) return jsonResponse(page([], 10, 1));
return jsonResponse(page([], 5, 1));
});
const counts = await api.getClientCountsAsync("site-1");
expect(counts).toEqual({ total: 512, wired: 400, wireless: 100, vpn: 12, guests: 5 });
expect(requested.some((url) => url.includes("and("))).toBe(false);
expect(requested.filter((url) => url.includes("filter=")).length).toBe(5);
});
test("uses the prefix filter syntax the API actually accepts", async () => {
const requested: string[] = [];
const { api } = createApi(async (url) => {
requested.push(url);
return jsonResponse(page([], url.includes("filter=") ? 1 : 512, 1));
});
await api.getClientCountsAsync("site-1");
const guestQuery = requested.find((url) => url.includes("GUEST"));
expect(decodeURIComponent(guestQuery ?? "")).toContain("access.type.eq('GUEST')");
expect(decodeURIComponent(guestQuery ?? "")).not.toContain(" and ");
});
});
describe("UnifiOsApi getFirstSiteAsync", () => {
test("returns null for a console exposing no site rather than throwing", async () => {
const { api } = createApi(async () => jsonResponse(page([])));
expect(await api.getFirstSiteAsync()).toBeNull();
});
});
- Step 2 : Lancer les tests pour vérifier qu'ils échouent
Run: pnpm test packages/integrations/src/unifi-os/test/unifi-os-api.spec.ts
Expected: FAIL — Cannot find module '../unifi-os-api'.
- Step 3 : Écrire l'implémentation
Créer packages/integrations/src/unifi-os/unifi-os-api.ts :
import { ResponseError } from "@homarr/common/server";
import type { z } from "zod/v4";
import type {
UnifiOsClientCounts,
UnifiOsDevice,
UnifiOsDeviceStatistics,
UnifiOsSite,
} from "./unifi-os-types";
import {
countClients,
createUnifiOsPageSchema,
parseUnifiOsAsync,
unifiOsClientSchema,
unifiOsDeviceSchema,
unifiOsDeviceStatisticsSchema,
unifiOsInfoSchema,
unifiOsSiteSchema,
unifiOsVpnServerSchema,
} from "./unifi-os-types";
export type UnifiOsFetch = (url: string, init?: RequestInit & { timeout?: number }) => Promise<Response>;
const INTEGRATION_PATH = "/proxy/network/integration/v1";
const REQUEST_TIMEOUT_MS = 10_000;
/** Plafond imposé par l'API : demander davantage renvoie quand même 200. */
const MAX_PAGE_LIMIT = 200;
const PARSE_ERROR_MESSAGE = "Invalid UniFi OS response";
const clientPageSchema = createUnifiOsPageSchema(unifiOsClientSchema);
const devicePageSchema = createUnifiOsPageSchema(unifiOsDeviceSchema);
const sitePageSchema = createUnifiOsPageSchema(unifiOsSiteSchema);
const vpnServerPageSchema = createUnifiOsPageSchema(unifiOsVpnServerSchema);
/**
* Client de l'API d'intégration locale d'UniFi OS.
*
* Ne connaît ni Homarr ni la notion d'intégration : il ne sait que parler à une
* console. Le `fetch` est injecté pour que les tests n'aient pas à mocker un module.
*/
export class UnifiOsApi {
private readonly baseUrl: string;
constructor(
origin: string,
private readonly apiKey: string,
private readonly fetchAsync: UnifiOsFetch,
) {
this.baseUrl = `${origin.replace(/\/+$/, "")}${INTEGRATION_PATH}`;
}
public async getInfoAsync(): Promise<{ applicationVersion: string }> {
return await this.requestAsync("/info", unifiOsInfoSchema);
}
public async getFirstSiteAsync(): Promise<UnifiOsSite | null> {
const page = await this.requestAsync("/sites", sitePageSchema);
return page.data[0] ?? null;
}
public async getDevicesAsync(siteId: string): Promise<UnifiOsDevice[]> {
const page = await this.requestAsync(`/sites/${encodeURIComponent(siteId)}/devices?limit=${MAX_PAGE_LIMIT}`, devicePageSchema);
return page.data;
}
public async getDeviceStatisticsAsync(siteId: string, deviceId: string): Promise<UnifiOsDeviceStatistics> {
return await this.requestAsync(
`/sites/${encodeURIComponent(siteId)}/devices/${encodeURIComponent(deviceId)}/statistics/latest`,
unifiOsDeviceStatisticsSchema,
);
}
public async getVpnServersAsync(siteId: string): Promise<{ enabled: boolean }[]> {
const page = await this.requestAsync(`/sites/${encodeURIComponent(siteId)}/vpn/servers`, vpnServerPageSchema);
return page.data;
}
/**
* Sous le plafond de 200 clients, une seule page suffit et le comptage se fait
* en mémoire. Au-delà, rapatrier tous les enregistrements pour n'en tirer que
* des compteurs coûterait plus cher que cinq requêtes bornées.
*/
public async getClientCountsAsync(siteId: string): Promise<UnifiOsClientCounts> {
const path = `/sites/${encodeURIComponent(siteId)}/clients`;
const firstPage = await this.requestAsync(`${path}?limit=${MAX_PAGE_LIMIT}`, clientPageSchema);
if (firstPage.totalCount <= MAX_PAGE_LIMIT) {
return countClients(firstPage.data);
}
const countByFilterAsync = async (filter: string) => {
const page = await this.requestAsync(`${path}?limit=1&filter=${encodeURIComponent(filter)}`, clientPageSchema);
return page.totalCount;
};
const [wired, wireless, vpn, teleport, guests] = await Promise.all([
countByFilterAsync("type.eq('WIRED')"),
countByFilterAsync("type.eq('WIRELESS')"),
countByFilterAsync("type.eq('VPN')"),
countByFilterAsync("type.eq('TELEPORT')"),
countByFilterAsync("access.type.eq('GUEST')"),
]);
return { total: firstPage.totalCount, wired, wireless, vpn: vpn + teleport, guests };
}
private async requestAsync<TOutput>(path: string, schema: z.ZodType<TOutput>): Promise<TOutput> {
const response = await this.fetchAsync(`${this.baseUrl}${path}`, {
headers: { "X-API-KEY": this.apiKey, Accept: "application/json" },
timeout: REQUEST_TIMEOUT_MS,
});
if (!response.ok) {
throw new ResponseError(response);
}
return await parseUnifiOsAsync(await response.json(), schema, PARSE_ERROR_MESSAGE);
}
}
- Step 4 : Lancer les tests pour vérifier qu'ils passent
Run: pnpm test packages/integrations/src/unifi-os/test/unifi-os-api.spec.ts
Expected: PASS, 7 tests.
- Step 5 : Committer
pnpm format
git add packages/integrations/src/unifi-os/
git commit -m "feat(integrations): add UniFi OS local API client"
Task 4 : Client HTTP cloud, optionnel et caché
Files:
- Create:
packages/integrations/src/unifi-os/unifi-sm-api.ts - Test:
packages/integrations/src/unifi-os/test/unifi-sm-api.spec.ts
Interfaces:
-
Consumes:
unifiSmSiteSchema,unifiSmIspMetricsResponseSchema,matchCloudSite,parseUnifiOsAsync,UnifiOsIspMetricsde la Task 2 ;UnifiOsFetchde la Task 3. -
Produces :
class UnifiSmApi— constructeur(apiKey: string, fetchAsync: UnifiOsFetch)getIspMetricsAsync(gatewayMac: string | null): Promise<UnifiOsIspMetrics | null>static clearCache(): void— réservé aux tests
-
Step 1 : Écrire les tests qui échouent
Créer packages/integrations/src/unifi-os/test/unifi-sm-api.spec.ts :
import { Response } from "undici";
import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
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();
});
});
- Step 2 : Lancer les tests pour vérifier qu'ils échouent
Run: pnpm test packages/integrations/src/unifi-os/test/unifi-sm-api.spec.ts
Expected: FAIL — Cannot find module '../unifi-sm-api'.
- Step 3 : Écrire l'implémentation
Créer packages/integrations/src/unifi-os/unifi-sm-api.ts :
import { createLogger } from "@homarr/core/infrastructure/logs";
import type { UnifiOsFetch } from "./unifi-os-api";
import type { UnifiOsIspMetrics } from "./unifi-os-types";
import { matchCloudSite, parseUnifiOsAsync, unifiSmIspMetricsResponseSchema, unifiSmSiteSchema } from "./unifi-os-types";
import { z } from "zod/v4";
const logger = createLogger({ module: "unifiSmApi" });
const BASE_URL = "https://api.ui.com";
const REQUEST_TIMEOUT_MS = 15_000;
/**
* Les métriques cloud sont agrégées par tranches de 5 min et publiées avec un
* retard mesuré d'environ 27 min. Les rafraîchir plus souvent que le cache
* n'apporterait aucune donnée nouvelle et rapprocherait d'une limitation de débit.
*/
const CACHE_TTL_MS = 5 * 60 * 1000;
/** Une fenêtre de 15 min renvoie un tableau vide sur l'API réelle ; 3 h fonctionne. */
const QUERY_WINDOW_MS = 3 * 60 * 60 * 1000;
const siteListSchema = z.looseObject({ data: z.array(unifiSmSiteSchema) });
interface CacheEntry {
expiresAt: number;
value: UnifiOsIspMetrics | null;
}
/**
* Client de l'API cloud Site Manager. Entièrement optionnel : il n'est instancié
* que lorsqu'une clé Site Manager est configurée.
*
* Toute erreur est absorbée et convertie en `null`. Le cloud est un enrichissement ;
* son indisponibilité ne doit jamais faire tomber le widget.
*/
export class UnifiSmApi {
private static readonly cache = new Map<string, CacheEntry>();
constructor(
private readonly apiKey: string,
private readonly fetchAsync: UnifiOsFetch,
) {}
/** Réservé aux tests : le cache est statique et survivrait d'un cas à l'autre. */
public static clearCache(): void {
UnifiSmApi.cache.clear();
}
public async getIspMetricsAsync(gatewayMac: string | null): Promise<UnifiOsIspMetrics | null> {
if (gatewayMac === null) return null;
const cached = UnifiSmApi.cache.get(gatewayMac);
if (cached !== undefined && cached.expiresAt > Date.now()) {
return cached.value;
}
let value: UnifiOsIspMetrics | null = null;
try {
value = await this.fetchIspMetricsAsync(gatewayMac);
} catch (error) {
logger.warn("Failed to read UniFi Site Manager metrics", { error });
}
UnifiSmApi.cache.set(gatewayMac, { expiresAt: Date.now() + CACHE_TTL_MS, value });
return value;
}
private async fetchIspMetricsAsync(gatewayMac: string): Promise<UnifiOsIspMetrics | null> {
const sitesResponse = await this.fetchAsync(`${BASE_URL}/v1/sites`, {
headers: { "X-API-KEY": this.apiKey, Accept: "application/json" },
timeout: REQUEST_TIMEOUT_MS,
});
if (!sitesResponse.ok) return null;
const sites = await parseUnifiOsAsync(await sitesResponse.json(), siteListSchema, "Invalid Site Manager sites response");
const site = matchCloudSite(gatewayMac, sites.data);
if (site === null) return null;
const end = new Date();
const begin = new Date(end.getTime() - QUERY_WINDOW_MS);
const metricsResponse = await this.fetchAsync(`${BASE_URL}/v1/isp-metrics/5m/query`, {
method: "POST",
headers: { "X-API-KEY": this.apiKey, Accept: "application/json", "Content-Type": "application/json" },
timeout: REQUEST_TIMEOUT_MS,
body: JSON.stringify({
sites: [
{
hostId: site.hostId,
siteId: site.siteId,
beginTimestamp: begin.toISOString(),
endTimestamp: end.toISOString(),
},
],
}),
});
if (!metricsResponse.ok) return null;
const parsed = await parseUnifiOsAsync(
await metricsResponse.json(),
unifiSmIspMetricsResponseSchema,
"Invalid Site Manager ISP metrics response",
);
const periods = parsed.data.metrics[0]?.periods ?? [];
const latest = periods.at(-1);
const wan = latest?.data.wan;
if (latest === undefined || wan === undefined) return null;
const externalIp = Object.values(site.statistics?.wans ?? {})
.map((entry) => entry.externalIp)
.find((ip) => ip !== undefined);
return {
name: wan.ispName ?? site.statistics?.ispInfo?.name ?? "",
externalIp: externalIp ?? null,
latencyMs: wan.avgLatency ?? 0,
maxLatencyMs: wan.maxLatency ?? 0,
packetLossPct: wan.packetLoss ?? 0,
uptimePct: wan.uptime ?? site.statistics?.percentages?.wanUptime ?? 0,
measuredAt: new Date(latest.metricTime),
};
}
}
- Step 4 : Lancer les tests pour vérifier qu'ils passent
Run: pnpm test packages/integrations/src/unifi-os/test/unifi-sm-api.spec.ts
Expected: PASS, 7 tests.
- Step 5 : Committer
pnpm format
git add packages/integrations/src/unifi-os/
git commit -m "feat(integrations): add optional UniFi Site Manager client with 5min cache"
Task 5 : Classe d'intégration et enregistrement
Files:
- Create:
packages/integrations/src/interfaces/unifi-os-summary/unifi-os-summary-integration.ts - Create:
packages/integrations/src/unifi-os/unifi-os-integration.ts - Test:
packages/integrations/src/unifi-os/test/unifi-os-integration.spec.ts - Modify:
packages/integrations/src/base/creator.ts - Modify:
packages/integrations/src/index.ts - Modify:
packages/integrations/src/types.ts
Interfaces:
-
Consumes:
UnifiOsApi(Task 3),UnifiSmApi(Task 4), les mappers et types (Task 2), le kindunifiOs(Task 1). -
Produces :
interface UnifiOsSummaryIntegration { getUnifiOsSummaryAsync(): Promise<UnifiOsSummary> }class UnifiOsIntegration extends Integration implements UnifiOsSummaryIntegration- entrée
unifiOsdansintegrationCreators
-
Step 1 : Écrire les tests qui échouent
Créer packages/integrations/src/unifi-os/test/unifi-os-integration.spec.ts :
// @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);
});
});
- Step 2 : Lancer les tests pour vérifier qu'ils échouent
Run: pnpm test packages/integrations/src/unifi-os/test/unifi-os-integration.spec.ts
Expected: FAIL — Cannot find module '../unifi-os-integration'.
- Step 3 : Écrire l'interface
Créer packages/integrations/src/interfaces/unifi-os-summary/unifi-os-summary-integration.ts :
import type { UnifiOsSummary } from "../../unifi-os/unifi-os-types";
export interface UnifiOsSummaryIntegration {
getUnifiOsSummaryAsync(): Promise<UnifiOsSummary>;
}
- Step 4 : Écrire la classe d'intégration
Créer packages/integrations/src/unifi-os/unifi-os-integration.ts :
import { fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/http";
import type { IntegrationTestingInput } from "../base/integration";
import { Integration } from "../base/integration";
import { TestConnectionError } from "../base/test-connection/test-connection-error";
import type { TestingResult } from "../base/test-connection/test-connection-service";
import type { UnifiOsSummaryIntegration } from "../interfaces/unifi-os-summary/unifi-os-summary-integration";
import type { UnifiOsFetch } from "./unifi-os-api";
import { UnifiOsApi } from "./unifi-os-api";
import { UnifiSmApi } from "./unifi-sm-api";
import type { UnifiOsDevice, UnifiOsDeviceStatistics, UnifiOsSummary } from "./unifi-os-types";
import { findGateway, summarizeDevices } from "./unifi-os-types";
const EMPTY_CLIENT_COUNTS = { total: 0, wired: 0, wireless: 0, vpn: 0, guests: 0 } as const;
const EMPTY_DEVICE_COUNTS = { total: 0, online: 0, offline: 0, firmwareUpdatable: 0 } as const;
/** `Promise.allSettled` renvoie `rejected` sans valeur ; on retombe sur un défaut. */
const settledValue = <T>(result: PromiseSettledResult<T>, fallback: T): T =>
result.status === "fulfilled" ? result.value : fallback;
export class UnifiOsIntegration extends Integration implements UnifiOsSummaryIntegration {
public async getUnifiOsSummaryAsync(): Promise<UnifiOsSummary> {
return await this.buildSummaryAsync(fetchWithTrustedCertificatesAsync as UnifiOsFetch);
}
protected async testingAsync({ fetchAsync }: IntegrationTestingInput): Promise<TestingResult> {
const api = this.createLocalApi(fetchAsync as unknown as UnifiOsFetch);
try {
await api.getInfoAsync();
} catch (error) {
return TestConnectionError.UnknownResult(error);
}
const site = await api.getFirstSiteAsync();
if (site === null) {
// Une clé valide sur une console sans site est configurable mais inutile :
// mieux vaut le dire au moment du test que laisser un widget vide.
return TestConnectionError.UnknownResult(new Error("The UniFi OS console exposes no site"));
}
return { success: true };
}
private createLocalApi(fetchAsync: UnifiOsFetch) {
return new UnifiOsApi(this.integration.url, this.getSecretValue("apiKey"), fetchAsync);
}
private async buildSummaryAsync(fetchAsync: UnifiOsFetch): Promise<UnifiOsSummary> {
const api = this.createLocalApi(fetchAsync);
const [info, site] = await Promise.all([api.getInfoAsync(), api.getFirstSiteAsync()]);
if (site === null) {
throw new Error("The UniFi OS console exposes no site");
}
const [clientsResult, devicesResult] = await Promise.allSettled([
api.getClientCountsAsync(site.id),
api.getDevicesAsync(site.id),
]);
const clients = settledValue(clientsResult, { ...EMPTY_CLIENT_COUNTS });
const devices = settledValue<UnifiOsDevice[]>(devicesResult, []);
const gatewayDevice = findGateway(devices);
// Les statistiques dépendent du gateway : sans gateway identifié, il n'y a
// rien à demander. Un échec ici ne doit vider que le débit et l'uptime.
let statistics: UnifiOsDeviceStatistics | null = null;
if (gatewayDevice !== null) {
try {
statistics = await api.getDeviceStatisticsAsync(site.id, gatewayDevice.id);
} catch {
statistics = null;
}
}
const isp = await this.readIspMetricsAsync(fetchAsync, gatewayDevice?.macAddress ?? null);
return {
site: { id: site.id, name: site.name, applicationVersion: info.applicationVersion },
wan: {
state: gatewayDevice === null ? "unknown" : gatewayDevice.state === "ONLINE" ? "online" : "offline",
throughput:
statistics?.uplink === undefined
? null
: { txBps: statistics.uplink.txRateBps, rxBps: statistics.uplink.rxRateBps },
isp,
},
clients,
devices: devicesResult.status === "fulfilled" ? summarizeDevices(devices) : { ...EMPTY_DEVICE_COUNTS },
gateway:
gatewayDevice === null
? null
: {
name: gatewayDevice.name,
model: gatewayDevice.model,
macAddress: gatewayDevice.macAddress,
uptimeSec: statistics?.uptimeSec ?? null,
cpuPct: statistics?.cpuUtilizationPct ?? null,
memoryPct: statistics?.memoryUtilizationPct ?? null,
},
};
}
/**
* Le cloud n'est jamais interrogé sans clé configurée : le module n'est même
* pas instancié, ce qui rend impossible un appel réseau accidentel.
*/
private async readIspMetricsAsync(fetchAsync: UnifiOsFetch, gatewayMac: string | null) {
if (!this.hasSecretValue("siteManagerApiKey")) return null;
const smApi = new UnifiSmApi(this.getSecretValue("siteManagerApiKey"), fetchAsync);
return await smApi.getIspMetricsAsync(gatewayMac);
}
}
- Step 5 : Enregistrer la classe
Dans packages/integrations/src/base/creator.ts, ajouter l'import à côté de celui de UnifiControllerIntegration :
import { UnifiOsIntegration } from "../unifi-os/unifi-os-integration";
et, dans l'objet des créateurs, juste après unifiController: UnifiControllerIntegration, :
unifiOs: UnifiOsIntegration,
Dans packages/integrations/src/index.ts, ajouter :
export { UnifiOsIntegration } from "./unifi-os/unifi-os-integration";
Dans packages/integrations/src/types.ts, à côté de la ligne export * from "./unifi-controller/unifi-controller-types"; :
export * from "./unifi-os/unifi-os-types";
export * from "./interfaces/unifi-os-summary/unifi-os-summary-integration";
- Step 6 : Lancer les tests pour vérifier qu'ils passent
Run: pnpm test packages/integrations/src/unifi-os/
Expected: PASS, l'ensemble des tests des tâches 2 à 5.
- Step 7 : Vérifier le typage
Run: pnpm turbo typecheck --filter=@homarr/integrations
Expected: PASS.
- Step 8 : Vérifier qu'aucune intégration existante n'a bougé
git status --short packages/integrations/src/unifi-controller packages/integrations/src/opnsense packages/integrations/src/interfaces/network-controller-summary
Expected: aucune sortie. Une sortie non vide signifie que la contrainte « ne pas toucher aux intégrations existantes » a été violée — annuler ces modifications.
- Step 9 : Committer
pnpm format
git add packages/integrations/
git commit -m "feat(integrations): add UnifiOsIntegration with optional cloud enrichment"
Task 6 : Request handler et routeur tRPC
Files:
- Create:
packages/request-handler/src/unifi-os.ts - Create:
packages/api/src/router/widgets/unifi-os.ts - Modify:
packages/api/src/router/widgets/index.ts
Interfaces:
-
Consumes:
UnifiOsIntegration.getUnifiOsSummaryAsync()et le typeUnifiOsSummary(Task 5). -
Produces :
unifiOsRequestHandleravec.handler(integration, {}).getDataAsync()unifiOsRouterexposantclientApi.widget.unifiOs.summary.useQuery({ integrationIds })
-
Step 1 : Écrire le request handler
Créer packages/request-handler/src/unifi-os.ts, calqué sur network-controller.ts :
import { createIntegrationAsync } from "@homarr/integrations";
import type { UnifiOsSummary } from "@homarr/integrations/types";
import { createIntegrationRequestHandler } from "./lib/integration-request-handler";
export const unifiOsRequestHandler = createIntegrationRequestHandler<UnifiOsSummary, "unifiOs", Record<string, never>>({
async requestAsync(integration, _input) {
const integrationInstance = await createIntegrationAsync(integration);
return await integrationInstance.getUnifiOsSummaryAsync();
},
cacheTtlMs: 60 * 1000,
// Une console momentanément injoignable doit afficher la dernière valeur connue
// plutôt qu'une tuile d'erreur ; le widget signale la péremption.
fallbackToStaleOnError: true,
staleIfErrorTtlMs: 10 * 60 * 1000,
});
Le paramètre de kind est ici le littéral "unifiOs" et non IntegrationKindByCategory<"unifiOs"> : une seule intégration appartient à cette catégorie, et l'écrire en clair évite un aller-retour de lecture.
- Step 2 : Écrire le routeur tRPC
Créer packages/api/src/router/widgets/unifi-os.ts :
import { unifiOsRequestHandler } from "@homarr/request-handler/unifi-os";
import { createManyIntegrationMiddleware } from "../../middlewares/integration";
import { settleIntegrationQueries } from "../../settle-integrations";
import { createTRPCRouter, publicProcedure } from "../../trpc";
export const unifiOsRouter = createTRPCRouter({
summary: publicProcedure.concat(createManyIntegrationMiddleware("query", "unifiOs")).query(async ({ ctx }) => {
return await settleIntegrationQueries(ctx.integrations, async (integration) => {
const innerHandler = unifiOsRequestHandler.handler(integration, {});
const { data, timestamp } = await innerHandler.getDataAsync();
return {
integration: {
id: integration.id,
name: integration.name,
kind: integration.kind,
},
summary: data,
updatedAt: timestamp,
};
});
}),
});
- Step 3 : Enregistrer le routeur
Dans packages/api/src/router/widgets/index.ts, à côté de la ligne networkController: lazy(...), ajouter :
unifiOs: lazy(() => import("./unifi-os").then((mod) => mod.unifiOsRouter)),
- Step 4 : Vérifier l'export du sous-chemin
@homarr/request-handler/unifi-os
Run: grep -n '"./\*"\|exports' packages/request-handler/package.json
Expected: le champ exports utilise un motif générique ("./*"). Si ce n'est pas le cas, ajouter explicitement l'entrée "./unifi-os" en copiant la forme de "./network-controller".
- Step 5 : Vérifier le typage
Run: pnpm turbo typecheck --filter=@homarr/api --filter=@homarr/request-handler
Expected: PASS.
- Step 6 : Committer
pnpm format
git add packages/request-handler/src/unifi-os.ts packages/api/src/router/widgets/
git commit -m "feat(api): expose unifiOs widget summary query"
Task 7 : Widget
Files:
- Create:
packages/widgets/src/unifi-os/index.ts - Create:
packages/widgets/src/unifi-os/component.tsx - Modify:
packages/widgets/src/manifest.ts - Modify:
packages/widgets/src/index.tsx - Modify:
packages/widgets/src/catalog.ts - Modify:
packages/widgets/src/refetch-intervals.ts - Modify:
packages/translation/src/lang/en.json
Interfaces:
-
Consumes:
clientApi.widget.unifiOs.summary(Task 6),UnifiOsSummary(Task 2), leWidgetKindunifiOs(Task 1). -
Produces: le widget affichable, disposition « bandeau WAN + lignes » de la spec §8.
-
Step 1 : Écrire la définition du widget
Créer packages/widgets/src/unifi-os/index.ts :
import { IconRouter, IconServerOff } from "@tabler/icons-react";
import { createWidgetDefinition } from "../definition";
import { optionsBuilder } from "../options";
export const { definition, componentLoader } = createWidgetDefinition("unifiOs", {
icon: IconRouter,
supportedIntegrations: ["unifiOs"],
integrationsRequired: true,
createOptions() {
return optionsBuilder.from((factory) => ({
showIsp: factory.switch({ defaultValue: true, withDescription: true }),
showDevices: factory.switch({ defaultValue: true, withDescription: true }),
showFirmwareUpdates: factory.switch({ defaultValue: true, withDescription: true }),
}));
},
errors: {
INTERNAL_SERVER_ERROR: {
icon: IconServerOff,
message: (t) => t("widget.unifiOs.error.internalServerError"),
},
},
}).withDynamicImport(() => import("./component"));
- Step 2 : Écrire le composant
Créer packages/widgets/src/unifi-os/component.tsx. Disposition : bandeau WAN
dominant, puis une ligne par thème.
"use client";
import { useMemo } from "react";
import { Badge, Box, Group, Stack, Text, Tooltip } from "@mantine/core";
import { IconCircleFilled } from "@tabler/icons-react";
import dayjs from "dayjs";
import relativeTime from "dayjs/plugin/relativeTime";
import { clientApi } from "@homarr/api/client";
import { useI18n } from "@homarr/translation/client";
import type { WidgetComponentProps } from "../definition";
dayjs.extend(relativeTime);
const formatBitsPerSecond = (bps: number): string => {
const units = ["b/s", "Kb/s", "Mb/s", "Gb/s"];
let value = bps;
let unitIndex = 0;
while (value >= 1000 && unitIndex < units.length - 1) {
value /= 1000;
unitIndex += 1;
}
return `${value.toFixed(value >= 100 || unitIndex === 0 ? 0 : 1)} ${units[unitIndex]}`;
};
const formatUptime = (seconds: number): string => {
const days = Math.floor(seconds / 86400);
const hours = Math.floor((seconds % 86400) / 3600);
return days > 0 ? `${days}d ${hours}h` : `${hours}h`;
};
export default function UnifiOsWidget({ integrationIds, options }: WidgetComponentProps<"unifiOs">) {
const t = useI18n();
const { data: results = [] } = clientApi.widget.unifiOs.summary.useQuery({ integrationIds });
const summary = useMemo(() => results[0]?.summary ?? null, [results]);
if (summary === null) {
return (
<Box h="100%" p="sm">
<Text c="dimmed" size="sm">
{t("widget.unifiOs.error.noData")}
</Text>
</Box>
);
}
const wanColor = summary.wan.state === "online" ? "green" : summary.wan.state === "offline" ? "red" : "gray";
return (
<Stack h="100%" p="sm" gap="xs" justify="space-between">
{/* Le nom du site n'est pas décoratif : une console peut héberger plusieurs
sites et le widget n'en affiche qu'un. L'afficher rend ce choix visible. */}
<Group gap={6} wrap="nowrap">
<IconCircleFilled size={8} color={`var(--mantine-color-${wanColor}-6)`} />
<Text size="xs" c="dimmed" tt="uppercase" fw={600} truncate>
{summary.site.name}
</Text>
</Group>
<Stack gap={4} p="xs" style={{ borderRadius: "var(--mantine-radius-md)", background: "var(--mantine-color-default-hover)" }}>
<Group justify="space-between" wrap="nowrap" gap="xs">
<Group gap={6} wrap="nowrap">
<IconCircleFilled size={10} color={`var(--mantine-color-${wanColor}-6)`} />
<Text fw={600} size="sm">
{t("widget.unifiOs.card.internet")}
</Text>
</Group>
{summary.wan.throughput !== null && (
<Text size="sm" ff="monospace">
↑{formatBitsPerSecond(summary.wan.throughput.txBps)} ↓{formatBitsPerSecond(summary.wan.throughput.rxBps)}
</Text>
)}
</Group>
{options.showIsp && summary.wan.isp !== null && (
<Group justify="space-between" wrap="nowrap" gap="xs">
<Text size="xs" c="dimmed" truncate>
{summary.wan.isp.name}
{summary.wan.isp.externalIp !== null ? ` · ${summary.wan.isp.externalIp}` : ""}
</Text>
<Group gap={6} wrap="nowrap">
<Text size="xs">
{t("widget.unifiOs.card.latency", { value: `${summary.wan.isp.latencyMs}` })}
</Text>
<Tooltip label={t("widget.unifiOs.card.measuredAt", { time: dayjs(summary.wan.isp.measuredAt).format("HH:mm") })}>
<Badge size="xs" variant="light" color="yellow">
{dayjs(summary.wan.isp.measuredAt).fromNow()}
</Badge>
</Tooltip>
</Group>
</Group>
)}
</Stack>
<Stack gap={2}>
<Group justify="space-between" wrap="nowrap">
<Text size="sm" c="dimmed">
{t("widget.unifiOs.card.clients")}
</Text>
<Text size="sm" fw={600}>
{t("widget.unifiOs.card.clientBreakdown", {
total: `${summary.clients.total}`,
wired: `${summary.clients.wired}`,
wireless: `${summary.clients.wireless}`,
})}
</Text>
</Group>
{options.showDevices && (
<Group justify="space-between" wrap="nowrap">
<Text size="sm" c="dimmed">
{t("widget.unifiOs.card.devices")}
</Text>
<Text size="sm" fw={600} c={summary.devices.offline > 0 ? "red" : undefined}>
{t("widget.unifiOs.card.devicesOnline", {
online: `${summary.devices.online}`,
total: `${summary.devices.total}`,
})}
</Text>
</Group>
)}
{options.showFirmwareUpdates && summary.devices.firmwareUpdatable > 0 && (
<Group justify="space-between" wrap="nowrap">
<Text size="sm" c="dimmed">
{t("widget.unifiOs.card.firmware")}
</Text>
<Text size="sm" fw={600} c="yellow">
{t("widget.unifiOs.card.firmwarePending", { count: `${summary.devices.firmwareUpdatable}` })}
</Text>
</Group>
)}
</Stack>
<Group justify="space-between" wrap="nowrap">
<Text size="xs" c="dimmed" truncate>
{t("widget.unifiOs.card.version", { version: summary.site.applicationVersion })}
</Text>
{summary.gateway?.uptimeSec != null && (
<Text size="xs" c="dimmed">
{t("widget.unifiOs.card.gatewayUptime", { uptime: formatUptime(summary.gateway.uptimeSec) })}
</Text>
)}
</Group>
</Stack>
);
}
- Step 3 : Enregistrer dans le manifeste
Dans packages/widgets/src/manifest.ts, ajouter dans la carte des modules (à côté de networkControllerSummary) :
unifiOs: () => import("./unifi-os") as Promise<WidgetModule>,
et dans la carte des composants :
unifiOs: () => import("./unifi-os/component") as Promise<WidgetComponentModule>,
- Step 4 : Enregistrer dans l'index et le catalogue
Dans packages/widgets/src/index.tsx, ajouter l'import à côté de networkControllerSummary :
import * as unifiOs from "./unifi-os";
et l'entrée correspondante dans l'objet exporté :
unifiOs,
Dans packages/widgets/src/catalog.ts, importer IconRouter depuis @tabler/icons-react (en respectant l'ordre alphabétique de la liste d'imports existante) et ajouter au widgetCatalogIcons :
unifiOs: IconRouter,
L'icône doit être exactement la même que celle de la définition — manifest.spec.ts compare les deux par identité (toBe).
- Step 5 : Déclarer l'intervalle de rafraîchissement
Dans packages/widgets/src/refetch-intervals.ts, ajouter à widgetQueryRefetchIntervals :
{ queryKey: [["widget", "unifiOs"]], intervalSeconds: 60 },
- Step 6 : Ajouter les traductions
Dans packages/translation/src/lang/en.json, dans l'objet widget, ajouter :
"unifiOs": {
"name": "UniFi OS",
"description": "Network overview from a UniFi OS console",
"option": {
"showIsp": { "label": "Show ISP details", "description": "Requires a Site Manager API key" },
"showDevices": { "label": "Show devices", "description": "Display how many devices are online" },
"showFirmwareUpdates": { "label": "Show firmware updates", "description": "Display how many devices have a pending firmware update" }
},
"card": {
"internet": "Internet",
"latency": "{value} ms",
"measuredAt": "Measured at {time}",
"clients": "Clients",
"clientBreakdown": "{total} · {wired} wired · {wireless} Wi-Fi",
"devices": "Devices",
"devicesOnline": "{online} / {total} online",
"firmware": "Firmware",
"firmwarePending": "{count} to update",
"version": "Network {version}",
"gatewayUptime": "Gateway up {uptime}"
},
"error": {
"internalServerError": "Could not reach the UniFi OS console",
"noData": "No data available"
}
}
- Step 7 : Lancer les tests du paquet widgets
Run: pnpm test packages/widgets/src/manifest.spec.ts
Expected: PASS. Ce test vérifie que le nouveau WidgetKind est présent dans le manifeste, dans le catalogue avec la même icône, et dans les intervalles de rafraîchissement. Un échec ici indique un point d'enregistrement oublié.
- Step 8 : Vérifier le typage global
Run: pnpm turbo typecheck
Expected: PASS sur tous les paquets.
- Step 9 : Lint
Run: pnpm lint
Expected: PASS.
- Step 10 : Committer
pnpm format
git add packages/widgets/ packages/translation/src/lang/en.json
git commit -m "feat(widgets): add UniFi OS widget"
Task 8 : Vérification contre la console réelle
Les tâches précédentes prouvent que le code fait ce qu'on croit. Celle-ci prouve que ce qu'on croit correspond à la réalité.
Files:
- Aucun fichier versionné n'est créé. Le script de vérification reste hors dépôt.
Interfaces:
-
Consumes: l'intégralité des tâches 1 à 7.
-
Produces: la confirmation que les valeurs affichées correspondent à la console.
-
Step 1 : Démarrer l'environnement de développement
corepack enable
pnpm install
pnpm docker:dev:up
pnpm dev
- Step 2 : Créer l'intégration dans l'interface
Dans Homarr, créer une intégration de type UniFi OS :
- URL : l'origine de la console, sans chemin.
apiKey: clé générée dans l'application Network (Paramètres → Control Plane → Integrations). Pas une clé du site manager : elle serait rejetée en401.siteManagerApiKey: optionnelle, générée surunifi.ui.com.
Puis lancer le test de connexion. Expected: succès. Un échec ici concerne la couche cliente, pas l'interface.
- Step 3 : Comparer les valeurs à la console
Ajouter le widget UniFi OS sur un board et comparer, champ par champ, avec l'interface UniFi :
| Champ | Où vérifier dans UniFi |
|---|---|
| Clients filaires / Wi-Fi | Client Devices, filtré par type de connexion |
| Équipements en ligne | UniFi Devices |
| Firmwares en attente | UniFi Devices, colonne de mise à jour |
| Débit WAN | Tableau de bord, graphe du gateway |
| Latence et fraîcheur | Site Manager cloud — l'écart d'environ 27 min est attendu |
- Step 4 : Vérifier la dégradation
Retirer la siteManagerApiKey de l'intégration et recharger.
Expected: le bloc ISP disparaît, tout le reste continue de s'afficher.
- Step 5 : Consigner l'écart éventuel
Si un chiffre diverge, ne pas ajuster le widget : corriger le mapper de la Task 2 et ajouter un test reproduisant le cas. Un chiffre corrigé sans test revient la fois suivante.
Task 9 : Build et déploiement sur le LXC
Files:
- Aucun fichier versionné.
Interfaces:
- Consumes: une branche
feat/unifi-os-integrationdont toutes les tâches sont validées. - Produces: l'instance de production servant le widget.
⚠️ Ne pas démarrer cette tâche tant que la Task 8 n'est pas concluante.
- Step 1 : Vérifier l'alignement des migrations avant toute chose
ls packages/db/migrations/sqlite/ | tail -3
ssh zachary@10.70.1.13 'ls /opt/homarr/db/migrations/*/ | tail -3'
Expected: la dernière migration est identique des deux côtés. Si elles divergent, arrêter et traiter la mise à jour de schéma comme un sujet distinct : le rollback ne serait plus une simple restauration d'archive.
- Step 2 : Construire
pnpm turbo build
Expected: build complet sans erreur.
- Step 3 : Sauvegarder l'instance
ssh zachary@10.70.1.13 'sudo tar czf /root/homarr-backup-$(date +%F-%H%M).tar.gz /opt/homarr && sudo ls -la /root/ | grep homarr-backup'
Expected: l'archive existe et n'est pas vide. Sauvegarder également la base
selon le DB_DRIVER déclaré dans /etc/homarr/homarr.env.
- Step 4 : Arrêter le service
ssh zachary@10.70.1.13 'sudo systemctl stop homarr && systemctl is-active homarr || true'
Expected: inactive. Ne jamais rsync sur un Next.js en cours d'exécution.
- Step 5 : Déployer
Reproduire la disposition existante de /opt/homarr (apps/, packages/,
build/, node_modules/) à partir de la sortie standalone du build. Ne pas
toucher à /etc/homarr/homarr.env ni à run.sh, nginx.conf, redis.conf,
entrypoint.sh, qui appartiennent à l'installation et non au build.
- Step 6 : Redémarrer et vérifier
ssh zachary@10.70.1.13 'sudo systemctl start homarr && sleep 10 && systemctl is-active homarr && sudo journalctl -u homarr -n 40 --no-pager'
Expected: active, aucune erreur de migration dans les journaux.
- Step 7 : Vérifier dans le navigateur
Ouvrir l'instance de production, vérifier que le widget affiche les mêmes valeurs
qu'en développement, et que les intégrations préexistantes fonctionnent
toujours — c'est le contrôle qui prouve que SECRET_ENCRYPTION_KEY est intact.
- Step 8 : En cas de problème, restaurer
ssh zachary@10.70.1.13 'sudo systemctl stop homarr && sudo rm -rf /opt/homarr && sudo tar xzf /root/homarr-backup-<horodatage>.tar.gz -C / && sudo systemctl start homarr'
Points laissés ouverts
À trancher hors de ce plan, sans bloquer son exécution :
- Où pousser le fork. Une instance Gitea est disponible. Sans dépôt distant, la branche n'existe que sur le poste — une panne de disque effacerait le travail.
- Stratégie de rebase. Homarr publie fréquemment. Les modifications sont concentrées dans un dossier neuf, mais les douze points d'attache du §5.2 de la spec sont autant de sources de conflit à chaque montée de version.
- Révocation des clés d'API utilisées pendant la conception.