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

packages/docker/src/endpoint-descriptor.ts

@@ -0,0 +1,152 @@
+export const dockerEndpointCapabilities = ["inventory", "logs", "lifecycle", "remove"] as const;
+export type DockerEndpointCapability = (typeof dockerEndpointCapabilities)[number];
+
+export type DockerEndpointTransport =
+  | { type: "socket"; path: string }
+  | { type: "tcp"; host: string; port: number; allowInsecure: true }
+  | {
+      type: "tls";
+      host: string;
+      port: number;
+      caPath: string;
+      certPath?: string;
+      keyPath?: string;
+    };
+
+export interface DockerEndpointDescriptor {
+  id: string;
+  name: string;
+  kind: "docker" | "podman";
+  transport: DockerEndpointTransport;
+  capabilities: DockerEndpointCapability[];
+  scope: "admin";
+  source: "environment" | "legacy" | "default";
+}
+
+const allCapabilities = [...dockerEndpointCapabilities];
+
+export const parseDockerEndpointDescriptors = (value: string): DockerEndpointDescriptor[] => {
+  let input: unknown;
+  try {
+    input = JSON.parse(value);
+  } catch (error) {
+    throw new Error("DOCKER_ENDPOINTS must be valid JSON", { cause: error });
+  }
+  if (!Array.isArray(input) || input.length === 0) {
+    throw new Error("DOCKER_ENDPOINTS must be a non-empty JSON array");
+  }
+
+  const descriptors = input.map((entry, index) => parseDescriptor(entry, index));
+  const ids = new Set(descriptors.map(({ id }) => id));
+  if (ids.size !== descriptors.length) throw new Error("DOCKER_ENDPOINTS ids must be unique");
+  return descriptors;
+};
+
+const parseDescriptor = (value: unknown, index: number): DockerEndpointDescriptor => {
+  const entry = getRecord(value, `DOCKER_ENDPOINTS[${index}]`);
+  const id = getNonEmptyString(entry.id, `DOCKER_ENDPOINTS[${index}].id`);
+  const name = getNonEmptyString(entry.name, `DOCKER_ENDPOINTS[${index}].name`);
+  const kind =
+    entry.kind === "podman" ? "podman" : entry.kind === "docker" || entry.kind === undefined ? "docker" : null;
+  if (!kind) throw new Error(`DOCKER_ENDPOINTS[${index}].kind must be docker or podman`);
+  const transport = parseTransport(entry.transport, index);
+  const capabilities = parseCapabilities(entry.capabilities, index);
+
+  return { id, name, kind, transport, capabilities, scope: "admin", source: "environment" };
+};
+
+const parseTransport = (value: unknown, index: number): DockerEndpointTransport => {
+  const transport = getRecord(value, `DOCKER_ENDPOINTS[${index}].transport`);
+  if (transport.type === "socket") {
+    return { type: "socket", path: getAbsolutePath(transport.path, `DOCKER_ENDPOINTS[${index}].transport.path`) };
+  }
+  if (transport.type === "tcp") {
+    if (transport.allowInsecure !== true) {
+      throw new Error(`DOCKER_ENDPOINTS[${index}] plaintext TCP requires allowInsecure: true`);
+    }
+    return {
+      type: "tcp",
+      host: getNonEmptyString(transport.host, `DOCKER_ENDPOINTS[${index}].transport.host`),
+      port: getPort(transport.port, index),
+      allowInsecure: true,
+    };
+  }
+  if (transport.type === "tls") {
+    const certPath = getOptionalAbsolutePath(transport.certPath, `DOCKER_ENDPOINTS[${index}].transport.certPath`);
+    const keyPath = getOptionalAbsolutePath(transport.keyPath, `DOCKER_ENDPOINTS[${index}].transport.keyPath`);
+    if (Boolean(certPath) !== Boolean(keyPath)) {
+      throw new Error(`DOCKER_ENDPOINTS[${index}] TLS certPath and keyPath must be provided together`);
+    }
+    return {
+      type: "tls",
+      host: getNonEmptyString(transport.host, `DOCKER_ENDPOINTS[${index}].transport.host`),
+      port: getPort(transport.port, index),
+      caPath: getAbsolutePath(transport.caPath, `DOCKER_ENDPOINTS[${index}].transport.caPath`),
+      ...(certPath && keyPath ? { certPath, keyPath } : {}),
+    };
+  }
+  throw new Error(`DOCKER_ENDPOINTS[${index}].transport.type must be socket, tcp, or tls`);
+};
+
+const parseCapabilities = (value: unknown, index: number): DockerEndpointCapability[] => {
+  if (value === undefined) return [...allCapabilities];
+  if (!Array.isArray(value) || value.some((capability) => !dockerEndpointCapabilities.includes(capability))) {
+    throw new Error(`DOCKER_ENDPOINTS[${index}].capabilities contains an unsupported capability`);
+  }
+  const capabilities = [...new Set(value)] as DockerEndpointCapability[];
+  if (!capabilities.includes("inventory")) {
+    throw new Error(`DOCKER_ENDPOINTS[${index}].capabilities must include inventory`);
+  }
+  return capabilities;
+};
+
+const getRecord = (value: unknown, path: string): Record<string, unknown> => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${path} must be an object`);
+  return value as Record<string, unknown>;
+};
+
+const getNonEmptyString = (value: unknown, path: string) => {
+  if (typeof value !== "string" || value.trim().length === 0) throw new Error(`${path} must be a non-empty string`);
+  return value.trim();
+};
+
+const getAbsolutePath = (value: unknown, path: string) => {
+  const result = getNonEmptyString(value, path);
+  if (!result.startsWith("/")) throw new Error(`${path} must be an absolute path`);
+  return result;
+};
+
+const getOptionalAbsolutePath = (value: unknown, path: string) =>
+  value === undefined ? undefined : getAbsolutePath(value, path);
+
+const getPort = (value: unknown, index: number) => {
+  if (!Number.isInteger(value) || Number(value) < 1 || Number(value) > 65_535) {
+    throw new Error(`DOCKER_ENDPOINTS[${index}].transport.port must be an integer from 1 to 65535`);
+  }
+  return Number(value);
+};
+
+export const getDockerEndpointHost = (descriptor: DockerEndpointDescriptor) =>
+  descriptor.transport.type === "socket"
+    ? descriptor.transport.path
+    : `${descriptor.transport.host}:${descriptor.transport.port}`;
+
+export const createLegacySocketDescriptor = (path: string): DockerEndpointDescriptor => ({
+  id: `socket:${path}`,
+  name: path,
+  kind: path.toLowerCase().includes("podman") ? "podman" : "docker",
+  transport: { type: "socket", path },
+  capabilities: [...allCapabilities],
+  scope: "admin",
+  source: "legacy",
+});
+
+export const createLegacyTcpDescriptor = (host: string, port: number): DockerEndpointDescriptor => ({
+  id: `tcp:${host}:${port}`,
+  name: `${host}:${port}`,
+  kind: "docker",
+  transport: { type: "tcp", host, port, allowInsecure: true },
+  capabilities: [...allCapabilities],
+  scope: "admin",
+  source: "legacy",
+});

packages/docker/src/env.ts

@@ -9,6 +9,8 @@ export const env = createEnv({
     DOCKER_PORTS: z.string().optional(),
     // Comma separated paths to Docker-compatible Unix sockets (e.g., /var/run/docker.sock,/run/user/1000/podman/podman.sock)
     DOCKER_SOCKET_PATHS: z.string().optional(),
+    // JSON descriptors for friendly names, TLS, Podman identity, and per-endpoint capabilities.
+    DOCKER_ENDPOINTS: z.string().optional(),
     ENABLE_DOCKER: createBooleanSchema(true),
     ENABLE_KUBERNETES: createBooleanSchema(false),
   },

packages/docker/src/index.ts

@@ -1,12 +1,31 @@
 import type Docker from "dockerode";
+import type { DockerEndpointCapability } from "./endpoint-descriptor";
 
-export type { DockerInstance } from "./singleton";
+export type { DockerEndpointInitializationFailure, DockerInstance } from "./singleton";
 export { DockerSingleton } from "./singleton";
+export * from "./endpoint-descriptor";
 export type { ContainerInfo, Container, Port } from "dockerode";
 export type { Docker };
 
 export const containerStates = ["created", "running", "paused", "restarting", "exited", "removing", "dead"] as const;
 
 export type ContainerState = (typeof containerStates)[number];
+
+export interface DockerContainerTarget {
+  endpointId: string;
+  id: string;
+}
+
+export interface DockerEndpointStatus {
+  id: string;
+  name: string;
+  status: "available" | "degraded" | "unavailable";
+  kind?: "docker" | "podman";
+  transport?: "socket" | "tcp" | "tls";
+  capabilities?: DockerEndpointCapability[];
+  source?: "environment" | "legacy" | "default";
+  scope?: "admin";
+}
+
 export * from "./labels";
 export * from "./discovery";

packages/docker/src/singleton.ts

@@ -1,26 +1,70 @@
+import { readFileSync } from "node:fs";
 import Docker from "dockerode";
 
+import { createLogger } from "@homarr/core/infrastructure/logs";
+import { ErrorWithMetadata } from "@homarr/core/infrastructure/logs/error";
+
 import { env } from "./env";
+import type { DockerEndpointCapability, DockerEndpointDescriptor } from "./endpoint-descriptor";
+import {
+  createLegacySocketDescriptor,
+  createLegacyTcpDescriptor,
+  getDockerEndpointHost,
+  parseDockerEndpointDescriptors,
+} from "./endpoint-descriptor";
 
 export interface DockerInstance {
+  endpointId: string;
+  endpointName: string;
   host: string;
+  descriptor: DockerEndpointDescriptor;
   instance: Docker;
 }
 
+export interface DockerEndpointInitializationFailure {
+  descriptor: DockerEndpointDescriptor;
+  host: string;
+}
+
+const logger = createLogger({ module: "dockerSingleton" });
+
 export class DockerSingleton {
   private static instances: DockerInstance[] | null = null;
+  private static initializationFailures: DockerEndpointInitializationFailure[] = [];
+
+  private createInstanceSafely(descriptor: DockerEndpointDescriptor): DockerInstance[] {
+    try {
+      return [createInstance(descriptor)];
+    } catch (error) {
+      const host = getDockerEndpointHost(descriptor);
+      DockerSingleton.initializationFailures.push({ descriptor, host });
+      logger.warn(
+        new ErrorWithMetadata(
+          "Failed to initialize Docker endpoint",
+          { endpointId: descriptor.id, host },
+          { cause: error },
+        ),
+      );
+      return [];
+    }
+  }
 
   private createInstances() {
+    if (env.DOCKER_ENDPOINTS) {
+      return parseDockerEndpointDescriptors(env.DOCKER_ENDPOINTS).flatMap((descriptor) =>
+        this.createInstanceSafely(descriptor),
+      );
+    }
+
     const socketPaths = env.DOCKER_SOCKET_PATHS;
     const hostVariable = env.DOCKER_HOSTNAMES;
     const portVariable = env.DOCKER_PORTS;
 
     // Socket instances from DOCKER_SOCKET_PATHS
     const socketInstances: DockerInstance[] = socketPaths
-      ? socketPaths.split(",").map((socketPath) => ({
-          host: socketPath,
-          instance: new Docker({ socketPath }),
-        }))
+      ? socketPaths
+          .split(",")
+          .flatMap((socketPath) => this.createInstanceSafely(createLegacySocketDescriptor(socketPath)))
       : [];
 
     // TCP instances from existing DOCKER_HOSTNAMES/DOCKER_PORTS
@@ -33,25 +77,34 @@ export class DockerSingleton {
         throw new Error("The number of hosts and ports must match");
       }
 
-      tcpInstances = hostnames.map((host, i) => ({
-        host: `${host}:${ports[i]}`,
+      tcpInstances = hostnames.flatMap((host, i) =>
         // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-        instance: new Docker({ host, port: parseInt(ports[i]!, 10) }),
-      }));
+        this.createInstanceSafely(createLegacyTcpDescriptor(host, parseInt(ports[i]!, 10))),
+      );
     }
 
     const instances = [...socketInstances, ...tcpInstances];
 
     // Default: local socket if nothing else configured
     if (instances.length === 0) {
-      return [{ host: "socket", instance: new Docker() }];
+      const descriptor = {
+        ...createLegacySocketDescriptor("/var/run/docker.sock"),
+        id: "socket:default",
+        name: "Local Docker",
+        source: "default" as const,
+      };
+      return [createInstance(descriptor)];
     }
 
     return instances;
   }
 
-  public static findInstance(host: string): DockerInstance | undefined {
-    return this.instances?.find((instance) => instance.host === host);
+  public static findInstance(endpointId: string): DockerInstance | undefined {
+    return this.getInstances().find((instance) => instance.endpointId === endpointId);
+  }
+
+  public static hasCapability(endpointId: string, capability: DockerEndpointCapability): boolean {
+    return this.findInstance(endpointId)?.descriptor.capabilities.includes(capability) ?? false;
   }
 
   public static getInstances(): DockerInstance[] {
@@ -59,7 +112,41 @@ export class DockerSingleton {
       return this.instances;
     }
 
+    this.initializationFailures = [];
     this.instances = new DockerSingleton().createInstances();
     return this.instances;
   }
+
+  public static getInitializationFailures(): DockerEndpointInitializationFailure[] {
+    this.getInstances();
+    return [...this.initializationFailures];
+  }
+
+  public static reset(): void {
+    this.instances = null;
+    this.initializationFailures = [];
+  }
 }
+
+const createInstance = (descriptor: DockerEndpointDescriptor): DockerInstance => ({
+  endpointId: descriptor.id,
+  endpointName: descriptor.name,
+  host: getDockerEndpointHost(descriptor),
+  descriptor,
+  instance: new Docker(createDockerOptions(descriptor)),
+});
+
+const createDockerOptions = (descriptor: DockerEndpointDescriptor) => {
+  const transport = descriptor.transport;
+  if (transport.type === "socket") return { socketPath: transport.path };
+  if (transport.type === "tcp") return { host: transport.host, port: transport.port, protocol: "http" as const };
+  return {
+    host: transport.host,
+    port: transport.port,
+    protocol: "https" as const,
+    ca: readFileSync(transport.caPath),
+    ...(transport.certPath && transport.keyPath
+      ? { cert: readFileSync(transport.certPath), key: readFileSync(transport.keyPath) }
+      : {}),
+  };
+};

packages/docker/src/test/endpoint-descriptor.spec.ts

@@ -0,0 +1,71 @@
+import { describe, expect, test } from "vitest";
+
+import { parseDockerEndpointDescriptors } from "../endpoint-descriptor";
+
+describe("parseDockerEndpointDescriptors", () => {
+  test("parses friendly TLS and read-only Podman endpoints", () => {
+    const descriptors = parseDockerEndpointDescriptors(
+      JSON.stringify([
+        {
+          id: "nas",
+          name: "NAS Docker",
+          transport: { type: "tls", host: "nas.internal", port: 2376, caPath: "/run/secrets/docker-ca" },
+        },
+        {
+          id: "podman",
+          name: "Build host",
+          kind: "podman",
+          transport: { type: "socket", path: "/run/podman/podman.sock" },
+          capabilities: ["inventory", "logs"],
+        },
+      ]),
+    );
+
+    expect(descriptors).toEqual([
+      expect.objectContaining({ id: "nas", name: "NAS Docker", kind: "docker", source: "environment" }),
+      expect.objectContaining({ id: "podman", kind: "podman", capabilities: ["inventory", "logs"] }),
+    ]);
+  });
+
+  test("requires an explicit opt-in for plaintext TCP", () => {
+    expect(() =>
+      parseDockerEndpointDescriptors(
+        JSON.stringify([{ id: "nas", name: "NAS", transport: { type: "tcp", host: "nas", port: 2375 } }]),
+      ),
+    ).toThrow("allowInsecure: true");
+  });
+
+  test("rejects duplicate identities and capabilities without inventory", () => {
+    expect(() =>
+      parseDockerEndpointDescriptors(
+        JSON.stringify([
+          { id: "same", name: "A", transport: { type: "socket", path: "/a" } },
+          { id: "same", name: "B", transport: { type: "socket", path: "/b" } },
+        ]),
+      ),
+    ).toThrow("ids must be unique");
+    expect(() =>
+      parseDockerEndpointDescriptors(
+        JSON.stringify([
+          {
+            id: "limited",
+            name: "Limited",
+            transport: { type: "socket", path: "/run/docker.sock" },
+            capabilities: ["logs"],
+          },
+        ]),
+      ),
+    ).toThrow("must include inventory");
+  });
+
+  test("returns independent default capability arrays", () => {
+    const [first, second] = parseDockerEndpointDescriptors(
+      JSON.stringify([
+        { id: "first", name: "First", transport: { type: "socket", path: "/first.sock" } },
+        { id: "second", name: "Second", transport: { type: "socket", path: "/second.sock" } },
+      ]),
+    );
+
+    expect(first?.capabilities).not.toBe(second?.capabilities);
+  });
+});

packages/docker/src/test/singleton.spec.ts

@@ -6,6 +6,7 @@ const mockEnv = vi.hoisted(() => ({
   DOCKER_SOCKET_PATHS: undefined as string | undefined,
   DOCKER_HOSTNAMES: undefined as string | undefined,
   DOCKER_PORTS: undefined as string | undefined,
+  DOCKER_ENDPOINTS: undefined as string | undefined,
   ENABLE_DOCKER: true,
   ENABLE_KUBERNETES: false,
 }));
@@ -32,13 +33,17 @@ describe("DockerSingleton", () => {
     mockEnv.DOCKER_SOCKET_PATHS = undefined;
     mockEnv.DOCKER_HOSTNAMES = undefined;
     mockEnv.DOCKER_PORTS = undefined;
+    mockEnv.DOCKER_ENDPOINTS = undefined;
   });
 
   test("should return default socket when no env vars set", () => {
     const instances = DockerSingleton.getInstances();
 
     expect(instances).toHaveLength(1);
-    expect(instances[0]?.host).toBe("socket");
+    expect(instances[0]?.host).toBe("/var/run/docker.sock");
+    expect(instances[0]).toMatchObject({ endpointId: "socket:default", endpointName: "Local Docker" });
+    const options = (instances[0]?.instance as unknown as { opts: { socketPath: string } } | undefined)?.opts;
+    expect(options?.socketPath).toBe("/var/run/docker.sock");
   });
 
   test("should return TCP instances only when DOCKER_HOSTNAMES and DOCKER_PORTS set", () => {
@@ -60,6 +65,7 @@ describe("DockerSingleton", () => {
     expect(instances).toHaveLength(2);
     expect(instances[0]?.host).toBe("host1:2375");
     expect(instances[1]?.host).toBe("host2:2376");
+    expect(instances.map(({ endpointId }) => endpointId)).toEqual(["tcp:host1:2375", "tcp:host2:2376"]);
   });
 
   test("should throw when hostname and port counts do not match", () => {
@@ -86,6 +92,7 @@ describe("DockerSingleton", () => {
     expect(instances).toHaveLength(2);
     expect(instances[0]?.host).toBe("/var/run/docker.sock");
     expect(instances[1]?.host).toBe("/run/user/1000/podman/podman.sock");
+    expect(DockerSingleton.findInstance("socket:/run/user/1000/podman/podman.sock")).toBe(instances[1]);
   });
 
   test("should combine socket and TCP instances", () => {
@@ -107,4 +114,39 @@ describe("DockerSingleton", () => {
 
     expect(first).toBe(second);
   });
+
+  test("uses the structured endpoint descriptor and exposes scoped capabilities", () => {
+    mockEnv.DOCKER_ENDPOINTS = JSON.stringify([
+      {
+        id: "readonly-podman",
+        name: "Read-only Podman",
+        kind: "podman",
+        transport: { type: "socket", path: "/run/podman/podman.sock" },
+        capabilities: ["inventory", "logs"],
+      },
+    ]);
+
+    const [endpoint] = DockerSingleton.getInstances();
+
+    expect(endpoint).toMatchObject({ endpointId: "readonly-podman", endpointName: "Read-only Podman" });
+    expect(endpoint?.descriptor).toMatchObject({ kind: "podman", source: "environment" });
+    expect(DockerSingleton.hasCapability("readonly-podman", "logs")).toBe(true);
+    expect(DockerSingleton.hasCapability("readonly-podman", "remove")).toBe(false);
+  });
+
+  test("isolates an unreadable TLS endpoint from healthy endpoints", () => {
+    mockEnv.DOCKER_ENDPOINTS = JSON.stringify([
+      { id: "local", name: "Local", transport: { type: "socket", path: "/var/run/docker.sock" } },
+      {
+        id: "broken-tls",
+        name: "Broken TLS",
+        transport: { type: "tls", host: "broken.example", port: 2376, caPath: "/missing/docker-ca.pem" },
+      },
+    ]);
+
+    expect(DockerSingleton.getInstances().map(({ endpointId }) => endpointId)).toEqual(["local"]);
+    expect(DockerSingleton.getInitializationFailures()).toEqual([
+      expect.objectContaining({ descriptor: expect.objectContaining({ id: "broken-tls" }) }),
+    ]);
+  });
 });