Harden gateway CLI lifecycle

Author: CharGrnmn

apps/gateway/src/index.test.ts

@@ -14,10 +14,29 @@ import {
   createGatewayRequestHandler,
   createGatewayServer,
   parseCliArgs,
+  runGatewayCli,
   startGateway,
   stopGateway,
 } from "./index.js";
 
+function createTestIo() {
+  let stderr = "";
+
+  return {
+    io: {
+      stderr: {
+        write(chunk: string | Uint8Array) {
+          stderr += String(chunk);
+          return true;
+        },
+      },
+    },
+    get stderr() {
+      return stderr;
+    },
+  };
+}
+
 async function closeServer(server: Server): Promise<void> {
   await new Promise<void>((resolve, reject) => {
     server.close((error) => {
@@ -183,6 +202,10 @@ test("gateway rejects invalid direct helper options", async () => {
     () => startGateway({ config, configPath: 42 } as never),
     /configPath must be a string/,
   );
+  await assert.rejects(
+    () => startGateway({ config, configPath: "ray\0config.json" } as never),
+    /configPath must not contain control characters/,
+  );
   await assert.rejects(
     () => startGateway({ config, warmupRetry: null } as never),
     /warmupRetry must be an object/,
@@ -521,6 +544,103 @@ test("gateway parseCliArgs rejects ambiguous or malformed options", () => {
   assert.throws(() => parseCliArgs(["--config", 42] as unknown as string[]), /argv\[1\]/);
 });
 
+test("runGatewayCli rejects malformed direct io and options before boot", async () => {
+  const output = createTestIo();
+
+  await assert.rejects(() => runGatewayCli([], null as never), /gateway cli io must be an object/);
+  await assert.rejects(
+    () => runGatewayCli([], { stderr: {} } as never),
+    /gateway cli io\.stderr\.write must be a function/,
+  );
+  await assert.rejects(
+    () => runGatewayCli([], output.io, null as never),
+    /gateway cli options must be an object/,
+  );
+  await assert.rejects(
+    () => runGatewayCli([], output.io, { loadConfig: null } as never),
+    /loadConfig must be a function/,
+  );
+  await assert.rejects(
+    () => runGatewayCli([], output.io, { cwd: " /srv/ray" }),
+    /cwd must be a path without surrounding whitespace/,
+  );
+});
+
+test("runGatewayCli reports boot failures to injected stderr", async () => {
+  const output = createTestIo();
+  const status = await runGatewayCli(["--config", "./missing.json"], output.io, {
+    now: () => new Date("2026-05-14T00:00:00.000Z"),
+    loadConfig: async () => {
+      throw new Error("missing config");
+    },
+  });
+
+  assert.equal(status, 1);
+  const parsed = JSON.parse(output.stderr) as {
+    ts?: string;
+    level?: string;
+    message?: string;
+    error?: { message?: string };
+  };
+  assert.equal(parsed.ts, "2026-05-14T00:00:00.000Z");
+  assert.equal(parsed.level, "error");
+  assert.equal(parsed.message, "gateway boot failed");
+  assert.equal(parsed.error?.message, "missing config");
+});
+
+test("runGatewayCli starts the gateway and wires signal shutdown", async () => {
+  const output = createTestIo();
+  const config = createDefaultConfig("tiny");
+  const signals = new Map<NodeJS.Signals, () => void>();
+  const exitCodes: number[] = [];
+  const stoppedSignals: Array<NodeJS.Signals | undefined> = [];
+  const fakeGateway = {
+    logger: {
+      error() {
+        throw new Error("shutdown should not log errors");
+      },
+    },
+  } as never;
+
+  const status = await runGatewayCli(["--config", "./ray.json"], output.io, {
+    cwd: "/srv/ray",
+    loadConfig: async (options) => {
+      assert.deepEqual(options, {
+        cwd: "/srv/ray",
+        configPath: "./ray.json",
+      });
+      return {
+        config,
+        configPath: "/srv/ray/ray.json",
+      };
+    },
+    startGateway: async (options) => {
+      assert.equal(options.config, config);
+      assert.equal(options.configPath, "/srv/ray/ray.json");
+      return fakeGateway;
+    },
+    stopGateway: async (_gateway, options) => {
+      stoppedSignals.push(options?.signal);
+    },
+    onSignal: (signal, listener) => {
+      signals.set(signal, listener);
+    },
+    setExitCode: (code) => {
+      exitCodes.push(code);
+    },
+  });
+
+  assert.equal(status, 0);
+  assert.equal(output.stderr, "");
+  assert.deepEqual(Array.from(signals.keys()), ["SIGINT", "SIGTERM"]);
+
+  signals.get("SIGTERM")?.();
+  await new Promise((resolve) => setTimeout(resolve, 0));
+
+  assert.deepEqual(stoppedSignals, ["SIGTERM"]);
+  assert.deepEqual(exitCodes, [0]);
+});
+
 test("startGateway rejects malformed warmup retry options before listening", async () => {
   await assert.rejects(
     () =>

apps/gateway/src/index.ts

@@ -31,6 +31,22 @@ interface CliOptions {
   configPath?: string;
 }
 
+interface GatewayCliIo {
+  stderr: {
+    write(chunk: string | Uint8Array): unknown;
+  };
+}
+
+interface RunGatewayCliOptions {
+  cwd?: string;
+  loadConfig?: typeof loadRayConfig;
+  startGateway?: typeof startGateway;
+  stopGateway?: typeof stopGateway;
+  onSignal?: (signal: NodeJS.Signals, listener: () => void) => unknown;
+  setExitCode?: (code: number) => void;
+  now?: () => Date;
+}
+
 const MAX_GATEWAY_CLI_ARGS = 16;
 const MAX_GATEWAY_CLI_ARG_BYTES = 8_192;
 const MAX_GATEWAY_CONFIG_PATH_CHARS = 4_096;
@@ -84,6 +100,15 @@ const startGatewayOptionKeys = new Set([
   "configPath",
   "warmupRetry",
 ]);
+const runGatewayCliOptionKeys = new Set([
+  "cwd",
+  "loadConfig",
+  "startGateway",
+  "stopGateway",
+  "onSignal",
+  "setExitCode",
+  "now",
+]);
 const gatewayWarmupRetryOptionKeys = new Set(["initialDelayMs", "maxDelayMs"]);
 const stopGatewayOptionKeys = new Set(["signal", "timeoutMs"]);
 const acknowledgedExpectContinueRequests = new WeakSet<IncomingMessage>();
@@ -206,6 +231,56 @@ function assertOptionalGatewayFunction(value: unknown, label: string): void {
   }
 }
 
+function assertGatewayCliIo(io: unknown): asserts io is GatewayCliIo {
+  if (io === null || typeof io !== "object" || Array.isArray(io)) {
+    throw new Error("gateway cli io must be an object");
+  }
+
+  const stderr = (io as { stderr?: unknown }).stderr;
+  if (
+    stderr === null ||
+    typeof stderr !== "object" ||
+    Array.isArray(stderr) ||
+    typeof (stderr as { write?: unknown }).write !== "function"
+  ) {
+    throw new Error("gateway cli io.stderr.write must be a function");
+  }
+}
+
+function assertGatewayCliPathValue(value: unknown, label: string): asserts value is string {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`${label} must be a non-empty path`);
+  }
+
+  if (/[\0\r\n]/.test(value)) {
+    throw new Error(`${label} must not contain control characters`);
+  }
+
+  if (value.trim() !== value) {
+    throw new Error(`${label} must be a path without surrounding whitespace`);
+  }
+
+  if (value.length > MAX_GATEWAY_CONFIG_PATH_CHARS) {
+    throw new Error(`${label} must be at most ${MAX_GATEWAY_CONFIG_PATH_CHARS} characters`);
+  }
+}
+
+function assertRunGatewayCliOptions(value: unknown): asserts value is RunGatewayCliOptions {
+  assertGatewayOptionsObject(value, "gateway cli options");
+  assertGatewayOptionKeys(value, "gateway cli options", runGatewayCliOptionKeys);
+
+  if (value.cwd !== undefined) {
+    assertGatewayCliPathValue(value.cwd, "cwd");
+  }
+
+  assertOptionalGatewayFunction(value.loadConfig, "loadConfig");
+  assertOptionalGatewayFunction(value.startGateway, "startGateway");
+  assertOptionalGatewayFunction(value.stopGateway, "stopGateway");
+  assertOptionalGatewayFunction(value.onSignal, "onSignal");
+  assertOptionalGatewayFunction(value.setExitCode, "setExitCode");
+  assertOptionalGatewayFunction(value.now, "now");
+}
+
 function assertGatewayHandlerDependencies(value: Record<string, unknown>): void {
   assertGatewayOptionsObject(value.config, "config");
   assertOptionalGatewayObject(value.runtime, "runtime");
@@ -765,7 +840,7 @@ function requireFlagValue(flag: string, value: string | undefined): string {
 }
 
 function assertConfigPathFlagValue(value: string, flag: string): void {
-  if (/[\r\n]/.test(value)) {
+  if (/[\0\r\n]/.test(value)) {
     throw new Error(`${flag} must not contain control characters`);
   }
 
@@ -2368,49 +2443,75 @@ export async function stopGateway(
   }
 }
 
-async function main(): Promise<void> {
-  const cli = parseCliArgs(process.argv.slice(2));
-  const { config, configPath } = await loadRayConfig({
-    cwd: process.cwd(),
-    ...(cli.configPath ? { configPath: cli.configPath } : {}),
-  });
+export async function runGatewayCli(
+  argv: string[] = process.argv.slice(2),
+  io: GatewayCliIo = process,
+  options: RunGatewayCliOptions = {},
+): Promise<number> {
+  assertGatewayCliIo(io);
+  assertRunGatewayCliOptions(options);
 
-  const gateway = await startGateway({
-    config,
-    ...(configPath ? { configPath } : {}),
-  });
+  const loadConfig = options.loadConfig ?? loadRayConfig;
+  const start = options.startGateway ?? startGateway;
+  const stop = options.stopGateway ?? stopGateway;
+  const onSignal =
+    options.onSignal ??
+    ((signal: NodeJS.Signals, listener: () => void) => {
+      process.on(signal, listener);
+    });
+  const setExitCode =
+    options.setExitCode ??
+    ((code: number) => {
+      process.exitCode = code;
+    });
+  const now = options.now ?? (() => new Date());
 
-  const shutdown = async (signal: NodeJS.Signals) => {
-    try {
-      await stopGateway(gateway, { signal });
-      process.exit(0);
-    } catch (error) {
-      gateway.logger.error("gateway shutdown failed", {
-        signal,
-        error: serializeError(error),
-      });
-      process.exit(1);
-    }
-  };
+  try {
+    const cli = parseCliArgs(argv);
+    const { config, configPath } = await loadConfig({
+      cwd: options.cwd ?? process.cwd(),
+      ...(cli.configPath ? { configPath: cli.configPath } : {}),
+    });
 
-  process.on("SIGINT", () => {
-    void shutdown("SIGINT");
-  });
-  process.on("SIGTERM", () => {
-    void shutdown("SIGTERM");
-  });
-}
+    const gateway = await start({
+      config,
+      ...(configPath ? { configPath } : {}),
+    });
 
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
-  void main().catch((error) => {
-    console.error(
-      JSON.stringify({
-        ts: new Date().toISOString(),
+    const shutdown = async (signal: NodeJS.Signals) => {
+      try {
+        await stop(gateway, { signal });
+        setExitCode(0);
+      } catch (error) {
+        gateway.logger.error("gateway shutdown failed", {
+          signal,
+          error: serializeError(error),
+        });
+        setExitCode(1);
+      }
+    };
+
+    onSignal("SIGINT", () => {
+      void shutdown("SIGINT");
+    });
+    onSignal("SIGTERM", () => {
+      void shutdown("SIGTERM");
+    });
+
+    return 0;
+  } catch (error) {
+    io.stderr.write(
+      `${JSON.stringify({
+        ts: now().toISOString(),
         level: "error",
         message: "gateway boot failed",
         error: serializeError(error),
-      }),
+      })}\n`,
     );
-    process.exit(1);
-  });
+    return 1;
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  process.exitCode = await runGatewayCli();
 }

scripts/cli-entrypoints.test.ts

@@ -4,15 +4,16 @@ import path from "node:path";
 import test from "node:test";
 
 const repoRoot = process.cwd();
-const maintenanceCliEntrypoints = [
+const embeddableCliEntrypoints = [
+  "apps/gateway/src/index.ts",
   "scripts/deploy-storage-preflight.ts",
   "scripts/docs-link-check.ts",
   "scripts/package-runtime-coverage.ts",
   "scripts/test.mjs",
 ];
 
-test("maintenance CLI entrypoints avoid abrupt process exits", async () => {
-  for (const relativePath of maintenanceCliEntrypoints) {
+test("embeddable CLI entrypoints avoid abrupt process exits", async () => {
+  for (const relativePath of embeddableCliEntrypoints) {
     const contents = await readFile(path.join(repoRoot, relativePath), "utf8");
 
     assert.doesNotMatch(contents, /\bprocess\.exit\s*\(/, relativePath);