geneseed 3.1.3 → 3.3.0

package/js/web/daemon.mjs

@@ -14,11 +14,9 @@ import { isTruthy, jsonDumpsCompact } from '../lib/json.mjs';
 import { webState } from './api.mjs';
 import { spawn } from 'node:child_process';
 import { chmodSync, mkdirSync, openSync, readFileSync, unlinkSync } from 'node:fs';
-import { request as httpRequest } from 'node:http';
 import { join, resolve as pathResolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
 
-const ROOT = pathResolve(fileURLToPath(import.meta.url), '..', '..', '..');
+const ROOT = pathResolve(import.meta.dirname, '..', '..');
 
 // ---- the daemon record -----------------------------------------------------
 
@@ -38,9 +36,9 @@ export function writeDaemon(target, data) {
     const p = statePath(target);
     writeText(p, jsonDumpsCompact(data, { bareInts: true }));
     // Owner-only: the record carries the API token. A no-op on Windows, where the
-    // mode only maps to the read-only attribute — same as the reference's os.chmod.
+    // mode only maps to the read-only attribute.
     chmodSync(p, 0o600);
-  } catch { /* the reference swallows OSError here too */ }
+  } catch { /* best-effort: a failed write here just means no daemon record */ }
 }
 
 export function clearDaemon(target) {
@@ -51,75 +49,62 @@ export function clearDaemon(target) {
 
 // ---- daemon mode -----------------------------------------------------------
 //
-// `geneseed web start|stop|status|restart`. The reference's own banner explains the design
-// — the running server records pid/port/token/url in a small JSON file and control is over
-// HTTP, so nothing here needs OS process-kill semantics, only a localhost request with the
-// token. Two things about the TWIN, neither of which is in that banner:
+// `geneseed web start|stop|status|restart`. The running server records pid/port/token/url
+// in a small JSON file and control is over HTTP, so nothing here needs OS process-kill
+// semantics, only a localhost request with the token.
 //
-//   * `_probe` and `_post_shutdown` are `urllib.request.urlopen` with a timeout, which is
-//     synchronous. Node has no synchronous HTTP client, so every function below that
-//     reaches one is `async` and `cmdWeb` awaits it — which is why `bin/geneseed-cli.mjs`
-//     awaits its dispatch. Nothing about the ORDER of the reference's steps changes.
-//   * `agent: false` on both requests. Node's global agent has kept sockets alive by
-//     default since v19, and a pooled idle socket keeps the event loop referenced — a
-//     `web status` that answered correctly would then hang for the keep-alive timeout
-//     instead of exiting. Python's `urlopen` opens and closes a connection per call.
+//   * Every function below that touches the network is `async` (`fetch` has no
+//     synchronous equivalent), and `cmdWeb` awaits it.
+//   * Both requests are drained (`res.body?.cancel()`) whether or not the caller wants the
+//     body: an undrained `fetch` response can keep a keep-alive socket referenced, which is
+//     the same hang a `web status` that answered correctly would otherwise suffer while
+//     waiting to exit.
 
-/** `f"{url}/api/ping"` answered 200 — the cheap liveness probe both `status` and the
- *  launcher's wait loop are built on. Every failure mode is False, as the reference's
- *  `(URLError, OSError, ValueError)` catch is. */
-export function probe(url, timeout = 1.5) {
-  return new Promise((done) => {
-    let settled = false;
-    const finish = (v) => { if (!settled) { settled = true; done(v); } };
-    let req;
-    try {
-      req = httpRequest(`${url}/api/ping`, { method: 'GET', agent: false }, (res) => {
-        res.resume();          // drain, or the socket never closes
-        finish(res.statusCode === 200);
-      });
-    } catch {
-      return finish(false);    // a malformed url is `ValueError` there and a throw here
-    }
-    req.setTimeout(Math.round(timeout * 1000), () => { req.destroy(); finish(false); });
-    req.on('error', () => finish(false));
-    req.end();
-    return undefined;
-  });
+/**
+ * `${url}/api/ping` answered 200 — the cheap liveness probe both `status` and the launcher's
+ * wait loop are built on. Every failure mode (network error, timeout, malformed url) is
+ * `false`.
+ */
+export async function probe(url, timeout = 1.5) {
+  try {
+    const res = await fetch(`${url}/api/ping`, {
+      method: 'GET',
+      signal: AbortSignal.timeout(Math.round(timeout * 1000)),
+    });
+    const ok = res.status === 200;
+    // Drained after the verdict is already read: a failure canceling the body must not
+    // flip an already-successful ping to `false`.
+    await res.body?.cancel().catch(() => {});
+    return ok;
+  } catch {
+    // network error, timeout abort, or a malformed url — all become `false`.
+    return false;
+  }
 }
 
 /** The token-carrying POST `geneseed web stop` and the in-page Stop button both send. */
-export function postShutdown(url, token, timeout = 3.0) {
-  return new Promise((done) => {
-    let settled = false;
-    const finish = (v) => { if (!settled) { settled = true; done(v); } };
-    let req;
-    try {
-      req = httpRequest(`${url}/api/shutdown`, {
-        method: 'POST',
-        agent: false,
-        headers: { 'X-Geneseed-Token': token, 'Content-Type': 'application/json' },
-      }, (res) => {
-        res.resume();
-        finish(res.statusCode === 200);
-      });
-    } catch {
-      return finish(false);
-    }
-    req.setTimeout(Math.round(timeout * 1000), () => { req.destroy(); finish(false); });
-    req.on('error', () => finish(false));
-    req.end('{}');
-    return undefined;
-  });
+export async function postShutdown(url, token, timeout = 3.0) {
+  try {
+    const res = await fetch(`${url}/api/shutdown`, {
+      method: 'POST',
+      headers: { 'X-Geneseed-Token': token, 'Content-Type': 'application/json' },
+      body: '{}',
+      signal: AbortSignal.timeout(Math.round(timeout * 1000)),
+    });
+    const ok = res.status === 200;
+    await res.body?.cancel().catch(() => {});
+    return ok;
+  } catch {
+    return false;
+  }
 }
 
 /**
- * The record ONLY if a server is answering; otherwise the stale file is deleted.
- *
- * The deletion is the part a port drops, and it is what stops a machine that crashed with
- * a daemon running from re-probing a dead URL on every `status` forever. Both of its arms
- * are gated by a `harness_golden` cell — a record whose url nothing answers, and a record
- * carrying no url at all, which skips the probe and still clears.
+ * The record ONLY if a server is answering; otherwise the stale file is deleted — which is
+ * what stops a machine that crashed with a daemon running from re-probing a dead URL on
+ * every `status` forever. Both arms are gated by a `harness_golden` cell — a record whose
+ * url nothing answers, and a record carrying no url at all, which skips the probe and still
+ * clears.
  */
 export async function liveDaemon(target) {
   const st = readDaemon(target);
@@ -130,76 +115,76 @@ export async function liveDaemon(target) {
 
 const sleep = (ms) => new Promise((r) => { setTimeout(r, ms); });
 
-/** `st.get(k)` rendered as Python renders it — a missing key prints `None`, not
- *  `undefined`. Only reachable through a hand-edited record, and one character of
- *  divergence in a message is still a divergence. */
+/**
+ * A missing key prints `None`, not `undefined` — only reachable through a hand-edited
+ * record, kept for consistency with how every other missing value is reported here.
+ */
 export const none = (v) => (v === undefined || v === null ? 'None' : String(v));
 
 /**
- * `_spawn_detached` — the daemon launcher, and the second `_ALLOWED_SPAWNS` entry this
- * module owns.
+ * The daemon launcher, and the second `ALLOWED_SPAWNS` entry this module owns.
  *
  * WHY THERE IS NO IN-PROCESS EQUIVALENT: the whole contract is that the server OUTLIVES
  * the process that started it. `geneseed web start` prints a URL and returns to the shell;
  * the server it started must still be there. A thread, a `worker_thread` or an in-process
  * `serve()` all die with the launcher.
  *
- * WHAT IT STARTS IS THIS PROGRAM, named as `process.execPath` + `bin/geneseed-cli.mjs` —
- * the running interpreter by absolute path and this repo's own CLI. The reference names
- * `sys.executable` + `rituals/harness.py`; each side re-executes ITSELF, which is what
- * makes this not the passthrough the port exists to remove, and
- * `tests/test_web_daemon.py` asserts the twin's argv contains no `python`, no `harness.py`
- * and no `build.py` at all.
+ * WHAT IT STARTS IS THIS PROGRAM: `process.execPath` + `bin/geneseed-cli.mjs` — the running
+ * interpreter by absolute path and this repo's own CLI, re-executing itself rather than
+ * shelling out to anything else. `tests/unit/web_daemon.test.mjs:199-223` scans this
+ * function's own source for `python`/`harness.py`/`build.py`/`sys.executable` and asserts
+ * none of them appear — this daemon may re-execute only itself.
  */
 function spawnDetached(webArgs, log) {
   const cmd = [process.execPath, join(ROOT, 'bin', 'geneseed-cli.mjs'), 'web', ...webArgs];
   let out = 'ignore';
   try {
-    out = openSync(log, 'a');       // `open(log, "ab")`; DEVNULL on OSError, as there
-  } catch { /* the reference falls back to DEVNULL on exactly this failure */ }
+    out = openSync(log, 'a');
+  } catch { /* falls back to 'ignore' if the log can't be opened */ }
   const child = spawn(cmd[0], cmd.slice(1), {
-    // `DETACHED_PROCESS | NEW_PROCESS_GROUP` on Windows and `start_new_session` on POSIX
-    // are both `detached` here; `unref()` is what lets the launcher's event loop end while
-    // the child runs on, which is `Popen`'s default and Node's is not.
+    // `detached: true` covers `DETACHED_PROCESS | NEW_PROCESS_GROUP` on Windows and
+    // `start_new_session` on POSIX; `unref()` is what then lets the launcher's own event
+    // loop end while the child keeps running — Node does not do this by default.
     detached: true, windowsHide: true, stdio: ['ignore', out, out],
   });
   child.unref();
 }
 
-/** The `web` argv the launcher passes. Pure, and compared against `_daemon_args` by the
- *  corpus: the binary differs per side by design, the FLAGS may not. */
+/** The `web` argv the launcher passes. Pure and side-effect free. */
 export function daemonArgs(port, theme) {
   const args = ['--daemon-internal', '--port', String(port), '--no-browser'];
   if (isTruthy(theme)) args.push('--theme', theme);
   return args;
 }
 
-/** The same for the out-of-band restart — `_restart_args`. */
+/** The same for the out-of-band restart. */
 export function restartArgs(theme) {
   const args = ['restart', '--no-browser'];
   if (isTruthy(theme)) args.push('--theme', theme);
   return args;
 }
 
-/** `request_restart` — a detached `web restart`, so the new server survives the exit of
- *  the very process asking for it. Called by POST `/api/restart`. */
+/**
+ * A detached `web restart`, so the new server survives the exit of the very process asking
+ * for it. Called by POST `/api/restart`.
+ */
 export function requestRestart(theme) {
   const target = webState(theme).target;
   spawnDetached(restartArgs(theme), join(target, '.geneseed-web.log'));
 }
 
 /**
- * `webbrowser.open(url)`, which has no Node equivalent at all — there is no stdlib module
- * that knows what a desktop's default browser is.
+ * Opens a URL in the desktop's default browser. No Node stdlib API knows what that is, so
+ * this shells out to an OS-native opener (`start`/`open`/`xdg-open`).
  *
- * IT IS A MACHINE PRIMITIVE, the same class as `taskkill` and `java -version` and the
+ * IT IS A MACHINE PRIMITIVE, the same class as `taskkill` and `java -version`, and the
  * opposite of a passthrough: it asks the OS to open a URL and hands it nothing of this
  * program's work. Declining it instead would have been a silent regression in the one verb
  * whose job is to put a UI on screen — `geneseed web` would print an address and do
- * nothing, and no cell would say so because every cell passes `--no-browser`.
+ * nothing, and no automated test would catch it, because every test passes `--no-browser`.
  *
- * The reference swallows every failure here (`contextlib.suppress(Exception)` in two call
- * sites and a bare `except` in the third), and so does this.
+ * Every failure here is swallowed — a machine with no browser opener configured must not
+ * crash a server that is otherwise working fine.
  */
 export function openUrl(url) {
   const [file, args, extra] = process.platform === 'win32'
@@ -214,19 +199,17 @@ export function openUrl(url) {
       detached: true, stdio: 'ignore', windowsHide: true, ...extra,
     });
     // ⚠ ENOENT ARRIVES AS AN EVENT, NOT AS A THROW, AND THE `try` ABOVE CANNOT SEE IT.
-    // This is where the reference's suppression failed to survive translation: Python's
-    // `subprocess` raises `FileNotFoundError` synchronously, so `contextlib.suppress(Exception)`
-    // really did swallow a missing opener. Node's `spawn` reports the same condition on the
-    // child's `error` event, and an 'error' with no listener is re-thrown as an uncaught
-    // exception. So the port's `try/catch` read as equivalent and suppressed nothing.
+    // Node's `spawn` reports a missing executable on the child's `error` event; an 'error'
+    // with no listener is re-thrown as an uncaught exception that would crash the daemon
+    // over a browser it doesn't strictly need to open. The listener below is what actually
+    // suppresses it — the `try`/`catch` around this call catches nothing here.
     //
-    // MEASURED, in the packaged no-python container: `geneseed web` on a headless Linux box
-    // printed `Error: spawn xdg-open ENOENT`. Found by the acceptance gate rather than by the
-    // 690-cell corpus, and the docblock above says why the corpus never could — every cell
-    // passes `--no-browser`, so no recorded cell has ever executed this line.
+    // MEASURED: `geneseed web` on a headless Linux box with no browser opener printed
+    // `Error: spawn xdg-open ENOENT` before this listener existed. No automated test catches
+    // this, because every test passes `--no-browser`.
     child.on('error', () => { /* no opener on this machine; the daemon is still serving */ });
     child.unref();
-  } catch { /* the reference suppresses every exception from this call too */ }
+  } catch { /* spawn itself can still throw synchronously on some platforms; same rule */ }
 }
 
 export async function startDaemon(theme, port, openBrowser = true) {
@@ -240,8 +223,8 @@ export async function startDaemon(theme, port, openBrowser = true) {
   clearDaemon(target);
   const log = join(target, '.geneseed-web.log');
   spawnDetached(daemonArgs(port, theme), log);
-  // `for _ in range(60): ... time.sleep(0.2)` — twelve seconds for the child to bind and
-  // write its record. The probe timeout is the reference's shorter 0.5 here, not 1.5.
+  // Twelve seconds for the child to bind and write its record (60 * 200ms). The probe
+  // timeout here is the shorter 0.5s, not the default 1.5s.
   for (let i = 0; i < 60; i += 1) {
     const rec = readDaemon(target);
      
@@ -264,10 +247,9 @@ export async function stopDaemon(theme = null) {
   const { target } = webState(theme);
   const st = readDaemon(target);
   if (!isTruthy(st) || !isTruthy(st.url)) {
-    // NO `clearDaemon` HERE, and the asymmetry with `liveDaemon` is the reference's. A
-    // record that names no url is left exactly where it is; `web status` on the same file
-    // deletes it. Both directions are cells, because a port that unified them would delete
-    // a file the reference keeps and stdout would look identical.
+    // NO `clearDaemon` HERE — deliberately asymmetric with `liveDaemon`/`statusDaemon`,
+    // which DO delete a record naming no url. Unifying the two would delete a file this
+    // function is not supposed to touch.
     printOut('[web] no running server recorded.\n');
     return 0;
   }
@@ -304,7 +286,7 @@ export async function restartDaemon(theme = null, port = 4747, openBrowser = tru
   let open = openBrowser;
   if (live) {
     // A live daemon means a tab is already open on this (preserved) port and will
-    // reconnect on its own — the reference's `ponytail:` note, kept.
+    // reconnect on its own — no need to open a fresh browser window here.
     open = false;
     await stopDaemon(theme);
     for (let i = 0; i < 50; i += 1) {