@hienlh/ppm 0.18.7 → 0.18.9

package/src/services/system-metrics/process-net-collector-darwin.ts

@@ -0,0 +1,103 @@
+/**
+ * Per-process network bytes on macOS via `nettop`. This is the ONLY mainstream
+ * OS with an unprivileged per-process network source: Windows needs an ETW
+ * session and Linux needs packet capture, so both leave the Net column hidden.
+ *
+ *   nettop -P -x -L 1 -J bytes_in,bytes_out
+ *     -P  aggregate per process instead of per connection
+ *     -x  raw byte counts, no "1.2M" suffixes
+ *     -L 1  one CSV sample, then exit (no interactive curses mode)
+ *     -J  emit only these two columns
+ *
+ * The CSV shape varies between macOS releases (a leading timestamp column comes
+ * and goes), so the parser hunts for the `<name>.<pid>` cell and takes the next
+ * two numeric cells rather than trusting fixed column indexes.
+ *
+ * UNVERIFIED on real macOS hardware — fixture-driven only.
+ */
+import type { Runner } from "../host-info/spawn-runner.ts";
+import { defaultRunner } from "../host-info/spawn-runner.ts";
+
+export const NETTOP_ARGV = ["nettop", "-P", "-x", "-L", "1", "-J", "bytes_in,bytes_out"];
+const NETTOP_TIMEOUT_MS = 5000;
+
+export interface ProcNetBytes {
+  inBytes: number;
+  outBytes: number;
+}
+
+/** `<process name>.<pid>` — the name may itself contain dots
+ *  ("com.apple.WebKit.Networking.431"), so the pid is the LAST segment. The
+ *  name must contain a letter: the leading timestamp cell some macOS releases
+ *  emit ("14:33:05.976") is otherwise a perfect match and would invent a pid
+ *  out of the fractional seconds. */
+const NAME_PID_CELL = /^(.+)\.(\d+)$/;
+const NUMERIC_CELL = /^\d+$/;
+
+function pidCell(cell: string): number | null {
+  const m = NAME_PID_CELL.exec(cell);
+  if (!m || !/[A-Za-z]/.test(m[1]!)) return null;
+  const pid = Number(m[2]);
+  return Number.isInteger(pid) && pid > 0 ? pid : null;
+}
+
+export function parseNettopCsv(text: string): Map<number, ProcNetBytes> {
+  const byPid = new Map<number, ProcNetBytes>();
+  for (const line of text.split("\n")) {
+    const cells = line.split(",").map((c) => c.trim());
+    const at = cells.findIndex((c) => pidCell(c) !== null);
+    if (at < 0) continue;
+    const pid = pidCell(cells[at]!)!;
+    const numbers = cells.slice(at + 1).filter((c) => NUMERIC_CELL.test(c));
+    if (numbers.length < 2) continue;
+    const inBytes = Number(numbers[0]);
+    const outBytes = Number(numbers[1]);
+    if (!Number.isFinite(inBytes) || !Number.isFinite(outBytes)) continue;
+    // A pid can appear twice when nettop splits interfaces; sum them.
+    const prev = byPid.get(pid);
+    byPid.set(pid, {
+      inBytes: (prev?.inBytes ?? 0) + inBytes,
+      outBytes: (prev?.outBytes ?? 0) + outBytes,
+    });
+  }
+  return byPid;
+}
+
+export interface ProcessNetCollector {
+  /** Null when the sample failed — the rows then carry no net figures at all
+   *  rather than a fabricated 0. */
+  collect(): Promise<Map<number, ProcNetBytes> | null>;
+  isDisabled(): boolean;
+}
+
+const MAX_FAILURES = 3;
+
+export function createDarwinProcessNetCollector(
+  run: Runner = defaultRunner,
+  log: (message: string) => void = (m) => console.log(m),
+): ProcessNetCollector {
+  let failures = 0;
+  let disabled = false;
+  let logged = false;
+  return {
+    isDisabled: () => disabled,
+    async collect() {
+      if (disabled) return null;
+      const startedAt = Date.now();
+      try {
+        const r = await run(NETTOP_ARGV, NETTOP_TIMEOUT_MS);
+        if (r.code !== 0 || r.timedOut) throw new Error(r.stderr || `exit ${r.code}`);
+        failures = 0;
+        if (!logged) {
+          logged = true;
+          // The 2 s tick budget is what breaks first if nettop turns out slow.
+          log(`[system-metrics] nettop sample: ${Date.now() - startedAt} ms`);
+        }
+        return parseNettopCsv(r.stdout);
+      } catch {
+        if (++failures >= MAX_FAILURES) disabled = true;
+        return null;
+      }
+    },
+  };
+}

