@kabmo-labs/kabmo 0.8.0 → 0.9.0

package/src/server/lib/lifecycle/port-guard.test.ts

@@ -4,22 +4,18 @@
  */
 
 /**
- * `port-guard.ts` decides whether this process may take a port, and its whole
- * value is in the failure path: a starter that loses the race must fail with a
- * message that names the real situation instead of a bare `EADDRINUSE`. These
- * tests therefore drive both mechanisms the module can pick — the `flock(2)`
- * lease and the PID-file fallback — and both claim outcomes: the bind succeeds,
- * or the error text carries the occupant / the underlying bind error.
+ * `acquirePortLock` — the per-port startup lease, which exists so two starters
+ * racing on one free port fail with a message that names the real situation
+ * instead of a bare `EADDRINUSE`.
  *
- * The fallback is forced where its recovery logic is the subject (a dead
- * holder, a recycled PID): `flock` ignores the lock file's contents, so those
- * branches are otherwise unreachable on this host. Everything runs against
- * temp data directories and OS-assigned ports; the only subprocesses are
- * throwaway `bun -e` holders, never an `omp` server.
+ * Both mechanisms are driven: the `flock(2)` lease and the PID-file fallback.
+ * The fallback is FORCED where its recovery logic is the subject (a dead
+ * holder, a recycled PID) — `flock` keys on the inode and ignores the file's
+ * contents, so those branches are otherwise unreachable on this host. The claim
+ * itself is `claim-port`.
  */
 
 import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
-import type { Server } from 'bun';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -29,18 +25,15 @@ import { flockAvailable } from '@/server/lib/lifecycle/flock';
 import type { FlockHandle } from '@/server/lib/lifecycle/flock';
 import { getProcessState } from '@/server/lib/lifecycle/identity';
 import { getLockPath } from '@/server/lib/lifecycle/paths';
-import { acquirePortLock, claimPort, PortInUseError } from '@/server/lib/lifecycle/port-guard';
+import { acquirePortLock } from '@/server/lib/lifecycle/port-guard';
 import type { PortLock } from '@/server/lib/lifecycle/port-guard';
-import { waitForPortFree } from '@/server/lib/lifecycle/probe';
+import { createLoopbackHarness, realFetch } from '@/test-support/loopback';
+
+const harness = createLoopbackHarness();
 
 let tempDir: string;
 let originalDataDir: string | undefined;
-/** The runner's own fetch, captured before any test runs. */
-/** The runner's own fetch, reached through `Bun` so a stub leaked onto the global cannot be mistaken for it. */
-const realFetch = Bun.fetch;
 const leases: (PortLock | FlockHandle)[] = [];
