navis.js 3.0.2 → 4.0.0

package/src/core/lambda-handler.js

@@ -0,0 +1,130 @@
+/**
+ * Optimized Lambda Handler
+ * v3.1: Enhanced Lambda handler with cold start optimizations
+ */
+
+class LambdaHandler {
+  constructor(app, options = {}) {
+    this.app = app;
+    this.isWarm = false;
+    this.initTime = Date.now();
+    this.invocationCount = 0;
+    this.coldStartCount = 0;
+    this.enableMetrics = options.enableMetrics !== false;
+    this.warmupPath = options.warmupPath || '/warmup';
+  }
+
+  /**
+   * Handle Lambda invocation
+   * @param {Object} event - Lambda event
+   * @param {Object} context - Lambda context
+   * @returns {Promise<Object>} - Lambda response
+   */
+  async handle(event, context) {
+    this.invocationCount++;
+
+    // Detect warm-up events
+    if (this.isWarmupEvent(event)) {
+      return this.handleWarmup();
+    }
+
+    // Track cold start
+    const isColdStart = !this.isWarm;
+    if (isColdStart) {
+      this.isWarm = true;
+      this.coldStartCount++;
+      
+      if (this.enableMetrics) {
+        const coldStartDuration = Date.now() - this.initTime;
+        console.log(JSON.stringify({
+          type: 'cold-start',
+          duration: coldStartDuration,
+          memoryLimit: context.memoryLimitInMB,
+          requestId: context.requestId,
+        }));
+      }
+    }
+
+    // Add cold start headers to response
+    const response = await this.app.handleLambda(event);
+    
+    if (isColdStart && response.headers) {
+      response.headers['X-Cold-Start'] = 'true';
+      response.headers['X-Init-Time'] = (Date.now() - this.initTime).toString();
+    }
+
+    return response;
+  }
+
+  /**
+   * Check if event is a warm-up event
+   * @param {Object} event - Lambda event
+   * @returns {boolean} - True if warm-up event
+   */
+  isWarmupEvent(event) {
+    // Check various warm-up event formats
+    if (event.source === 'serverless-plugin-warmup') {
+      return true;
+    }
+    
+    if (event.warmup === true || event['serverless-plugin-warmup']) {
+      return true;
+    }
+    
+    // Check if it's a warm-up HTTP request
+    if (event.httpMethod === 'GET' && 
+        (event.path === this.warmupPath || event.rawPath === this.warmupPath)) {
+      return true;
+    }
+    
+    return false;
+  }
+
+  /**
+   * Handle warm-up event
+   * @returns {Object} - Warm-up response
+   */
+  handleWarmup() {
+    // Mark as warm
+    this.isWarm = true;
+    
+    return {
+      statusCode: 200,
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        status: 'warmed',
+        invocationCount: this.invocationCount,
+        coldStartCount: this.coldStartCount,
+      }),
+    };
+  }
+
+  /**
+   * Get handler statistics
+   * @returns {Object} - Handler statistics
+   */
+  getStats() {
+    return {
+      isWarm: this.isWarm,
+      invocationCount: this.invocationCount,
+      coldStartCount: this.coldStartCount,
+      initTime: this.initTime,
+      uptime: Date.now() - this.initTime,
+    };
+  }
+
+  /**
+   * Reset handler state (useful for testing)
+   */
+  reset() {
+    this.isWarm = false;
+    this.invocationCount = 0;
+    this.coldStartCount = 0;
+    this.initTime = Date.now();
+  }
+}
+
+module.exports = LambdaHandler;
+

package/src/errors/error-handler.js