package/src/services/system-metrics/process-rows-builder.ts

@@ -0,0 +1,111 @@
+/**
+ * Raw collector rows → `ProcessInfo[]` for one tick: instantaneous CPU%, the
+ * cosmetic `ppm` flag, the guard-derived `protected` flag and a redacted,
+ * truncated command line.
+ */
+import type { MetricsPlatform, ProcessInfo } from "../../types/system-metrics.ts";
+import { redactSecrets } from "../redact-secrets.ts";
+import type { RawProcessRow } from "./process-collector-types.ts";
+import { computeCpuPercents, cpuSampleKey, type CpuDeltaState } from "./process-cpu-delta.ts";
+import { computeProcIoRates, type ProcIoDeltaState } from "./process-io-delta.ts";
+import { checkKillAllowed, type KillGuardContext } from "./kill-guard.ts";
+import { buildGuardMaps, type GuardMaps } from "./kill-identity-resolver.ts";
+import { computePpmPids } from "./ppm-process-ownership.ts";
+import type { ProtectedPids } from "./ppm-protected-pids.ts";
+
+/** Command lines are for recognising a process, not for archiving it. A 400-row
+ *  frame measured ~120 KB at 300 chars; 160 keeps it recognisable in a table
+ *  column while cutting roughly a quarter of every 2 s frame over the tunnel. */
+export const COMMAND_MAX_CHARS = 160;
+
+export interface BuildRowsInput {
+  rows: readonly RawProcessRow[];
+  platform: MetricsPlatform;
+  coreCount: number;
+  now: number;
+  prevCpu: CpuDeltaState | null;
+  prevIo: ProcIoDeltaState | null;
+  /** Resolved against THIS tick's rows, so liveness means "present in the table". */
+  resolveProtected: (isAlive: (pid: number) => boolean, nameOf: (pid: number) => string | undefined) => ProtectedPids;
+}
+
+export interface BuiltRows {
+  processes: ProcessInfo[];
+  nextCpu: CpuDeltaState;
+  nextIo: ProcIoDeltaState;
+  guardCtx: KillGuardContext;
+  protectedPids: ProtectedPids;
+  maps: GuardMaps;
+}
+
+/** Redact first, truncate second: secrets live at the front of argv. */
+export function sanitizeCommand(command: string | null, fallback: string): string {
+  if (!command) return fallback;
+  const redacted = redactSecrets(command);
+  return redacted.length > COMMAND_MAX_CHARS ? redacted.slice(0, COMMAND_MAX_CHARS) : redacted;
+}
+
+export function buildProcessRows(input: BuildRowsInput): BuiltRows {
+  const { platform } = input;
+  const maps = buildGuardMaps(input.rows);
+  // Only the de-duplicated rows are trusted from here on.
+  const rows = [...maps.byPid.values()];
+  const protectedPids = input.resolveProtected(
+    (pid) => maps.byPid.has(pid),
+    (pid) => maps.byPid.get(pid)?.name.toLowerCase(),
+  );
+  const guardCtx: KillGuardContext = {
+    platform,
+    protectedPids: protectedPids.pids,
+    ppidOf: maps.ppidOf,
+    startedAtOf: maps.startedAtOf,
+  };
+  const ppmPids = computePpmPids({
+    roots: protectedPids.roots,
+    extraPids: [...protectedPids.pids],
+    ppidOf: maps.ppidOf,
+    startedAtOf: maps.startedAtOf,
+  });
+
+  const samples = rows.map((r) => ({ key: cpuSampleKey(r.pid, r.startedAt), cpuMs: r.cpuMs }));
+  const { percentByKey, next } = computeCpuPercents(input.prevCpu, samples, input.now, input.coreCount);
+  // Same key and the same wall interval as the CPU delta, so a row's CPU% and
+  // its Bps figures can never describe two different spans of time.
+  const io = computeProcIoRates(
+    input.prevIo,
+    rows.map((r) => ({
+      key: cpuSampleKey(r.pid, r.startedAt),
+      diskReadBytes: r.diskReadBytes,
+      diskWriteBytes: r.diskWriteBytes,
+      netInBytes: r.netInBytes,
+      netOutBytes: r.netOutBytes,
+    })),
+    input.now,
+  );
+
+  const processes: ProcessInfo[] = rows.map((r) => {
+    const key = cpuSampleKey(r.pid, r.startedAt);
+    const rates = io.ratesByKey.get(key);
+    return {
+      pid: r.pid,
+      ppid: r.ppid,
+      name: r.name,
+      command: sanitizeCommand(r.command, r.name),
+      cpu: percentByKey.get(key) ?? 0,
+      ramMB: Math.round(r.ramMB * 10) / 10,
+      startedAt: r.startedAt,
+      ppm: ppmPids.has(r.pid),
+      protected: !checkKillAllowed({ pid: r.pid, name: r.name }, false, guardCtx).allowed,
+      // Left undefined (and therefore absent from the JSON frame) whenever the
+      // OS gave nothing for that counter.
+      diskReadBps: rates?.diskReadBps,
+      diskWriteBps: rates?.diskWriteBps,
+      netInBps: rates?.netInBps,
+      netOutBps: rates?.netOutBps,
+      gpuPct: r.gpuPct,
+      gpuMemMB: r.gpuMemMB,
+    };
+  });
+
+  return { processes, nextCpu: next, nextIo: io.next, guardCtx, protectedPids, maps };
+}

