feat: add Synology integration support for health/system monitoring (#6121)

This commit is contained in:
Josh Preston authored and GitHub committed 2026-07-09 18:23:21 +02:00
1 parent 260b167134
commit 65ba866239
35 files changed
+2263 -98

No files matched your search

+1 -1
View File
@@ -11,7 +11,7 @@ export interface CommonWidgetInputProps<TKey extends WidgetOptionType> {
itemId?: string;
}
type UseWidgetInputTranslationReturnType = (key: "label" | "description") => string;
type UseWidgetInputTranslationReturnType = (key: "label" | "description" | "placeholder") => string;
/**
* Short description why as and unknown convertions are used below:
+2
View File
@@ -17,6 +17,7 @@ import { WidgetUmamiEventInput } from "./widget-umami-event-input";
import { WidgetUmamiEventNamesInput } from "./widget-umami-event-names-input";
import { WidgetUmamiWebsiteInput } from "./widget-umami-website-input";
import { WidgetIntegrationSelectInput } from "./widget-integration-select-input";
import { WidgetIntegrationMultiSelectInput } from "./widget-integration-multi-select-input";
const mapping = {
anchorNote: WidgetAnchorNoteInput,
@@ -37,6 +38,7 @@ const mapping = {
umamiWebsite: WidgetUmamiWebsiteInput,
customWidgetSelect: WidgetCustomWidgetSelectInput,
integrationSelect: WidgetIntegrationSelectInput,
integrationMultiSelect: WidgetIntegrationMultiSelectInput,
} satisfies Record<WidgetOptionType, unknown>;
export const getInputForType = <TType extends WidgetOptionType>(type: TType) => {
@@ -0,0 +1,60 @@
"use client";
import { MultiSelect, Text } from "@mantine/core";
import { useScopedI18n } from "@homarr/translation/client";
import type { CommonWidgetInputProps } from "./common";
import { useWidgetInputTranslation } from "./common";
import { useFormContext } from "./form";
const useIntegrationSelectTranslation = () => useScopedI18n("widget.integrationSelect");
export const WidgetIntegrationMultiSelectInput = ({
property,
kind,
options,
}: CommonWidgetInputProps<"integrationMultiSelect">) => {
const t = useIntegrationSelectTranslation();
const tInput = useWidgetInputTranslation(kind, property);
const form = useFormContext();
const integrationIds = form.values.integrationIds as string[];
const inputProps = form.getInputProps(`options.${property}`);
const selectedValues = (inputProps.value as string[] | undefined) ?? [];
const { data: selectData = [], isPending, isError } = options.useOptions(integrationIds);
const data = [
...selectData,
...selectedValues
.filter((selectedValue) => !selectData.some((option) => option.value === selectedValue))
.map((selectedValue) => ({ value: selectedValue, label: selectedValue })),
];
if (integrationIds.length === 0) {
return (
<Text size="sm" c="dimmed">
{t("configureIntegrationFirst")}
</Text>
);
}
const description = options.withDescription ? tInput("description") : undefined;
const placeholder = isPending ? t("loading") : tInput("placeholder");
const loadError = isError ? t("loadError") : undefined;
return (
<MultiSelect
{...inputProps}
label={tInput("label")}
description={description}
placeholder={placeholder}
searchable
clearable
nothingFoundMessage={t("noResults")}
data={data}
disabled={isError}
error={loadError ?? inputProps.error}
/>
);
};
@@ -0,0 +1,146 @@
import { describe, expect, test } from "vitest";
import {
filterStorageVolumes,
normalizeStorageDeviceName,
toScopedStorageVolumeValue,
} from "./filter-storage-volumes";
import { matchFileSystemAndSmart } from "./health-monitoring/system-health";
describe("normalizeStorageDeviceName", () => {
test("strips partition suffixes from block device paths", () => {
expect(normalizeStorageDeviceName("/dev/sda1")).toBe("/dev/sda");
expect(normalizeStorageDeviceName("/dev/sda")).toBe("/dev/sda");
});
test("preserves Synology-style volume names", () => {
expect(normalizeStorageDeviceName("volume_1")).toBe("volume_1");
expect(normalizeStorageDeviceName("volume_2")).toBe("volume_2");
});
test("strips NVMe partition suffixes without collapsing the namespace id", () => {
expect(normalizeStorageDeviceName("/dev/nvme0n1")).toBe("/dev/nvme0n1");
expect(normalizeStorageDeviceName("/dev/nvme0n1p2")).toBe("/dev/nvme0n1");
expect(normalizeStorageDeviceName("/dev/nvme0n2p1")).toBe("/dev/nvme0n2");
});
test("does not collapse unrelated md devices", () => {
expect(normalizeStorageDeviceName("/dev/md0")).toBe("/dev/md0");
expect(normalizeStorageDeviceName("/dev/md1")).toBe("/dev/md1");
});
});
describe("toScopedStorageVolumeValue", () => {
test("scopes unscoped volume names to the query integration", () => {
expect(toScopedStorageVolumeValue("nas-a", "volume_1")).toBe("nas-a:volume_1");
});
test("re-scopes already-prefixed values using the query integration", () => {
expect(toScopedStorageVolumeValue("nas-b", "nas-a:volume_1")).toBe("nas-b:volume_1");
});
});
describe("filterStorageVolumes", () => {
const integrationId = "nas-1";
test("matches SMART entries using normalized partition identifiers", () => {
const entries = [
{ deviceName: "/dev/sda1", used: "1", available: "2", percentage: 50 },
{ deviceName: "/dev/sdb1", used: "1", available: "2", percentage: 50 },
];
const smartEntries = [
{ deviceName: "/dev/sda", temperature: 35, overallStatus: "GOOD" },
{ deviceName: "/dev/sdb", temperature: 40, overallStatus: "GOOD" },
];
const visibleVolumes = [`${integrationId}:/dev/sda1`];
expect(filterStorageVolumes(entries, visibleVolumes, integrationId)).toHaveLength(1);
expect(filterStorageVolumes(smartEntries, visibleVolumes, integrationId)).toHaveLength(1);
});
test("keeps exact Synology volume matches", () => {
const entries = [{ deviceName: "volume_1" }, { deviceName: "volume_2" }];
const visibleVolumes = [`${integrationId}:volume_1`];
expect(filterStorageVolumes(entries, visibleVolumes, integrationId)).toEqual([{ deviceName: "volume_1" }]);
});
test("does not apply another integration's scoped selection", () => {
const entries = [{ deviceName: "volume_1" }, { deviceName: "volume_2" }];
const visibleVolumes = ["nas-b:volume_1"];
expect(filterStorageVolumes(entries, visibleVolumes, integrationId)).toEqual([]);
});
test("does not treat different md devices as the same volume", () => {
const entries = [{ deviceName: "/dev/md0" }, { deviceName: "/dev/md1" }];
const visibleVolumes = [`${integrationId}:/dev/md0`];
expect(filterStorageVolumes(entries, visibleVolumes, integrationId)).toEqual([{ deviceName: "/dev/md0" }]);
});
});
describe("matchFileSystemAndSmart", () => {
test("joins partitioned filesystem entries with base SMART device names", () => {
const result = matchFileSystemAndSmart(
[{ deviceName: "/dev/sda1", used: "100", available: "900", percentage: 10 }],
[{ deviceName: "/dev/sda", temperature: 42, overallStatus: "GOOD" }],
);
expect(result).toEqual([
{
deviceName: "/dev/sda",
used: "100",
available: "900",
percentage: 10,
temperature: 42,
overallStatus: "GOOD",
},
]);
});
test("joins Synology volume names without stripping volume suffixes", () => {
const result = matchFileSystemAndSmart(
[{ deviceName: "volume_1", used: "100", available: "900", percentage: 10 }],
[{ deviceName: "volume_1", temperature: 39, overallStatus: "normal" }],
);
expect(result[0]).toMatchObject({
deviceName: "volume_1",
temperature: 39,
overallStatus: "normal",
});
});
test("joins NVMe partitions with their base device SMART data", () => {
const result = matchFileSystemAndSmart(
[{ deviceName: "/dev/nvme0n1p2", used: "100", available: "900", percentage: 10 }],
[{ deviceName: "/dev/nvme0n1", temperature: 41, overallStatus: "GOOD" }],
);
expect(result).toEqual([
{
deviceName: "/dev/nvme0n1",
used: "100",
available: "900",
percentage: 10,
temperature: 41,
overallStatus: "GOOD",
},
]);
});
test("does not join SMART data from a different md device", () => {
const result = matchFileSystemAndSmart(
[{ deviceName: "/dev/md0", used: "100", available: "900", percentage: 10 }],
[{ deviceName: "/dev/md1", temperature: 41, overallStatus: "GOOD" }],
);
expect(result[0]).toMatchObject({
deviceName: "/dev/md0",
temperature: null,
overallStatus: "",
});
});
});
@@ -0,0 +1,67 @@
interface StorageVolumeEntry {
deviceName: string;
}
const partitionSuffixPatterns: ReadonlyArray<{ pattern: RegExp; baseGroupIndex: number }> = [
// SCSI/SATA/VirtIO: /dev/sda1 -> /dev/sda
{ pattern: /^(\/dev\/(?:sd|vd|hd|xvd)[a-z]+)[0-9]+$/, baseGroupIndex: 1 },
// NVMe: /dev/nvme0n1p2 -> /dev/nvme0n1
{ pattern: /^(\/dev\/nvme[0-9]+n[0-9]+)p[0-9]+$/, baseGroupIndex: 1 },
// eMMC: /dev/mmcblk0p1 -> /dev/mmcblk0
{ pattern: /^(\/dev\/mmcblk[0-9]+)p[0-9]+$/, baseGroupIndex: 1 },
];
export const normalizeStorageDeviceName = (deviceName: string): string => {
for (const { pattern, baseGroupIndex } of partitionSuffixPatterns) {
const match = deviceName.match(pattern);
if (match) {
return match[baseGroupIndex] ?? deviceName;
}
}
return deviceName;
};
export const toScopedStorageVolumeValue = (integrationId: string, value: string): string => {
const separatorIndex = value.indexOf(":");
const volumeName = separatorIndex === -1 ? value : value.slice(separatorIndex + 1);
return `${integrationId}:${volumeName}`;
};
const storageDeviceNamesMatch = (leftDeviceName: string, rightDeviceName: string): boolean => {
return (
leftDeviceName === rightDeviceName ||
normalizeStorageDeviceName(leftDeviceName) === normalizeStorageDeviceName(rightDeviceName)
);
};
const matchesVisibleStorageVolume = (
visibleVolume: string,
integrationId: string,
deviceName: string,
): boolean => {
const separatorIndex = visibleVolume.indexOf(":");
if (separatorIndex === -1) {
return storageDeviceNamesMatch(visibleVolume, deviceName);
}
const visibleIntegrationId = visibleVolume.slice(0, separatorIndex);
const visibleVolumeName = visibleVolume.slice(separatorIndex + 1);
return visibleIntegrationId === integrationId && storageDeviceNamesMatch(visibleVolumeName, deviceName);
};
export const filterStorageVolumes = <TEntry extends StorageVolumeEntry>(
entries: TEntry[],
visibleStorageVolumes: string[] | undefined,
integrationId: string,
): TEntry[] => {
if (!visibleStorageVolumes || visibleStorageVolumes.length === 0) {
return entries;
}
return entries.filter((entry) =>
visibleStorageVolumes.some((visibleVolume) =>
matchesVisibleStorageVolume(visibleVolume, integrationId, entry.deviceName),
),
);
};
@@ -4,6 +4,7 @@ import { getIntegrationKindsByCategory } from "@homarr/definitions";
import { createWidgetDefinition } from "../definition";
import { optionsBuilder } from "../options";
import { createStorageVolumeMultiSelectOptions } from "../storage-volume-options";
export const { definition, componentLoader } = createWidgetDefinition("healthMonitoring", {
icon: IconHeartRateMonitor,
@@ -28,6 +29,7 @@ export const { definition, componentLoader } = createWidgetDefinition("healthMon
fileSystem: factory.switch({
defaultValue: true,
}),
visibleStorageVolumes: factory.integrationMultiSelect(createStorageVolumeMultiSelectOptions()),
visibleClusterSections: factory.multiSelect({
options: [
{
@@ -77,6 +79,11 @@ export const { definition, componentLoader } = createWidgetDefinition("healthMon
return integrationKinds.every((kind) => kind === "proxmox") || integrationKinds.length === 0;
},
},
visibleStorageVolumes: {
shouldHide(_, integrationKinds) {
return integrationKinds.length === 0 || !integrationKinds.every((kind) => kind === "synology");
},
},
showUptime: {
shouldHide(_, integrationKinds) {
// Uptime is only shown on cluster health tab
@@ -36,8 +36,9 @@ import { humanFileSize } from "@homarr/common";
import type { TranslationFunction } from "@homarr/translation";
import { useI18n } from "@homarr/translation/client";
import type { WidgetComponentProps } from "../definition";
import { filterStorageVolumes, normalizeStorageDeviceName } from "../filter-storage-volumes";
import { WidgetEmptyState } from "../common/empty-state";
import type { WidgetComponentProps } from "../definition";
import { CpuRing } from "./rings/cpu-ring";
import { CpuTempRing } from "./rings/cpu-temp-ring";
import { GpuRing } from "./rings/gpu-ring";
@@ -65,7 +66,13 @@ export const SystemHealthMonitoring = ({
return (
<Stack h="100%" gap="sm" className="health-monitoring">
{healthData.map(({ integrationId, integrationName, healthInfo }) => {
const disksData = matchFileSystemAndSmart(healthInfo.fileSystem, healthInfo.smart);
const filteredFileSystem = filterStorageVolumes(
healthInfo.fileSystem,
options.visibleStorageVolumes,
integrationId,
);
const filteredSmart = filterStorageVolumes(healthInfo.smart, options.visibleStorageVolumes, integrationId);
const disksData = matchFileSystemAndSmart(filteredFileSystem, filteredSmart);
const memoryUsage = formatMemoryUsage(healthInfo.memAvailableInBytes, healthInfo.memUsedInBytes);
return (
<Stack
@@ -289,8 +296,12 @@ interface SmartData {
export const matchFileSystemAndSmart = (fileSystems: FileSystem[], smartData: SmartData[]) => {
return fileSystems
.map((fileSystem) => {
const baseDeviceName = fileSystem.deviceName.replace(/[0-9]+$/, "");
const smartDisk = smartData.find((smart) => smart.deviceName === baseDeviceName);
const normalizedFileSystemName = normalizeStorageDeviceName(fileSystem.deviceName);
const smartDisk = smartData.find(
(smart) =>
smart.deviceName === fileSystem.deviceName ||
normalizeStorageDeviceName(smart.deviceName) === normalizedFileSystemName,
);
return {
deviceName: smartDisk?.deviceName ?? fileSystem.deviceName,
+15
View File
@@ -72,6 +72,15 @@ interface IntegrationSelectInput extends CommonInput<string> {
};
}
interface IntegrationMultiSelectInput extends CommonInput<string[]> {
withDescription?: boolean;
useOptions: (integrationIds: string[]) => {
data: { value: string; label: string }[];
isPending: boolean;
isError: boolean;
};
}
interface NumberInput extends CommonInput<number> {
validate: z.ZodNumber;
step?: number;
@@ -196,6 +205,12 @@ const optionsFactory = {
searchable: input.searchable ?? true,
useOptions: input.useOptions,
}),
integrationMultiSelect: (input: IntegrationMultiSelectInput) => ({
type: "integrationMultiSelect" as const,
defaultValue: input.defaultValue ?? [],
withDescription: input.withDescription ?? false,
useOptions: input.useOptions,
}),
customWidgetSelect: (input?: CommonInput<string>) => ({
type: "customWidgetSelect" as const,
defaultValue: input?.defaultValue ?? "",
@@ -0,0 +1,39 @@
import { clientApi } from "@homarr/api/client";
import { toScopedStorageVolumeValue } from "./filter-storage-volumes";
export const createStorageVolumeMultiSelectOptions = () => ({
defaultValue: [] as string[],
withDescription: true,
useOptions: (integrationIds: string[]) => {
const queryResults = clientApi.useQueries((queryBuilder) =>
integrationIds.map((integrationId) =>
queryBuilder.widget.healthMonitoring.listStorageVolumes({
integrationId,
}),
),
);
const isPending = queryResults.some((queryResult) => queryResult.isPending);
const isError = queryResults.every((queryResult) => queryResult.isError);
const options = queryResults.flatMap((queryResult, index) => {
const integrationId = integrationIds[index];
if (!integrationId) {
return [];
}
return (queryResult.data ?? []).map((option) => ({
label: option.label,
value: toScopedStorageVolumeValue(integrationId, option.value),
}));
});
const uniqueOptions = [...new Map(options.map((option) => [option.value, option])).values()];
return {
data: uniqueOptions,
isPending,
isError: isError && uniqueOptions.length === 0,
};
},
});
@@ -10,6 +10,7 @@ import { useI18n } from "@homarr/translation/client";
import { WidgetEmptyState } from "../common/empty-state";
import type { WidgetComponentProps } from "../definition";
import { filterStorageVolumes } from "../filter-storage-volumes";
import { NoIntegrationDataError } from "../errors/no-data-integration";
type DisplayMode = WidgetComponentProps<"systemDisks">["options"]["displayMode"];
@@ -123,12 +124,25 @@ export default function SystemResources({ integrationIds, options }: WidgetCompo
const lastItem = data.at(-1);
if (!lastItem) return <WidgetEmptyState />;
const { fileSystem, smart } = lastItem.healthInfo;
if (fileSystem.length === 0) {
const rawFileSystem = lastItem.healthInfo.fileSystem;
if (rawFileSystem.length === 0) {
throw new NoIntegrationDataError();
}
const fileSystem = filterStorageVolumes(
rawFileSystem,
options.visibleStorageVolumes,
lastItem.integrationId,
);
const smart = filterStorageVolumes(
lastItem.healthInfo.smart,
options.visibleStorageVolumes,
lastItem.integrationId,
);
if (fileSystem.length === 0) return <WidgetEmptyState />;
return (
<Stack gap="xs" p="xs" h="100%">
{fileSystem.map((item) => {
+22 -11
View File
@@ -2,21 +2,32 @@ import { IconServer2 } from "@tabler/icons-react";
import { createWidgetDefinition } from "../definition";
import { optionsBuilder } from "../options";
import { createStorageVolumeMultiSelectOptions } from "../storage-volume-options";
export const { definition, componentLoader } = createWidgetDefinition("systemDisks", {
icon: IconServer2,
supportedIntegrations: ["dashDot", "openmediavault", "truenas", "unraid"],
supportedIntegrations: ["dashDot", "openmediavault", "truenas", "unraid", "synology"],
createOptions() {
return optionsBuilder.from((factory) => ({
showTemperatureIfAvailable: factory.switch({ defaultValue: true }),
displayMode: factory.select({
options: (["percentage", "absolute", "free"] as const).map((value) => ({
value,
label: (t) => t(`widget.systemDisks.option.displayMode.option.${value}.label`),
})),
defaultValue: "percentage",
return optionsBuilder.from(
(factory) => ({
showTemperatureIfAvailable: factory.switch({ defaultValue: true }),
displayMode: factory.select({
options: (["percentage", "absolute", "free"] as const).map((value) => ({
value,
label: (t) => t(`widget.systemDisks.option.displayMode.option.${value}.label`),
})),
defaultValue: "percentage",
}),
showBackgroundBar: factory.switch({ defaultValue: true }),
visibleStorageVolumes: factory.integrationMultiSelect(createStorageVolumeMultiSelectOptions()),
}),
showBackgroundBar: factory.switch({ defaultValue: true }),
}));
{
visibleStorageVolumes: {
shouldHide(_, integrationKinds) {
return integrationKinds.length === 0 || !integrationKinds.every((kind) => kind === "synology");
},
},
},
);
},
}).withDynamicImport(() => import("./component"));
@@ -14,7 +14,7 @@ const labelDisplayModeOptions = {
export const { definition, componentLoader } = createWidgetDefinition("systemResources", {
icon: IconGraphFilled,
supportedIntegrations: ["dashDot", "openmediavault", "truenas", "unraid", "glances"],
supportedIntegrations: ["dashDot", "openmediavault", "truenas", "unraid", "glances", "synology"],
createOptions() {
return optionsBuilder.from((factory) => ({
hasShadow: factory.switch({ defaultValue: true }),