<!-- Generated by scripts/ax-docs.mts from the JSDoc in registry/ouro/ax/. Do not edit; run `pnpm run docs`. -->

# 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.

```sh
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](ax.md) 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.

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

Example:

```ts
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.

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

Example:

```ts
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.

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

Example:

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

### `ProbeOptions`

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