package/src/services/system-metrics/rate-delta.ts

@@ -0,0 +1,47 @@
+/**
+ * Cumulative byte counters → bytes/second. Disk and net are the same problem
+ * twice, so one helper serves both.
+ */
+import type { RateMetrics } from "../../types/system-metrics.ts";
+
+export interface CounterSample {
+  inBytes: number;
+  outBytes: number;
+  /** The counter's OWN clock, in seconds — never `Date.now()` when the source
+   *  carries a timestamp, because the tick's scheduling jitter (a Windows CIM
+   *  round trip alone is ~174 ms and can slip) would otherwise leak into the rate. */
+  atSec: number;
+}
+
+const UINT32 = 2 ** 32;
+/** Faster than any bus this code will meet; a corrected wrap that lands above
+ *  it is a counter reset, not a transfer. */
+const MAX_PLAUSIBLE_BPS = 100 * 1024 ** 3;
+
+export const UNAVAILABLE_RATE: RateMetrics = { inBps: 0, outBps: 0, available: false };
+
+/**
+ * - first sample → `available:false` (no baseline)
+ * - non-positive interval → `available:false`
+ * - negative delta → retry with +2^32 (`BytesReceivedPersec` is a 32-bit counter
+ *   that wraps roughly every 34 s of sustained gigabit); accept only when the
+ *   corrected rate is physically plausible, else `available:false`
+ */
+export function toRate(prev: CounterSample | null, next: CounterSample): RateMetrics {
+  if (!prev) return UNAVAILABLE_RATE;
+  const dt = next.atSec - prev.atSec;
+  if (!Number.isFinite(dt) || dt <= 0) return UNAVAILABLE_RATE;
+
+  const inBps = deltaRate(next.inBytes - prev.inBytes, dt);
+  const outBps = deltaRate(next.outBytes - prev.outBytes, dt);
+  if (inBps === null || outBps === null) return UNAVAILABLE_RATE;
+  return { inBps, outBps, available: true };
+}
+
+function deltaRate(delta: number, dtSec: number): number | null {
+  if (!Number.isFinite(delta)) return null;
+  const corrected = delta < 0 ? delta + UINT32 : delta;
+  if (corrected < 0) return null;
+  const bps = Math.round(corrected / dtSec);
+  return bps > MAX_PLAUSIBLE_BPS ? null : bps;
+}

