feat(reliability): separate liveness and readiness checks for deployment-safe health monitoring #892

[doctorlight0]

Overview

This PR separates liveness and readiness checks for deployment-safe health monitoring, so orchestrators can distinguish a running process from one that is ready to serve dependent services. It adds a dependency-free liveness endpoint and a readiness endpoint that verifies PostgreSQL and Redis capabilities with bounded timeouts — returning a non-2xx status when essential dependencies are unavailable while keeping responses free of credentials, connection strings, and stack traces.

Related Issue

Closes #892

Changes

Health Monitoring

• [ADD] backend/src/db/readinessMonitor.ts

  • Runs database SELECT 1 and Redis PING in parallel with bounded timeouts (HEALTH_READINESS_TIMEOUT_MS, default 3000ms).
  • Sanitized per-dependency results (ready / unavailable); full error details are logged server-side only.

• [MODIFY] backend/src/routes/health.routes.ts

  • Adds GET /live and GET /ready (also available under /api/v1/health) with OpenAPI docs.
  • GET /health/live — liveness probe with zero dependency calls, returns 200 while the process is alive.
  • GET /health/ready — readiness probe, returns 503 when database or Redis is unavailable.

• [MODIFY] backend/src/index.ts

  • Registers root-level GET /health/live and GET /health/ready probes.

• [MODIFY] Docker healthchecks — docker-compose.yml and backend/Dockerfile

  • Healthchecks now target /health/ready so containers are only marked healthy once dependencies are reachable.

• [ADD] docs/deployment/HEALTH_PROBES.md

  • Probe configuration for Docker Compose, Dockerfile, Kubernetes, Render, Fly.io, Heroku, and Railway.

• [MODIFY] backend/src/services/storage/queue.ts

  • Removes a duplicate const redisUrl declaration that was a syntax error on main and broke the health test suite.

Tests

• [MODIFY] backend/tests/health.test.ts

  • Integration tests for /health, /health/live (success, no dependency calls), and /health/ready (ready, dependency failure, no credential leakage).

• [ADD] backend/tests/readinessMonitor.test.ts

  • Unit tests covering ready state, database failure, Redis failure, disconnected client, timeout, and error sanitization.

Verification Results

npx jest --runInBand --forceExit tests/health.test.ts tests/readinessMonitor.test.ts
Test Suites: 2 passed, 2 total
Tests:       16 passed, 16 total

✅ Liveness returns 200 without any dependency calls
✅ Readiness returns 503 when database/Redis unavailable
✅ Responses avoid credentials, connection strings, and stack traces
✅ Full backend suite runs the previously-broken health test suite

Acceptance Criteria	Status
Liveness remains fast and succeeds while the process is alive	✅ dependency-free, returns 200
Readiness fails when required dependencies are unavailable or unhealthy	✅ returns 503 with per-dependency status
Responses avoid credentials, connection strings, and internal stack traces	✅ sanitized messages only
Health routes have automated success and dependency-failure tests	✅ 16 tests covering success, failure, timeout
Deployment documentation includes probe examples	✅ docs/deployment/HEALTH_PROBES.md

[vercel]

@glorious21-coder is attempting to deploy a commit to the Ayomide Adeniran's projects Team on Vercel.

A member of the Team first needs to authorize it.

[drips-wave]

@doctorlight0 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[ayomideadeniran]

pr under review