Description
Dots exposes two health levels for deployment and operations. /api/v1/healthz is a minimal unauthenticated liveness response mounted before authentication, allowing container probes, the desktop shell, and the credential-free local CLI to determine that the process is listening. /api/v1/health is authenticated and performs the deeper dependency and background-work inspection.
The detailed report pings the database, reads outbox backlog, reports the last sweeper pass, summarizes durable-job runner state, includes component failure trackers, and identifies the running build. Status becomes degraded when the database fails or a tracked component has failures. Local doctor consumes these signals alongside filesystem and engine facts.
Selling Points
- Separates “the process is alive” from “the application dependencies are healthy,” enabling correct supervisor decisions.
- Gives operators one structured view of database, outbox, jobs, sweeper, component, and build state.
- Keeps dependency details behind authentication while preserving a safe liveness probe for orchestration.
- Powers desktop and CLI startup polling, reducing races where a spawned daemon exists but is not ready.
- Uses live runtime facts rather than a static always-OK response.
User Story
A container platform probes /healthz during startup and routes traffic only after the API responds. An authenticated operator investigating delayed jobs calls /health and sees the database is fine but an outbox component has recorded failures and a backlog. On a laptop, dots local doctor combines the same daemon health with disk and migration evidence.
Extension Surface
This feature is automatable. packages/api/src/routes/health.ts exposes stable JSON endpoints, and packages/local-runtime/src/client/health-poll.ts demonstrates scriptable readiness polling. Supervisors and monitoring agents can consume both endpoints end to end. Components report through in-repo tracker seams, but deployments cannot register arbitrary public health schemas at runtime.
Capabilities & Limits
- Provides pre-auth liveness and authenticated deep health with clear
okordegradedstatus. - Reports database, outbox, sweeper, jobs, component trackers, and build identity.
- Supports daemon startup polling and richer local doctor diagnostics.
- Limit: liveness confirms an answering process, not that the caller is authorized or every dependency works.
- Limit: contributors omitted by a composition report explicit null/default state rather than fabricated measurements.
Implementation Map
packages/api/src/routes/health.tspackages/api/src/app.ts/healthzpackages/api/src/background.tspackages/local-runtime/src/client/health-poll.tspackages/local-runtime/src/client/operability.ts