feat(docker): add container logs modal and stats columns (#4807)

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>

packages/request-handler/src/docker-log-decode.spec.ts

@@ -0,0 +1,53 @@
+import { describe, expect, test } from "vitest";
+
+import { createDockerLogStreamProcessor, decodeDockerLogs } from "./docker-log-decode";
+
+const encodeDockerLogFrame = (streamType: number, message: string) => {
+  const payload = Buffer.from(message, "utf-8");
+  const header = Buffer.alloc(8);
+  header.writeUInt8(streamType, 0);
+  header.writeUInt32BE(payload.length, 4);
+  return Buffer.concat([header, payload]);
+};
+
+describe("decodeDockerLogs", () => {
+  test("decodes multiplexed docker log frames", () => {
+    const logs = Buffer.concat([encodeDockerLogFrame(1, "hello "), encodeDockerLogFrame(2, "world")]);
+
+    expect(decodeDockerLogs(logs)).toBe("hello world");
+  });
+
+  test("returns plain text logs unchanged", () => {
+    expect(decodeDockerLogs("plain text log")).toBe("plain text log");
+  });
+
+  test("falls back to raw buffer text for non-multiplexed output", () => {
+    expect(decodeDockerLogs(Buffer.from("raw docker output", "utf-8"))).toBe("raw docker output");
+  });
+});
+
+describe("createDockerLogStreamProcessor", () => {
+  test("emits decoded chunks from a stream", () => {
+    const messages: string[] = [];
+    const processChunk = createDockerLogStreamProcessor(
+      (data) => messages.push(data),
+      () => undefined,
+      1024,
+    );
+
+    const chunk = encodeDockerLogFrame(1, "streamed log");
+    expect(processChunk(chunk)).toBe(true);
+    expect(messages).toEqual(["streamed log"]);
+  });
+
+  test("returns false when message size exceeds limit", () => {
+    const processChunk = createDockerLogStreamProcessor(
+      () => undefined,
+      () => undefined,
+      4,
+    );
+
+    const chunk = encodeDockerLogFrame(1, "this message is too long");
+    expect(processChunk(chunk)).toBe(false);
+  });
+});

packages/request-handler/src/docker-log-decode.ts

@@ -0,0 +1,89 @@
+const DOCKER_STREAM_HEADER_SIZE = 8;
+const DOCKER_STREAM_TYPES = new Set([1, 2]);
+
+export const decodeDockerLogs = (logs: Buffer | string) => {
+  if (typeof logs === "string") {
+    return logs;
+  }
+
+  if (logs.length === 0) {
+    return "";
+  }
+
+  let cursor = 0;
+  const parts: string[] = [];
+
+  while (cursor < logs.length) {
+    if (cursor + DOCKER_STREAM_HEADER_SIZE > logs.length) {
+      break;
+    }
+
+    const streamType = logs.readUInt8(cursor);
+    if (!DOCKER_STREAM_TYPES.has(streamType)) {
+      return logs.toString("utf-8");
+    }
+
+    const length = logs.readUInt32BE(cursor + 4);
+    const start = cursor + DOCKER_STREAM_HEADER_SIZE;
+    const end = start + length;
+    if (end > logs.length) {
+      break;
+    }
+
+    parts.push(logs.subarray(start, end).toString("utf-8"));
+    cursor = end;
+  }
+
+  const decoded = parts.join("");
+  if (decoded.length === 0) {
+    return logs.toString("utf-8");
+  }
+
+  return decoded;
+};
+
+export const createDockerLogStreamProcessor = (
+  onData: (data: string) => void,
+  onError: (err: Error) => void,
+  maxMessageSize: number,
+) => {
+  let buffer = Buffer.alloc(0);
+
+  const processChunk = (chunk: Buffer) => {
+    buffer = Buffer.concat([buffer, chunk]);
+
+    while (buffer.length > 0) {
+      if (buffer.length < DOCKER_STREAM_HEADER_SIZE) {
+        break;
+      }
+
+      const streamType = buffer.readUInt8(0);
+      if (!DOCKER_STREAM_TYPES.has(streamType)) {
+        onData(buffer.toString("utf-8"));
+        buffer = Buffer.alloc(0);
+        break;
+      }
+
+      const length = buffer.readUInt32BE(4);
+      if (length > maxMessageSize) {
+        onError(
+          new Error(`Docker log message size (${length} bytes) exceeds maximum allowed (${maxMessageSize} bytes)`),
+        );
+        return false;
+      }
+
+      const fullMessageSize = DOCKER_STREAM_HEADER_SIZE + length;
+      if (buffer.length < fullMessageSize) {
+        break;
+      }
+
+      const payload = buffer.subarray(DOCKER_STREAM_HEADER_SIZE, fullMessageSize);
+      onData(payload.toString("utf-8"));
+      buffer = buffer.subarray(fullMessageSize);
+    }
+
+    return true;
+  };
+
+  return processChunk;
+};

packages/request-handler/src/docker.ts

@@ -1,5 +1,6 @@
+import type { Readable } from "node:stream";
 import dayjs from "dayjs";
-import type { ContainerInfo, ContainerStats } from "dockerode";
+import type { Container, ContainerInfo, ContainerStats } from "dockerode";
 import type Dockerode from "dockerode";
 
 import { bestMatch } from "@homarr/common";
@@ -11,6 +12,7 @@ import { extractContainerImageName } from "@homarr/definitions";
 import type { ContainerState, Port } from "@homarr/docker";
 import { dockerLabels, DockerSingleton } from "@homarr/docker";
 
+import { createDockerLogStreamProcessor, decodeDockerLogs } from "./docker-log-decode";
 import { createCachedWidgetRequestHandler } from "./lib/cached-widget-request-handler";
 
 const logger = createLogger({ module: "dockerRequestHandler" });
@@ -183,6 +185,84 @@ export const dockerContainersRequestHandler = createCachedWidgetRequestHandler({
 
 const extractImage = (container: ContainerInfo) => extractContainerImageName(container.Image);
 
+const findContainerByIdAsync = async (id: string) => {
+  const dockerInstances = DockerSingleton.getInstances();
+  const containers = await Promise.all(
+    dockerInstances.map(async ({ instance }) => {
+      const container = instance.getContainer(id);
+
+      return await new Promise<Container | null>((resolve) => {
+        container.inspect((err, data) => {
+          if (err || !data) {
+            resolve(null);
+          } else {
+            resolve(container);
+          }
+        });
+      });
+    }),
+  );
+
+  return containers.find((container) => container) ?? null;
+};
+
+export const getContainerLogsAsync = async (id: string, tail = 200) => {
+  const container = await findContainerByIdAsync(id);
+  if (!container) {
+    return null;
+  }
+
+  const rawLogs = await container.logs({
+    tail,
+    stdout: true,
+    stderr: true,
+    follow: false,
+  });
+
+  return decodeDockerLogs(rawLogs);
+};
+
+export const streamContainerLogsAsync = async (
+  id: string,
+  tail: number,
+  onData: (data: string) => void,
+  onError: (err: Error) => void,
+) => {
+  const container = await findContainerByIdAsync(id);
+  if (!container) {
+    onError(new Error("Container not found"));
+    return () => undefined;
+  }
+
+  const stream = (await container.logs({
+    tail,
+    stdout: true,
+    stderr: true,
+    follow: true,
+  })) as Readable;
+
+  const MAX_MESSAGE_SIZE = 1024 * 1024;
+  const processChunk = createDockerLogStreamProcessor(onData, onError, MAX_MESSAGE_SIZE);
+
+  const handleChunk = (chunk: Buffer) => {
+    const shouldContinue = processChunk(chunk);
+    if (!shouldContinue) {
+      stream.removeListener("data", handleChunk);
+      stream.removeListener("error", onError);
+      stream.destroy();
+    }
+  };
+
+  stream.on("data", handleChunk);
+  stream.on("error", onError);
+
+  return () => {
+    stream.removeListener("data", handleChunk);
+    stream.removeListener("error", onError);
+    stream.destroy();
+  };
+};
+
 async function getContainersWithStatsAsync() {
   const dockerInstances = DockerSingleton.getInstances();
   const results = await Promise.allSettled(
@@ -275,8 +355,6 @@ export function calculateMemoryUsage(stats: ContainerStats): number {
     return 0;
   }
 
-  // memory usage by default includes cache, which should not be shown as it is also not shown with docker stats command
-  // See https://docs.docker.com/reference/cli/docker/container/stats/ how it is / was calculated
   return (
     stats.memory_stats.usage -
     // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition