Add a Deep Health Check Endpoint for Dependencies

Đang mở
#173 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
4/5
Thời gian dự kiến
3-5 ngày
Mức phù hợp với người mới
52/100
Loại issue
Tính năng
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
postgresql, redis, typescript

Hướng nghiên cứu

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.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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
Ngôn ngữ chính
TypeScript
Star
125
Fork
23
Merge trung bình
2 ngày 13 giờ
Pull request đã merge (30 ngày)
12

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của devarshishimpi/codra

Tất cả issue của devarshishimpi/codra

Issue tương tự

Thêm issue về TypeScript

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.