Add a Deep Health Check Endpoint for Dependencies

Aperta
#173 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
52/100
Tipo di issue
Funzionalità
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
postgresql, redis, typescript

Direzione di ricerca

Start with packages/api/src/router.ts lines 58–61 and trace how the apps/worker and apps/node runtime adapters access PostgreSQL and KV or Redis. Then check the existing deployment documentation, Docker Compose configuration, and health check tests. Done means both runtimes expose /health/ready with bounded dependency probes, structured healthy or failed responses, and updated deployment guidance and tests.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

enhancement good first issue

Summary

The existing GET /health endpoint returns { "status": "ok" } unconditionally without testing any infrastructure dependency. In a Docker or Kubernetes deployment, if PostgreSQL crashes or Redis becomes unreachable, Codra's health probe continues to return HTTP 200 OK, preventing orchestrators from detecting the failure and restarting the container.

Affected File

packages/api/src/router.ts lines 58-61:

// Machine health check - no session required
app.get("/health", (c) =>
  c.json({ status: "ok", timestamp: new Date().toISOString() }),
);

Proposed Changes

Add a /health/ready endpoint (or extend /health?deep=1) that performs lightweight dependency probes:

  • PostgreSQL: SELECT 1
  • Redis/KV (Node runtime only): PING command via ioredis
  • Cloudflare KV (Workers runtime only): get("__health_check__") - expected to return null, not an error

Return HTTP 200 only when all required dependencies respond. Return HTTP 503 Service Unavailable with a structured JSON body when any required dependency fails:

{
  "status": "unhealthy",
  "timestamp": "2026-11-17T16:30:00.000Z",
  "checks": {
    "database": { "status": "failed", "error": "Connection refused" },
    "kv": { "status": "ok" },
    "queue": { "status": "unavailable" }
  }
}

Keep the existing GET /health as a lightweight liveness probe (process is alive, no DB calls). Add /health/ready as the readiness probe (dependencies are reachable).

Implementation Notes

  • Probe logic should live in the runtime platform adapter (apps/worker and apps/node) since KV, Redis, and PostgreSQL clients differ between runtimes
  • Keep probe timeouts short (1-2 seconds) so a slow probe does not block the health check response indefinitely
  • Do not log individual health check requests to avoid flooding production logs
  • Do not expose sensitive connection strings or credentials in the response body

Kubernetes / Docker Config Examples

# docker-compose.yml healthcheck
healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:3000/health/ready"]
  interval: 30s
  timeout: 5s
  retries: 3
  start_period: 10s
# Kubernetes readinessProbe
readinessProbe:
  httpGet:
    path: /health/ready
    port: 3000
  initialDelaySeconds: 10
  periodSeconds: 15

Done When

  • GET /health (liveness) continues to return 200 OK without touching any infrastructure
  • GET /health/ready (readiness) performs a SELECT 1 probe on PostgreSQL and a KV/Redis ping
  • Returns HTTP 503 with structured JSON when any required dependency is down
  • The readiness probe works in both Cloudflare Workers and Node/Docker runtimes
  • No credentials or secrets appear in the health check response body
  • docker-compose.yml and deployment documentation are updated with the new probe path
  • Tests cover healthy, partial-failure, and fully-down states
  • npm run typecheck, npm test, and npm run lint all pass
Lingua principale
TypeScript
Stelle
125
Fork
23
Merge medio
2g 13h
PR unite (30g)
12

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di devarshishimpi/codra

Tutte le issue di devarshishimpi/codra

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.