@hellcoder/companion 0.116.1-preview.20260814050532.93fba26 → 0.117.0

package/server/system-disk.test.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect } from "vitest";
+import { getSystemDisk } from "./system-disk.js";
+
+// getSystemDisk reads the real filesystem via statfs(2), so exact byte counts
+// are machine-dependent. The invariants below must hold on any host where
+// statfs succeeds. On a host without statfs the function returns null, which
+// every test tolerates — the meter is best-effort by design.
+describe("getSystemDisk", () => {
+  it("returns a coherent snapshot with sane invariants", () => {
+    const d = getSystemDisk();
+    if (!d) return; // statfs unavailable — nothing to assert
+
+    // A mounted filesystem always has positive capacity.
+    expect(d.total_bytes).toBeGreaterThan(0);
+
+    expect(d.used_bytes).toBeGreaterThanOrEqual(0);
+    expect(d.available_bytes).toBeGreaterThanOrEqual(0);
+    expect(d.used_bytes).toBeLessThanOrEqual(d.total_bytes);
+    expect(d.available_bytes).toBeLessThanOrEqual(d.total_bytes);
+
+    // used is derived as total - available (never bfree), so the identity
+    // must hold exactly. This is the guard against a future refactor
+    // switching to bfree and silently under-reporting usage.
+    expect(d.used_bytes).toBe(Math.max(0, d.total_bytes - d.available_bytes));
+  });
+
+  it("reports used_percent in 0–100 rounded to one decimal", () => {
+    const d = getSystemDisk();
+    if (!d) return;
+    expect(d.used_percent).toBeGreaterThanOrEqual(0);
+    expect(d.used_percent).toBeLessThanOrEqual(100);
+    expect(Math.round(d.used_percent * 10)).toBe(d.used_percent * 10);
+  });
+
+  it("reports the Companion data dir as the measured path", () => {
+    const d = getSystemDisk();
+    if (!d) return;
+    // The meter must describe the volume that session/recording files grow
+    // into, which is not necessarily the one holding "/".
+    expect(d.path).toBeTruthy();
+    expect(typeof d.path).toBe("string");
+  });
+
+  it("never throws, even though the underlying syscall can fail", () => {
+    // The route calls this on every poll with no try/catch of its own.
+    expect(() => getSystemDisk()).not.toThrow();
+  });
+});

package/server/system-disk.ts

@@ -0,0 +1,55 @@
+import { statfsSync } from "node:fs";
+import { COMPANION_HOME } from "./paths.js";
+
+export interface SystemDiskInfo {
+  /** Total size of the filesystem holding COMPANION_HOME, in bytes. */
+  total_bytes: number;
+  /** Space in use (total - available), in bytes. */
+  used_bytes: number;
+  /** Space available to this (unprivileged) user, in bytes. */
+  available_bytes: number;
+  /** Used percentage of total, 0–100, rounded to one decimal. */
+  used_percent: number;
+  /** Path the figures were measured for. */
+  path: string;
+}
+
+/**
+ * Snapshot of free space on the filesystem that holds the Companion data
+ * directory — that's the volume sessions, recordings and logs actually grow
+ * into, which is not necessarily the one holding "/".
+ *
+ * Deliberately uses statfs(2) rather than shelling out to `df`, and never
+ * walks the tree the way `du` would: this is a single syscall against the
+ * already-in-memory superblock (~0.1ms, no disk I/O), so it is safe to call
+ * on a poll interval and needs no caching layer.
+ *
+ * We report `bavail` (blocks free to unprivileged users) rather than `bfree`,
+ * which excludes the root-reserved reserve. That mirrors how getSystemMemory()
+ * prefers MemAvailable over MemFree: both answer "how much can I actually
+ * still use" rather than "how much is technically unallocated". It is also why
+ * this can read a percent or two above `df` for the same filesystem.
+ */
+export function getSystemDisk(): SystemDiskInfo | null {
+  try {
+    const stats = statfsSync(COMPANION_HOME);
+    // bsize is the preferred I/O block size that blocks/bavail are counted in.
+    const total = stats.blocks * stats.bsize;
+    const available = stats.bavail * stats.bsize;
+    const used = Math.max(0, total - available);
+    const used_percent =
+      total > 0 ? Math.round((used / total) * 1000) / 10 : 0;
+    return {
+      total_bytes: total,
+      used_bytes: used,
+      available_bytes: available,
+      used_percent,
+      path: COMPANION_HOME,
+    };
+  } catch {
+    // statfs is unavailable (very old runtime) or the path does not exist yet
+    // on a first run. The meter is best-effort — the route returns 204 and the
+    // UI renders nothing rather than showing a bogus zeroed bar.
+    return null;
+  }
+}

package/server/system-memory.test.ts

@@ -28,4 +28,36 @@ describe("getSystemMemory", () => {
     // At most one decimal place.
     expect(Math.round(m.used_percent * 10)).toBe(m.used_percent * 10);
   });
