homeio

1/**
2 * What an app or container is actually doing, finer than running/stopped: the
3 * desktop tells a clean stop from a crash, a container that never started, a
4 * restart loop and a failing health check.
5 */
6export type AppCondition =
7  | "running"
8  | "starting"
9  | "unhealthy"
10  | "restarting"
11  | "partial"
12  | "paused"
13  | "stopped"
14  | "crashed"
15  | "created"
16  | "unknown";
17
18export type AppConditionSummary = {
19  condition: AppCondition;
20  /** The exit code behind a stop, crash or partial stack; null otherwise. */
21  exitCode: number | null;
22};
23
24export type ContainerHealth = "healthy" | "unhealthy" | "starting";
25
26export type ContainerSnapshot = {
27  state: string;
28  exitCode: number | null;
29  health: ContainerHealth | null;
30};
31
32// How `docker stop` ends things: exited by itself (0), SIGINT (130), SIGTERM
33// (143), or SIGKILL after the stop timeout (137). Counting these as crashes
34// would flag every app the user stopped on purpose.
35const CLEAN_EXIT_CODES = new Set([0, 130, 137, 143]);
36
37function isCrash(container: ContainerSnapshot) {
38  if (container.state === "dead") return true;
39  return container.state === "exited" && container.exitCode !== null && !CLEAN_EXIT_CODES.has(container.exitCode);
40}
41
42export function toContainerHealth(value: unknown): ContainerHealth | null {
43  const health = typeof value === "string" ? value.trim().toLowerCase() : "";
44  if (health === "healthy" || health === "unhealthy" || health === "starting") return health;
45  return null;
46}
47
48/**
49 * Exit code and health from Docker's status line: "Exited (137) 2 hours ago",
50 * "Restarting (1) 7 seconds ago" (the code of the last run), "Up 3 days (unhealthy)".
51 */
52export function parseDockerStatusLine(status: string): { exitCode: number | null; health: ContainerHealth | null } {
53  const exit = /(?:Exited|Restarting) \((-?\d+)\)/i.exec(status);
54  const health = /\((healthy|unhealthy|health: starting)\)/i.exec(status);
55  return {
56    exitCode: exit ? Number(exit[1]) : null,
57    health: health ? toContainerHealth(health[1].toLowerCase().replace("health: ", "")) : null,
58  };
59}
60
61/** One condition for a container or a whole Compose stack. */
62export function summarizeContainers(input: ContainerSnapshot[]): AppConditionSummary {
63  const containers = input.map((c) => ({ ...c, state: c.state.trim().toLowerCase() }));
64  if (containers.length === 0) return { condition: "stopped", exitCode: null };
65
66  const restarting = containers.find((c) => c.state === "restarting");
67  if (restarting) return { condition: "restarting", exitCode: restarting.exitCode };
68
69  const running = containers.filter((c) => c.state === "running");
70  if (running.length > 0) {
71    if (running.some((c) => c.health === "unhealthy")) return { condition: "unhealthy", exitCode: null };
72
73    // A one-shot container that finished cleanly (exit 0) is part of a
74    // healthy stack; anything else not running means the stack is incomplete.
75    const missing = containers.filter(
76      (c) => c.state !== "running" && !(c.state === "exited" && c.exitCode === 0),
77    );
78    if (missing.length > 0) {
79      const crashed = missing.find(isCrash);
80      return { condition: "partial", exitCode: (crashed ?? missing[0]).exitCode };
81    }
82
83    if (running.some((c) => c.health === "starting")) return { condition: "starting", exitCode: null };
84    return { condition: "running", exitCode: null };
85  }
86
87  if (containers.some((c) => c.state === "paused")) return { condition: "paused", exitCode: null };
88
89  const crashed = containers.find(isCrash);
90  if (crashed) return { condition: "crashed", exitCode: crashed.exitCode };
91
92  if (containers.every((c) => c.state === "created")) return { condition: "created", exitCode: null };
93
94  if (containers.every((c) => c.state === "exited" || c.state === "created")) {
95    const stopped = containers.find((c) => c.state === "exited");
96    return { condition: "stopped", exitCode: stopped?.exitCode ?? null };
97  }
98
99  return { condition: "unknown", exitCode: null };
100}
101