feat: port release-v2 experience improvements from #6582 (audited subset) (#6609)

This commit is contained in:
Thomas authored and GitHub committed 2026-08-18 09:40:02 +02:00
1 parent e3a713d2df
commit e842177d9b
163 files changed
+7390 -1240

No files matched your search

@@ -0,0 +1,147 @@
import {
extractContainerImageName,
matchIntegrationKind,
matchIntegrationKindFromContainer,
} from "./docker-integration-match";
import type { IntegrationKind } from "./integration";
export type DockerServiceMatchConfidence = "high" | "medium";
export type DockerServiceMatchSource = "image" | "name";
export type DockerUrlCandidateSource = "publishedAddress" | "endpointHost" | "containerDns" | "manual";
export type DockerUrlCandidateScope = "browser" | "server";
export type DockerUrlCandidateReason =
| "publishedAddress"
| "dockerEndpointHost"
| "sharedContainerNetwork"
| "manualHostRequired";
export interface DockerServiceMatch {
kind: IntegrationKind;
confidence: DockerServiceMatchConfidence;
source: DockerServiceMatchSource;
}
export interface DockerServicePort {
IP?: string;
PrivatePort: number;
PublicPort?: number;
Type: string;
}
export interface DockerServiceUrlCandidate {
id: string;
url: string;
rank: number;
source: DockerUrlCandidateSource;
scopes: DockerUrlCandidateScope[];
reason: DockerUrlCandidateReason;
}
export const matchDockerService = (container: { image: string; name: string }): DockerServiceMatch | null => {
const kind = matchIntegrationKindFromContainer(container);
if (!kind) return null;
const imageMatch = matchIntegrationKind(extractContainerImageName(container.image));
return imageMatch === kind
? { kind, confidence: "high", source: "image" }
: { kind, confidence: "medium", source: "name" };
};
export const buildDockerServiceUrlCandidates = ({
containerName,
endpointHost,
ports,
preferredPort,
}: {
containerName: string;
endpointHost: string;
ports: DockerServicePort[] | undefined;
preferredPort?: number;
}): DockerServiceUrlCandidate[] => {
const candidates: DockerServiceUrlCandidate[] = [];
const endpointHostname = getEndpointHostname(endpointHost);
const tcpPorts = (ports ?? [])
.filter((port) => port.Type.toLowerCase() === "tcp")
.toSorted(
(left, right) => Number(right.PrivatePort === preferredPort) - Number(left.PrivatePort === preferredPort),
);
const addCandidate = (candidate: Omit<DockerServiceUrlCandidate, "id">) => {
if (candidates.some(({ url, scopes }) => url === candidate.url && scopes.join() === candidate.scopes.join()))
return;
candidates.push({
...candidate,
id: `${candidate.source}:${candidate.scopes.join("-")}:${candidate.url || "manual"}`,
});
};
for (const port of tcpPorts) {
if (port.PublicPort) {
const publishedHost = isUsablePublishedAddress(port.IP)
? port.IP
: isUsablePublishedAddress(endpointHostname ?? undefined)
? endpointHostname
: null;
if (publishedHost) {
addCandidate({
url: `http://${formatUrlHost(publishedHost)}:${port.PublicPort}`,
rank: port.PrivatePort === preferredPort ? 1 : 2,
source: isUsablePublishedAddress(port.IP) ? "publishedAddress" : "endpointHost",
scopes: ["browser", "server"],
reason: isUsablePublishedAddress(port.IP) ? "publishedAddress" : "dockerEndpointHost",
});
}
}
addCandidate({
url: `http://${containerName}:${port.PrivatePort}`,
rank: port.PrivatePort === preferredPort ? 3 : 4,
source: "containerDns",
scopes: ["server"],
reason: "sharedContainerNetwork",
});
}
addCandidate({
url: "",
rank: 99,
source: "manual",
scopes: ["browser"],
reason: "manualHostRequired",
});
return candidates.toSorted((left, right) => left.rank - right.rank);
};
export const normalizeDockerServiceUrl = (value: string | null | undefined) => {
if (!value) return null;
try {
const url = new URL(value);
url.hash = "";
return url.toString().replace(/\/$/, "").toLowerCase();
} catch {
return value.trim().replace(/\/$/, "").toLowerCase() || null;
}
};
const isUsablePublishedAddress = (value: string | undefined): value is string => {
if (!value) return false;
const host = value.toLowerCase().replace(/^\[|\]$/gu, "");
return (
!["0.0.0.0", "::", "::0", "::1", "localhost"].includes(host) &&
!host.endsWith(".localhost") &&
!/^127(?:\.\d{1,3}){3}$/.test(host) &&
!host.startsWith("::ffff:127.")
);
};
const getEndpointHostname = (host: string) => {
if (host === "socket" || host.startsWith("/") || /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(host)) return null;
try {
return new URL(`http://${host}`).hostname || null;
} catch {
return null;
}
};
const formatUrlHost = (host: string) => (host.includes(":") && !host.startsWith("[") ? `[${host}]` : host);
@@ -332,6 +332,7 @@ export type HomarrDocumentationPath =
| "/docs/integrations/peanut"
| "/docs/integrations/beszel"
| "/docs/integrations/traefik"
| "/docs/integrations/archiveteam-warrior"
| "/docs/integrations/whats-up-docker"
| "/docs/widgets/clock"
| "/docs/widgets/weather"
@@ -53,7 +53,7 @@ export const integrationDocSlugs: Record<IntegrationKind, string | null> = {
peaNut: "peanut",
beszel: "beszel",
traefik: "traefik",
archiveTeamWarrior: null,
archiveTeamWarrior: "archiveteam-warrior",
wud: "whats-up-docker",
mock: null,
};
+1
View File
@@ -16,6 +16,7 @@ export * from "./widget-integration-map";
export * from "./emptysuperjson";
export * from "./hotkeys";
export * from "./docker-integration-match";
export * from "./docker-service-discovery";
export * from "./integration-url-template";
export * from "./release-provider";
export * from "./assistant";
+3 -2
View File
@@ -73,8 +73,8 @@ export interface KubernetesNamespace extends KubernetesBaseResource {
export interface KubernetesNode {
name: string;
status: KubernetesNodeState;
allocatableCpuPercentage: number;
allocatableRamPercentage: number;
allocatableCpuPercentage: number | null;
allocatableRamPercentage: number | null;
podsCount: number;
operatingSystem?: string;
architecture?: string;
@@ -88,6 +88,7 @@ export interface KubernetesCluster {
kubernetesVersion: string;
architecture: string;
nodeCount: number;
metricsAvailable: boolean;
capacity: KubernetesCapacity[];
}
@@ -0,0 +1,93 @@
import { describe, expect, test } from "vitest";
import { buildDockerServiceUrlCandidates, matchDockerService } from "../docker-service-discovery";
describe("matchDockerService", () => {
test("reports image matches with high confidence and name fallbacks with medium confidence", () => {
expect(matchDockerService({ image: "linuxserver/sonarr:latest", name: "media" })).toEqual({
kind: "sonarr",
confidence: "high",
source: "image",
});
expect(matchDockerService({ image: "custom/media:latest", name: "sonarr" })).toEqual({
kind: "sonarr",
confidence: "medium",
source: "name",
});
});
});
describe("buildDockerServiceUrlCandidates", () => {
test("never emits wildcard or socket-path browser URLs", () => {
const candidates = buildDockerServiceUrlCandidates({
containerName: "sonarr",
endpointHost: "/var/run/docker.sock",
preferredPort: 8989,
ports: [{ IP: "0.0.0.0", PrivatePort: 8989, PublicPort: 8989, Type: "tcp" }],
});
expect(candidates.map(({ url }) => url)).not.toContain("http://0.0.0.0:8989");
expect(candidates.map(({ url }) => url)).not.toContain("http:///var/run/docker.sock:8989");
expect(candidates[0]).toMatchObject({
url: "http://sonarr:8989",
scopes: ["server"],
reason: "sharedContainerNetwork",
});
expect(candidates.at(-1)).toMatchObject({ url: "", reason: "manualHostRequired" });
});
test("uses a remote Docker endpoint hostname for wildcard published ports", () => {
const candidates = buildDockerServiceUrlCandidates({
containerName: "sonarr",
endpointHost: "docker.example.test:2375",
preferredPort: 8989,
ports: [{ IP: "0.0.0.0", PrivatePort: 8989, PublicPort: 8989, Type: "tcp" }],
});
expect(candidates[0]).toMatchObject({
url: "http://docker.example.test:8989",
scopes: ["browser", "server"],
reason: "dockerEndpointHost",
});
});
test.each(["127.0.0.1", "127.12.0.9", "::1", "::ffff:127.0.0.1", "localhost"])(
"does not advertise loopback address %s to browsers",
(address) => {
const candidates = buildDockerServiceUrlCandidates({
containerName: "sonarr",
endpointHost: "socket",
preferredPort: 8989,
ports: [{ IP: address, PrivatePort: 8989, PublicPort: 8989, Type: "tcp" }],
});
expect(candidates.some(({ source }) => source === "publishedAddress")).toBe(false);
expect(candidates.some(({ url, scopes }) => url.includes(address) && scopes.includes("browser"))).toBe(false);
},
);
test("does not use a loopback Docker endpoint as a browser URL", () => {
const candidates = buildDockerServiceUrlCandidates({
containerName: "sonarr",
endpointHost: "[::1]:2375",
preferredPort: 8989,
ports: [{ IP: "0.0.0.0", PrivatePort: 8989, PublicPort: 8989, Type: "tcp" }],
});
expect(candidates.some(({ source }) => source === "endpointHost")).toBe(false);
});
test.each(["tcp://10.0.0.5:2375", "unix:///var/run/docker.sock", "https://10.0.0.5"])(
"rejects a scheme-bearing endpoint host %s as a browser URL",
(endpointHost) => {
const candidates = buildDockerServiceUrlCandidates({
containerName: "sonarr",
endpointHost,
preferredPort: 8989,
ports: [{ IP: "0.0.0.0", PrivatePort: 8989, PublicPort: 8989, Type: "tcp" }],
});
expect(candidates.some(({ source }) => source === "endpointHost")).toBe(false);
},
);
});
@@ -1,10 +1,17 @@
import { describe, expect, it } from "vitest";
import { beforeEach, describe, expect, it, vi } from "vitest";
import { objectEntries } from "@homarr/common";
import { integrationDefs } from "../integration";
describe("Icon url's of integrations should be valid and return 200", () => {
beforeEach(() => {
vi.stubGlobal(
"fetch",
vi.fn(async () => new Response(null, { status: 200 })),
);
});
objectEntries(integrationDefs).forEach(([integration, { iconUrl }]) => {
it(`should return 200 for ${integration}`, { concurrent: true, retry: 2, timeout: 15_000 }, async () => {
const res = await fetch(iconUrl);
@@ -0,0 +1,47 @@
import { describe, expect, test } from "vitest";
import { integrationKinds } from "../integration";
import {
getWidgetKindsForIntegration,
integrationWidgetSupport,
nativeFeatureCapabilities,
widgetIntegrationLimits,
widgetIntegrationSupport,
widgetKindsWithOptionalIntegrations,
} from "../widget-integration-map";
describe("native feature capability descriptor", () => {
test("derives forward and reverse support without losing relationships", () => {
for (const [widgetKind, capability] of Object.entries(nativeFeatureCapabilities)) {
expect(widgetIntegrationSupport[widgetKind as keyof typeof widgetIntegrationSupport]).toEqual(
capability.integrations,
);
for (const integrationKind of capability.integrations) {
expect(integrationWidgetSupport[integrationKind]).toContain(widgetKind);
}
}
for (const integrationKind of integrationKinds) {
expect(getWidgetKindsForIntegration(integrationKind)).toEqual(integrationWidgetSupport[integrationKind]);
}
});
test("derives optional connections and server selection limits", () => {
expect(widgetKindsWithOptionalIntegrations).toEqual(new Set(["calendar"]));
expect(widgetIntegrationLimits).toEqual({
"smartHome-entityState": 1,
"smartHome-executeAutomation": 1,
mediaTranscoding: 1,
"immich-serverStats": 1,
"immich-albumCarousel": 1,
paperlessNgx: 1,
patchmon: 1,
bazarr: 1,
audioStats: 1,
umami: 1,
archiveTeamWarrior: 1,
anchorNote: 1,
wud: 1,
});
});
});
@@ -1,69 +1,105 @@
import { createDocumentationLink } from "./docs";
import type { IntegrationKind } from "./integration";
import { getIntegrationKindsByCategory } from "./integration";
import { getIntegrationKindsByCategory, integrationKinds } from "./integration";
import type { WidgetKind } from "./widget";
import { widgetDefaultSizes } from "./widget";
/**
* Static mapping of widget kinds to the integration kinds they support.
* Mirrors the supportedIntegrations declared in each widget definition
* but lives in @homarr/definitions so server-side code (API layer)
* can use it without importing @homarr/widgets.
* Server-safe capability metadata shared by the API and widget catalog.
* Keep this intentionally small: presentation, options, and request contracts
* remain owned by their feature packages.
*/
export const widgetIntegrationSupport: Partial<Record<WidgetKind, readonly IntegrationKind[]>> = {
dnsHoleSummary: getIntegrationKindsByCategory("dnsHole"),
dnsHoleControls: getIntegrationKindsByCategory("dnsHole"),
"smartHome-entityState": getIntegrationKindsByCategory("smartHomeServer"),
"smartHome-executeAutomation": getIntegrationKindsByCategory("smartHomeServer"),
mediaServer: getIntegrationKindsByCategory("mediaService"),
calendar: getIntegrationKindsByCategory("calendar"),
downloads: getIntegrationKindsByCategory("downloadClient"),
"mediaRequests-requestList": getIntegrationKindsByCategory("mediaRequest"),
"mediaRequests-requestStats": getIntegrationKindsByCategory("mediaRequest"),
mediaTranscoding: getIntegrationKindsByCategory("mediaTranscoding"),
mediaMissing: getIntegrationKindsByCategory("mediaOrganizer"),
networkControllerSummary: getIntegrationKindsByCategory("networkController"),
networkControllerStatus: getIntegrationKindsByCategory("networkController"),
indexerManager: getIntegrationKindsByCategory("indexerManager"),
healthMonitoring: getIntegrationKindsByCategory("healthMonitoring").filter(
(kind) => kind !== "patchmon" && kind !== "wud",
),
firewall: getIntegrationKindsByCategory("firewall"),
notifications: getIntegrationKindsByCategory("notifications"),
mediaReleases: ["mock", "emby", "jellyfin", "plex"],
systemResources: ["dashDot", "openmediavault", "truenas", "unraid", "glances", "synology"],
systemDisks: ["dashDot", "openmediavault", "truenas", "unraid", "synology"],
beszelAlerts: ["beszel", "mock"],
beszelSystemGrid: ["beszel", "mock"],
beszelSystemStats: ["beszel", "mock"],
beszelSystemTable: ["beszel", "mock"],
coolify: ["coolify"],
"immich-serverStats": ["immich"],
"immich-albumCarousel": ["immich"],
paperlessNgx: ["paperlessNgx"],
patchmon: ["patchmon"],
bazarr: ["bazarr"],
tracearr: ["tracearr"],
speedtestTracker: ["speedtestTracker"],
uptimeKuma: ["uptimeKuma"],
audioStats: ["navidrome", "audiobookshelf"],
umami: ["umami"],
vpn: getIntegrationKindsByCategory("vpn"),
ups: getIntegrationKindsByCategory("ups"),
archiveTeamWarrior: ["archiveTeamWarrior"],
anchorNote: ["anchor"],
traefik: ["traefik"],
wud: ["wud"],
export interface NativeFeatureCapabilityDescriptor {
integrations: readonly IntegrationKind[];
connectionOptional?: true;
serverMaxIntegrations?: number;
}
export const nativeFeatureCapabilities = {
dnsHoleSummary: { integrations: getIntegrationKindsByCategory("dnsHole") },
dnsHoleControls: { integrations: getIntegrationKindsByCategory("dnsHole") },
"smartHome-entityState": {
integrations: getIntegrationKindsByCategory("smartHomeServer"),
serverMaxIntegrations: 1,
},
"smartHome-executeAutomation": {
integrations: getIntegrationKindsByCategory("smartHomeServer"),
serverMaxIntegrations: 1,
},
mediaServer: { integrations: getIntegrationKindsByCategory("mediaService") },
calendar: { integrations: getIntegrationKindsByCategory("calendar"), connectionOptional: true },
downloads: { integrations: getIntegrationKindsByCategory("downloadClient") },
"mediaRequests-requestList": { integrations: getIntegrationKindsByCategory("mediaRequest") },
"mediaRequests-requestStats": { integrations: getIntegrationKindsByCategory("mediaRequest") },
mediaTranscoding: { integrations: getIntegrationKindsByCategory("mediaTranscoding"), serverMaxIntegrations: 1 },
mediaMissing: { integrations: getIntegrationKindsByCategory("mediaOrganizer") },
networkControllerSummary: { integrations: getIntegrationKindsByCategory("networkController") },
networkControllerStatus: { integrations: getIntegrationKindsByCategory("networkController") },
indexerManager: { integrations: getIntegrationKindsByCategory("indexerManager") },
healthMonitoring: {
integrations: getIntegrationKindsByCategory("healthMonitoring").filter(
(kind) => kind !== "patchmon" && kind !== "wud",
),
},
firewall: { integrations: getIntegrationKindsByCategory("firewall") },
notifications: { integrations: getIntegrationKindsByCategory("notifications") },
mediaReleases: { integrations: ["mock", "emby", "jellyfin", "plex"] },
systemResources: { integrations: ["dashDot", "openmediavault", "truenas", "unraid", "glances", "synology"] },
systemDisks: { integrations: ["dashDot", "openmediavault", "truenas", "unraid", "synology"] },
beszelAlerts: { integrations: ["beszel", "mock"] },
beszelSystemGrid: { integrations: ["beszel", "mock"] },
beszelSystemStats: { integrations: ["beszel", "mock"] },
beszelSystemTable: { integrations: ["beszel", "mock"] },
coolify: { integrations: ["coolify"] },
"immich-serverStats": { integrations: ["immich"], serverMaxIntegrations: 1 },
"immich-albumCarousel": { integrations: ["immich"], serverMaxIntegrations: 1 },
paperlessNgx: { integrations: ["paperlessNgx"], serverMaxIntegrations: 1 },
patchmon: { integrations: ["patchmon"], serverMaxIntegrations: 1 },
bazarr: { integrations: ["bazarr"], serverMaxIntegrations: 1 },
tracearr: { integrations: ["tracearr"] },
speedtestTracker: { integrations: ["speedtestTracker"] },
uptimeKuma: { integrations: ["uptimeKuma"] },
audioStats: { integrations: ["navidrome", "audiobookshelf"], serverMaxIntegrations: 1 },
umami: { integrations: ["umami"], serverMaxIntegrations: 1 },
vpn: { integrations: getIntegrationKindsByCategory("vpn") },
ups: { integrations: getIntegrationKindsByCategory("ups") },
archiveTeamWarrior: { integrations: ["archiveTeamWarrior"], serverMaxIntegrations: 1 },
anchorNote: { integrations: ["anchor"], serverMaxIntegrations: 1 },
traefik: { integrations: ["traefik"] },
wud: { integrations: ["wud"], serverMaxIntegrations: 1 },
} as const satisfies Partial<Record<WidgetKind, NativeFeatureCapabilityDescriptor>>;
const nativeFeatureCapabilityEntries = Object.entries(nativeFeatureCapabilities) as [
WidgetKind,
NativeFeatureCapabilityDescriptor,
][];
const createWidgetIntegrationSupport = () => {
const result: Partial<Record<WidgetKind, readonly IntegrationKind[]>> = {};
for (const [kind, capability] of nativeFeatureCapabilityEntries) result[kind] = capability.integrations;
return result;
};
export const widgetIntegrationSupport = createWidgetIntegrationSupport();
/** Widgets that remain useful without a configured integration. */
export const widgetKindsWithOptionalIntegrations = new Set<WidgetKind>(["calendar"]);
export const widgetKindsWithOptionalIntegrations = new Set<WidgetKind>(
nativeFeatureCapabilityEntries
.filter(([, capability]) => capability.connectionOptional === true)
.map(([kind]) => kind),
);
/** Widgets that support fewer integrations than the default unlimited selection. */
export const widgetIntegrationLimits: Partial<Record<WidgetKind, number>> = {
audioStats: 1,
const createWidgetIntegrationLimits = () => {
const result: Partial<Record<WidgetKind, number>> = {};
for (const [kind, capability] of nativeFeatureCapabilityEntries) {
if (capability.serverMaxIntegrations !== undefined) result[kind] = capability.serverMaxIntegrations;
}
return result;
};
export const widgetIntegrationLimits = createWidgetIntegrationLimits();
export type WidgetIntegrationIssue =
| { code: "integration-not-supported" }
| { code: "integration-required" }
@@ -98,16 +134,23 @@ export const getWidgetIntegrationIssueMessage = (widgetKind: WidgetKind, issue:
return `${widgetKind} does not support integration kind${issue.incompatibleKinds.length === 1 ? "" : "s"}: ${issue.incompatibleKinds.join(", ")}`;
};
export const getWidgetKindsForIntegration = (integrationKind: IntegrationKind): WidgetKind[] => {
const result: WidgetKind[] = [];
for (const [widgetKind, supportedIntegrations] of Object.entries(widgetIntegrationSupport)) {
if (supportedIntegrations.includes(integrationKind)) {
result.push(widgetKind as WidgetKind);
}
/** Reverse capability index generated from nativeFeatureCapabilities. */
const createIntegrationWidgetSupport = () => {
const result = {} as Record<IntegrationKind, readonly WidgetKind[]>;
for (const integrationKind of integrationKinds) {
result[integrationKind] = nativeFeatureCapabilityEntries
.filter(([, capability]) => capability.integrations.includes(integrationKind))
.map(([widgetKind]) => widgetKind);
}
return result;
};
export const integrationWidgetSupport = createIntegrationWidgetSupport();
export const getWidgetKindsForIntegration = (integrationKind: IntegrationKind): WidgetKind[] => [
...integrationWidgetSupport[integrationKind],
];
export interface DefaultWidgetConfig {
kind: WidgetKind;
width: number;