@openparachute/hub 0.6.5-rc.6 → 0.6.5-rc.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.6.5-rc.6",
+  "version": "0.6.5-rc.7",
   "description": "parachute — the local hub for the Parachute ecosystem (discovery, ports, lifecycle, soon OAuth).",
   "license": "AGPL-3.0",
   "publishConfig": {

package/src/__tests__/serve.test.ts

@@ -4,6 +4,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { _resetBootstrapTokenForTests, getBootstrapToken } from "../bootstrap-token.ts";
 import {
+  armServeDbWatchdog,
   formatBootstrapTokenBanner,
   formatListeningBanner,
   hubPortConflictMessage,
@@ -463,3 +464,74 @@ describe("resolveStartupIssuer — expose-state fallback (#531)", () => {
     expect(resolveStartupIssuer({}, {}, throwing)).toBeUndefined();
   });
 });
+
+describe("armServeDbWatchdog — #610/#619 ghost-fd watchdog wiring on the serve path", () => {
+  let tmp: string;
+  let realDbPath: string;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), "serve-watchdog-"));
+    realDbPath = join(tmp, "hub.db");
+  });
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  test("starts the liveness timer (without it, a wipe is never noticed)", () => {
+    let tick: (() => void) | undefined;
+    const { livenessTimer } = armServeDbWatchdog(realDbPath, {
+      openDb: () => openHubDb(realDbPath),
+      statInode: () => ({ dev: 1, ino: 42 }),
+      setIntervalFn: (cb) => {
+        tick = cb;
+        return 0;
+      },
+      clearIntervalFn: () => {},
+    });
+    // The timer must actually be armed — the captured tick callback proves
+    // startDbPathLivenessTimer ran (the #619 bug was that it never did on this path).
+    expect(tick).toBeInstanceOf(Function);
+    expect(livenessTimer).toBeDefined();
+  });
+
+  test("opens the db BEFORE snapshotting the inode, so a wipe tick self-exits (#619 ordering)", () => {
+    // The load-bearing invariant: `initialInode` must be a DEFINED baseline so
+    // a later "gone" verdict fires reopen-or-exit. If the helper statted before
+    // opening (the bug), a fresh path would yield ENOENT → undefined baseline →
+    // probe stuck at "unknown" → NEVER exits on a wipe.
+    let opened = false;
+    let wiped = false;
+    let tick: (() => void) | undefined;
+    const exitCodes: number[] = [];
+    armServeDbWatchdog(realDbPath, {
+      openDb: () => {
+        if (wiped) throw new Error("ENOENT: state dir wiped");
+        opened = true;
+        return openHubDb(realDbPath);
+      },
+      statInode: () => {
+        if (wiped) return undefined; // path gone
+        // Proves ordering: if the helper statted before opening, this throws and
+        // the helper's catch leaves initialInode undefined (watchdog disabled).
+        if (!opened) throw Object.assign(new Error("ENOENT"), { code: "ENOENT" });
+        return { dev: 1, ino: 42 };
+      },
+      setIntervalFn: (cb) => {
+        tick = cb;
+        return 0;
+      },
+      clearIntervalFn: () => {},
+      exit: (code) => exitCodes.push(code),
+    });
+
+    // Simulate the wipe, then drive one watchdog tick.
+    wiped = true;
+    expect(tick).toBeInstanceOf(Function);
+    tick?.();
+
+    // The probe saw "gone" against a real baseline → reopen threw (dir gone) →
+    // exit(1). A non-zero exitCodes proves `initialInode` was a defined baseline,
+    // which proves the db was opened before the inode snapshot.
+    expect(exitCodes).toEqual([1]);
+  });
+});

package/src/commands/serve.ts

@@ -34,7 +34,7 @@ import { generateBootstrapToken } from "../bootstrap-token.ts";
 // path isolation.
 import { CONFIG_DIR, SERVICES_MANIFEST_PATH } from "../config.ts";
 import { readExposeState } from "../expose-state.ts";
-import { createDbHolder } from "../hub-db-liveness.ts";
+import { createDbHolder, defaultStatInode, startDbPathLivenessTimer } from "../hub-db-liveness.ts";
 import { hubDbPath, openHubDb } from "../hub-db.ts";
 import { hubFetch } from "../hub-server.ts";
 import { writeHubFile } from "../hub.ts";
@@ -304,6 +304,80 @@ export function formatBootstrapTokenBanner(token: string, hubUrl?: string): stri
   ].join("\n");
 }
 
