feat: add Uptime Kuma, Audiobookshelf, Paperless-ngx, and Navidrome integrations (#5910)
This commit is contained in:
1 parent
a4db9cf0dc
commit
d77c6f8d4e
46 files changed
+2994
-16
No files matched your search
@@ -0,0 +1,162 @@
|
||||
import { Response } from "undici";
|
||||
import { beforeEach, describe, expect, test, vi } from "vitest";
|
||||
|
||||
import { fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/http";
|
||||
|
||||
import type { IntegrationSecret } from "../../base/types";
|
||||
import { UptimeKumaIntegration } from "../uptime-kuma-integration";
|
||||
import { uptimeKumaHeartbeatCategoryMap } from "../uptime-kuma-types";
|
||||
|
||||
vi.mock("@homarr/core/infrastructure/http", () => ({
|
||||
fetchWithTrustedCertificatesAsync: vi.fn(),
|
||||
}));
|
||||
|
||||
const TEST_URL = "https://uptime.example.com";
|
||||
const mockFetch = vi.mocked(fetchWithTrustedCertificatesAsync);
|
||||
|
||||
const toUrlString = (url: unknown): string => String(url);
|
||||
|
||||
const createIntegration = (secrets: IntegrationSecret[] = []) =>
|
||||
new UptimeKumaIntegration({
|
||||
id: "test-uptime-kuma",
|
||||
name: "Test Uptime Kuma",
|
||||
url: TEST_URL,
|
||||
externalUrl: null,
|
||||
decryptedSecrets: secrets,
|
||||
});
|
||||
|
||||
beforeEach(() => {
|
||||
mockFetch.mockReset();
|
||||
});
|
||||
|
||||
describe("uptimeKumaHeartbeatCategoryMap", () => {
|
||||
test("maps status 0 (down) to 'down'", () => {
|
||||
expect(uptimeKumaHeartbeatCategoryMap[0]).toBe("down");
|
||||
});
|
||||
|
||||
test("maps status 1 (up) to 'up'", () => {
|
||||
expect(uptimeKumaHeartbeatCategoryMap[1]).toBe("up");
|
||||
});
|
||||
|
||||
test("maps status 2 (pending) to 'paused'", () => {
|
||||
expect(uptimeKumaHeartbeatCategoryMap[2]).toBe("paused");
|
||||
});
|
||||
|
||||
test("maps status 3 (maintenance) to 'paused'", () => {
|
||||
expect(uptimeKumaHeartbeatCategoryMap[3]).toBe("paused");
|
||||
});
|
||||
|
||||
test("returns undefined for unknown status codes", () => {
|
||||
expect(uptimeKumaHeartbeatCategoryMap[99]).toBeUndefined();
|
||||
});
|
||||
});
|
||||
|
||||
describe("UptimeKumaIntegration.getDashboardDataAsync", () => {
|
||||
const statusPageResponse = {
|
||||
publicGroupList: [
|
||||
{
|
||||
id: 1,
|
||||
name: "Services",
|
||||
monitorList: [
|
||||
{ id: 10, name: "Web" },
|
||||
{ id: 20, name: "API" },
|
||||
{ id: 30, name: "DB" },
|
||||
],
|
||||
},
|
||||
],
|
||||
};
|
||||
|
||||
const heartbeatResponse = {
|
||||
heartbeatList: {
|
||||
"10": [{ status: 1, time: "2025-01-01" }],
|
||||
"20": [{ status: 0, time: "2025-01-01" }],
|
||||
"30": [{ status: 2, time: "2025-01-01" }],
|
||||
},
|
||||
uptimeList: {
|
||||
"10_24": 0.995,
|
||||
"20_24": 0.5,
|
||||
"30_24": 0.8,
|
||||
},
|
||||
};
|
||||
|
||||
const mockResponses = () => {
|
||||
mockFetch.mockImplementation((url) => {
|
||||
const urlStr = toUrlString(url);
|
||||
|
||||
if (urlStr.includes("/heartbeat/")) {
|
||||
return Promise.resolve(
|
||||
new Response(JSON.stringify(heartbeatResponse), { status: 200 }),
|
||||
) as unknown as ReturnType<typeof fetchWithTrustedCertificatesAsync>;
|
||||
}
|
||||
|
||||
return Promise.resolve(
|
||||
new Response(JSON.stringify(statusPageResponse), { status: 200 }),
|
||||
) as unknown as ReturnType<typeof fetchWithTrustedCertificatesAsync>;
|
||||
});
|
||||
};
|
||||
|
||||
test("aggregates monitor counts correctly", async () => {
|
||||
mockResponses();
|
||||
const integration = createIntegration([{ kind: "slug", value: "default" }]);
|
||||
const result = await integration.getDashboardDataAsync();
|
||||
|
||||
expect(result.totalMonitors).toBe(3);
|
||||
expect(result.upCount).toBe(1);
|
||||
expect(result.downCount).toBe(1);
|
||||
expect(result.pausedCount).toBe(1);
|
||||
});
|
||||
|
||||
test("computes average uptime from uptimeList", async () => {
|
||||
mockResponses();
|
||||
const integration = createIntegration([{ kind: "slug", value: "default" }]);
|
||||
const result = await integration.getDashboardDataAsync();
|
||||
|
||||
const expectedAverage = ((0.995 + 0.5 + 0.8) * 100) / 3;
|
||||
expect(result.averageUptimePercent).toBeCloseTo(expectedAverage, 5);
|
||||
});
|
||||
|
||||
test("defaults unknown heartbeat status to 'down'", async () => {
|
||||
const unknownHeartbeat = {
|
||||
heartbeatList: { "10": [{ status: 99, time: "2025-01-01" }] },
|
||||
uptimeList: { "10_24": 1 },
|
||||
};
|
||||
|
||||
mockFetch.mockImplementation((url) => {
|
||||
const urlStr = toUrlString(url);
|
||||
if (urlStr.includes("/heartbeat/")) {
|
||||
return Promise.resolve(
|
||||
new Response(JSON.stringify(unknownHeartbeat), { status: 200 }),
|
||||
) as unknown as ReturnType<typeof fetchWithTrustedCertificatesAsync>;
|
||||
}
|
||||
return Promise.resolve(
|
||||
new Response(
|
||||
JSON.stringify({
|
||||
publicGroupList: [{ id: 1, name: "G", monitorList: [{ id: 10, name: "Svc" }] }],
|
||||
}),
|
||||
{ status: 200 },
|
||||
),
|
||||
) as unknown as ReturnType<typeof fetchWithTrustedCertificatesAsync>;
|
||||
});
|
||||
|
||||
const integration = createIntegration([{ kind: "slug", value: "default" }]);
|
||||
const result = await integration.getDashboardDataAsync();
|
||||
|
||||
expect(result.monitors[0]?.status).toBe("down");
|
||||
expect(result.downCount).toBe(1);
|
||||
});
|
||||
|
||||
test("handles empty monitor list gracefully", async () => {
|
||||
mockFetch.mockImplementation(
|
||||
() =>
|
||||
Promise.resolve(
|
||||
new Response(JSON.stringify({ publicGroupList: [], heartbeatList: {}, uptimeList: {} }), { status: 200 }),
|
||||
) as unknown as ReturnType<typeof fetchWithTrustedCertificatesAsync>,
|
||||
);
|
||||
|
||||
const integration = createIntegration([{ kind: "slug", value: "default" }]);
|
||||
const result = await integration.getDashboardDataAsync();
|
||||
|
||||
expect(result.totalMonitors).toBe(0);
|
||||
expect(result.averageUptimePercent).toBe(0);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,140 @@
|
||||
import { ParseError, ResponseError } from "@homarr/common/server";
|
||||
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 {
|
||||
uptimeKumaHeartbeatCategoryMap,
|
||||
uptimeKumaHeartbeatResponseSchema,
|
||||
uptimeKumaStatusPageResponseSchema,
|
||||
} from "./uptime-kuma-types";
|
||||
import type { UptimeKumaDashboardData, UptimeKumaMonitor, UptimeKumaMonitorCategory } from "./uptime-kuma-types";
|
||||
|
||||
export class UptimeKumaIntegration extends Integration {
|
||||
protected async testingAsync(input: IntegrationTestingInput): Promise<TestingResult> {
|
||||
const statusPageResponse = await input.fetchAsync(this.statusPageUrl());
|
||||
|
||||
if (!statusPageResponse.ok) {
|
||||
return TestConnectionError.StatusResult(statusPageResponse);
|
||||
}
|
||||
|
||||
const statusPageParsed = uptimeKumaStatusPageResponseSchema.safeParse(await statusPageResponse.json());
|
||||
|
||||
if (!statusPageParsed.success) {
|
||||
return TestConnectionError.ParseResult(
|
||||
new ParseError("Invalid Uptime Kuma status page response", { cause: statusPageParsed.error }),
|
||||
);
|
||||
}
|
||||
|
||||
const heartbeatResponse = await input.fetchAsync(this.heartbeatUrl());
|
||||
|
||||
if (!heartbeatResponse.ok) {
|
||||
return TestConnectionError.StatusResult(heartbeatResponse);
|
||||
}
|
||||
|
||||
const heartbeatParsed = uptimeKumaHeartbeatResponseSchema.safeParse(await heartbeatResponse.json());
|
||||
|
||||
if (!heartbeatParsed.success) {
|
||||
return TestConnectionError.ParseResult(
|
||||
new ParseError("Invalid Uptime Kuma heartbeat response", { cause: heartbeatParsed.error }),
|
||||
);
|
||||
}
|
||||
|
||||
return { success: true };
|
||||
}
|
||||
|
||||
public async getDashboardDataAsync(): Promise<UptimeKumaDashboardData> {
|
||||
const [statusPageResponse, heartbeatResponse] = await Promise.all([
|
||||
this.getStatusPageAsync(),
|
||||
this.getHeartbeatAsync(),
|
||||
]);
|
||||
|
||||
const statusPage = uptimeKumaStatusPageResponseSchema.parse(await statusPageResponse.json());
|
||||
const heartbeat = uptimeKumaHeartbeatResponseSchema.parse(await heartbeatResponse.json());
|
||||
|
||||
const monitors = statusPage.publicGroupList.flatMap((group) =>
|
||||
group.monitorList.map((monitor) => this.mapMonitor(monitor, heartbeat)),
|
||||
);
|
||||
|
||||
return this.buildDashboardData(monitors);
|
||||
}
|
||||
|
||||
private mapMonitor(
|
||||
monitor: { id: number; name: string },
|
||||
heartbeat: { heartbeatList: Record<string, { status: number }[]>; uptimeList: Record<string, number> },
|
||||
): UptimeKumaMonitor {
|
||||
const heartbeats = heartbeat.heartbeatList[String(monitor.id)] ?? [];
|
||||
const latestHeartbeat = heartbeats.at(-1);
|
||||
const uptimeKey = `${monitor.id}_24`;
|
||||
const uptimeRaw = heartbeat.uptimeList[uptimeKey];
|
||||
const uptimePercent24h = typeof uptimeRaw === "number" ? uptimeRaw * 100 : null;
|
||||
const status: UptimeKumaMonitorCategory =
|
||||
(latestHeartbeat && (uptimeKumaHeartbeatCategoryMap[latestHeartbeat.status] ?? "down")) || "paused";
|
||||
|
||||
return {
|
||||
id: monitor.id,
|
||||
name: monitor.name,
|
||||
status,
|
||||
uptimePercent24h,
|
||||
};
|
||||
}
|
||||
|
||||
private buildDashboardData(monitors: UptimeKumaMonitor[]): UptimeKumaDashboardData {
|
||||
const counts = monitors.reduce(
|
||||
(acc, monitor) => {
|
||||
acc[monitor.status] += 1;
|
||||
return acc;
|
||||
},
|
||||
{ up: 0, down: 0, paused: 0 },
|
||||
);
|
||||
|
||||
const uptimeValues = monitors
|
||||
.map((monitor) => monitor.uptimePercent24h)
|
||||
.filter((value): value is number => value !== null);
|
||||
|
||||
const averageUptimePercent = uptimeValues.reduce((sum, value) => sum + value, 0) / Math.max(uptimeValues.length, 1);
|
||||
|
||||
return {
|
||||
totalMonitors: monitors.length,
|
||||
upCount: counts.up,
|
||||
downCount: counts.down,
|
||||
pausedCount: counts.paused,
|
||||
averageUptimePercent,
|
||||
monitors,
|
||||
};
|
||||
}
|
||||
|
||||
private async fetchOkAsync(url: string | URL) {
|
||||
const response = await fetchWithTrustedCertificatesAsync(url);
|
||||
if (!response.ok) {
|
||||
throw new ResponseError(response);
|
||||
}
|
||||
return response;
|
||||
}
|
||||
|
||||
private getStatusPageAsync() {
|
||||
return this.fetchOkAsync(this.statusPageUrl());
|
||||
}
|
||||
|
||||
private getHeartbeatAsync() {
|
||||
return this.fetchOkAsync(this.heartbeatUrl());
|
||||
}
|
||||
|
||||
private statusPageUrl() {
|
||||
return this.url(`/api/status-page/${this.getSlug()}`);
|
||||
}
|
||||
|
||||
private heartbeatUrl() {
|
||||
return this.url(`/api/status-page/heartbeat/${this.getSlug()}`);
|
||||
}
|
||||
|
||||
private getSlug() {
|
||||
if (this.hasSecretValue("slug")) {
|
||||
return this.getSecretValue("slug").toLowerCase();
|
||||
}
|
||||
|
||||
return "default";
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,62 @@
|
||||
import { z } from "zod";
|
||||
|
||||
export const uptimeKumaHeartbeatStatus = {
|
||||
down: 0,
|
||||
up: 1,
|
||||
pending: 2,
|
||||
maintenance: 3,
|
||||
} as const;
|
||||
|
||||
export type UptimeKumaMonitorCategory = "up" | "down" | "paused";
|
||||
|
||||
export const uptimeKumaHeartbeatCategoryMap: Record<number, UptimeKumaMonitorCategory> = {
|
||||
[uptimeKumaHeartbeatStatus.down]: "down",
|
||||
[uptimeKumaHeartbeatStatus.up]: "up",
|
||||
[uptimeKumaHeartbeatStatus.pending]: "paused",
|
||||
[uptimeKumaHeartbeatStatus.maintenance]: "paused",
|
||||
};
|
||||
|
||||
export const uptimeKumaStatusPageMonitorSchema = z.object({
|
||||
id: z.number().int(),
|
||||
name: z.string(),
|
||||
});
|
||||
|
||||
export const uptimeKumaStatusPageGroupSchema = z.object({
|
||||
id: z.number().int(),
|
||||
name: z.string(),
|
||||
monitorList: z.array(uptimeKumaStatusPageMonitorSchema),
|
||||
});
|
||||
|
||||
export const uptimeKumaStatusPageResponseSchema = z.object({
|
||||
publicGroupList: z.array(uptimeKumaStatusPageGroupSchema),
|
||||
});
|
||||
|
||||
export const uptimeKumaHeartbeatEntrySchema = z.object({
|
||||
status: z.number().int(),
|
||||
time: z.string(),
|
||||
ping: z.number().nullable().optional(),
|
||||
});
|
||||
|
||||
export const uptimeKumaHeartbeatResponseSchema = z.object({
|
||||
heartbeatList: z.record(z.string(), z.array(uptimeKumaHeartbeatEntrySchema)),
|
||||
uptimeList: z.record(z.string(), z.number()),
|
||||
});
|
||||
|
||||
export interface UptimeKumaMonitor {
|
||||
id: number;
|
||||
name: string;
|
||||
status: UptimeKumaMonitorCategory;
|
||||
uptimePercent24h: number | null;
|
||||
}
|
||||
|
||||
export interface UptimeKumaDashboardData {
|
||||
totalMonitors: number;
|
||||
upCount: number;
|
||||
downCount: number;
|
||||
pausedCount: number;
|
||||
averageUptimePercent: number;
|
||||
monitors: UptimeKumaMonitor[];
|
||||
}
|
||||
|
||||
export type UptimeKumaStatusPageResponse = z.infer<typeof uptimeKumaStatusPageResponseSchema>;
|
||||
export type UptimeKumaHeartbeatResponse = z.infer<typeof uptimeKumaHeartbeatResponseSchema>;
|
||||
Reference in new issue
Block a user