@od-oneapp/ai-platform 0.1.0

package/src/server/routes/HEALTH_CHECK.md

@@ -0,0 +1,502 @@
+# Health Check Endpoint Pattern
+
+Production health check endpoint for deployment verification, monitoring, and load balancer integration.
+
+**Source**: Implementation based on VERCEL_AI_SDK_V6_PATTERNS.md section 5.7
+
+## Overview
+
+The health check endpoint is essential for production deployments to verify application and dependency health. It
+enables:
+
+- Kubernetes health probes (liveness, readiness, startup)
+- Monitoring and alerting systems integration
+- Load balancer health checks
+- Deployment verification (smoke tests)
+- Performance monitoring
+- Production debugging
+
+## Quick Start
+
+### Next.js 13+ Route Handler
+
+```typescript
+// app/api/health/route.ts
+import { createNextHealthCheckHandler } from "@od-oneapp/ai-platform";
+
+export const GET = createNextHealthCheckHandler({
+  enableDatabase: true,
+  enableRedis: true,
+  enableAIProvider: true,
+  enableMemory: true
+});
+```
+
+### Express.js
+
+```typescript
+// src/routes/health.ts
+import express from "express";
+import { createHealthCheckHandler } from "@od-oneapp/ai-platform";
+
+const router = express.Router();
+
+router.get(
+  "/health",
+  createHealthCheckHandler({
+    enableDatabase: true,
+    enableRedis: true,
+    enableAIProvider: true,
+    enableMemory: true
+  })
+);
+
+export default router;
+```
+
+## API
+
+### `checkHealth(config: HealthCheckConfig): Promise<HealthCheckResult>`
+
+Main function that performs comprehensive health checks.
+
+```typescript
+const result = await checkHealth({
+  enableDatabase: true,
+  enableRedis: true,
+  enableAIProvider: true,
+  enableMemory: true,
+  timeoutMs: 5000,
+  checkTimeoutMs: 2000
+});
+
+// Result includes:
+// - status: 'healthy' | 'degraded' | 'unhealthy'
+// - timestamp: ISO date string
+// - version: package version
+// - environment: NODE_ENV
+// - uptime: process uptime in seconds
+// - responseTime: health check duration in ms
+// - checks: detailed status of each component
+```
+
+### `createHealthCheckHandler(config: HealthCheckConfig): RequestHandler`
+
+Creates a handler for Express and compatible frameworks.
+
+### `createNextHealthCheckHandler(config: HealthCheckConfig): Function`
+
+Creates a handler for Next.js 13+ Route Handlers.
+
+### `createHealthCheckMiddleware(config: HealthCheckConfig): Function`
+
+Creates Express middleware that handles `/health` requests.
+
+## Health Check Components
+
+### Database Health
+
+Checks PostgreSQL connectivity and connection pool status.
+
+```typescript
+database: {
+  connected: boolean;
+  status: 'up' | 'down' | 'degraded';
+  latency?: number;
+  pool?: {
+    active: number;
+    idle: number;
+    max: number;
+  };
+  error?: string;
+}
+```
+
+**Configuration**:
+
+- `enableDatabase`: Enable/disable database checks (default: true)
+- `databaseUrl`: Database connection string (uses process.env.DATABASE_URL)
+
+### Redis Health
+
+Checks Redis connectivity and memory usage.
+
+```typescript
+redis: {
+  connected: boolean;
+  status: 'up' | 'down' | 'degraded';
+  latency?: number;
+  memory?: {
+    used_memory: number;
+    used_memory_human: string;
+  };
+  error?: string;
+}
+```
+
+**Configuration**:
+
+- `enableRedis`: Enable/disable Redis checks (default: true)
+- `redisUrl`: Redis connection string (uses process.env.REDIS_URL)
+
+### AI Provider Health
+
+Checks availability of AI model providers (OpenAI, Anthropic, Gemini, etc.).
+
+```typescript
+aiProvider: {
+  available: boolean;
+  status: 'up' | 'down' | 'degraded';
+  latency?: number;
+  providers?: {
+    openai?: boolean;
+    anthropic?: boolean;
+    gemini?: boolean;
+  };
+  error?: string;
+}
+```
+
+**Configuration**:
+
+- `enableAIProvider`: Enable/disable AI provider checks (default: true)
+- `aiGatewayUrl`: AI Gateway URL
+
+### Memory Health
+
+Monitors heap and process memory usage.
+
+```typescript
+memory: {
+  heapUsed: number; // Bytes
+  heapTotal: number; // Bytes
+  external: number; // Bytes
+  rss: number; // Resident set size in bytes
+  heapUsedPercent: number; // 0-100
+  status: "ok" | "warning" | "critical";
+}
+```
+
+**Configuration**:
+
+- `enableMemory`: Enable/disable memory checks (default: true)
+- `memoryWarningThreshold`: Heap usage percent for warning (default: 80)
+- `memoryCriticalThreshold`: Heap usage percent for critical (default: 90)
+
+## Status Levels
+
+| Status        | HTTP Code | Meaning                                             |
+| ------------- | --------- | --------------------------------------------------- |
+| **healthy**   | 200       | All critical dependencies operational               |
+| **degraded**  | 200       | Core functionality works, some features unavailable |
+| **unhealthy** | 503       | Critical dependency failure, cannot serve requests  |
+
+## Response Example
+
+```json
+{
+  "status": "healthy",
+  "timestamp": "2024-01-29T12:34:56.789Z",
+  "version": "1.0.0",
+  "environment": "production",
+  "uptime": 86400.123,
+  "responseTime": 245,
+  "checks": {
+    "database": {
+      "connected": true,
+      "status": "up",
+      "latency": 12,
+      "pool": {
+        "active": 3,
+        "idle": 2,
+        "max": 10
+      }
+    },
+    "redis": {
+      "connected": true,
+      "status": "up",
+      "latency": 5,
+      "memory": {
+        "used_memory": 1048576,
+        "used_memory_human": "1.0M"
+      }
+    },
+    "aiProvider": {
+      "available": true,
+      "status": "up",
+      "latency": 150,
+      "providers": {
+        "openai": true,
+        "anthropic": true,
+        "gemini": true
+      }
+    },
+    "memory": {
+      "heapUsed": 52428800,
+      "heapTotal": 209715200,
+      "external": 1048576,
+      "rss": 312098816,
+      "heapUsedPercent": 25.0,
+      "status": "ok"
+    }
+  }
+}
+```
+
+## Configuration Options
+
+```typescript
+interface HealthCheckConfig {
+  // Component Enablement
+  enableDatabase?: boolean;
+  enableRedis?: boolean;
+  enableAIProvider?: boolean;
+  enableMemory?: boolean;
+
+  // Custom Checks
+  customChecks?: Array<{
+    name: string;
+    check: () => Promise<ComponentHealth>;
+  }>;
+
+  // Timeouts
+  timeoutMs?: number; // Overall timeout (default: 5000ms)
+  checkTimeoutMs?: number; // Per-check timeout (default: 2000ms)
+
+  // Connection Strings
+  databaseUrl?: string;
+  redisUrl?: string;
+  aiGatewayUrl?: string;
+
+  // Memory Thresholds
+  memoryWarningThreshold?: number; // Percent (default: 80)
+  memoryCriticalThreshold?: number; // Percent (default: 90)
+
+  // Response Options
+  includeSensitiveDetails?: boolean; // Include error details (default: false)
+  version?: string; // Version to include in response
+}
+```
+
+## Usage Examples
+
+### With Custom Checks
+
+```typescript
+import { checkHealth } from "@od-oneapp/ai-platform";
+
+async function checkSearchIndex(): Promise<ComponentHealth> {
+  const response = await fetch("http://elasticsearch:9200/_cluster/health");
+  const data = await response.json();
+  return {
+    status: data.status === "green" ? "up" : "degraded",
+    available: data.status !== "red"
+  };
+}
+
+const health = await checkHealth({
+  enableDatabase: true,
+  enableRedis: true,
+  customChecks: [{ name: "elasticsearch", check: checkSearchIndex }]
+});
+```
+
+### With Monitoring Integration
+
+```typescript
+import { checkHealth } from "@od-oneapp/ai-platform";
+
+async function monitorHealth() {
+  const health = await checkHealth({
+    enableDatabase: true,
+    enableRedis: true,
+    enableAIProvider: true,
+    enableMemory: true
+  });
+
+  if (health.status === "unhealthy") {
+    // Send alert to Slack
+    await sendSlackAlert(`🚨 App Unhealthy: ${JSON.stringify(health.checks)}`);
+  }
+
+  // Send metrics to Datadog
+  await datadog.gauge("app.health.status", health.status === "healthy" ? 1 : 0);
+  await datadog.gauge("app.health.response_time", health.responseTime);
+}
+
+setInterval(monitorHealth, 30000);
+```
+
+### Kubernetes Integration
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: ai-platform
+spec:
+  template:
+    spec:
+      containers:
+        - name: app
+          image: ai-platform:latest
+
+          # Restart pod if unhealthy
+          livenessProbe:
+            httpGet:
+              path: /api/health
+              port: 3000
+            initialDelaySeconds: 30
+            periodSeconds: 10
+            timeoutSeconds: 5
+            failureThreshold: 3
+
+          # Remove from service if not ready
+          readinessProbe:
+            httpGet:
+              path: /api/health
+              port: 3000
+            initialDelaySeconds: 10
+            periodSeconds: 5
+            timeoutSeconds: 3
+            failureThreshold: 2
+```
+
+### Load Balancer Integration
+
+```nginx
+upstream ai_platform {
+    server app1:3000 max_fails=3 fail_timeout=30s;
+    server app2:3000 max_fails=3 fail_timeout=30s;
+
+    health_check uri=/api/health interval=10s fails=3 passes=2;
+}
+```
+
+## Best Practices
+
+1. **Keep Checks Fast**: Health checks should complete in <5 seconds
+2. **Use Connection Pools**: Don't create new connections for each check
+3. **Timeout Properly**: Set aggressive timeouts to prevent hanging
+4. **Return Proper Status Codes**: 503 for unhealthy (tells load balancers to stop routing)
+5. **Include Response Time**: Helps identify degrading performance
+6. **Version Information**: Helps verify correct deployment
+7. **Parallel Checks**: Run checks concurrently to minimize latency
+8. **Cache Results**: Use `cacheDurationMs` option for frequent checks
+9. **Sensitive Info**: Set `includeSensitiveDetails: false` in production
+10. **Monitor the Monitor**: Track health check latency and failures
+
+## Anti-Patterns
+
+- ❌ Long-running checks (>5 seconds)
+- ❌ Creating new DB connections per check
+- ❌ No timeout on external service checks
+- ❌ Returning 200 for unhealthy state
+- ❌ Exposing sensitive error details in production
+- ❌ Not checking critical dependencies
+- ❌ Complex business logic in health checks
+- ❌ Database transactions in health checks
+- ❌ Checking too many secondary services
+- ❌ No logging or metrics collection
+
+## Use Cases
+
+### ✅ When to Use
+
+- All production deployments
+- Containerized applications (Docker, Kubernetes)
+- Load-balanced applications
+- Applications with external dependencies (database, cache, APIs)
+- CI/CD pipelines (deployment verification)
+- Blue-green deployments (health check before routing traffic)
+- Canary deployments (verify new version health)
+- Multi-region deployments (monitor each region)
+
+### ⚠️ When to Consider
+
+- Local development (optional but recommended)
+- Monitoring and alerting integration
+- Performance tracking over time
+- Debugging production issues
+
+### ❌ When NOT to Use
+
+- Stateless functions with no dependencies
+- Single-instance deployments without monitoring
+- Applications that don't use containerization
+
+## Performance Considerations
+
+### Recommended Timeouts
+
+| Scenario         | Timeout   |
+| ---------------- | --------- |
+| Liveness probe   | 5 seconds |
+| Readiness probe  | 3 seconds |
+| Monitoring check | 5 seconds |
+| Startup probe    | 2 seconds |
+| Individual check | 2 seconds |
+
+### Optimization Tips
+
+1. **Parallel Execution**: All checks run concurrently
+2. **Connection Reuse**: Use connection pools, don't create new ones
+3. **Result Caching**: Cache results for 5-10 seconds if checking frequently
+4. **Minimal Queries**: Simple SELECT 1, PING, or connection tests only
+5. **Skip Optional Services**: Disable checks for optional dependencies
+
+## Monitoring & Alerting
+
+Track these metrics from health check responses:
+
+- `health.status`: Overall service status (1=healthy, 0=unhealthy)
+- `health.response_time_ms`: Time to complete all checks
+- `health.database.connected`: Database connectivity
+- `health.redis.connected`: Redis connectivity
+- `health.aiProvider.available`: AI provider availability
+- `health.memory.heap_percent`: Heap memory usage percentage
+- `health.uptime`: Application uptime in seconds
+
+## Troubleshooting
+
+### Health check timeout
+
+- Increase `checkTimeoutMs` or `timeoutMs` values
+- Check network connectivity to services
+- Verify service is not overloaded
+- Check database connection pool limits
+
+### Database always shows unhealthy
+
+- Verify `DATABASE_URL` environment variable is set
+- Check database credentials and network access
+- Ensure connection pool has available connections
+- Check database is running and accepting connections
+
+### High memory reported
+
+- Check memory usage in production
+- Adjust thresholds if normal memory usage is higher
+- Look for memory leaks in application code
+- Consider using memory profiling tools
+
+### Frequent unhealthy status
+
+- Check dependent services (database, Redis, AI providers)
+- Verify network connectivity
+- Check resource utilization (CPU, memory, connections)
+- Review logs for errors during health checks
+
+## Related Patterns
+
+- [Route Handlers](#5-route-handlers)
+- [Analytics & Monitoring](#20-analytics-monitoring)
+- [Error Handling](#18-error-handling)
+- [Edge Runtime Compatibility](#54-edge-runtime-compatibility)
+
+## See Also
+
+- [Kubernetes Health Probes Documentation](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/)
+- [Next.js Route Handlers](https://nextjs.org/docs/app/building-your-application/routing/route-handlers)
+- [Express.js Middleware](https://expressjs.com/en/guide/using-middleware.html)
+- [VERCEL_AI_SDK_V6_PATTERNS.md](../../VERCEL_AI_SDK_V6_PATTERNS.md)