navis.js 3.1.0 → 5.0.0

package/README.md

@@ -112,7 +112,7 @@ navis metrics
 - ✅ **Distributed tracing** - Trace and span management
 - ✅ **Enhanced CLI** - Test and metrics commands
 
-### v3.1 (Current)
+### v3.1
 
 - ✅ **Lambda cold start optimization** - Connection pooling, lazy initialization
 - ✅ **ServiceClientPool** - Reuse HTTP connections across invocations
@@ -120,6 +120,24 @@ navis metrics
 - ✅ **LambdaHandler** - Optimized handler with warm-up support
 - ✅ **Cold start tracking** - Monitor and log cold start metrics
 
+### v4
+
+- ✅ **Advanced routing** - Route parameters (`:id`), nested routes, PATCH method
+- ✅ **Request validation** - Schema-based validation with comprehensive rules
+- ✅ **Authentication** - JWT and API Key authentication
+- ✅ **Authorization** - Role-based access control
+- ✅ **Rate limiting** - In-memory rate limiting with configurable windows
+- ✅ **Enhanced error handling** - Custom error classes and error handler middleware
+
+### v5 (Current)
+
+- ✅ **Caching layer** - In-memory cache with TTL and Redis adapter
+- ✅ **CORS support** - Cross-Origin Resource Sharing middleware
+- ✅ **Security headers** - Protection against common attacks
+- ✅ **Response compression** - Gzip and Brotli compression
+- ✅ **Health checks** - Liveness and readiness probes
+- ✅ **Graceful shutdown** - Clean shutdown handling
+
 ## API Reference
 
 ### NavisApp
@@ -304,6 +322,8 @@ See the `examples/` directory:
 - `server.js` - Node.js HTTP server example
 - `lambda.js` - AWS Lambda handler example
 - `lambda-optimized.js` - Optimized Lambda handler with cold start optimizations (v3.1)
+- `v4-features-demo.js` - v4 features demonstration (routing, validation, auth, rate limiting, etc.)
+- `v5-features-demo.js` - v5 features demonstration (caching, CORS, security, compression, health checks, etc.)
 - `service-client-demo.js` - ServiceClient usage example
 - `v2-features-demo.js` - v2 features demonstration (retry, circuit breaker, etc.)
 - `v3-features-demo.js` - v3 features demonstration (messaging, observability, etc.)
@@ -316,13 +336,21 @@ Core functionality: routing, middleware, Lambda support, ServiceClient
 ### v2 ✅
 Resilience patterns: retry, circuit breaker, service discovery, CLI generators
 
-### v3 ✅ (Current)
+### v3 ✅
 Advanced features: async messaging (SQS/Kafka/NATS), observability, enhanced CLI
 
+### v4 ✅
+Production-ready: advanced routing, validation, authentication, rate limiting, error handling
+
+### v5 ✅ (Current)
+Enterprise-grade: caching, CORS, security headers, compression, health checks, graceful shutdown
+
 ## Documentation
 
 - [V2 Features Guide](./V2_FEATURES.md) - Complete v2 features documentation
 - [V3 Features Guide](./V3_FEATURES.md) - Complete v3 features documentation
+- [V4 Features Guide](./V4_FEATURES.md) - Complete v4 features documentation
+- [V5 Features Guide](./V5_FEATURES.md) - Complete v5 features documentation
 - [Lambda Optimization Guide](./LAMBDA_OPTIMIZATION.md) - Lambda cold start optimization guide (v3.1)
 - [Verification Guide v2](./VERIFY_V2.md) - How to verify v2 features
 - [Verification Guide v3](./VERIFY_V3.md) - How to verify v3 features

package/examples/v4-features-demo.js

