Never stop coding. Free MIT AI gateway: one endpoint, 375 providers (150+ free), 1,400+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 900+ contributors
TypeScript a2aai-agentsai-gatewayanthropicclaudeclaude-codeclinecodexcopilotcursordeepseekfree-aigeminikimillm-gatewaymcpopenaiopenai-proxyqwentoken-saver
/**
* Pre-spawn port/health probe for embedded services (#6205).
*
* Before the supervisor spawns a service child, it probes the service's port
* and health endpoint. This turns two failure modes into graceful outcomes
* instead of a raw `EADDRINUSE` stack trace crashing the child:
*
* - A healthy prior instance is already answering → ADOPT it (skip spawn).
* - The port is held but nothing healthy answers → surface a CLEAR error.
* - The port is free → SPAWN normally.
*
* `decidePreSpawn` is a pure function so the decision logic is unit-testable
* without binding a real port or spawning a process.
*/
import { createConnection } from "node:net";
import { spawn } from "node:child_process";
import os from "node:os";
/** Result of probing the service before spawning. */
export interface PreSpawnProbe {
/** true when the service's healthUrl answered with a 2xx. */
healthy: boolean;
/** true when something is already listening on the service's port. */
portInUse: boolean;
}
/** Outcome of the pre-spawn decision. */
export type PreSpawnDecision =
{ action: "spawn" } | { action: "adopt" } | { action: "error"; message: string };
const HEALTH_PROBE_TIMEOUT_MS = 3_000;
const PORT_PROBE_TIMEOUT_MS = 1_000;
const PID_RESOLVE_TIMEOUT_MS = 2_000;
/**
* Decide what to do before spawning, given a probe of the port + health.
*
* Pure — no I/O — so it can be exhaustively unit-tested.
*/
export function decidePreSpawn(
probe: PreSpawnProbe,
port: number,
allowAdopt = false
): PreSpawnDecision {
if (probe.healthy) {
// A 2xx on the health path does NOT prove the listener is our service: a
// local process can squat the port, answer 200, and get adopted — receiving
// the injected service API key and script execution inside the dashboard
// origin (GHSA-wg9p-6m2g-4v27). Adopt an already-healthy listener only when
// the operator explicitly opts in; otherwise surface the same actionable
// error we already use for a held-but-unhealthy port instead of silently
// trusting the listener.
if (allowAdopt) {
return { action: "adopt" };
}
return {
action: "error",
message:
`Port ${port} is already serving a healthy response, but adopting an ` +
`existing listener is disabled by default (a 2xx cannot prove the listener ` +
`is this service). Set OMNIROUTE_ADOPT_EXISTING_SERVICE=1 to allow adoption, ` +
`or stop the process holding the port and start the service again.`,
};
}
// Port is held but nothing healthy answers: an orphaned or unrelated process
// is squatting on it. Surface a clear, actionable error instead of letting
// the child crash with a raw EADDRINUSE stack.
if (probe.portInUse) {
return {
action: "error",
message:
`Port ${port} is already in use but the service did not respond to a health ` +
`check. An orphaned previous instance or an unrelated process may be holding ` +
`the port — stop it (or free the port) and try starting the service again.`,
};
}
// Port is free and nothing is answering — safe to spawn.
return { action: "spawn" };
}
/**
* Whether the operator opted in to adopting an already-healthy listener on a
* service port. Off by default (GHSA-wg9p-6m2g-4v27): a squatter can answer a
* 2xx, so auto-adoption is only safe when the operator knows the listener is
* genuinely their (externally-managed) instance.
*/
export function isAdoptExistingEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
const v = env.OMNIROUTE_ADOPT_EXISTING_SERVICE;
return v === "1" || v === "true";
}
/** TCP connect check: resolves true when something accepts a connection. */
function isPortInUse(port: number, timeoutMs: number): Promise<boolean> {
return new Promise<boolean>((resolve) => {
const socket = createConnection({ host: "127.0.0.1", port }, () => {
socket.destroy();
resolve(true);
});
socket.setTimeout(timeoutMs);
socket.on("error", () => resolve(false));
socket.on("timeout", () => {
socket.destroy();
resolve(false);
});
});
}
/** Health check: resolves true when healthUrl answers with a 2xx. */
async function isHealthy(healthUrl: string, timeoutMs: number): Promise<boolean> {
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), timeoutMs);
try {
const res = await fetch(healthUrl, { signal: controller.signal });
return res.ok;
} catch {
return false;
} finally {
clearTimeout(timeout);
}
}
/**
* Probe the service's port + health endpoint before spawning.
*
* @param healthUrl The service's health endpoint URL.
* @param port The service's registered port.
*/
export async function probeBeforeSpawn(healthUrl: string, port: number): Promise<PreSpawnProbe> {
const [healthy, portInUse] = await Promise.all([
isHealthy(healthUrl, HEALTH_PROBE_TIMEOUT_MS),
isPortInUse(port, PORT_PROBE_TIMEOUT_MS),
]);
return { healthy, portInUse };
}
/** `lsof -ti :PORT` prints one pid per line and nothing else. */
export function parseLsofPid(stdout: string): number | null {
const firstLine = stdout
.split("\n")
.map((line) => line.trim())
.find((line) => line.length > 0);
const parsed = firstLine ? Number.parseInt(firstLine, 10) : Number.NaN;
return Number.isFinite(parsed) ? parsed : null;
}
/**
* `ss -tlnp 'sport = :PORT'` carries the pid inside the process column:
*
* LISTEN 0 511 127.0.0.1:20128 0.0.0.0:* users:(("node",pid=596922,fd=18))
*
* The filter is applied by `ss` itself, so any `pid=` on any line belongs to
* the requested port.
*/
export function parseSsPid(stdout: string): number | null {
const match = /\bpid=(\d+)/.exec(stdout);
const parsed = match ? Number.parseInt(match[1], 10) : Number.NaN;
return Number.isFinite(parsed) ? parsed : null;
}
/**
* `netstat -tlnp` cannot filter by port, so the port is matched here:
*
* tcp 0 0 127.0.0.1:20128 0.0.0.0:* LISTEN 596922/node
*
* Matching on the local-address column keeps a foreign address that happens to
* end in the same number from being read as a listener.
*/
export function parseNetstatPid(stdout: string, port: number): number | null {
for (const line of stdout.split("\n")) {
const columns = line.trim().split(/\s+/);
// Linux: proto recv-q send-q local-address foreign-address state pid/program
if (columns.length < 7 || columns[5] !== "LISTEN") continue;
const linuxAddress = columns[3].endsWith(`:${port}`);
const macAddress = columns[3].endsWith(`.${port}`);
if (!linuxAddress && !macAddress) continue;
if (linuxAddress) {
const linuxPid = Number.parseInt(columns[6], 10);
if (Number.isFinite(linuxPid)) return linuxPid;
}
// macOS `netstat -anv -p tcp` appends a `process:pid` column after
// the socket counters. Process names may contain spaces, so scan instead
// of relying on one fixed column index.
for (const column of columns.slice(6)) {
const match = /:(\d+)$/.exec(column);
if (match) return Number.parseInt(match[1], 10);
}
}
return null;
}
/**
* Windows `netstat -ano` carries the pid in its own last column (#11236):
*
* Proto Local Address Foreign Address State PID
* TCP 0.0.0.0:20128 0.0.0.0:0 LISTENING 12345
* TCP [::]:20128 [::]:0 LISTENING 12345
*
* Only TCP LISTENING rows carry a pid (UDP rows have no state column at all).
* The local address is matched on `:<port>` — the `:` anchor keeps a port that
* merely shares a suffix (128 vs 20128) or a foreign address ending in the
* same digits from being read as the listener.
*/
export function parseWindowsNetstatPid(stdout: string, port: number): number | null {
for (const line of stdout.split("\n")) {
const columns = line.trim().split(/\s+/);
// proto local-address foreign-address state pid
if (columns.length < 5) continue;
if (columns[3].toUpperCase() !== "LISTENING") continue;
if (!columns[1].endsWith(`:${port}`)) continue;
const pid = Number.parseInt(columns[columns.length - 1], 10);
if (Number.isFinite(pid)) return pid;
}
return null;
}
/**
* Ways to ask the OS which process holds a port, in preference order.
*
* `lsof` stays first because it is the most direct, but it is absent from slim
* container images, and a missing binary is indistinguishable from a free port
* once `spawn` has turned ENOENT into a null. `ss` ships with iproute2 and
* `netstat` with net-tools, so between the three there is normally something
* to ask on any host the supervisor runs on.
*
* The Windows `netstat -ano` probe runs last: on Windows the earlier probes
* fail fast (lsof/ss do not exist; the net-tools flags are rejected by the
* Windows netstat), while on Unix `netstat -ano` either errors out or prints
* the Linux/macOS row shapes the Windows parser deliberately never matches
* (LISTEN vs LISTENING), so it degrades to a no-op instead of a false pid.
*/
export const PID_PROBES: ReadonlyArray<{
command: string;
args: (port: number) => string[];
parse: (stdout: string, port: number) => number | null;
}> = [
// #14722: listeners only, matching the win32/ss/netstat LISTEN filters and omniroute stop (#14605).
// A bare `lsof -ti :PORT` also returns every client connected to the port (for example a browser
// tab on the dashboard, a Docker/VM port forward, or an SSH tunnel), which can cause the supervisor
// to kill the client or track the wrong pid when adopting.
{
command: "lsof",
args: (port) => ["-nP", "-t", `-iTCP:${port}`, "-sTCP:LISTEN"],
parse: (stdout) => parseLsofPid(stdout),
},
{
command: "ss",
args: (port) => ["-tlnp", `sport = :${port}`],
parse: (stdout) => parseSsPid(stdout),
},
{
command: "netstat",
// #11236: runtime os.platform() read — a process.platform literal is
// constant-folded to the Linux build machine in the published artifact,
// pruning the darwin branch on macOS (same fold class as b43a212680).
args: () => (os.platform() === "darwin" ? ["-anv", "-p", "tcp"] : ["-tlnp"]),
parse: parseNetstatPid,
},
{
command: "netstat",
args: () => ["-ano"],
parse: parseWindowsNetstatPid,
},
];
/** Run one probe, resolving null on a missing binary, a non-match or a timeout. */
function runPidProbe(
probe: (typeof PID_PROBES)[number],
port: number,
timeoutMs: number
): Promise<number | null> {
return new Promise((resolve) => {
if (timeoutMs <= 0) {
resolve(null);
return;
}
const proc = spawn(probe.command, probe.args(port));
let output = "";
let settled = false;
const finish = (value: number | null) => {
if (settled) return;
settled = true;
clearTimeout(timeout);
resolve(value);
};
const timeout = setTimeout(() => {
proc.kill();
finish(null);
}, timeoutMs);
proc.stdout?.on("data", (chunk: Buffer) => {
output += chunk.toString("utf8");
});
// ENOENT when the binary is not installed — fall through to the next probe.
proc.on("error", () => finish(null));
proc.on("close", () => finish(probe.parse(output, port)));
});
}
/**
* Resolve the pid of whatever process is listening on `port`, if any.
*
* Used when adopting an already-healthy instance (see `decidePreSpawn`'s
* "adopt" outcome): the supervisor didn't spawn that process itself, so it
* has no pid from a `ChildProcess` handle, but tracking a real pid is still
* needed for downstream liveness checks to trust an adopted service the same
* way they trust a freshly-spawned one. Returns null if nothing is found or
* the lookup fails/times out (best-effort; never blocks adoption on this).
*
* Tries `lsof`, then `ss`, then `netstat`, then the Windows `netstat -ano`
* shape, so a host missing any one of them — including a stock Windows host
* with none of the Unix tools — still reports a real pid instead of a silent
* null (#10431, #11236). The probes share one deadline, so the whole lookup
* still costs at most `PID_RESOLVE_TIMEOUT_MS`.
*/
export async function resolvePortPid(port: number): Promise<number | null> {
const deadline = Date.now() + PID_RESOLVE_TIMEOUT_MS;
for (const probe of PID_PROBES) {
const pid = await runPidProbe(probe, port, deadline - Date.now());
if (pid !== null) return pid;
}
return null;
}