navis.js 3.0.2 → 4.0.0

package/README.md

@@ -112,6 +112,23 @@ navis metrics
 - ✅ **Distributed tracing** - Trace and span management
 - ✅ **Enhanced CLI** - Test and metrics commands
 
+### v3.1
+
+- ✅ **Lambda cold start optimization** - Connection pooling, lazy initialization
+- ✅ **ServiceClientPool** - Reuse HTTP connections across invocations
+- ✅ **LazyInit utility** - Defer heavy operations until needed
+- ✅ **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
@@ -248,12 +265,55 @@ await nats.connect();
 await nats.publish('user.created', { userId: 123 });
 ```
 
+### Lambda Optimization (v3.1)
+
+```javascript
+const {
+  NavisApp,
+  getPool,
+  LambdaHandler,
+  coldStartTracker,
+  LazyInit,
+} = require('navis.js');
+
+// Initialize app OUTSIDE handler (reused across invocations)
+const app = new NavisApp();
+app.use(coldStartTracker);
+
+// Connection pooling - reuse HTTP connections
+const client = getPool().get('http://api.example.com', {
+  timeout: 3000,
+  maxRetries: 2,
+});
+
+// Lazy initialization - defer heavy operations
+const dbConnection = new LazyInit();
+app.get('/users', async (req, res) => {
+  const db = await dbConnection.init(async () => {
+    return await connectToDatabase(); // Only runs once
+  });
+  res.body = await db.query('SELECT * FROM users');
+});
+
+// Optimized Lambda handler
+const handler = new LambdaHandler(app, {
+  enableMetrics: true,
+  warmupPath: '/warmup',
+});
+
+exports.handler = async (event, context) => {
+  return await handler.handle(event, context);
+};
+```
+
 ## Examples
 
 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.)
@@ -266,13 +326,18 @@ 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/lambda-optimized.js

@@ -0,0 +1,103 @@
+/**
+ * Optimized Lambda Handler Example
+ * v3.1: Best practices for reducing cold start time
+ */
+
+const { NavisApp, response, getPool } = require('../src/index');
+const LambdaHandler = require('../src/core/lambda-handler');
+const { coldStartTracker } = require('../src/middleware/cold-start-tracker');
+
+// ============================================
+// CRITICAL: Initialize app OUTSIDE handler
+// This ensures the app is reused across invocations
+// ============================================
+const app = new NavisApp();
+
+// Add cold start tracking middleware
+app.use(coldStartTracker);
+
+// ============================================
+// Register routes at MODULE LEVEL (not in handler)
+// This runs once per container, not per invocation
+// ============================================
+app.get('/', (req, res) => {
+  res.statusCode = 200;
+  res.body = { 
+    message: 'Welcome to Navis.js Lambda (Optimized)!',
+    optimized: true,
+  };
+});
+
+app.get('/health', (req, res) => {
+  res.statusCode = 200;
+  res.body = { status: 'ok' };
+});
+
+app.get('/warmup', (req, res) => {
+  res.statusCode = 200;
+  res.body = { status: 'warmed' };
+});
+
+// Example: Using ServiceClient with connection pooling
+app.get('/external', async (req, res) => {
+  try {
+    // Get client from pool (reuses connections)
+    const client = getPool().get('http://api.example.com', {
+      timeout: 3000,
+      maxRetries: 2,
+    });
+    
+    const result = await client.get('/data');
+    res.statusCode = 200;
+    res.body = { data: result.data };
+  } catch (error) {
+    res.statusCode = 500;
+    res.body = { error: error.message };
+  }
+});
+
+// ============================================
+// OPTIMIZED HANDLER
+// ============================================
+
+// Create handler instance (reused across invocations)
+const handler = new LambdaHandler(app, {
+  enableMetrics: true,
+  warmupPath: '/warmup',
+});
+
+// Cache the handler function (V8 optimization)
+let cachedHandler = null;
+
+/**
+ * Lambda handler - optimized for cold starts
+ * @param {Object} event - Lambda event
+ * @param {Object} context - Lambda context
+ */
+exports.handler = async (event, context) => {
+  // Reuse handler function (V8 JIT optimization)
+  if (!cachedHandler) {
+    cachedHandler = async (event, context) => {
+      return await handler.handle(event, context);
+    };
+  }
+  
+  return await cachedHandler(event, context);
+};
+
+/**
+ * Optional: Pre-warm function
+ * Can be called during container initialization
+ */
+exports.preWarm = async () => {
+  // Pre-initialize any heavy operations
+  // This runs once per container
+  console.log('Pre-warming Lambda container...');
+  
+  // Example: Pre-initialize service clients
+  const pool = getPool();
+  pool.get('http://api.example.com', { timeout: 3000 });
+  
+  console.log('Pre-warming complete');
+};
+

package/examples/lambda.js

@@ -1,30 +1,31 @@
-const { NavisApp } = require('../src/index');
-
-const app = new NavisApp();
-
-// Middleware example
-app.use((req, res, next) => {
-  console.log(`Lambda: ${req.method} ${req.path}`);
-  next();
-});
-
-// Routes
-app.get('/', (req, res) => {
-  res.statusCode = 200;
-  res.body = { message: 'Welcome to Navis.js Lambda!' };
-});
-
-app.get('/health', (req, res) => {
-  res.statusCode = 200;
-  res.body = { status: 'ok' };
-});
-
-app.post('/echo', (req, res) => {
-  res.statusCode = 200;
-  res.body = { echo: req.body };
-});
-
-// Lambda handler
-exports.handler = async (event) => {
-  return await app.handleLambda(event);
+const { NavisApp } = require('../src/index');
+
+// Initialize app at module level (reused across invocations)
+const app = new NavisApp();
+
+// Middleware example
+app.use((req, res, next) => {
+  console.log(`Lambda: ${req.method} ${req.path}`);
+  next();
+});
+
+// Routes registered at module level (not in handler)
+app.get('/', (req, res) => {
+  res.statusCode = 200;
+  res.body = { message: 'Welcome to Navis.js Lambda!' };
+});
+
+app.get('/health', (req, res) => {
+  res.statusCode = 200;
+  res.body = { status: 'ok' };
+});
+
+app.post('/echo', (req, res) => {
+  res.statusCode = 200;
+  res.body = { echo: req.body };
+});
+
+// Lambda handler - optimized for reuse
+exports.handler = async (event) => {
+  return await app.handleLambda(event);
 };

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.0.2",
+  "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,
+};
+