Skip to main content

Ouro AX

ax-probe

How a doctor tells a local process's state from outside it, so it answers whatever state the app is in: an HTTP endpoint that answers is up, one that takes the request and gives no answer in time is stuck, and one that refuses it is down. A person needs to know which of those it is, and "not reachable" hides it.

npx shadcn@latest add ourostack/ouro-ui/ax-probe#v1.3.344

It installs lib/ouro/ax/probe.ts, with ax-doctor. Its tests are ax-probe-tests. Every item runs on Node 22.18 or later as it is copied: the files import each other as ./<file>.ts. The Ouro AX guide shows how they fit together.

Exports

pidAlive

Whether a process with this pid runs, including one that runs as another user (the system answers EPERM). Anything but a positive whole number is no process.

function pidAlive(pid: unknown, kill?: (pid: number, signal: 0) => unknown): boolean

Example:

pidAlive(Number(readFileSync(pidFile, "utf8"))); // true while it runs

Probe

How a doctor tells a local process's state from outside it, so it answers whatever state the app is in: an HTTP endpoint that answers is up, one that takes the request and gives no answer in time is stuck, and one that refuses it is down. A person needs to know which of those it is, and "not reachable" hides it.

interface Probe {
  state: Extract<PartState, "up" | "stuck" | "down">;
  status?: number;
  body?: unknown;
}

Example:

const service = await probeHttp("http://127.0.0.1:5180/health", { timeoutMs: 1500 });
// { state: "up", status: 200, body: { ok: true } }, { state: "stuck" } or { state: "down" }

probeHttp

GETs url with a time limit: "up" with its status, and its JSON when the answer is JSON; "stuck" when no answer came in timeoutMs, or the headers came and the rest of the answer didn't; "down" when the request failed without an answer, as when nothing listens on the port. On a local port, stuck means the process took the connection and never answered.

function probeHttp(url: string, { timeoutMs, fetchImpl, headers }?: ProbeOptions): Promise<Probe>

Example:

const asked = await probeHttp(`${serviceUrl}/api/doctor`, { timeoutMs: 8000 });
if (asked.state === "up" && isDoctorReport(asked.body)) return asked.body;

ProbeOptions

interface ProbeOptions {
  timeoutMs?: number;
  fetchImpl?: typeof fetch;
  headers?: Record<string, string>;
}