package/src/services/system-metrics/system-metrics-platform.ts

@@ -0,0 +1,51 @@
+/** Per-OS collector wiring for the snapshot service. Nothing here spawns until
+ *  a full-tier tick actually calls a collector. */
+import type { MetricsPlatform } from "../../types/system-metrics.ts";
+import type { ProcessCollector } from "./process-collector-types.ts";
+import { EMPTY_PROCESS_COLLECTOR } from "./process-collector-types.ts";
+import type { DiskNetCounters } from "./disk-net-collector-linux.ts";
+import { collectLinuxDiskNet } from "./disk-net-collector-linux.ts";
+import { collectDarwinDiskNet } from "./disk-net-collector-darwin.ts";
+import { createNvidiaGpuCollector, type GpuCollector } from "./gpu-collector-nvidia.ts";
+import { createNvidiaProcessMemoryCollector } from "./gpu-process-memory-nvidia.ts";
+import { createLinuxProcessCollector } from "./process-collector-linux.ts";
+import { createDarwinProcessCollector } from "./process-collector-darwin.ts";
+import { createDarwinProcessNetCollector } from "./process-net-collector-darwin.ts";
+import { createWindowsProcessCollector } from "./process-collector-windows.ts";
+import { readProcTable } from "../proc-table-linux.ts";
+
+export interface PlatformCollectors {
+  platform: MetricsPlatform;
+  processes: ProcessCollector;
+  /** Null on win32: the counters ride along in the process round trip. */
+  diskNet: (() => Promise<DiskNetCounters>) | null;
+  gpus: GpuCollector;
+}
+
+export function toMetricsPlatform(p: NodeJS.Platform = process.platform): MetricsPlatform {
+  return p === "win32" || p === "darwin" ? p : "linux";
+}
+
+export function createPlatformCollectors(platform: MetricsPlatform = toMetricsPlatform()): PlatformCollectors {
+  const gpus = createNvidiaGpuCollector();
+  switch (platform) {
+    case "win32":
+      return { platform, processes: createWindowsProcessCollector(), diskNet: null, gpus };
+    case "darwin":
+      return {
+        platform,
+        processes: createDarwinProcessCollector(undefined, undefined, { net: createDarwinProcessNetCollector() }),
+        diskNet: () => collectDarwinDiskNet(),
+        gpus,
+      };
+    case "linux":
+      return {
+        platform,
+        processes: createLinuxProcessCollector(readProcTable, { gpuMemory: createNvidiaProcessMemoryCollector() }),
+        diskNet: async () => collectLinuxDiskNet(),
+        gpus,
+      };
+    default:
+      return { platform, processes: EMPTY_PROCESS_COLLECTOR, diskNet: null, gpus };
+  }
+}

package/src/services/system-metrics/system-metrics-tick.ts