+
+  // Swap is read from the same /proc/meminfo snapshot as RAM. A host may have
+  // no swap at all, in which case every swap field must be 0 — the UI keys off
+  // swap_total_bytes === 0 to hide the meter entirely.
+  it("returns coherent swap figures, or zeroes when swap is absent", () => {
+    const m = getSystemMemory();
+
+    expect(m.swap_total_bytes).toBeGreaterThanOrEqual(0);
+    expect(m.swap_used_bytes).toBeGreaterThanOrEqual(0);
+
+    if (m.swap_total_bytes === 0) {
+      // No swap configured (or a non-Linux host): must not report phantom use.
+      expect(m.swap_used_bytes).toBe(0);
+      expect(m.swap_used_percent).toBe(0);
+      return;
+    }
+
+    // Used swap can never exceed the configured total, even though SwapFree
+    // can briefly exceed SwapTotal during swapoff — that's what the clamp is for.
+    expect(m.swap_used_bytes).toBeLessThanOrEqual(m.swap_total_bytes);
+    expect(m.swap_used_percent).toBeGreaterThanOrEqual(0);
+    expect(m.swap_used_percent).toBeLessThanOrEqual(100);
+    expect(Math.round(m.swap_used_percent * 10)).toBe(m.swap_used_percent * 10);
+  });
+
+  it("keeps swap independent of the RAM figures", () => {
+    // MemAvailable deliberately excludes swap, so a swapping box shows healthy
+    // RAM headroom while thrashing. Guards against a refactor that folds swap
+    // into used_bytes and hides exactly the condition we want to surface.
+    const m = getSystemMemory();
+    expect(m.used_bytes).toBe(Math.max(0, m.total_bytes - m.available_bytes));
+  });
 });

package/server/system-memory.ts

@@ -10,6 +10,15 @@ export interface SystemMemoryInfo {
   available_bytes: number;
   /** Used percentage of total, 0–100, rounded to one decimal. */
   used_percent: number;
+  /**
+   * Total swap, in bytes. 0 when no swap is configured, or on platforms where
+   * we cannot read it — callers should treat 0 as "no swap meter to show".
+   */
+  swap_total_bytes: number;
+  /** Swap in use (total - free), in bytes. */
+  swap_used_bytes: number;
+  /** Used percentage of swap, 0–100, rounded to one decimal. 0 when no swap. */
+  swap_used_percent: number;
 }
 
 /**
@@ -25,10 +34,19 @@ function readMeminfoKb(meminfo: string, key: string): number | null {
  * MemAvailable, which accounts for reclaimable page cache and therefore
  * reflects true OOM headroom far better than os.freemem(). Everywhere else
  * (or if /proc is unreadable) we fall back to the os module.
+ *
+ * Swap comes from the same single /proc/meminfo read, so reporting it costs
+ * nothing extra. It is worth surfacing separately rather than folding into the
+ * RAM figure: a box that has begun swapping heavily is already thrashing, and
+ * because MemAvailable excludes swap the RAM meter alone cannot show it. Swap
+ * exhaustion on top of high RAM use is the state immediately preceding the OOM
+ * killer, which is exactly what these meters exist to warn about.
  */
 export function getSystemMemory(): SystemMemoryInfo {
   let total = os.totalmem();
   let available = os.freemem();
+  let swapTotal = 0;
+  let swapUsed = 0;
 
   try {
     const meminfo = readFileSync("/proc/meminfo", "utf8");
@@ -38,16 +56,30 @@ export function getSystemMemory(): SystemMemoryInfo {
       total = totalKb * 1024;
       available = availableKb * 1024;
     }
+    const swapTotalKb = readMeminfoKb(meminfo, "SwapTotal");
+    const swapFreeKb = readMeminfoKb(meminfo, "SwapFree");
+    if (swapTotalKb !== null && swapFreeKb !== null) {
+      swapTotal = swapTotalKb * 1024;
+      // Clamp: SwapFree can momentarily exceed SwapTotal mid-swapoff.
+      swapUsed = Math.max(0, swapTotal - swapFreeKb * 1024);
+    }
   } catch {
     // Not Linux, or /proc/meminfo unavailable — keep the os module values.
+    // The os module exposes no swap figures, so swap stays 0 (= "unknown",
+    // rendered as no meter) rather than being reported as 0-bytes-used.
   }
 
   const used = Math.max(0, total - available);
   const used_percent = total > 0 ? Math.round((used / total) * 1000) / 10 : 0;
+  const swap_used_percent =
+    swapTotal > 0 ? Math.round((swapUsed / swapTotal) * 1000) / 10 : 0;
   return {
     total_bytes: total,
     used_bytes: used,
     available_bytes: available,
     used_percent,
+    swap_total_bytes: swapTotal,
+    swap_used_bytes: swapUsed,
+    swap_used_percent,
   };
 }