-const children: Bun.Subprocess[] = [];
-const servers: Server<undefined>[] = [];
 
 /** The flock singleton is anchored on `globalThis`; leaked state spans suites. */
 function flockHost(): { __kabmoFlock?: unknown } {
@@ -63,80 +56,17 @@ function track<T extends PortLock | FlockHandle>(lease: T | null): T | null {
   return lease;
 }
 
-/**
- * A real process whose argv says `kabmo`, i.e. `matched` to identity.ts.
- *
- * The child announces itself before it parks, and that line is what says the OS
- * has finished `exec`: a freshly spawned process's command line is unreadable
- * for the instant between fork and exec (`/proc/<pid>/cmdline` reads empty
- * there, so Linux's probe falls back to `comm` and identity answers
- * `mismatched` for a process that IS ours). Production reads a PID out of a
- * lock file written by a process started long before, so it never sees that
- * window — no fixed delay to guess at here.
- */
-async function spawnChamberHolder(): Promise<Bun.Subprocess> {
-  const child = Bun.spawn({
-    cmd: ['bun', '-e', 'console.log("ready"); await new Promise(() => {})', 'kabmo-holder'],
-    stdout: 'pipe',
-    stderr: 'ignore',
-  });
-  children.push(child);
-  const reader = (child.stdout as ReadableStream<Uint8Array>).getReader();
-  await reader.read();
-  reader.releaseLock();
-  expect(getProcessState(child.pid)).toBe('matched');
-  return child;
-}
-
-/** A PID that has exited and been reaped, so it reads as `dead`. */
-async function deadPid(): Promise<number> {
-  const child = Bun.spawn({ cmd: ['bun', '-e', 'process.exit(0)'], stdout: 'ignore', stderr: 'ignore' });
-  const pid = child.pid;
-  await child.exited;
-  expect(getProcessState(pid)).toBe('dead');
-  return pid;
-}
-
-/** An OS-assigned port, released and confirmed free before use. */
-async function freePort(): Promise<number> {
-  const server = Bun.serve({ port: 0, hostname: '127.0.0.1', fetch: () => new Response('unused') });
-  const port = server.port;
-  if (port === undefined) throw new Error('the OS did not assign an ephemeral port');
-  server.stop(true);
-  if (!(await waitForPortFree(port, '127.0.0.1', 2_000, 25))) throw new Error(`ephemeral port ${port} never became free`);
-  return port;
-}
-
-/** A live listener on an OS-assigned port, held for the whole test. */
-/** A live listener on an OS-assigned port; the guard reads the assigned
- *  number, never `server.port` (`number | undefined` in Bun's types). */
-function occupy(fetch: (request: Request) => Response): number {
-  const server = Bun.serve({ port: 0, hostname: '127.0.0.1', fetch });
-  const port = server.port;
-  if (port === undefined) throw new Error('the OS did not assign an ephemeral port');
-  servers.push(server);
-  return port;
-}
-
 beforeEach(() => {
   originalDataDir = Bun.env.KABMO_DATA_DIR;
   tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kabmo-test-port-guard-'));
   Bun.env.KABMO_DATA_DIR = tempDir;
-  // `claimPort` asks the occupant whether it is a Kabmo server, over the
-  // global fetch. A stub another file left installed would answer for it.
+  // The guard asks the occupant whether it is a Kabmo server, over the global
+  // fetch. A stub another file left installed would answer for it.
   globalThis.fetch = realFetch;
 });
 
 afterEach(async () => {
-  for (const child of children.splice(0)) {
-    try {
-      child.kill('SIGKILL');
-      await child.exited;
-    } catch {
-      // Already gone.
-    }
-  }
-  for (const server of servers.splice(0)) server.stop(true);
+  await harness.dispose();
   for (const lease of leases.splice(0)) lease.release();
   delete flockHost().__kabmoFlock;
   if (originalDataDir === undefined) delete Bun.env.KABMO_DATA_DIR;
@@ -176,7 +106,7 @@ describe('acquirePortLock', () => {
   test('reclaims a lock whose holder is dead', async () => {
     usePidFileFallback();
     const lockPath = getLockPath(4213);
-    fs.writeFileSync(lockPath, String(await deadPid()));
+    fs.writeFileSync(lockPath, String(await harness.deadPid()));
 
     const reclaimed = track(await acquirePortLock(4213, 0));
 
@@ -194,17 +124,16 @@ describe('acquirePortLock', () => {
     usePidFileFallback();
     // A live PID that is not Kabmo means the recorded instance is gone;
     // refusing here would block startup on a free port forever.
-    const stranger = Bun.spawn({ cmd: ['bun', '-e', 'await new Promise(() => {})'], stdout: 'ignore', stderr: 'ignore' });
-    children.push(stranger);
-    expect(getProcessState(stranger.pid)).toBe('mismatched');
-    fs.writeFileSync(getLockPath(4214), String(stranger.pid));
+    const stranger = await harness.livePid();
+    expect(getProcessState(stranger)).toBe('mismatched');
+    fs.writeFileSync(getLockPath(4214), String(stranger));
 
     expect(track(await acquirePortLock(4214, 0))).not.toBeNull();
   });
 
   testPosix('refuses a lock held by a live Kabmo process', async () => {
     usePidFileFallback();
-    const holder = await spawnChamberHolder();
+    const holder = await harness.spawnChamberHolder();
     const lockPath = getLockPath(4215);
     fs.writeFileSync(lockPath, String(holder.pid));
 
@@ -213,76 +142,3 @@ describe('acquirePortLock', () => {
     expect(fs.readFileSync(lockPath, 'utf8')).toBe(String(holder.pid));
   });
 });
-
-describe('claimPort', () => {
-  test('binds a free port through the injected listen', async () => {
-    const port = await freePort();
-    let binds = 0;
-
-    await claimPort({ port, host: '127.0.0.1', listen: async () => { binds += 1; } });
-
-    expect(binds).toBe(1);
-  });
-
-  test('re-binds when the occupant is this very process', async () => {
-    // `bun run --hot` re-evaluates the entry inside the running process, so the
-    // port is held by us and Bun swaps the handler on the next listen. Killing
-    // the dev loop on every save is the failure this prevents.
-    const port = occupy(() => Response.json({ service: 'kabmo', pid: process.pid }));
-    let binds = 0;
-
-    await claimPort({ port, host: '127.0.0.1', listen: async () => { binds += 1; } });
-
-    expect(binds).toBe(1);
-  });
-
-  testPosix('names a Kabmo occupant held by another process', async () => {
-    const holder = await spawnChamberHolder();
-    const port = occupy(() => Response.json({ service: 'kabmo', pid: holder.pid, version: '9.9.9' }));
-    let binds = 0;
-
-    const error = await claimPort({ port, host: '127.0.0.1', listen: async () => { binds += 1; } })
-      .then(() => null, (thrown: unknown) => thrown);
-
-    expect(error).toBeInstanceOf(PortInUseError);
-    const message = (error as Error).message;
-    expect(message).toContain(`Port ${port} is already served by Kabmo`);
-    expect(message).toContain(`pid ${holder.pid}`);
-    expect(message).toContain('v9.9.9');
-    expect(message).toContain('Nothing was stopped');
-    // A starting instance never binds over an identified one.
-    expect(binds).toBe(0);
-  });
-
-  test('names a foreign listener as not Kabmo, without a bind error', async () => {
-    // Nothing answers `/api/health` and nothing identifies itself, so the probe
-    // fails first and `listen` is never attempted.
-    const port = occupy(() => new Response('not kabmo'));
-    let binds = 0;
-
-    const error = await claimPort({ port, host: '127.0.0.1', listen: async () => { binds += 1; } })
-      .then(() => null, (thrown: unknown) => thrown);
-
-    expect(error).toBeInstanceOf(PortInUseError);
-    const message = (error as Error).message;
-    expect(message).toContain(`Port ${port} is in use by another process`);
-    expect(message).toContain(`lsof -nP -iTCP:${port} -sTCP:LISTEN`);
-    expect(message).not.toContain('Bind error');
-    expect(binds).toBe(0);
-  });
-
-  test('carries the bind error when the port looked free', async () => {
-    // The probe is only a short-circuit; when `listen` fails anyway, the real
-    // reason must survive into the error rather than being replaced by a guess.
-    const port = await freePort();
-
-    const error = await claimPort({
-      port,
-      host: '127.0.0.1',
-      listen: async () => { throw new Error('EADDRINUSE: address already in use'); },
-    }).then(() => null, (thrown: unknown) => thrown);
-
-    expect(error).toBeInstanceOf(PortInUseError);
-    expect((error as Error).message).toContain('Bind error: EADDRINUSE: address already in use');
-  });
-});

package/src/server/lib/lifecycle/port-guard.ts

@@ -18,6 +18,12 @@
  * receive connections. The newcomer would look healthy in its own log while the
  * browser kept talking to the old build; the guard stops that state from being
  * created in the first place.
+ *
+ * "One port" is every ADDRESS the bind host stands for. A name is not one
+ * socket: `localhost` is `127.0.0.1` and `::1`, and Bun binds the one it
+ * resolves first — so asking about that family alone let a stale instance keep
+ * the other, and the browser landed on whichever it resolved. See
+ * `probeAddresses`; the failure message names the address that is held.
  */
 
 import fs from 'fs';
@@ -26,7 +32,7 @@ import { flockAvailable, tryFlock } from '@/server/lib/lifecycle/flock';
 import { getProcessState } from '@/server/lib/lifecycle/identity';
 import { describeOccupant, findOccupant } from '@/server/lib/lifecycle/occupant';
 import { getLockPath } from '@/server/lib/lifecycle/paths';
-import { isPortAvailable } from '@/server/lib/lifecycle/probe';
+import { probeAddresses, unavailableAddresses } from '@/server/lib/lifecycle/probe';
 
 const LOCK_WAIT_MS = 3_000;
 /** Grace period for a port that is settling (a server that just exited, or one that is starting). */
@@ -129,7 +135,13 @@ export async function claimPort({ port, host, listen }: ClaimPortOptions): Promi
   let bindError: unknown = null;
 
   for (;;) {
-    if (await isPortAvailable(port, host)) {
+    // Every address the host can land on, not just the first one it resolves
+    // to. `localhost` is two sockets, Bun binds one of them, and asking about
+    // only that one let a stale instance keep the other half of the port — two
+    // servers, one port, and a browser that reached whichever family it
+    // happened to resolve. See `probeAddresses`.
+    const blocked = await unavailableAddresses(port, host);
+    if (blocked.length === 0) {
       try {
         await listen();
         return;
@@ -148,9 +160,9 @@ export async function claimPort({ port, host, listen }: ClaimPortOptions): Promi
       return;
     }
 
-    if (occupant) throw await buildPortInUseError(port, host, bindError);
+    if (occupant) throw await buildPortInUseError(port, host, bindError, blocked);
 
-    if (Date.now() >= deadline) throw await buildPortInUseError(port, host, bindError);
+    if (Date.now() >= deadline) throw await buildPortInUseError(port, host, bindError, blocked);
     await Bun.sleep(200);
   }
 }
@@ -164,13 +176,33 @@ function portGuidance(): string {
   ].join('\n');
 }
 
-async function buildPortInUseError(port: number, host: string, bindError: unknown): Promise<PortInUseError> {
+/**
+ * The address clause, when the host is a name that stands for more than one.
+ *
+ * `Port 3000 is in use` is not actionable on a machine where `localhost` is two
+ * sockets: it names neither the one that is taken nor the one that is free, and
+ * `lsof` lists both. Naming it is the whole difference between "something is
+ * wrong" and "this address is held, that one is not".
+ */
+function addressClause(host: string, blocked: string[]): string {
+  if (blocked.length === 0) return '';
+  if (probeAddresses(host).length < 2) return '';
+  return ` on ${blocked.join(', ')}`;
+}
+
+async function buildPortInUseError(
+  port: number,
+  host: string,
+  bindError: unknown,
+  blocked: string[],
+): Promise<PortInUseError> {
   const occupant = await findOccupant(port, host);
   const bindDetail = bindError instanceof Error ? `\n  Bind error: ${bindError.message}` : '';
+  const address = addressClause(host, blocked);
 
   if (occupant) {
     return new PortInUseError(
-      `Port ${port} is already served by Kabmo ${describeOccupant(occupant)}.\n`
+      `Port ${port} is already served by Kabmo ${describeOccupant(occupant)}${address}.\n`
       + `  Nothing was stopped — a starting instance never stops another one.\n`
       + `  Stop it first:  kabmo stop --port ${port}\n`
       + `  Or start on another port:\n${portGuidance()}`,
@@ -178,7 +210,7 @@ async function buildPortInUseError(port: number, host: string, bindError: unknow
   }
 
   return new PortInUseError(
-    `Port ${port} is in use by another process (no Kabmo instance answered on it).${bindDetail}\n`
+    `Port ${port} is in use by another process${address} (no Kabmo instance answered on it).${bindDetail}\n`
     + `  Find it with:  lsof -nP -iTCP:${port} -sTCP:LISTEN\n`
     + `  Start on another port:\n${portGuidance()}`,
   );

package/src/server/lib/lifecycle/probe-health.test.ts

@@ -0,0 +1,166 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The IDENTIFICATION half of `probe.ts`: `GET /api/health`, which is how every
+ * CLI command and the port guard find out who is on a port.
+ *
+ * The cases run against real HTTP stubs on loopback, because the questions are
+ * about a real exchange — a status code, a body's shape, a scheme, and which
+ * ADDRESS the request was aimed at. That last one is the reported bug: a
+ * single-address request for a name that stands for two sockets reported a live
+ * instance as absent, so `status` and `stop` saw nothing while a browser kept
+ * landing on it.
+ */
+
+import { afterAll, afterEach, beforeEach, describe, expect, test } from 'bun:test';
+
+import { fetchHealth } from '@/server/lib/lifecycle/probe';
+import { createLoopbackHarness, ipv6Loopback, realFetch } from '@/test-support/loopback';
+
+const harness = createLoopbackHarness();
+const { occupy, occupyAt, freePort, freePortBothFamilies } = harness;
+
+/**
+ * Another file in the same `bun test` process may have left a stub installed on
+ * the global, and every case here talks to a REAL listener it just started on
+ * loopback — so the global is put back before each one rather than trusting the
+ * ambient one.
+ */
+beforeEach(() => {
+  globalThis.fetch = realFetch;
+});
+
+afterEach(async () => {
+  await harness.dispose();
+});
+
+afterAll(async () => {
+  await harness.dispose();
+});
+
+describe('fetchHealth', () => {
+  test('returns the payload of a Kabmo listener, keeping only known fields', async () => {
+    const full = occupy(() => Response.json({
+      service: 'kabmo',
+      pid: 4242,
+      version: '3.10.1',
+      startedAt: '2026-01-01T00:00:00.000Z',
+      uptime: 12.5,
+      mock: false,
+      runtime: 'bun',
+      mode: 'dev',
+      port: 1234,
+      host: '127.0.0.1',
+      tls: false,
+      tray: true,
+      authEnabled: true,
+      fds: { open: 3352, highest: 3351, limit: 61_440, nearCliff: false },
+      extra: 'dropped',
+    }));
+
+    const health = await fetchHealth(full.port, '127.0.0.1', 1000, false);
+
+    expect(health).toEqual({
+      service: 'kabmo',
+      pid: 4242,
+      version: '3.10.1',
+      startedAt: '2026-01-01T00:00:00.000Z',
+      uptime: 12.5,
+      mock: false,
+      runtime: 'bun',
+      mode: 'dev',
+      port: 1234,
+      host: '127.0.0.1',
+      tls: false,
+      tray: true,
+      authEnabled: true,
+      // Carried, not dropped: `status` prints this as its warning line, and
+      // whitelisting it away left the report without one.
+      fds: { open: 3352, highest: 3351, limit: 61_440, nearCliff: false },
+    });
+  });
+
+  test('reports a malformed fds field as null rather than a half-trusted object', async () => {
+    const partial = occupy(() => Response.json({
+      service: 'kabmo',
+      fds: { open: 1, highest: 1, limit: 2 },
+    }));
+
+    const health = await fetchHealth(partial.port, '127.0.0.1', 1000, false);
+
+    expect(health?.service).toBe('kabmo');
+    expect(health?.fds).toBeNull();
+  });
+
+  test('drops fields whose type is wrong rather than passing them on', async () => {
+    const mistyped = occupy(() => Response.json({ service: 'kabmo', pid: '4242', version: 7, tls: 'yes' }));
+
+    const health = await fetchHealth(mistyped.port, '127.0.0.1', 1000, false);
+
+    expect(health?.service).toBe('kabmo');
+    expect(health?.pid).toBeUndefined();
+    expect(health?.version).toBeUndefined();
+    expect(health?.tls).toBeUndefined();
+  });
+
+  test.skipIf(!ipv6Loopback)('finds a listener on either address of a name', async () => {
+    // `localhost` is two sockets and a server binds one. Asking only the family
+    // Bun happens to pick left the other instance undiscoverable: `kabmo status`
+    // and `kabmo stop` reported nothing while the browser kept reaching it.
+    const port = await freePortBothFamilies();
+    const health = () => Response.json({ service: 'kabmo', pid: process.pid });
+
+    const v4 = occupyAt(port, '127.0.0.1', health);
+    expect((await fetchHealth(port, 'localhost', 1000, false))?.service).toBe('kabmo');
+    v4.stop(true);
+
+    const v6 = occupyAt(port, '::1', health);
+    expect((await fetchHealth(port, 'localhost', 1000, false))?.service).toBe('kabmo');
+    v6.stop(true);
+  });
+
+  test('recognizes a pre-rename listener, and reports it under the current name', async () => {
+    // A server started before the rename is still running the old build: its
+    // health payload says `ompchamber`, and `status`/`stop` must still find it.
+    const legacy = occupy(() => Response.json({ service: 'ompchamber', pid: 4242, port: 3000 }));
+
+    const health = await fetchHealth(legacy.port, '127.0.0.1', 1000, false);
+
+    expect(health?.service).toBe('kabmo');
+    expect(health?.pid).toBe(4242);
+  });
+
+  test('ignores a listener that is not Kabmo', async () => {
+    const foreign = occupy(() => Response.json({ service: 'something-else', pid: process.pid }));
+    expect(await fetchHealth(foreign.port, '127.0.0.1', 1000, false)).toBeNull();
+  });
+
+  test('ignores error responses, non-JSON bodies, and non-objects', async () => {
+    const broken = occupy(() => new Response('nope', { status: 500 }));
+    expect(await fetchHealth(broken.port, '127.0.0.1', 1000, false)).toBeNull();
+
+    const html = occupy(() => new Response('<html>not json</html>', { headers: { 'content-type': 'text/html' } }));
+    expect(await fetchHealth(html.port, '127.0.0.1', 1000, false)).toBeNull();
+
+    const list = occupy(() => Response.json([{ service: 'kabmo' }]));
+    expect(await fetchHealth(list.port, '127.0.0.1', 1000, false)).toBeNull();
+  });
+
+  test('returns null for a port nobody listens on, and for a bad port', async () => {
+    expect(await fetchHealth(await freePort(), '127.0.0.1', 500)).toBeNull();
+    expect(await fetchHealth(0, '127.0.0.1', 500)).toBeNull();
+    expect(await fetchHealth(Number.NaN, '127.0.0.1', 500)).toBeNull();
+  });
+
+  test('a plaintext listener is not found over TLS, and the mode decides the scheme', async () => {
+    const plain = occupy(() => Response.json({ service: 'kabmo', pid: process.pid }));
+
+    expect(await fetchHealth(plain.port, '127.0.0.1', 1000, true)).toBeNull();
+    expect(await fetchHealth(plain.port, '127.0.0.1', 1000, false)).not.toBeNull();
+    // 'auto' cannot know which scheme a live instance chose, so it tries both.
+    expect(await fetchHealth(plain.port, '127.0.0.1', 1000)).not.toBeNull();
+  });
+});