@@ -0,0 +1,178 @@
+/**
+ * Assembles ONE snapshot for a tier. Touches only local variables and returns
+ * the next delta state alongside the snapshot, so the service can commit the
+ * baseline as a single unit AFTER a full assembly — a collector throwing halfway
+ * can then never leave a half-advanced baseline behind.
+ */
+import type {
+  MetricsPlatform, MetricsSnapshot, MetricsTier, MemoryMetrics, ProcessColumnAvailability, SystemMetrics,
+} from "../../types/system-metrics.ts";
+import { METRICS_INTERVAL_MS, METRICS_LIGHT_INTERVAL_MS } from "../../types/system-metrics.ts";
+import { computeCpuFromSamples, type CpuTimesSample } from "./cpu-memory-collector.ts";
+import { toRate, UNAVAILABLE_RATE, type CounterSample } from "./rate-delta.ts";
+import type { DiskNetCounters } from "./disk-net-collector-linux.ts";
+import type { GpuCollector } from "./gpu-collector-nvidia.ts";
+import type { ProcessCollection, ProcessCollector } from "./process-collector-types.ts";
+import { NO_PROCESS_COLUMNS } from "./process-collector-types.ts";
+import type { CpuDeltaState } from "./process-cpu-delta.ts";
+import type { ProcIoDeltaState } from "./process-io-delta.ts";
+import { buildProcessRows, type BuildRowsInput } from "./process-rows-builder.ts";
+import { groupProcesses } from "./process-grouping.ts";
+import type { KillGuardContext } from "./kill-guard.ts";
+
+export interface TickDeltaState {
+  cpu: CpuTimesSample | null;
+  disk: CounterSample | null;
+  net: CounterSample | null;
+  procCpu: CpuDeltaState | null;
+  procIo: ProcIoDeltaState | null;
+}
+
+export const EMPTY_DELTA_STATE: TickDeltaState = { cpu: null, disk: null, net: null, procCpu: null, procIo: null };
+
+export interface TickDeps {
+  platform: MetricsPlatform;
+  memory: () => MemoryMetrics;
+  processes: ProcessCollector;
+  /** Null on win32 — the counters ride along in the process round trip. */
+  diskNet: (() => Promise<DiskNetCounters>) | null;
+  gpus: GpuCollector;
+  resolveProtected: BuildRowsInput["resolveProtected"];
+  now: () => number;
+  sampleCpu: (now: number) => CpuTimesSample;
+}
+
+export interface AssembledTick {
+  snapshot: MetricsSnapshot;
+  nextState: TickDeltaState;
+  /** Fresh guard context from this tick's rows (full tier only). */
+  guardCtx: KillGuardContext | null;
+}
+
+/**
+ * `previousFull` is the last published full snapshot. When the process
+ * collection itself fails (a wedged CIM call, a busy session) its rows and
+ * groups are re-published with a warning and the per-process CPU baseline is
+ * kept — committing an empty baseline would make every process read 0 % on the
+ * next good tick, and an empty frame would flash the table blank.
+ */
+export async function assembleTick(
+  tier: MetricsTier,
+  state: TickDeltaState,
+  deps: TickDeps,
+  previousFull: MetricsSnapshot | null = null,
+): Promise<AssembledTick> {
+  const now = deps.now();
+  const cpuSample = deps.sampleCpu(now);
+  const cpu = computeCpuFromSamples(state.cpu, cpuSample);
+  const mem = deps.memory();
+  const warnings: string[] = [];
+
+  const system: SystemMetrics = {
+    cpu, mem, disk: UNAVAILABLE_RATE, net: UNAVAILABLE_RATE, gpus: [], processCount: 0,
+  };
+  const nextState: TickDeltaState = { ...state, cpu: cpuSample };
+  let groups: MetricsSnapshot["groups"] = [];
+  let processes: MetricsSnapshot["processes"] = [];
+  let processColumns: ProcessColumnAvailability = NO_PROCESS_COLUMNS;
+  let guardCtx: KillGuardContext | null = null;
+
+  if (tier === "full") {
+    const collection = await collectProcessesSafely(deps.processes, warnings);
+    const counters = await collectCounters(collection ?? { rows: [], warnings: [] }, deps, warnings);
+    if (counters.disk) {
+      system.disk = toRate(state.disk, counters.disk);
+      nextState.disk = counters.disk;
+    }
+    if (counters.net) {
+      system.net = toRate(state.net, counters.net);
+      nextState.net = counters.net;
+    }
+    system.gpus = await deps.gpus.collect();
+
+    if (collection) {
+      const built = buildProcessRows({
+        rows: collection.rows,
+        platform: deps.platform,
+        coreCount: cpuSample.times.length,
+        now,
+        prevCpu: state.procCpu,
+        prevIo: state.procIo,
+        resolveProtected: deps.resolveProtected,
+      });
+      warnings.push(...built.maps.warnings);
+      nextState.procCpu = built.nextCpu;
+      nextState.procIo = built.nextIo;
+      processes = built.processes;
+      processColumns = collection.columns ?? NO_PROCESS_COLUMNS;
+      guardCtx = built.guardCtx;
+      groups = groupProcesses(processes, deps.platform, built.protectedPids.roots, built.protectedPids.selfPid);
+    } else if (previousFull) {
+      processes = previousFull.processes;
+      groups = previousFull.groups;
+      // Re-published rows keep the columns they were measured with.
+      processColumns = previousFull.processColumns;
+    }
+    system.processCount = processes.length;
+  }
+
+  const snapshot: MetricsSnapshot = {
+    ts: now,
+    platform: deps.platform,
+    tier,
+    intervalMs: tier === "full" ? METRICS_INTERVAL_MS : METRICS_LIGHT_INTERVAL_MS,
+    system,
+    groups,
+    processes,
+    processColumns,
+    total: { cpu: cpu.total, ramMB: mem.usedMB, processCount: system.processCount },
+    warnings,
+  };
+  return { snapshot, nextState, guardCtx };
+}
+
+/** A light-tier view of a full snapshot, so one timer can feed both tiers. */
+export function projectLight(full: MetricsSnapshot): MetricsSnapshot {
+  return {
+    ...full,
+    tier: "light",
+    system: { ...full.system, disk: UNAVAILABLE_RATE, net: UNAVAILABLE_RATE, gpus: [], processCount: 0 },
+    groups: [],
+    processes: [],
+    processColumns: NO_PROCESS_COLUMNS,
+    total: { ...full.total, processCount: 0 },
+  };
+}
+
+/** Null means the collection FAILED (as opposed to a legitimately empty table). */
+async function collectProcessesSafely(collector: ProcessCollector, warnings: string[]): Promise<ProcessCollection | null> {
+  try {
+    const c = await collector.collect();
+    warnings.push(...c.warnings);
+    return c;
+  } catch (e) {
+    warnings.push(`Process list unavailable this tick: ${(e as Error)?.message ?? String(e)}`);
+    return null;
+  }
+}
+
+async function collectCounters(
+  collection: ProcessCollection,
+  deps: TickDeps,
+  warnings: string[],
+): Promise<{ disk: CounterSample | null; net: CounterSample | null }> {
+  if (collection.disk !== undefined || collection.net !== undefined) {
+    if (!collection.disk) warnings.push("Disk throughput unavailable: perf counters returned no _Total row (try `lodctr /R`)");
+    if (!collection.net) warnings.push("Network throughput unavailable: perf counters returned no adapters (try `lodctr /R`)");
+    return { disk: collection.disk ?? null, net: collection.net ?? null };
+  }
+  if (!deps.diskNet) return { disk: null, net: null };
+  try {
+    const c = await deps.diskNet();
+    warnings.push(...c.warnings);
+    return { disk: c.disk, net: c.net };
+  } catch (e) {
+    warnings.push(`Disk/network throughput unavailable: ${(e as Error)?.message ?? String(e)}`);
+    return { disk: null, net: null };
+  }
+}