cube-ms/IMPROVEMENTS.md

Production-ready microservice framework with health monitoring, validation, error handling, and Docker Swarm support

# Framework Improvements - High Priority Features

This document outlines the high-priority improvements added to the Cube Microservice framework for production readiness.

## 🔧 1. Connection Pooling Singleton

**Problem Solved:** Multiple MongoDB connections were created per service call, leading to resource waste and connection limits.

**Implementation:** `src/db_connection_manager.js`

### Features:
- **Singleton Pattern**: One connection pool per database URL
- **Connection Reuse**: Efficient connection pooling across services
- **Health Monitoring**: Built-in connection health checks
- **Graceful Cleanup**: Proper connection closure on shutdown

### Usage:
```javascript
import connectionManager from './src/db_connection_manager.js';

// Get connection (creates if not exists, reuses if exists)
const client = await connectionManager.getClient('mongodb://localhost:27017');

// Connection info
console.log('Active connections:', connectionManager.getConnectionCount());
```

---

## 🛡️ 2. Error Handling & Graceful Shutdown

**Problem Solved:** Poor error handling, abrupt shutdowns, and unhandled promise rejections.

**Implementation:** 
- `src/error_handler.js` - Error types and global handlers
- `src/graceful_shutdown.js` - Coordinated shutdown process

### Error Types:
```javascript
import { ValidationError, DatabaseError, ServiceUnavailableError, TimeoutError } from 'cube-ms';

// Custom error handling
throw new ValidationError("Invalid email format", "email");
throw new DatabaseError("Connection failed", originalError);
```

### Graceful Shutdown Features:
- **Signal Handling**: SIGTERM, SIGINT, SIGUSR2 support
- **Connection Tracking**: Monitor active HTTP connections  
- **Staged Shutdown**: Ordered cleanup process
- **Timeout Protection**: Force exit if shutdown hangs
- **PM2 Support**: Handle PM2 reload signals

### Usage:
```javascript
const service = CreateService({ port: 3000 });

// Manual shutdown
service.shutdown();

// Check if shutting down
if (service.isShuttingDown()) {
  // Handle accordingly
}
```

---

## ✅ 3. Input Validation Middleware

**Problem Solved:** No built-in request validation, leading to security vulnerabilities and runtime errors.

**Implementation:** `src/middlewares/validation.js`

### Schema Builder:
```javascript
import { Schema, validate } from 'cube-ms';

const userSchema = {
  body: Schema.object({
    name: Schema.string({ required: true, minLength: 2, maxLength: 50 }),
    email: Schema.email({ required: true }),
    age: Schema.number({ required: true, min: 18, max: 120, integer: true }),
    role: Schema.string({ enum: ['user', 'admin'], required: false }),
    tags: Schema.array(Schema.string(), { maxItems: 5 })
  }),
  params: {
    id: Schema.mongoId({ required: true })
  },
  query: {
    limit: Schema.number({ min: 1, max: 100, integer: true })
  }
};

// Apply validation
service.addRoute("post", "/users", handler, [validate(userSchema)]);
```

### Built-in Validators:
- `Schema.string()` - String validation with length, pattern
- `Schema.number()` - Number validation with min/max
- `Schema.email()` - Email format validation
- `Schema.url()` - URL format validation
- `Schema.uuid()` - UUID format validation
- `Schema.mongoId()` - MongoDB ObjectId validation
- `Schema.array()` - Array validation with items
- `Schema.object()` - Object validation with properties

### Sanitization:
```javascript
import { sanitize } from 'cube-ms';

// Auto-sanitization
service.use(sanitize({
  stripHtml: true,      // Remove HTML tags
  trim: true,           // Trim whitespace
  maxStringLength: 1000,// Limit string length
  removeNullBytes: true // Remove null bytes
}));
```

---

## 🏥 4. Health Check Endpoints

**Problem Solved:** No built-in monitoring or health check capabilities for production deployments.

**Implementation:** `src/health_check.js`

### Automatic Health Checks:
- **Database**: MongoDB connection and response time
- **Memory**: Heap usage and total memory consumption
- **CPU**: CPU usage percentage over time
- **Process**: Uptime, PID, Node.js version

### Built-in Endpoints:
```bash
# Comprehensive health check
GET /health
{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z",
  "service": {
    "name": "microservice",
    "version": "1.0.0",
    "environment": "production"
  },
  "checks": {
    "database": {
      "status": "healthy",
      "responseTime": "12ms",
      "connections": {...}
    },
    "memory": {
      "status": "healthy",
      "totalMemory": "156MB",
      "heapUsage": "65%"
    }
  }
}

# Simple liveness check (for Kubernetes)
GET /health/live
{
  "status": "alive",
  "timestamp": "2024-01-15T10:30:00Z",
  "uptime": 3600
}

# Readiness check (for load balancers)
GET /health/ready
{
  "status": "ready",
  "timestamp": "2024-01-15T10:30:00Z",
  "database": {...}
}
```

