Public: anyone can read this; the crew can change it.

The forge says how it is at /api/v1/health: disk, memory, queue, stuck runs, apps asleep and previews, as one plain answer #343

shipped production is serving it opened this has it
opened this

Part of #334 (1, Observability). The forge already answers /healthz (ready or draining) for the orchestrator; nothing tells a person whether the forge itself is fine. This issue adds that answer as data. The board and the asks screen come later and read it.

Done when

  • [ ] a module src/kernel/vitals.ts (or src/core/health.ts, one concept: the forge's standing) takes the db and returns plain data: { ok, needs: string[], disk: { freeBytes, totalBytes }, memory: { rssBytes, hostFreeBytes, hostTotalBytes }, queue: { <run kind>: queued }, stuck: [{ runId, repo, issue, since }], apps: { serving, asleep, previews } , at }
  • [ ] disk is measured on the volume holding FORGE_DATA (fs.statfsSync), memory from process.memoryUsage() and os; no shelling out
  • [ ] stuck means running with a lapsed lease (leaseLapsed, STALE_AFTER_MS) or no progress past a stated bound; queue depth is one grouped query, not a query per kind
  • [ ] needs holds one short sentence per thing off (disk under 10%, a stuck run, a queue older than its bound); ok is needs.length === 0
  • [ ] GET /api/v1/health returns it to a site admin (isAdmin), session or token, ro is enough; anyone else gets 404, never the numbers; /healthz is unchanged
  • [ ] answers in well under 50 ms on the bench data: a test asserts the query count is fixed regardless of runs and apps
  • [ ] tests: shape, the admin gate, a stuck run appears in stuck and needs, a full queue appears in queue
  • [ ] docs/ARCHITECTURE.md (or docs/CONTRACT.md where the API is listed) names the route

Files: new src/kernel/vitals.ts, src/http/api.ts, src/core/runs.ts (one grouped count), tests. Risks: leaking host facts to non-admins; a slow statfs on a network volume — measure once per request, nothing cached across requests is needed yet. Brief: a server-side builder; no page work.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs