Add a Deep Health Check Endpoint for Dependencies

オープン
#173 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 1 日以内に返信

まだ誰も着手していません。

評価

難易度
4/5
見積もり時間
3〜5日
初心者へのやさしさ
52/100
issue の種類
機能追加
明瞭さ
明確に書かれている
活発さ
活発
技術スタック
postgresql, redis, typescript

調査の方向性

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.

索引モデルが issue の本文から書いたものです。

説明

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
主要言語
TypeScript
スター
125
フォーク
23
平均マージ
2日 13時間
マージ済み PR(30日)
12

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

devarshishimpi/codra のほかの issue

devarshishimpi/codra の issue をすべて見る

似ている issue

TypeScript の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。