@@ -0,0 +1,171 @@
+/**
+ * Navis.js v4 Features Demo
+ * Demonstrates advanced routing, validation, auth, rate limiting, and error handling
+ */
+
+const {
+  NavisApp,
+  response,
+  validate,
+  authenticateJWT,
+  authorize,
+  rateLimit,
+  errorHandler,
+  asyncHandler,
+  NotFoundError,
+  BadRequestError,
+} = require('../src/index');
+
+const app = new NavisApp();
+
+// Set error handler
+app.setErrorHandler(errorHandler({
+  includeStack: true,
+  logErrors: true,
+}));
+
+// Global rate limiting
+app.use(rateLimit({
+  windowMs: 60000, // 1 minute
+  max: 100, // 100 requests per minute
+}));
+
+// Example 1: Route Parameters
+console.log('\n=== Route Parameters (v4) ===\n');
+
+app.get('/users/:id', (req, res) => {
+  console.log('User ID:', req.params.id);
+  response.success(res, {
+    message: `Fetching user ${req.params.id}`,
+    userId: req.params.id,
+  });
+});
+
+app.get('/users/:id/posts/:postId', (req, res) => {
+  console.log('User ID:', req.params.id);
+  console.log('Post ID:', req.params.postId);
+  response.success(res, {
+    userId: req.params.id,
+    postId: req.params.postId,
+  });
+});
+
+// Example 2: Request Validation
+console.log('\n=== Request Validation (v4) ===\n');
+
+const createUserSchema = {
+  body: {
+    name: {
+      type: 'string',
+      required: true,
+      minLength: 3,
+      maxLength: 50,
+    },
+    email: {
+      type: 'string',
+      required: true,
+      format: 'email',
+    },
+    age: {
+      type: 'number',
+      min: 18,
+      max: 100,
+    },
+  },
+};
+
+app.post('/users', validate(createUserSchema), (req, res) => {
+  console.log('Validated body:', req.body);
+  response.success(res, {
+    message: 'User created',
+    user: req.body,
+  }, 201);
+});
+
+// Example 3: Authentication (Mock JWT)
+console.log('\n=== Authentication (v4) ===\n');
+
+// Mock JWT secret (in production, use environment variable)
+process.env.JWT_SECRET = 'your-secret-key';
+
+// Protected route
+app.get('/profile', authenticateJWT(), (req, res) => {
+  response.success(res, {
+    message: 'Protected route',
+    user: req.user,
+  });
+});
+
+// Role-based authorization
+app.get('/admin', authenticateJWT(), authorize(['admin']), (req, res) => {
+  response.success(res, {
+    message: 'Admin area',
+    user: req.user,
+  });
+});
+
+// Example 4: Error Handling
+console.log('\n=== Error Handling (v4) ===\n');
+
+app.get('/error-test', asyncHandler(async (req, res) => {
+  throw new BadRequestError('This is a bad request');
+}));
+
+app.get('/not-found-test', asyncHandler(async (req, res) => {
+  throw new NotFoundError('Resource not found');
+}));
+
+// Example 5: Rate Limiting per Route
+console.log('\n=== Rate Limiting (v4) ===\n');
+
+app.post('/login', rateLimit({ max: 5, windowMs: 60000 }), (req, res) => {
+  response.success(res, {
+    message: 'Login endpoint (5 requests per minute)',
+  });
+});
+
+// Example 6: Query Parameters
+app.get('/search', (req, res) => {
+  console.log('Query params:', req.query);
+  response.success(res, {
+    query: req.query.q,
+    filters: req.query,
+  });
+});
+
+// Example 7: PATCH Method (v4)
+app.patch('/users/:id', validate({
+  body: {
+    name: { type: 'string', required: false },
+    email: { type: 'string', required: false, format: 'email' },
+  },
+}), (req, res) => {
+  response.success(res, {
+    message: `Updating user ${req.params.id}`,
+    updates: req.body,
+  });
+});
+
+// Start server
+const PORT = 3000;
+app.listen(PORT, () => {
+  console.log(`\n🚀 Navis.js v4 Features Demo Server`);
+  console.log(`📡 Listening on http://localhost:${PORT}\n`);
+  console.log('Available endpoints:');
+  console.log('  GET  /users/:id');
+  console.log('  GET  /users/:id/posts/:postId');
+  console.log('  POST /users (with validation)');
+  console.log('  GET  /profile (requires JWT)');
+  console.log('  GET  /admin (requires admin role)');
+  console.log('  GET  /error-test');
+  console.log('  GET  /not-found-test');
+  console.log('  POST /login (rate limited)');
+  console.log('  GET  /search?q=test');
+  console.log('  PATCH /users/:id');
+  console.log('\n💡 Test with:');
+  console.log('  curl http://localhost:3000/users/123');
+  console.log('  curl -X POST http://localhost:3000/users -H "Content-Type: application/json" -d \'{"name":"John","email":"john@example.com","age":25}\'');
+});
+
+module.exports = app;
+

package/examples/v5-features-demo.js

