navis.js 3.1.0 → 4.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,15 @@ navis metrics
 - ✅ **LambdaHandler** - Optimized handler with warm-up support
 - ✅ **Cold start tracking** - Monitor and log cold start metrics
 
+### v4 (Current)
+
+- ✅ **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
+
 ## API Reference
 
 ### NavisApp
@@ -304,6 +313,7 @@ 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.)
 - `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 +326,17 @@ 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 ✅ (Current)
+Production-ready: advanced routing, validation, authentication, rate limiting, error handling
+
 ## 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
 - [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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "navis.js",
-  "version": "3.1.0",
+  "version": "4.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,
+};
+

package/src/core/advanced-router.js

@@ -0,0 +1,186 @@
+/**
+ * Advanced Router with Parameters and Path Matching
+ * v4: Support for route parameters, wildcards, and path matching
+ */
+
+class AdvancedRouter {
+  constructor() {
+    this.routes = {
+      GET: [],
+      POST: [],
+      PUT: [],
+      DELETE: [],
+      PATCH: [],
+    };
+  }
+
+  /**
+   * Register a route handler
+   * @param {string} method - HTTP method
+   * @param {string} path - Route path (supports :param and * wildcards)
+   * @param {Function} handler - Route handler function
+   */
+  register(method, path, handler) {
+    const normalizedMethod = method.toUpperCase();
+    if (!this.routes[normalizedMethod]) {
+      throw new Error(`Unsupported HTTP method: ${method}`);
+    }
+
+    // Parse route pattern
+    const pattern = this._parsePattern(path);
+    
+    this.routes[normalizedMethod].push({
+      pattern: path,
+      regex: pattern.regex,
+      params: pattern.params,
+      handler,
+    });
+
+    // Sort routes by specificity (more specific first)
+    this.routes[normalizedMethod].sort((a, b) => {
+      const aSpecificity = this._calculateSpecificity(a.pattern);
+      const bSpecificity = this._calculateSpecificity(b.pattern);
+      return bSpecificity - aSpecificity;
+    });
+  }
+
+  /**
+   * Find route handler for a method and path
+   * @param {string} method - HTTP method
+   * @param {string} path - Request path
+   * @returns {Object|null} - { handler, params } or null if not found
+   */
+  find(method, path) {
+    const normalizedMethod = method.toUpperCase();
+    const methodRoutes = this.routes[normalizedMethod] || [];
+
+    for (const route of methodRoutes) {
+      const match = path.match(route.regex);
+      if (match) {
+        // Extract parameters
+        const params = {};
+        route.params.forEach((param, index) => {
+          params[param] = match[index + 1];
+        });
+
+        return {
+          handler: route.handler,
+          params,
+        };
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Parse route pattern into regex and parameter names
+   * @private
+   */
+  _parsePattern(pattern) {
+    const params = [];
+    const parts = pattern.split('/').filter(p => p !== ''); // Remove empty parts
+    const regexParts = [];
+    
+    for (const part of parts) {
+      if (part.startsWith(':')) {
+        // Parameter
+        const paramName = part.substring(1);
+        params.push(paramName);
+        regexParts.push('([^/]+)');
+      } else if (part === '*') {
+        // Wildcard
+        regexParts.push('.*');
+      } else {
+        // Literal - escape regex special chars
+        regexParts.push(part.replace(/[.+?^${}()|[\]\\]/g, '\\$&'));
+      }
+    }
+    
+    // Build regex pattern
+    const regexPattern = '^/' + regexParts.join('/') + '/?$';
+
+    return {
+      regex: new RegExp(regexPattern),
+      params,
+    };
+  }
+
+  /**
+   * Calculate route specificity (higher = more specific)
+   * @private
+   */
+  _calculateSpecificity(pattern) {
+    let specificity = 0;
+    
+    // Count static segments
+    const staticSegments = pattern.split('/').filter(seg => 
+      seg && !seg.startsWith(':') && seg !== '*'
+    );
+    specificity += staticSegments.length * 10;
+
+    // Count parameters (less specific)
+    const params = (pattern.match(/:[^/]+/g) || []).length;
+    specificity += params * 5;
+
+    // Wildcards are least specific
+    if (pattern.includes('*')) {
+      specificity -= 10;
+    }
+
+    return specificity;
+  }
+
+  /**
+   * Get all registered routes
+   * @returns {Object} - All routes grouped by method
+   */
+  getAllRoutes() {
+    const allRoutes = {};
+    for (const method in this.routes) {
+      allRoutes[method] = this.routes[method].map(route => ({
+        pattern: route.pattern,
+        params: route.params,
+      }));
+    }
+    return allRoutes;
+  }
+
+  /**
+   * Register GET route
+   */
+  get(path, handler) {
+    this.register('GET', path, handler);
+  }
+
+  /**
+   * Register POST route
+   */
+  post(path, handler) {
+    this.register('POST', path, handler);
+  }
+
+  /**
+   * Register PUT route
+   */
+  put(path, handler) {
+    this.register('PUT', path, handler);
+  }
+
+  /**
+   * Register DELETE route
+   */
+  delete(path, handler) {
+    this.register('DELETE', path, handler);
+  }
+
+  /**
+   * Register PATCH route
+   */
+  patch(path, handler) {
+    this.register('PATCH', path, handler);
+  }
+}
+
+module.exports = AdvancedRouter;
+