Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
3.5 KB
Raw Blame
/**
 * Starting a real `gbrain serve --http` from a test without a port race.
 *
 * A port picked at random (`43000 + Math.random() * 2000`) sits inside the
 * kernel's ephemeral range (Linux 32768-60999). Any socket on the machine may
 * already hold it: another file's port-0 listener, a live loopback connection,
 * or a client connection closed in the last 60 s (TIME_WAIT). serve then
 * exits with serve_port_in_use, and a harness that discards its output only
 * sees /health fail until its deadline. `freePort()` asks the kernel for a
 * port nothing holds, and `startServeHttp()` keeps serve's output and fails
 * as soon as the child exits.
 */
import { spawn, type ChildProcess } from 'node:child_process';
import { createServer, type AddressInfo } from 'node:net';
import { join } from 'node:path';

const CLI = join(import.meta.dir, '..', '..', 'src', 'cli.ts');

/** A 127.0.0.1 port the kernel reports free right now: bind port 0, read it, release it. */
export function freePort(): Promise<number> {
  return new Promise((resolve, reject) => {
    const probe = createServer();
    probe.once('error', reject);
    probe.listen(0, '127.0.0.1', () => {
      const { port } = probe.address() as AddressInfo;
      probe.close(() => resolve(port));
    });
  });
}

export interface ServeHttp {
  port: number;
  /** `http://127.0.0.1:<port>` */
  base: string;
  child: ChildProcess;
  /** Everything serve wrote to stdout and stderr so far. */
  output(): string;
  /** SIGTERM, then wait for the exit. */
  stop(): Promise<void>;
}

/**
 * `gbrain serve --http --bind 127.0.0.1 --port <free port> [...args]`, resolved once
 * GET /health answers ok. If serve exits first (a taken port, a held lock, a bad
 * config) this throws at once with serve's output; a deadline failure carries it too.
 */
export async function startServeHttp(opts: { cwd: string; env: Record<string, string>; args?: string[]; timeoutMs?: number }): Promise<ServeHttp> {
  const port = await freePort();
  const base = `http://127.0.0.1:${port}`;
  const child = spawn(process.execPath, ['--no-env-file', CLI, 'serve', '--http', '--bind', '127.0.0.1', '--port', String(port), ...(opts.args ?? [])],
    { cwd: opts.cwd, env: opts.env, stdio: ['ignore', 'pipe', 'pipe'] });
  let output = '';
  child.stdout!.on('data', (d: Buffer) => { output += d.toString(); });
  child.stderr!.on('data', (d: Buffer) => { output += d.toString(); });
  const exited = new Promise<void>(resolve => child.once('exit', () => resolve()));
  const drained = new Promise<void>(resolve => child.once('close', () => resolve()));
  const settledOutput = async () => { await Promise.race([drained, Bun.sleep(1000)]); return output.slice(-4000); };
  const running = () => child.exitCode === null && child.signalCode === null;
  const stop = async () => {
    if (running()) child.kill('SIGTERM');
    await exited;
  };
  const timeoutMs = opts.timeoutMs ?? 60_000;
  const deadline = Date.now() + timeoutMs;
  for (;;) {
    if (!running()) {
      throw new Error(`gbrain serve --http on ${base} exited (code ${child.exitCode}, signal ${child.signalCode}) before /health answered ok. Its output:\n${await settledOutput()}`);
    }
    if ((await fetch(`${base}/health`).catch(() => null))?.ok) return { port, base, child, output: () => output, stop };
    if (Date.now() >= deadline) {
      child.kill('SIGKILL');
      await exited;
      throw new Error(`gbrain serve --http on ${base} did not answer /health ok within ${timeoutMs}ms. Its output:\n${await settledOutput()}`);
    }
    await Bun.sleep(250);
  }
}