feat(docker): Podman compatibility, multi-socket support, per-host error isolation (#5425)

Co-authored-by: Meier Lukas <meierschlumpf@gmail.com>

packages/request-handler/src/docker.ts

@@ -2,6 +2,8 @@ import dayjs from "dayjs";
 import type { ContainerInfo, ContainerStats } from "dockerode";
 import type Dockerode from "dockerode";
 
+import { createLogger } from "@homarr/core/infrastructure/logs";
+import { ErrorWithMetadata } from "@homarr/core/infrastructure/logs/error";
 import { db, like, or } from "@homarr/db";
 import { icons } from "@homarr/db/schema";
 import type { ContainerState } from "@homarr/docker";
@@ -9,6 +11,8 @@ import { dockerLabels, DockerSingleton } from "@homarr/docker";
 
 import { createCachedWidgetRequestHandler } from "./lib/cached-widget-request-handler";
 
+const logger = createLogger({ module: "dockerRequestHandler" });
+
 export const dockerContainersRequestHandler = createCachedWidgetRequestHandler({
   queryKey: "dockerContainersResult",
   widgetKind: "dockerContainers",
@@ -18,19 +22,34 @@ export const dockerContainersRequestHandler = createCachedWidgetRequestHandler({
   cacheDuration: dayjs.duration(20, "seconds"),
 });
 
-const dockerInstances = DockerSingleton.getInstances();
-
 const extractImage = (container: ContainerInfo) => container.Image.split("/").at(-1)?.split(":").at(0) ?? "";
 
 async function getContainersWithStatsAsync() {
-  const containers = await Promise.all(
+  const dockerInstances = DockerSingleton.getInstances();
+  const results = await Promise.allSettled(
     dockerInstances.map(async ({ instance, host }) => {
       const instanceContainers = await instance.listContainers({ all: true });
       return instanceContainers
         .filter((container) => !(dockerLabels.hide in container.Labels))
         .map((container) => ({ ...container, instance: host }));
     }),
-  ).then((res) => res.flat());
+  );
+
+  const containers = results.flatMap((result, index) => {
+    if (result.status === "fulfilled") return result.value;
+    logger.warn(
+      new ErrorWithMetadata(
+        "Failed to list containers from Docker host",
+        {
+          // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+          host: dockerInstances[index]!.host,
+        },
+        { cause: result.reason },
+      ),
+    );
+
+    return [];
+  });
   const likeQueries = containers.map((container) => like(icons.name, `%${extractImage(container)}%`));
 
   const dbIcons =
@@ -44,8 +63,6 @@ async function getContainersWithStatsAsync() {
     const instance = dockerInstances.find(({ host }) => host === container.instance)?.instance;
     if (!instance) return null;
 
-    // Get stats, falling back to an empty stats object if fetch fails
-    // calculateCpuUsage and calculateMemoryUsage will return 0 for invalid/missing stats
     const stats = await instance
       .getContainer(container.Id)
       .stats({ stream: false, "one-shot": true })
@@ -63,6 +80,7 @@ async function getContainersWithStatsAsync() {
     return {
       id: container.Id,
       name: container.Names[0]?.split("/")[1] ?? "Unknown",
+      host: container.instance,
       state: container.State as ContainerState,
       iconUrl:
         dbIcons.find((icon) => {
@@ -80,9 +98,10 @@ async function getContainersWithStatsAsync() {
   return (await Promise.all(containerStatsPromises)).filter((container) => container !== null);
 }
 
-function calculateCpuUsage(stats: ContainerStats): number {
-  // Handle containers with missing or invalid stats (e.g., exited, dead containers)
-  if (!stats.cpu_stats.online_cpus || stats.cpu_stats.online_cpus === 0 || !stats.cpu_stats.cpu_usage.total_usage) {
+export function calculateCpuUsage(stats: ContainerStats): number {
+  // Handle containers with missing or invalid stats (e.g., exited, dead containers, Podman responses)
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  if (!stats.cpu_stats?.online_cpus || stats.cpu_stats.online_cpus === 0 || !stats.cpu_stats.cpu_usage?.total_usage) {
     return 0;
   }
 
@@ -95,9 +114,10 @@ function calculateCpuUsage(stats: ContainerStats): number {
   return (stats.cpu_stats.cpu_usage.total_usage / usage) * numberOfCpus * 100;
 }
 
-function calculateMemoryUsage(stats: ContainerStats): number {
-  // Handle containers with missing or invalid stats (e.g., exited, dead containers)
-  if (!stats.memory_stats.usage) {
+export function calculateMemoryUsage(stats: ContainerStats): number {
+  // Handle containers with missing or invalid stats (e.g., exited, dead containers, Podman responses)
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  if (!stats.memory_stats?.usage) {
     return 0;
   }
 

packages/request-handler/src/test/docker.spec.ts

@@ -0,0 +1,121 @@
+import type { ContainerStats } from "dockerode";
+import { describe, expect, test, vi } from "vitest";
+
+import { createDb } from "@homarr/db/test";
+
+import { calculateCpuUsage, calculateMemoryUsage } from "../docker";
+
+vi.mock("@homarr/db", async (importActual) => {
+  // eslint-disable-next-line @typescript-eslint/consistent-type-imports
+  const actual = await importActual<typeof import("@homarr/db")>();
+  return {
+    ...actual,
+    db: createDb(),
+  };
+});
+
+// Helper to create a partial stats object, cast to ContainerStats.
+// This mirrors what Podman and other Docker-compatible runtimes may return
+// at runtime, even though @types/dockerode declares all fields as required.
+const createStats = (overrides: Record<string, unknown> = {}) => overrides as unknown as ContainerStats;
+
+describe("calculateCpuUsage", () => {
+  test("should return 0 when cpu_stats is undefined (Podman)", () => {
+    const stats = createStats({ cpu_stats: undefined });
+    expect(calculateCpuUsage(stats)).toBe(0);
+  });
+
+  test("should return 0 when online_cpus is 0", () => {
+    const stats = createStats({
+      cpu_stats: { online_cpus: 0, cpu_usage: { total_usage: 1000 }, system_cpu_usage: 5000 },
+    });
+    expect(calculateCpuUsage(stats)).toBe(0);
+  });
+
+  test("should return 0 when online_cpus is undefined", () => {
+    const stats = createStats({
+      cpu_stats: { cpu_usage: { total_usage: 1000 }, system_cpu_usage: 5000 },
+    });
+    expect(calculateCpuUsage(stats)).toBe(0);
+  });
+
+  test("should return 0 when cpu_usage is undefined", () => {
+    const stats = createStats({
+      cpu_stats: { online_cpus: 4, system_cpu_usage: 5000 },
+    });
+    expect(calculateCpuUsage(stats)).toBe(0);
+  });
+
+  test("should return 0 when total_usage is 0", () => {
+    const stats = createStats({
+      cpu_stats: { online_cpus: 4, cpu_usage: { total_usage: 0 }, system_cpu_usage: 5000 },
+    });
+    expect(calculateCpuUsage(stats)).toBe(0);
+  });
+
+  test("should return 0 when system_cpu_usage is 0", () => {
+    const stats = createStats({
+      cpu_stats: { online_cpus: 4, cpu_usage: { total_usage: 1000 }, system_cpu_usage: 0 },
+    });
+    expect(calculateCpuUsage(stats)).toBe(0);
+  });
+
+  test("should calculate correct CPU percentage for valid stats", () => {
+    const stats = createStats({
+      cpu_stats: { online_cpus: 4, cpu_usage: { total_usage: 2000 }, system_cpu_usage: 10000 },
+    });
+    // (2000 / 10000) * 4 * 100 = 80
+    expect(calculateCpuUsage(stats)).toBe(80);
+  });
+
+  test("should handle fractional CPU usage", () => {
+    const stats = createStats({
+      cpu_stats: { online_cpus: 2, cpu_usage: { total_usage: 500 }, system_cpu_usage: 100000 },
+    });
+    // (500 / 100000) * 2 * 100 = 1
+    expect(calculateCpuUsage(stats)).toBe(1);
+  });
+});
+
+describe("calculateMemoryUsage", () => {
+  test("should return 0 when memory_stats is undefined (Podman)", () => {
+    const stats = createStats({ memory_stats: undefined });
+    expect(calculateMemoryUsage(stats)).toBe(0);
+  });
+
+  test("should return 0 when memory_stats.usage is 0", () => {
+    const stats = createStats({ memory_stats: { usage: 0 } });
+    expect(calculateMemoryUsage(stats)).toBe(0);
+  });
+
+  test("should return 0 when memory_stats.usage is undefined", () => {
+    const stats = createStats({ memory_stats: {} });
+    expect(calculateMemoryUsage(stats)).toBe(0);
+  });
+
+  test("should subtract cache from usage", () => {
+    const stats = createStats({
+      memory_stats: { usage: 1000, stats: { cache: 200 } },
+    });
+    expect(calculateMemoryUsage(stats)).toBe(800);
+  });
+
+  test("should use total_inactive_file when cache is absent", () => {
+    const stats = createStats({
+      memory_stats: { usage: 1000, stats: { total_inactive_file: 300 } },
+    });
+    expect(calculateMemoryUsage(stats)).toBe(700);
+  });
+
+  test("should use inactive_file as last fallback", () => {
+    const stats = createStats({
+      memory_stats: { usage: 1000, stats: { inactive_file: 150 } },
+    });
+    expect(calculateMemoryUsage(stats)).toBe(850);
+  });
+
+  test("should return raw usage when memory_stats.stats is undefined", () => {
+    const stats = createStats({ memory_stats: { usage: 512 } });
+    expect(calculateMemoryUsage(stats)).toBe(512);
+  });
+});