feat: add request correlation, health checks, and graceful shutdown

[Unclebaffa]

Summary

I've successfully implemented request correlation, health checks, and graceful shutdown for the Learnault API. Here's what was delivered:

✅ Completed Features

1. Request Context Middleware (src/middleware/request-context.ts)

• Generates or validates request IDs (UUID format)
• Attaches actor context from authenticated users (without secrets)
• Tracks request timing and duration
• Logs request completion with correlation data
• Returns request ID in response headers

2. Health Check Routes (src/routes/health.routes.ts)

• /health/live - Liveness probe (process running check)
• /health/ready - Readiness probe (dependency health check with database connectivity)
• Returns appropriate HTTP status codes (200 for healthy, 503 for not ready)
• Includes timestamp and detailed check results

3. Graceful Shutdown (src/server.ts)

• Handles SIGTERM, SIGINT, uncaught exceptions, and unhandled rejections
• Stops HTTP server from accepting new connections
• Clears background job intervals (lifecycle sweep)
• Disconnects database connections properly
• Enforces configurable timeout (default 30s)
• Prevents duplicate shutdown processing

4. Enhanced Logging (src/config/logger.ts)

• JSON format for production (better for log aggregation)
• Human-readable format for development
• Automatic error stack trace capture
• Request correlation support
• Configurable log levels via environment variable

5. Updated Error Middleware (src/middleware/error.middleware.ts)

• Includes request ID in all error responses
• Logs errors with actor and correlation context
• Maintains existing error handling behavior

✅ Test Coverage

• 17 tests for request context middleware
• 9 tests for health routes
• 6 tests for graceful shutdown
• All existing tests pass: 423 passed, 3 skipped
• Zero linting errors
• Build successful

✅ Configuration Added

# .env.example updated with:
LOG_LEVEL=info
SHUTDOWN_TIMEOUT_MS=30000

✅ Test Scripts Created

• scripts/test-health.bat (Windows)
• scripts/test-health.sh (Unix/Linux)

✅ Documentation

• Comprehensive implementation summary created
• Kubernetes and Docker Compose usage examples
• Log correlation examples

✅ Verification

• Build passes
• All tests pass
• ESLint passes
• Request ID propagation works
• Readiness reflects database dependency
• Shutdown completes within deadline
• Logs are correlatable
• Changes committed to git

All acceptance criteria met and ready for deployment! 🚀

Closes #62