### Custom Health Checks:
```javascript
const service = CreateService({ enableHealthCheck: true });

// Add custom check
service.healthCheck.addCheck('redis', async () => {
  try {
    await redis.ping();
    return { status: 'healthy', responseTime: '5ms' };
  } catch (error) {
    return { status: 'unhealthy', error: error.message };
  }
});
```

---

## 🚀 Enhanced Service Creation

### New Options:
```javascript
const service = CreateService({
  port: 3000,
  appName: "myapp",
  serviceName: "api-service",
  containerName: "api-container",
  
  // New options
  enableHealthCheck: true,        // Enable /health endpoints
  requestTimeoutMs: 30000,       // Global request timeout
  no_console: false              // Disable console logging
});
```

### Enhanced Middlewares:
```javascript
const { MIDDLEWARES } = service;

// Now includes:
MIDDLEWARES.validateApiKey    // Existing
MIDDLEWARES.validateServiceID // Existing  
MIDDLEWARES.whitelist        // Existing
MIDDLEWARES.validate         // New: Schema validation
MIDDLEWARES.sanitize         // New: Input sanitization
MIDDLEWARES.asyncHandler     // New: Promise error handling
```

### Better Route Handling:
```javascript
// Automatic error handling and logging
service.addRoute("post", "/users", async (req, res, logger) => {
  // logger is automatically attached to request
  // Errors are automatically caught and handled
  // Request timeout is automatically applied
  
  logger.info("Processing user creation", { body: req.body });
  
  // If this throws, it's handled gracefully
  const user = await createUser(req.body);
  
  res.json({ success: true, data: user });
}, [validate(userSchema)]);
```

---

## 📊 Production Readiness Features

### 1. Enhanced Security:
- CSP headers via helmet
- Input sanitization 
- Request size limits (10MB default)
- HTML tag stripping
- SQL injection prevention

### 2. Better Logging:
- Structured error logging with context
- Request/response correlation IDs
- Performance metrics (response time)
- Automatic log tagging

### 3. Monitoring Ready:
- Health check endpoints for Kubernetes/Docker
- Prometheus-ready metrics structure
- Connection pool monitoring
- Memory and CPU tracking

### 4. Development Experience:
- Clear error messages with field names
- Request validation with helpful feedback
- Automatic error recovery
- Hot-reload friendly (graceful shutdown)

---

## 🔄 Migration Guide

### From Old Version:
```javascript
// Before
const service = CreateService({ port: 3000 });

service.addRoute("post", "/users", (req, res) => {
  // Manual error handling
  // No validation
  // Basic logging
});
```

### To New Version:
```javascript
// After  
import { CreateService, Schema, validate, ValidationError } from 'cube-ms';

const service = CreateService({ 
  port: 3000,
  enableHealthCheck: true,
  requestTimeoutMs: 15000
});

const schema = {
  body: Schema.object({
    name: Schema.string({ required: true }),
    email: Schema.email({ required: true })
  })
};

service.addRoute("post", "/users", async (req, res, logger) => {
  // Automatic error handling
  // Built-in validation
  // Enhanced logging
  logger.info("User creation started");
  
  const user = await createUser(req.body);
  res.json({ success: true, data: user });
}, [validate(schema)]);
```

### Breaking Changes:
- Route handlers now receive `logger` as third parameter
- All route handlers are automatically wrapped in `asyncHandler`
- Health check endpoints are added by default (disable with `enableHealthCheck: false`)
- Global error handler formats all error responses consistently

---

## 📚 Example Usage

See `Examples/enhancedService.mjs` for a comprehensive example showcasing all new features.

Run the example:
```bash
node Examples/enhancedService.mjs
```

Test endpoints:
```bash
# Health check
curl http://localhost:3001/health

# Validated endpoint
curl -X POST http://localhost:3001/users \
  -H "Content-Type: application/json" \
  -d '{"name":"John","email":"john@example.com","age":30}'

# Error handling
curl -X POST http://localhost:3001/error-test \
  -H "Content-Type: application/json" \
  -d '{"errorType":"validation"}'
```

---

These improvements make the framework production-ready with enterprise-grade error handling, monitoring, and security features while maintaining the original simplicity and developer experience.