@@ -0,0 +1,157 @@
+/**
+ * Enhanced Error Handling
+ * v4: Custom error classes and error handling middleware
+ */
+
+class AppError extends Error {
+  constructor(message, statusCode = 500, code = null) {
+    super(message);
+    this.name = this.constructor.name;
+    this.statusCode = statusCode;
+    this.code = code || this.constructor.name.toUpperCase();
+    this.isOperational = true;
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+class NotFoundError extends AppError {
+  constructor(message = 'Resource not found') {
+    super(message, 404, 'NOT_FOUND');
+  }
+}
+
+class BadRequestError extends AppError {
+  constructor(message = 'Bad request') {
+    super(message, 400, 'BAD_REQUEST');
+  }
+}
+
+class UnauthorizedError extends AppError {
+  constructor(message = 'Unauthorized') {
+    super(message, 401, 'UNAUTHORIZED');
+  }
+}
+
+class ForbiddenError extends AppError {
+  constructor(message = 'Forbidden') {
+    super(message, 403, 'FORBIDDEN');
+  }
+}
+
+class ConflictError extends AppError {
+  constructor(message = 'Conflict') {
+    super(message, 409, 'CONFLICT');
+  }
+}
+
+class InternalServerError extends AppError {
+  constructor(message = 'Internal server error') {
+    super(message, 500, 'INTERNAL_SERVER_ERROR');
+  }
+}
+
+/**
+ * Error handler middleware
+ * @param {Object} options - Error handler options
+ * @returns {Function} - Error handling middleware
+ */
+function errorHandler(options = {}) {
+  const {
+    format = 'json',
+    includeStack = process.env.NODE_ENV === 'development',
+    logErrors = true,
+    logger = console.error,
+  } = options;
+
+  return async (err, req, res, next) => {
+    // Determine status code
+    const statusCode = err.statusCode || err.status || 500;
+    const code = err.code || 'INTERNAL_SERVER_ERROR';
+    const message = err.message || 'Internal server error';
+
+    // Log error
+    if (logErrors) {
+      logger('Error:', {
+        message,
+        statusCode,
+        code,
+        stack: includeStack ? err.stack : undefined,
+        path: req.path,
+        method: req.method,
+      });
+    }
+
+    // Format error response
+    const errorResponse = {
+      error: {
+        message,
+        code,
+        statusCode,
+      },
+    };
+
+    // Include stack trace in development
+    if (includeStack && err.stack) {
+      errorResponse.error.stack = err.stack.split('\n');
+    }
+
+    // Include validation errors if present
+    if (err.errors && Array.isArray(err.errors)) {
+      errorResponse.error.errors = err.errors;
+    }
+
+    // Set response
+    res.statusCode = statusCode;
+    
+    if (format === 'json') {
+      res.headers = res.headers || {};
+      res.headers['Content-Type'] = 'application/json';
+      res.body = errorResponse;
+    } else {
+      res.body = `${statusCode} ${message}`;
+    }
+  };
+}
+
+/**
+ * Async error wrapper
+ * Wraps async route handlers to catch errors
+ * @param {Function} fn - Async function
+ * @returns {Function} - Wrapped function
+ */
+function asyncHandler(fn) {
+  return (req, res, next) => {
+    Promise.resolve(fn(req, res, next)).catch(next);
+  };
+}
+
+/**
+ * Not found handler
+ * @returns {Function} - Middleware function
+ */
+function notFoundHandler() {
+  return (req, res) => {
+    res.statusCode = 404;
+    res.body = {
+      error: {
+        message: `Route ${req.method} ${req.path} not found`,
+        code: 'NOT_FOUND',
+        statusCode: 404,
+      },
+    };
+  };
+}
+
+module.exports = {
+  AppError,
+  NotFoundError,
+  BadRequestError,
+  UnauthorizedError,
+  ForbiddenError,
+  ConflictError,
+  InternalServerError,
+  errorHandler,
+  asyncHandler,
+  notFoundHandler,
+};
+

package/src/index.js

@@ -16,6 +16,37 @@ const Logger = require('./observability/logger');
 const Metrics = require('./observability/metrics');
 const Tracer = require('./observability/tracer');
 
+// v3.1: Lambda Optimizations
+const { getPool, ServiceClientPool } = require('./utils/service-client-pool');
+const { LazyInit, createLazyInit } = require('./utils/lazy-init');
+const LambdaHandler = require('./core/lambda-handler');
+const { coldStartTracker } = require('./middleware/cold-start-tracker');
+
+// v4: Advanced Features
+const AdvancedRouter = require('./core/advanced-router');
+const { validate, ValidationError } = require('./validation/validator');
+const {
+  authenticateJWT,
+  authenticateAPIKey,
+  authorize,
+  optionalAuth,
+  AuthenticationError,
+  AuthorizationError,
+} = require('./auth/authenticator');
+const { rateLimit, RateLimiter } = require('./middleware/rate-limiter');
+const {
+  AppError,
+  NotFoundError,
+  BadRequestError,
+  UnauthorizedError,
+  ForbiddenError,
+  ConflictError,
+  InternalServerError,
+  errorHandler,
+  asyncHandler,
+  notFoundHandler,
+} = require('./errors/error-handler');
+
 module.exports = {
   // Core
   NavisApp,
@@ -38,6 +69,37 @@ module.exports = {
   Metrics,
   Tracer,
   
+  // v3.1: Lambda Optimizations
+  ServiceClientPool,
+  getPool,
+  LazyInit,
+  createLazyInit,
+  LambdaHandler,
+  coldStartTracker,
+  
+  // v4: Advanced Features
+  AdvancedRouter,
+  validate,
+  ValidationError,
+  authenticateJWT,
+  authenticateAPIKey,
+  authorize,
+  optionalAuth,
+  AuthenticationError,
+  AuthorizationError,
+  rateLimit,
+  RateLimiter,
+  AppError,
+  NotFoundError,
+  BadRequestError,
+  UnauthorizedError,
+  ForbiddenError,
+  ConflictError,
+  InternalServerError,
+  errorHandler,
+  asyncHandler,
+  notFoundHandler,
+  
   // Utilities
   response: {
     success,

package/src/middleware/cold-start-tracker.js

@@ -0,0 +1,56 @@
+/**
+ * Cold Start Tracker Middleware
+ * v3.1: Track and log cold start metrics
+ */
+
+let isFirstInvocation = true;
+let initTime = Date.now();
+
+/**
+ * Cold start tracking middleware
+ * Tracks cold starts and adds headers to response
+ * @param {Object} req - Request object
+ * @param {Object} res - Response object
+ * @param {Function} next - Next middleware
+ */
+function coldStartTracker(req, res, next) {
+  if (isFirstInvocation) {
+    const coldStartDuration = Date.now() - initTime;
+    
+    // Add cold start info to response headers
+    if (res.headers) {
+      res.headers['X-Cold-Start'] = 'true';
+      res.headers['X-Cold-Start-Duration'] = coldStartDuration.toString();
+    }
+    
+    // Log cold start (structured logging)
+    console.log(JSON.stringify({
+      type: 'cold-start',
+      duration: coldStartDuration,
+      path: req.path || req.url,
+      method: req.method,
+    }));
+    
+    isFirstInvocation = false;
+  } else {
+    if (res.headers) {
+      res.headers['X-Cold-Start'] = 'false';
+    }
+  }
+  
+  next();
+}
+
+/**
+ * Reset cold start tracker (useful for testing)
+ */
+function resetColdStartTracker() {
+  isFirstInvocation = true;
+  initTime = Date.now();
+}
+
+module.exports = {
+  coldStartTracker,
+  resetColdStartTracker,
+};
+

package/src/middleware/rate-limiter.js

@@ -0,0 +1,159 @@
+/**
+ * Rate Limiting Middleware
+ * v4: In-memory rate limiting with configurable windows
+ */
+
+class RateLimiter {
+  constructor(options = {}) {
+    this.windowMs = options.windowMs || 60000; // 1 minute default
+    this.max = options.max || 100; // 100 requests default
+    this.store = new Map(); // In-memory store
+    this.skipSuccessfulRequests = options.skipSuccessfulRequests || false;
+    this.skipFailedRequests = options.skipFailedRequests || false;
+    this.keyGenerator = options.keyGenerator || ((req) => {
+      // Default: IP address
+      return req.headers['x-forwarded-for']?.split(',')[0]?.trim() ||
+             req.headers['x-real-ip'] ||
+             'unknown';
+    });
+
+    // Cleanup old entries periodically
+    this.cleanupInterval = setInterval(() => {
+      this._cleanup();
+    }, this.windowMs);
+  }
+
+  /**
+   * Rate limit middleware
+   * @returns {Function} - Middleware function
+   */
+  middleware() {
+    const self = this; // Capture 'this' reference
+    
+    return async (req, res, next) => {
+      const key = self.keyGenerator(req);
+      const now = Date.now();
+
+      // Get or create rate limit entry
+      let entry = self.store.get(key);
+
+      if (!entry || now - entry.resetTime > self.windowMs) {
+        // Create new entry or reset expired one
+        entry = {
+          count: 0,
+          resetTime: now + self.windowMs,
+        };
+        self.store.set(key, entry);
+      }
+
+      // Increment count
+      entry.count++;
+
+      // Set rate limit headers
+      res.headers = res.headers || {};
+      res.headers['X-RateLimit-Limit'] = self.max.toString();
+      res.headers['X-RateLimit-Remaining'] = Math.max(0, self.max - entry.count).toString();
+      res.headers['X-RateLimit-Reset'] = new Date(entry.resetTime).toISOString();
+
+      // Check if limit exceeded
+      if (entry.count > self.max) {
+        res.statusCode = 429;
+        res.body = {
+          error: 'Too many requests',
+          retryAfter: Math.ceil((entry.resetTime - now) / 1000),
+        };
+        return;
+      }
+
+      // Track response status for skip options
+      const originalStatusCode = res.statusCode;
+      const originalFinish = res.finish || (() => {});
+      
+      // Wrap response finish to track status
+      res.finish = function(...args) {
+        const statusCode = res.statusCode || 200;
+        
+        if (self.skipSuccessfulRequests && statusCode < 400) {
+          entry.count = Math.max(0, entry.count - 1);
+        }
+        
+        if (self.skipFailedRequests && statusCode >= 400) {
+          entry.count = Math.max(0, entry.count - 1);
+        }
+
+        return originalFinish.apply(this, args);
+      };
+
+      next();
+    };
+  }
+
+  /**
+   * Cleanup expired entries
+   * @private
+   */
+  _cleanup() {
+    const now = Date.now();
+    for (const [key, entry] of this.store.entries()) {
+      if (now - entry.resetTime > this.windowMs) {
+        this.store.delete(key);
+      }
+    }
+  }
+
+  /**
+   * Reset rate limit for a key
+   * @param {string} key - Rate limit key
+   */
+  reset(key) {
+    this.store.delete(key);
+  }
+
+  /**
+   * Get rate limit info for a key
+   * @param {string} key - Rate limit key
+   * @returns {Object|null} - Rate limit info
+   */
+  get(key) {
+    const entry = this.store.get(key);
+    if (!entry) return null;
+
+    const now = Date.now();
+    if (now - entry.resetTime > this.windowMs) {
+      this.store.delete(key);
+      return null;
+    }
+
+    return {
+      count: entry.count,
+      remaining: Math.max(0, this.max - entry.count),
+      resetTime: entry.resetTime,
+    };
+  }
+
+  /**
+   * Destroy rate limiter (cleanup)
+   */
+  destroy() {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+    }
+    this.store.clear();
+  }
+}
+
+/**
+ * Create rate limit middleware
+ * @param {Object} options - Rate limit options
+ * @returns {Function} - Middleware function
+ */
+function rateLimit(options = {}) {
+  const limiter = new RateLimiter(options);
+  return limiter.middleware();
+}
+
+module.exports = {
+  rateLimit,
+  RateLimiter,
+};
+

package/src/utils/lazy-init.js

@@ -0,0 +1,100 @@
+/**
+ * Lazy Initialization Utility
+ * v3.1: Defer heavy initialization until needed (reduces cold start time)
+ */
+
+class LazyInit {
+  constructor(options = {}) {
+    this.initialized = false;
+    this.initPromise = null;
+    this.initFn = null;
+    this.autoInit = options.autoInit !== false; // Auto-init on first access
+    this.cacheResult = options.cacheResult !== false; // Cache initialization result
+    this.cachedResult = null;
+  }
+
+  /**
+   * Initialize with a function
+   * @param {Function} initFn - Initialization function (can be async)
+   * @returns {Promise} - Initialization promise
+   */
+  async init(initFn) {
+    if (this.initialized && this.cacheResult) {
+      return this.cachedResult;
+    }
+
+    if (!this.initPromise) {
+      this.initFn = initFn;
+      this.initPromise = Promise.resolve(initFn()).then(result => {
+        this.initialized = true;
+        if (this.cacheResult) {
+          this.cachedResult = result;
+        }
+        return result;
+      }).catch(error => {
+        // Reset on error so it can be retried
+        this.initPromise = null;
+        throw error;
+      });
+    }
+
+    return this.initPromise;
+  }
+
+  /**
+   * Check if initialized
+   * @returns {boolean} - True if initialized
+   */
+  isInitialized() {
+    return this.initialized;
+  }
+
+  /**
+   * Get cached result (if available)
+   * @returns {*} - Cached initialization result
+   */
+  getCached() {
+    return this.cachedResult;
+  }
+
+  /**
+   * Reset initialization state
+   */
+  reset() {
+    this.initialized = false;
+    this.initPromise = null;
+    this.cachedResult = null;
+  }
+
+  /**
+   * Execute function with lazy initialization
+   * @param {Function} fn - Function to execute after initialization
+   * @returns {Promise} - Result of function execution
+   */
+  async withInit(fn) {
+    if (!this.initialized && this.initFn) {
+      await this.init(this.initFn);
+    }
+    return await fn(this.cachedResult);
+  }
+}
+
+/**
+ * Create a lazy initializer
+ * @param {Function} initFn - Initialization function
+ * @param {Object} options - Options
+ * @returns {LazyInit} - LazyInit instance
+ */
+function createLazyInit(initFn, options = {}) {
+  const lazy = new LazyInit(options);
+  if (initFn) {
+    lazy.initFn = initFn;
+  }
+  return lazy;
+}
+
+module.exports = {
+  LazyInit,
+  createLazyInit,
+};
+