@@ -0,0 +1,167 @@
+/**
+ * Navis.js v5 Features Demo
+ * Demonstrates caching, CORS, security, compression, health checks, and graceful shutdown
+ */
+
+const {
+  NavisApp,
+  response,
+  Cache,
+  cache,
+  cors,
+  security,
+  compress,
+  createHealthChecker,
+  gracefulShutdown,
+} = require('../src/index');
+
+const app = new NavisApp();
+
+// ============================================
+// CORS Middleware
+// ============================================
+app.use(cors({
+  origin: ['http://localhost:3000', 'https://example.com'],
+  methods: ['GET', 'POST', 'PUT', 'DELETE'],
+  credentials: true,
+}));
+
+// ============================================
+// Security Headers
+// ============================================
+app.use(security({
+  helmet: true,
+  hsts: true,
+  noSniff: true,
+  xssFilter: true,
+  frameOptions: 'DENY',
+  referrerPolicy: 'no-referrer',
+}));
+
+// ============================================
+// Response Compression
+// ============================================
+app.use(compress({
+  level: 6,
+  threshold: 1024,
+  algorithm: 'gzip',
+}));
+
+// ============================================
+// Caching
+// ============================================
+const cacheStore = new Cache({
+  maxSize: 1000,
+  defaultTTL: 3600000, // 1 hour
+});
+
+// Cached route
+app.get('/users/:id', cache({
+  cacheStore,
+  ttl: 1800, // 30 minutes
+  keyGenerator: (req) => `user:${req.params.id}`,
+}), (req, res) => {
+  // Simulate database query
+  const user = {
+    id: req.params.id,
+    name: 'John Doe',
+    email: 'john@example.com',
+  };
+  
+  response.success(res, user);
+});
+
+// Non-cached route
+app.get('/users/:id/posts', (req, res) => {
+  response.success(res, {
+    userId: req.params.id,
+    posts: [],
+  });
+});
+
+// ============================================
+// Health Checks
+// ============================================
+const healthChecker = createHealthChecker({
+  livenessPath: '/health/live',
+  readinessPath: '/health/ready',
+  checks: {
+    database: async () => {
+      // Simulate database check
+      return true;
+    },
+    cache: async () => {
+      // Check cache
+      return cacheStore.size() >= 0;
+    },
+  },
+});
+
+app.use(healthChecker.middleware());
+
+// ============================================
+// Routes
+// ============================================
+app.get('/', (req, res) => {
+  response.success(res, {
+    message: 'Navis.js v5 Features Demo',
+    features: [
+      'Caching',
+      'CORS',
+      'Security Headers',
+      'Compression',
+      'Health Checks',
+      'Graceful Shutdown',
+    ],
+  });
+});
+
+app.get('/cache-stats', (req, res) => {
+  response.success(res, {
+    size: cacheStore.size(),
+    keys: cacheStore.keys().slice(0, 10), // First 10 keys
+  });
+});
+
+app.post('/cache/clear', (req, res) => {
+  cacheStore.clear();
+  response.success(res, { message: 'Cache cleared' });
+});
+
+// ============================================
+// Start Server
+// ============================================
+const PORT = 3000;
+const server = app.listen(PORT, () => {
+  console.log(`\n🚀 Navis.js v5 Features Demo Server`);
+  console.log(`📡 Listening on http://localhost:${PORT}\n`);
+  console.log('Available endpoints:');
+  console.log('  GET  /');
+  console.log('  GET  /users/:id (cached)');
+  console.log('  GET  /users/:id/posts');
+  console.log('  GET  /health/live (liveness)');
+  console.log('  GET  /health/ready (readiness)');
+  console.log('  GET  /cache-stats');
+  console.log('  POST /cache/clear');
+  console.log('\n💡 Test with:');
+  console.log('  curl http://localhost:3000/');
+  console.log('  curl http://localhost:3000/users/123');
+  console.log('  curl http://localhost:3000/health/ready');
+});
+
+// ============================================
+// Graceful Shutdown
+// ============================================
+gracefulShutdown(server, {
+  timeout: 10000,
+  onShutdown: async () => {
+    console.log('Cleaning up...');
+    // Close database connections
+    // Close cache connections
+    cacheStore.destroy();
+    console.log('Cleanup complete');
+  },
+});
+
+module.exports = app;
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "navis.js",
-  "version": "3.1.0",
+  "version": "5.0.0",
   "description": "A lightweight, serverless-first, microservice API framework designed for AWS Lambda and Node.js",
   "main": "src/index.js",
   "bin": {

package/src/auth/authenticator.js

@@ -0,0 +1,223 @@
+/**
+ * Authentication and Authorization Middleware
+ * v4: JWT, API Key, and role-based access control
+ */
+
+const crypto = require('crypto');
+
+class AuthenticationError extends Error {
+  constructor(message, statusCode = 401) {
+    super(message);
+    this.name = 'AuthenticationError';
+    this.statusCode = statusCode;
+  }
+}
+
+class AuthorizationError extends Error {
+  constructor(message, statusCode = 403) {
+    super(message);
+    this.name = 'AuthorizationError';
+    this.statusCode = statusCode;
+  }
+}
+
+/**
+ * JWT Authentication Middleware
+ * @param {Object} options - JWT options
+ * @returns {Function} - Middleware function
+ */
+function authenticateJWT(options = {}) {
+  const {
+    secret = process.env.JWT_SECRET,
+    algorithms = ['HS256'],
+    header = 'authorization',
+    extractToken = (req) => {
+      const authHeader = req.headers[header] || req.headers[header.toLowerCase()];
+      if (!authHeader) return null;
+      
+      // Support "Bearer <token>" format
+      const parts = authHeader.split(' ');
+      return parts.length === 2 && parts[0].toLowerCase() === 'bearer' 
+        ? parts[1] 
+        : authHeader;
+    },
+  } = options;
+
+  if (!secret) {
+    throw new Error('JWT secret is required');
+  }
+
+  return async (req, res, next) => {
+    try {
+      const token = extractToken(req);
+
+      if (!token) {
+        throw new AuthenticationError('No authentication token provided');
+      }
+
+      // Simple JWT decode and verify (for HS256)
+      // In production, use a proper JWT library like jsonwebtoken
+      const decoded = verifyJWT(token, secret);
+      
+      if (!decoded) {
+        throw new AuthenticationError('Invalid or expired token');
+      }
+
+      // Attach user info to request
+      req.user = decoded;
+      req.token = token;
+
+      next();
+    } catch (error) {
+      if (error instanceof AuthenticationError) {
+        res.statusCode = error.statusCode;
+        res.body = { error: error.message };
+        return;
+      }
+      throw error;
+    }
+  };
+}
+
+/**
+ * Simple JWT verification (HS256 only)
+ * For production, use jsonwebtoken library
+ * @private
+ */
+function verifyJWT(token, secret) {
+  try {
+    const parts = token.split('.');
+    if (parts.length !== 3) {
+      return null;
+    }
+
+    const [headerB64, payloadB64, signatureB64] = parts;
+    
+    // Verify signature
+    const signature = Buffer.from(signatureB64, 'base64url').toString('hex');
+    const expectedSignature = crypto
+      .createHmac('sha256', secret)
+      .update(`${headerB64}.${payloadB64}`)
+      .digest('hex');
+
+    if (signature !== expectedSignature) {
+      return null;
+    }
+
+    // Decode payload
+    const payload = JSON.parse(Buffer.from(payloadB64, 'base64url').toString());
+
+    // Check expiration
+    if (payload.exp && Date.now() >= payload.exp * 1000) {
+      return null;
+    }
+
+    return payload;
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * API Key Authentication Middleware
+ * @param {Object} options - API Key options
+ * @returns {Function} - Middleware function
+ */
+function authenticateAPIKey(options = {}) {
+  const {
+    header = 'x-api-key',
+    keys = process.env.API_KEYS ? process.env.API_KEYS.split(',') : [],
+    validateKey = (key) => keys.includes(key),
+  } = options;
+
+  return async (req, res, next) => {
+    try {
+      const apiKey = req.headers[header] || req.headers[header.toLowerCase()];
+
+      if (!apiKey) {
+        throw new AuthenticationError('API key is required');
+      }
+
+      const isValid = await validateKey(apiKey);
+
+      if (!isValid) {
+        throw new AuthenticationError('Invalid API key');
+      }
+
+      req.apiKey = apiKey;
+      next();
+    } catch (error) {
+      if (error instanceof AuthenticationError) {
+        res.statusCode = error.statusCode;
+        res.body = { error: error.message };
+        return;
+      }
+      throw error;
+    }
+  };
+}
+
+/**
+ * Role-based Authorization Middleware
+ * @param {string|Array} allowedRoles - Allowed roles
+ * @returns {Function} - Middleware function
+ */
+function authorize(allowedRoles) {
+  const roles = Array.isArray(allowedRoles) ? allowedRoles : [allowedRoles];
+
+  return async (req, res, next) => {
+    try {
+      if (!req.user) {
+        throw new AuthenticationError('Authentication required');
+      }
+
+      const userRoles = req.user.roles || req.user.role ? [req.user.role] : [];
+
+      const hasRole = roles.some(role => userRoles.includes(role));
+
+      if (!hasRole) {
+        throw new AuthorizationError('Insufficient permissions');
+      }
+
+      next();
+    } catch (error) {
+      if (error instanceof AuthenticationError || error instanceof AuthorizationError) {
+        res.statusCode = error.statusCode;
+        res.body = { error: error.message };
+        return;
+      }
+      throw error;
+    }
+  };
+}
+
+/**
+ * Optional authentication (doesn't fail if no token)
+ * @param {Object} options - JWT options
+ * @returns {Function} - Middleware function
+ */
+function optionalAuth(options = {}) {
+  const jwtAuth = authenticateJWT(options);
+
+  return async (req, res, next) => {
+    try {
+      await jwtAuth(req, res, () => {
+        // Continue even if auth fails
+        next();
+      });
+    } catch (error) {
+      // If auth fails, continue without user
+      next();
+    }
+  };
+}
+
+module.exports = {
+  authenticateJWT,
+  authenticateAPIKey,
+  authorize,
+  optionalAuth,
+  AuthenticationError,
+  AuthorizationError,
+};
+