+/**
+ * Injectable seams for {@link armServeDbWatchdog} (test-only). Generic on the
+ * timer handle `H` so the scheduler seams never name `setInterval` in type
+ * position — mirrors `DbLivenessTimerDeps<H>` in hub-db-liveness.ts, which
+ * keeps the public interface portable to a types-less tsc environment.
+ */
+export interface ServeDbWatchdogDeps<H = unknown> {
+  log?: (line: string) => void;
+  /** Open a db handle (default {@link openHubDb}). Tests inject a fake that creates a fixture. */
+  openDb?: (path: string) => ReturnType<typeof openHubDb>;
+  /** Path stat for the inode snapshot + proactive probe (default {@link defaultStatInode}). */
+  statInode?: typeof defaultStatInode;
+  /** Injectable scheduler threaded to the liveness timer (default `setInterval`). */
+  setIntervalFn?: (cb: () => void, ms: number) => H;
+  /** Injectable clear threaded to the liveness timer (default `clearInterval`). */
+  clearIntervalFn?: (handle: H) => void;
+  /** Process-exit fn threaded into the holder's reopen-or-exit (default `process.exit`). */
+  exit?: (code: number) => void;
+}
+
+/**
+ * Build the self-heal DB holder (#594) + start the proactive ghost-fd watchdog
+ * (#610) for the `parachute serve` path, returning both so the caller wires
+ * `getDb`/`onDbError`/`probeDbPath` and stops the timer on shutdown.
+ *
+ * Extracted + exported so the wiring is unit-testable WITHOUT binding a real
+ * port (#619): a serve()-level test would have to `Bun.serve` and risk the
+ * hub#535 launchd-bootout hazard, so this pure helper carries the load-bearing
+ * invariants instead — (1) the db is OPENED before the inode is snapshotted, so
+ * a fresh-install first boot gets a defined baseline (an ENOENT snapshot would
+ * silently disable the proactive probe for the whole process lifetime), and
+ * (2) the liveness timer is actually started. Both were absent on this path
+ * before #619 — the watchdog was wired only into `createHubServer`.
+ */
+export function armServeDbWatchdog<H = unknown>(
+  dbPath: string,
+  deps: ServeDbWatchdogDeps<H> = {},
+): {
+  dbHolder: ReturnType<typeof createDbHolder>;
+  livenessTimer: ReturnType<typeof startDbPathLivenessTimer>;
+} {
+  const openDb = deps.openDb ?? openHubDb;
+  const statInode = deps.statInode ?? defaultStatInode;
+  // Open FIRST — `openHubDb` mkdir's + creates the file when absent, so the
+  // stat below sees a real inode on a fresh-install first boot. Reversing this
+  // would leave `initialInode` undefined (ENOENT) and the probe at "unknown"
+  // for the process lifetime. Mirrors `createHubServer`'s ordering.
+  const db = openDb(dbPath);
+  let initialInode: ReturnType<typeof defaultStatInode> | undefined;
+  try {
+    initialInode = statInode(dbPath);
+  } catch {
+    initialInode = undefined;
+  }
+  const dbHolder = createDbHolder(db, {
+    reopen: () => openDb(dbPath),
+    dbPath,
+    statInode,
+    initialInode,
+    ...(deps.log !== undefined ? { log: deps.log } : {}),
+    ...(deps.exit !== undefined ? { exit: deps.exit } : {}),
+  });
+  // The active `parachute serve` path (systemd / launchd / container ExecStart)
+  // MUST start the watchdog here, not only in `createHubServer` — else a
+  // `rm -rf ~/.parachute` under a running unit leaves a ghost fd that keeps
+  // SELECT 1 succeeding with no thrown error, the reactive path never fires,
+  // and the hub never self-recovers (#619).
+  const livenessTimer = startDbPathLivenessTimer<H>(dbHolder, {
+    ...(deps.setIntervalFn !== undefined ? { setIntervalFn: deps.setIntervalFn } : {}),
+    ...(deps.clearIntervalFn !== undefined ? { clearIntervalFn: deps.clearIntervalFn } : {}),
+  });
+  return { dbHolder, livenessTimer };
+}
+
 /**
  * Run the hub fetch loop in the foreground. Resolves when `Bun.serve` is
  * bound; the returned `stop()` shuts the server down for tests.
@@ -355,15 +429,8 @@ export async function serve(opts: ServeOpts = {}): Promise<{
   writeHubFile(hubHtmlPath);
 
   const dbPath = hubDbPath();
-  // Self-heal-or-die DB holder (#594). The handle lives behind a mutable
-  // holder so a request that hits the persistent-corruption class (disk I/O
-  // error / malformed image — e.g. the state dir deleted under a running hub)
-  // can reopen the handle once, or exit(1) for the platform manager to restart
-  // us with a fresh one. `getDb` reads the current handle from the holder.
-  const dbHolder = createDbHolder(openHubDb(dbPath), {
-    reopen: () => openHubDb(dbPath),
-    log,
-  });
+  // Self-heal-or-die DB holder (#594) + proactive ghost-fd watchdog (#610/#619).
+  const { dbHolder, livenessTimer } = armServeDbWatchdog(dbPath, { log });
   const adminBootstrap = await seedInitialAdminIfNeeded(dbHolder.get(), env, log);
 
   if (adminBootstrap === "needs-setup") {
@@ -401,6 +468,9 @@ export async function serve(opts: ServeOpts = {}): Promise<{
       fetch: hubFetch(WELL_KNOWN_DIR, {
         getDb: () => dbHolder.get(),
         onDbError: (err) => dbHolder.healOrExit(err),
+        // #610: /health's db check probes the path so monitoring + the #591
+        // adoption probe see a wipe instead of the ghost-fd lie.
+        probeDbPath: () => dbHolder.probePath(),
         issuer,
         loopbackPort: port,
         supervisor,
@@ -486,6 +556,7 @@ export async function serve(opts: ServeOpts = {}): Promise<{
       for (const state of supervisor.list()) {
         await supervisor.stop(state.short);
       }
+      livenessTimer.stop();
       await server.stop();
       dbHolder.get().close();
     },