Node.js Middleware That Won't Ruin Your Weekend

Middleware sounds simple until production happens. You write a nice clean function, it works fine on your laptop, then at 2am it's eating all your server memory or hanging requests forever. I've been there. We've all been there.

The problem is that most middleware tutorials show you the happy path - they never mention that your authentication middleware will block everything when Redis goes down, or that your logging middleware will consume 2GB of memory if someone sends a 100MB request body.

The Reality Check: What Actually Gets Downloaded (September 2025)

Here's what's actually getting downloaded (checked npm-stat last week):

• Express.js: Still crushing it with something like 45M+ weekly downloads - the 800-pound gorilla isn't going anywhere
• Koa.js: Around 5M weekly downloads - solid but not exciting
• Fastify: Roughly 3M weekly downloads - the performance darling

Express isn't going anywhere despite what HackerNews tells you. It's boring, predictable, and has middleware for literally everything. Fastify is faster and has better architecture, but good luck finding middleware for that obscure OAuth provider you need to integrate with.

The Node.js ecosystem has evolved around Express patterns. When you look at production deployment guides, security best practices, and monitoring solutions, they all assume Express middleware patterns. This ecosystem momentum is why major companies still build on Express despite faster alternatives.

The real difference isn't those synthetic benchmarks (hello world apps don't represent real workloads) - it's whether your middleware will work when things go wrong. Express middleware fails loudly and obviously. Fastify's plugin system is elegant until you need to debug why your authentication isn't loading in the right order.

Express.js: Where Dreams Go to Die (And Sometimes Live)

Express middleware is just a function that gets req, res, and next. Sounds simple, right? It is, until you forget to call `next()` and wonder why half your routes stopped working. Or when you call next() twice and get that cryptic "Cannot set headers after they are sent" error.

The Production Nightmare Stories

Every Express app is middleware stacked on middleware stacked on more middleware. One bad middleware kills everything downstream. Here's the fun part - you won't know which one until 3am on a Friday.

I once spent 4 hours debugging random API timeouts. Turns out some genius added body parsing middleware that tried to shove 50MB file uploads into memory. No error, no log, just... silence. Like the server gave up on life. Another time, our rate limiting middleware started rejecting every request because the Redis connection pool was exhausted, but the middleware didn't handle connection failures. It just hung forever waiting for a response that would never come.

Production middleware failures follow predictable patterns. Memory leaks from unbounded arrays, unhandled promise rejections that crash the process, connection pool exhaustion, and race conditions in shared state. The Node.js debugging guide helps, but middleware bugs are context-dependent - they only surface under specific request patterns or loads.

Middleware That Actually Works

Here's logging middleware that won't kill your server:

// This took me way too long to get right, and it still breaks sometimes
function requestLogger(options = {}) {
  const { includeBody = false, maxBodySize = 1024 } = options;
  // TODO: make this configurable instead of hardcoded
  const sensitiveFields = ['password', 'token', 'authorization', 'cookie'];

  return (req, res, next) => {
    const start = process.hrtime.bigint();

    // Don't log health checks - they spam the shit out of the logs
    if (req.url === '/health' || req.url === '/ping') {
      return next();
    }

    const requestData = {
      method: req.method,
      url: req.url,
      ip: req.ip || 'unknown', // Sometimes this is undefined, Node.js is weird
      userAgent: req.get('User-Agent') || 'none'
    };

    // Only log body if it's small - learned this the hard way after a 50MB upload killed our logs
    if (includeBody && req.body) {
      try {
        // This JSON.stringify can throw if there's circular refs, ask me how I know
        const bodyStr = JSON.stringify(req.body);
        if (bodyStr.length < maxBodySize) {
          requestData.body = sanitizeObject(req.body, sensitiveFields);
        }
      } catch (err) {
        requestData.body = '[CIRCULAR_OR_FAILED_TO_STRINGIFY]'; // Happened more than I'd like to admit
      }
    }

    res.on('finish', () => {
      const duration = Number(process.hrtime.bigint() - start) / 1000000;

      // Only log slow requests to reduce noise - trust me, you don't want every request logged
      if (duration > 100) {
        console.log(JSON.stringify({
          ...requestData,
          statusCode: res.statusCode,
          duration: `${duration.toFixed(2)}ms`,
          warning: duration > 1000 ? 'SLOW_REQUEST' : undefined
        }));
      }
    });

    next();
  };
}

function sanitizeObject(obj, sensitiveFields) {
  if (!obj || typeof obj !== 'object') return obj;

  const sanitized = { ...obj };
  sensitiveFields.forEach(field => {
    // Handle nested fields like \"auth.password\"
    if (sanitized[field]) {
      sanitized[field] = '[REDACTED]';
    }
  });
  return sanitized;
}

Authentication: The Place Where Everything Goes Wrong

JWT authentication seems easy until you realize there are like 50 different ways it can fail. Missing tokens, expired tokens, malformed tokens, wrong algorithms, clock drift, and my personal favorite: when someone puts the JWT secret in the wrong environment variable and it takes down prod for 2 hours.

The JWT specification is deceptively simple, but production implementations need to handle algorithm confusion attacks, timing attacks on HMAC verification, and key rotation scenarios. The OWASP JWT Security Cheat Sheet covers the security pitfalls, while Auth0's JWT handbook explains the cryptographic details.

const jwt = require('jsonwebtoken');

function createAuthMiddleware(options = {}) {
  const {
    secret = process.env.JWT_SECRET,
    skipPaths = ['/health', '/ping', '/metrics'],
    optional = false
  } = options;

  // Fail fast during startup, not during request handling - learned this after 2am debugging session in December 2023
  if (!secret && !optional) {
    throw new Error('JWT_SECRET missing - seriously, set the damn environment variable');
  }

  // TODO: add support for rotating secrets, but that's a problem for future me

  return async (req, res, next) => {
    // Skip auth for health checks and public paths
    if (skipPaths.includes(req.path) || req.path.startsWith('/public/')) {
      return next();
    }

    const authHeader = req.headers.authorization;
    // Handle both \"Bearer TOKEN\" and just \"TOKEN\" because clients are inconsistent
    const token = authHeader?.startsWith('Bearer ')
      ? authHeader.slice(7)
      : authHeader;

    if (!token) {
      if (optional) {
        req.user = null;
        return next();
      }
      return res.status(401).json({
        error: 'Missing authorization header',
        code: 'NO_TOKEN',
        hint: 'Add Authorization: Bearer <your-token>'
      });
    }

    try {
      // Clock tolerance for servers with slightly different times
      const decoded = jwt.verify(token, secret, {
        algorithms: ['HS256'],
        clockTolerance: 30 // 30 seconds wiggle room
      });

      // Extra paranoia checks
      if (!decoded.sub) {
        return res.status(401).json({
          error: 'Token missing user ID',
          code: 'INVALID_CLAIMS'
        });
      }

      req.user = decoded;
      next();
    } catch (error) {
      // Be specific about what went wrong
      let errorResponse = {
        error: 'Token verification failed',
        code: 'AUTH_ERROR'
      };

      if (error.name === 'TokenExpiredError') {
        errorResponse = {
          error: 'Token expired',
          code: 'TOKEN_EXPIRED',
          hint: 'Get a new token from /auth/refresh'
        };
      } else if (error.name === 'JsonWebTokenError') {
        errorResponse = {
          error: 'Invalid token format',
          code: 'MALFORMED_TOKEN'
        };
      }

      // Log for debugging but don't expose internals - spent 3 hours once because I wasn't logging enough
      console.warn('Auth failed:', {
        error: error.message,
        token: token.substring(0, 20) + '...',
        ip: req.ip,
        userAgent: req.get('User-Agent')
        // TODO: add request ID for better tracing, but the logging system sucks
      });

      res.status(401).json(errorResponse);
    }
  };
}

The point is: auth middleware breaks in production in ways that make absolutely no sense at 3am. Plan for every failure mode or spend your weekends debugging why your API suddenly locked everyone out. Ask me how I know. (Spoiler: Node 18 changed crypto defaults and broke our JWT verification for exactly 3 hours on a Saturday.)

Fastify: When Express Isn't Fast Enough (But Do You Really Need It?)

Fastify's plugin system is genuinely elegant. Instead of stacking middleware like Express, you register plugins that have their own isolated scope. It's like microservices for your middleware - which sounds great until you need to debug why Plugin A can't see the configuration from Plugin B.

The Fastify Reality Check

Fastify plugins solve real problems:

1. Encapsulation: Your auth plugin can't accidentally break your logging plugin
2. Performance: Schema validation is compiled once at startup, not on every request
3. Dependency injection: Plugins declare what they need and load in the right order

But they also create new problems:

1. Debugging hell: Error stack traces through plugin loading are... not fun
2. Learning curve: Express middleware is just functions. Fastify plugins have lifecycle hooks, decorators, and registration patterns
3. Ecosystem: Still smaller than Express, though growing fast

Here's Fastify auth that actually works (most of the time):

const fp = require('fastify-plugin');

async function authPlugin(fastify, options) {
  const {
    secret = process.env.JWT_SECRET,
    skipRoutes = ['/health', '/ping'],
    optional = false
  } = options;

  if (!secret && !optional) {
    throw new Error('JWT_SECRET missing - this will break everything');
  }

  // Register the JWT plugin - this can fail in weird ways
  try {
    await fastify.register(require('@fastify/jwt'), {
      secret: secret
    });
  } catch (error) {
    // If JWT plugin fails to register, the whole app won't start
    fastify.log.error('JWT plugin registration failed:', error);
    throw error;
  }

  // This decorator gets added to every request
  fastify.decorate('authenticate', async function(request, reply) {
    if (skipRoutes.includes(request.routerPath) || skipRoutes.includes(request.url)) {
      return;
    }

    try {
      await request.jwtVerify();
      // At this point request.user is populated (hopefully)
    } catch (err) {
      if (optional) {
        request.user = null;
        return;
      }

      // Fastify JWT error codes are... inconsistent
      let errorMsg = 'Token verification failed';
      if (err.code === 'FST_JWT_NO_AUTHORIZATION_IN_HEADER') {
        errorMsg = 'Missing Authorization header';
      } else if (err.code === 'FST_JWT_AUTHORIZATION_TOKEN_EXPIRED') {
        errorMsg = 'Token expired - get a new one';
      } else if (err.code === 'FST_JWT_AUTHORIZATION_TOKEN_INVALID') {
        errorMsg = 'Token is malformed or invalid';
      }

      // Log for debugging because Fastify errors can be cryptic - this saved my ass when debugging plugin load order in Fastify 4.2
      fastify.log.warn('Auth failure:', {
        error: err.message,
        code: err.code,
        url: request.url,
        ip: request.ip
      });

      return reply.code(401).send({
        error: errorMsg,
        code: 'AUTH_FAILED'
      });
    }
  });

  // Role checking that actually checks roles
  fastify.decorate('requireRole', function(allowedRoles = []) {
    return async function(request, reply) {
      if (!request.user) {
        return reply.code(401).send({ error: 'Not authenticated' });
      }

      const userRoles = request.user.roles || [];
      const hasPermission = allowedRoles.some(role => userRoles.includes(role));

      if (!hasPermission) {
        fastify.log.warn('Role check failed:', {
          user: request.user.id,
          userRoles,
          required: allowedRoles
        });

        return reply.code(403).send({
          error: 'Insufficient permissions',
          required: allowedRoles,
          current: userRoles
        });
      }
    };
  });
}

// The fp wrapper is important - without it, plugin scope gets weird
module.exports = fp(authPlugin, {
  name: 'auth-plugin',
  version: '1.0.0',
  dependencies: ['@fastify/jwt'] // This plugin won't load until @fastify/jwt is ready
});

Schema Validation: Fastify's Secret Weapon

One of Fastify's biggest advantages is built-in JSON Schema validation. This isn't just input validation - it's performance optimization. Fastify compiles schemas at startup and uses them for both validation and response serialization.

// Fastify route with comprehensive schema validation
const userRouteSchema = {
  body: {
    type: 'object',
    required: ['email', 'password'],
    properties: {
      email: {
        type: 'string',
        format: 'email',
        maxLength: 255
      },
      password: {
        type: 'string',
        minLength: 8,
        maxLength: 128,
        pattern: '^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d)(?=.*[@$!%*?&])[A-Za-z\\d@$!%*?&]'
      },
      name: {
        type: 'string',
        minLength: 1,
        maxLength: 100
      }
    },
    additionalProperties: false
  },
  response: {
    201: {
      type: 'object',
      properties: {
        id: { type: 'string', format: 'uuid' },
        email: { type: 'string', format: 'email' },
        name: { type: 'string' },
        createdAt: { type: 'string', format: 'date-time' }
      }
    },
    400: {
      type: 'object',
      properties: {
        error: { type: 'string' },
        code: { type: 'string' },
        validation: {
          type: 'array',
          items: {
            type: 'object',
            properties: {
              field: { type: 'string' },
              message: { type: 'string' }
            }
          }
        }
      }
    }
  }
};

fastify.post('/users', {
  schema: userRouteSchema,
  preHandler: [fastify.authenticate]
}, async (request, reply) => {
  const { email, password, name } = request.body;

  try {
    const user = await createUser({ email, password, name });
    reply.code(201).send({
      id: user.id,
      email: user.email,
      name: user.name,
      createdAt: user.createdAt
    });
  } catch (error) {
    if (error.code === 'ER_DUP_ENTRY') {
      return reply.code(409).send({
        error: 'Email already exists',
        code: 'DUPLICATE_EMAIL'
      });
    }

    fastify.log.error('User creation failed:', error);
    reply.code(500).send({
      error: 'Internal server error',
      code: 'CREATE_USER_FAILED'
    });
  }
});

The schema validation above happens at startup compilation, not runtime, making it significantly faster than manual validation. More importantly, the response schema ensures consistent API contracts and enables automatic OpenAPI documentation generation.

Performance Considerations: The Hidden Costs

Middleware performance isn't just about execution time - it's about memory usage, error handling, and scalability patterns that only become apparent under load.

Memory Leaks in Middleware

The most common middleware performance killer is memory leaks caused by closures that hold references to large objects. Here's a pattern that will slowly consume all available memory:

// DON'T DO THIS - Memory leak waiting to happen
function badLoggingMiddleware() {
  const requestHistory = []; // This array grows forever

  return (req, res, next) => {
    requestHistory.push({
      url: req.url,
      body: req.body, // Keeps entire request body in memory
      timestamp: Date.now()
    });

    console.log(`Total requests: ${requestHistory.length}`);
    next();
  };
}

The correct approach uses bounded collections or external storage:

// Better: Bounded logging with LRU cache
const LRU = require('lru-cache');

function smartLoggingMiddleware(options = {}) {
  const { maxEntries = 1000, maxAge = 60000 } = options;

  const requestCache = new LRU({
    max: maxEntries,
    ttl: maxAge
  });

  return (req, res, next) => {
    const requestId = `${req.method}:${req.url}:${Date.now()}`;

    requestCache.set(requestId, {
      method: req.method,
      url: req.url,
      userAgent: req.get('User-Agent'),
      timestamp: Date.now()
    });

    // Log statistics without keeping full history
    console.log(`Active requests in cache: ${requestCache.size}`);
    next();
  };
}

The difference is dramatic: the bad middleware will consume 100MB+ of memory after handling 10,000 requests, while the LRU-based version maintains constant memory usage.

This foundation sets the stage for understanding how modern Node.js middleware and plugins work in practice. The next sections will dive into specific implementation patterns, testing strategies, and production deployment considerations that separate amateur middleware from enterprise-grade components.

Look, most middleware tutorials are garbage. They show you the happy path and call it a day. But production doesn't give a shit about your happy path. Production will find every edge case, every race condition, and every memory leak you didn't think of. Here's what actually matters when your middleware needs to handle real traffic.

The difference between toy middleware and production middleware is error handling patterns, resource management, and observability. Production-grade Node.js applications require middleware that gracefully handles failures, provides useful diagnostics, and doesn't leak resources under load.

When Your Middleware Actually Has to Work

Here's the thing nobody tells you: middleware doesn't just handle requests. It lives through your entire application lifecycle. Your request/response cycle is maybe 30% of what can go wrong. The other 70% happens during startup, configuration loading, shutdown, and all the monitoring that keeps you from getting paged at 3am.

Initialization: The Place Where Everything Goes Wrong First

Most tutorials skip the initialization phase entirely. They just show you the middleware function and call it a day. That's fine for hello world, but useless for anything that needs to actually work. Real middleware needs config validation, dependency checks, and graceful startup. Skip any of these and you'll be debugging at 2am.

// Rate limiter that actually works (most of the time)
function createRateLimiter(options = {}) {
  // Validate config at startup, not runtime - learned this after Redis credentials broke prod at 2:30am on Black Friday 2023
  const config = validateRateLimiterConfig(options);

  // Initialize dependencies during startup, not on first request
  let redisClient;
  let isHealthy = false; // TODO: make this more nuanced, Redis has many failure modes

  const initializeRedis = async () => {
    try {
      redisClient = new Redis(config.redis);
      await redisClient.ping();
      isHealthy = true;
      console.log('Rate limiter Redis connection established');
    } catch (error) {
      console.error('Rate limiter Redis initialization failed:', error);

      if (config.failOpen) {
        console.warn('Rate limiter running in fail-open mode');
        isHealthy = false;
      } else {
        throw error; // Fail startup if rate limiting is critical
      }
    }
  };

  // Initialize immediately, not on first request
  initializeRedis();

  // Return middleware function with closed-over dependencies
  return async (req, res, next) => {
    // Health check - fail fast if dependencies are down
    if (!isHealthy && !config.failOpen) {
      return res.status(503).json({
        error: 'Rate limiting service unavailable',
        code: 'RATE_LIMITER_DOWN'
      });
    }

    const key = generateRateLimitKey(req, config);
    const windowStart = Math.floor(Date.now() / config.windowMs) * config.windowMs;

    try {
      if (isHealthy) {
        const current = await redisClient.incr(`ratelimit:${key}:${windowStart}`);

        if (current === 1) {
          await redisClient.expire(`ratelimit:${key}:${windowStart}`,
                                   Math.ceil(config.windowMs / 1000));
        }

        if (current > config.limit) {
          return res.status(429).json({
            error: 'Rate limit exceeded',
            code: 'RATE_LIMITED',
            resetTime: windowStart + config.windowMs
          });
        }
      }

      next();
    } catch (error) {
      console.error('Rate limiter error:', error);

      if (config.failOpen) {
        console.warn('Rate limiter failing open due to error');
        next();
      } else {
        res.status(503).json({
          error: 'Rate limiting service error',
          code: 'RATE_LIMITER_ERROR'
        });
      }
    }
  };
}

function validateRateLimiterConfig(options) {
  const defaults = {
    limit: 100,
    windowMs: 60000, // 1 minute
    failOpen: false, // Fail closed by default for security
    redis: { host: 'localhost', port: 6379 }
  };

  const config = { ...defaults, ...options };

  if (typeof config.limit !== 'number' || config.limit <= 0) {
    throw new Error('Rate limit must be a positive number');
  }

  if (typeof config.windowMs !== 'number' || config.windowMs <= 0) {
    throw new Error('Window size must be a positive number in milliseconds');
  }

  return config;
}

This initialization pattern handles the most common production failures: dependency services being unavailable at startup, configuration errors, and runtime service degradation. The key insight is that middleware should fail fast during initialization, not during request handling.

The fail-fast principle reduces debugging time by surfacing problems early. Circuit breaker patterns prevent cascading failures, while health check endpoints enable external monitoring. Graceful degradation strategies allow applications to continue operating with reduced functionality when dependencies fail.

Error Boundaries: Containing the Blast Radius

Middleware errors have a nasty habit of taking down entire applications. The solution is implementing proper error boundaries that isolate failures and provide meaningful diagnostics.

Error boundary patterns originated in React applications but apply broadly to any component-based architecture. Fault isolation prevents failures from propagating through the system, while bulkhead patterns protect critical resources from being consumed by failing components.

// Error boundary middleware wrapper
function withErrorBoundary(middlewareFunction, options = {}) {
  const {
    name = middlewareFunction.name || 'anonymous',
    fallback = null,
    logErrors = true,
    metrics = null
  } = options;

  return async (req, res, next) => {
    try {
      await middlewareFunction(req, res, next);
    } catch (error) {
      if (logErrors) {
        console.error(`Middleware error in ${name}:`, {
          error: error.message,
          stack: error.stack,
          request: {
            method: req.method,
            url: req.url,
            ip: req.ip,
            userAgent: req.get('User-Agent')
          }
        });
      }

      if (metrics) {
        metrics.increment(`middleware.${name}.errors`);
      }

      if (fallback) {
        try {
          await fallback(req, res, next, error);
        } catch (fallbackError) {
          console.error(`Fallback error in ${name}:`, fallbackError);
          next(fallbackError);
        }
      } else {
        // Don't expose internal errors to clients
        const publicError = new Error('Internal middleware error');
        publicError.status = 500;
        publicError.code = 'MIDDLEWARE_ERROR';
        next(publicError);
      }
    }
  };
}

// Usage with fallback behavior
const rateLimiter = withErrorBoundary(
  createRateLimiter({ limit: 100, windowMs: 60000 }),
  {
    name: 'rate-limiter',
    fallback: async (req, res, next, error) => {
      // Log the rate limiter failure but allow request through
      console.warn('Rate limiter failed, allowing request through');
      next();
    }
  }
);

Advanced Authentication Patterns

Authentication middleware in production needs to handle token refresh, role-based access control, and integration with external identity providers. Here's a comprehensive authentication system that handles real-world requirements:

Auth in production is where everything goes sideways. OAuth 2.0 is supposed to be simple until you need to handle token refresh, clock drift, and the joy of debugging why your JWT secret is wrong in prod but works fine locally.

// Multi-strategy authentication middleware
const jwt = require('jsonwebtoken');
const { promisify } = require('util');

class AuthenticationManager {
  constructor(options = {}) {
    this.config = {
      strategies: ['jwt', 'apikey'],
      jwt: {
        secret: process.env.JWT_SECRET,
        algorithms: ['HS256'],
        clockTolerance: 30 // 30 seconds clock drift tolerance
      },
      apikey: {
        headerName: 'x-api-key',
        lookup: this.lookupApiKey.bind(this)
      },
      cache: {
        ttl: 300000, // 5 minutes
        maxSize: 1000
      },
      ...options
    };

    this.userCache = new Map();
    this.setupCacheCleanup();
  }

  // JWT authentication strategy
  async authenticateJWT(req) {
    const token = this.extractJWTToken(req);
    if (!token) return null;

    try {
      const decoded = jwt.verify(token, this.config.jwt.secret, {
        algorithms: this.config.jwt.algorithms,
        clockTolerance: this.config.jwt.clockTolerance
      });

      return this.enrichUserData(decoded);
    } catch (error) {
      if (error.name === 'TokenExpiredError') {
        throw new AuthError('Token expired', 'TOKEN_EXPIRED', 401);
      }
      if (error.name === 'JsonWebTokenError') {
        throw new AuthError('Invalid token', 'INVALID_TOKEN', 401);
      }
      throw new AuthError('Token verification failed', 'AUTH_FAILED', 401);
    }
  }

  // API key authentication strategy
  async authenticateAPIKey(req) {
    const apiKey = req.get(this.config.apikey.headerName);
    if (!apiKey) return null;

    // Check cache first
    const cacheKey = `apikey:${apiKey}`;
    if (this.userCache.has(cacheKey)) {
      const cachedData = this.userCache.get(cacheKey);
      if (Date.now() - cachedData.timestamp < this.config.cache.ttl) {
        return cachedData.user;
      }
      this.userCache.delete(cacheKey);
    }

    // Lookup API key
    const user = await this.config.apikey.lookup(apiKey);
    if (!user) {
      throw new AuthError('Invalid API key', 'INVALID_API_KEY', 401);
    }

    // Cache successful lookups
    this.userCache.set(cacheKey, {
      user,
      timestamp: Date.now()
    });

    return user;
  }

  // Main authentication middleware
  authenticate(options = {}) {
    const { optional = false, strategies = this.config.strategies } = options;

    return async (req, res, next) => {
      let lastError;
      let user = null;

      // Try each strategy in order
      for (const strategy of strategies) {
        try {
          switch (strategy) {
            case 'jwt':
              user = await this.authenticateJWT(req);
              break;
            case 'apikey':
              user = await this.authenticateAPIKey(req);
              break;
            default:
              console.warn(`Unknown authentication strategy: ${strategy}`);
          }

          if (user) {
            req.user = user;
            return next();
          }
        } catch (error) {
          lastError = error;
          // Continue trying other strategies unless it's a definitive failure
          if (error.code === 'TOKEN_EXPIRED' || error.code === 'INVALID_TOKEN') {
            continue;
          }
        }
      }

      // No successful authentication
      if (optional) {
        req.user = null;
        return next();
      }

      // Return the most relevant error
      if (lastError) {
        return res.status(lastError.status || 401).json({
          error: lastError.message,
          code: lastError.code || 'AUTH_FAILED'
        });
      }

      res.status(401).json({
        error: 'Authentication required',
        code: 'AUTH_REQUIRED'
      });
    };
  }

  // Role-based authorization
  authorize(requiredRoles = [], options = {}) {
    const { requireAll = false } = options;

    return (req, res, next) => {
      if (!req.user) {
        return res.status(401).json({
          error: 'Authentication required',
          code: 'AUTH_REQUIRED'
        });
      }

      if (requiredRoles.length === 0) {
        return next();
      }

      const userRoles = req.user.roles || [];
      const hasPermission = requireAll
        ? requiredRoles.every(role => userRoles.includes(role))
        : requiredRoles.some(role => userRoles.includes(role));

      if (!hasPermission) {
        return res.status(403).json({
          error: 'Insufficient permissions',
          code: 'FORBIDDEN',
          required: requiredRoles,
          current: userRoles
        });
      }

      next();
    };
  }

  extractJWTToken(req) {
    const authHeader = req.headers.authorization;
    if (authHeader && authHeader.startsWith('Bearer ')) {
      return authHeader.slice(7);
    }n
    // Also check for token in cookies or query params if configured
    return req.cookies?.token || req.query?.token || null;
  }

  async enrichUserData(user) {
    // Add additional user data from database, external services, etc.
    return {
      ...user,
      permissions: await this.getUserPermissions(user.id),
      lastSeen: new Date()
    };
  }

  async lookupApiKey(apiKey) {
    // Implement API key lookup logic
    // This would typically query a database or external service
    return null;
  }

  async getUserPermissions(userId) {
    // Implement permission lookup
    return [];
  }

  setupCacheCleanup() {
    // Clean up expired cache entries every 5 minutes
    setInterval(() => {
      const now = Date.now();
      for (const [key, value] of this.userCache.entries()) {
        if (now - value.timestamp > this.config.cache.ttl) {
          this.userCache.delete(key);
        }
      }
    }, 300000);
  }
}

class AuthError extends Error {
  constructor(message, code, status) {
    super(message);
    this.name = 'AuthError';
    this.code = code;
    this.status = status;
  }
}

// Usage
const authManager = new AuthenticationManager({
  jwt: {
    secret: process.env.JWT_SECRET,
    algorithms: ['HS256']
  },
  apikey: {
    headerName: 'x-api-key',
    lookup: async (apiKey) => {
      // Database lookup logic
      const user = await db.users.findOne({ apiKey });
      return user;
    }
  }
});

// Apply to routes
app.use('/api/protected', authManager.authenticate());
app.use('/api/admin', authManager.authenticate(), authManager.authorize(['admin']));
app.get('/api/user', authManager.authenticate({ optional: true }), (req, res) => {
  // Works for both authenticated and anonymous users
});

This authentication system demonstrates several production-ready patterns:

• Multiple authentication strategies with fallback behavior
• Caching to reduce database load for API key lookups
• Proper error handling with meaningful error codes
• Role-based authorization with flexible permission checking
• Memory management with cache cleanup to prevent memory leaks

Performance Monitoring and Metrics

Production middleware needs observability. Without metrics, you're flying blind when performance issues arise. Here's a comprehensive monitoring middleware that tracks the metrics that actually matter:

Effective observability requires structured logging, distributed tracing, application metrics, and error aggregation. The twelve-factor app methodology emphasizes treating logs as event streams, while monitoring best practices focus on measuring user experience and system reliability.

// Performance monitoring middleware
const { performance } = require('perf_hooks');

class MiddlewareMetrics {
  constructor(options = {}) {
    this.config = {
      sampleRate: 1.0, // Sample 100% of requests
      slowRequestThreshold: 1000, // 1 second
      trackMemory: true,
      trackDetailedTiming: true,
      ...options
    };

    this.metrics = {
      requests: new Map(),
      responses: new Map(),
      errors: new Map(),
      timing: {
        total: [],
        middleware: new Map()
      }
    };

    this.setupReporting();
  }

  // Request tracking middleware
  trackRequests() {
    return (req, res, next) => {
      // Sample requests based on configured rate
      if (Math.random() > this.config.sampleRate) {
        return next();
      }

      const startTime = performance.now();
      const startMemory = this.config.trackMemory ? process.memoryUsage() : null;

      // Unique request ID for tracing
      req.trackingId = `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;

      // Track middleware execution times
      const originalNext = next;
      const middlewareTimes = [];
      let lastMiddlewareTime = startTime;

      req.trackMiddleware = (name) => {
        const now = performance.now();
        middlewareTimes.push({
          name,
          duration: now - lastMiddlewareTime
        });
        lastMiddlewareTime = now;
      };

      // Response finished handler
      res.on('finish', () => {
        const endTime = performance.now();
        const duration = endTime - startTime;
        const endMemory = this.config.trackMemory ? process.memoryUsage() : null;

        this.recordRequestMetrics({
          id: req.trackingId,
          method: req.method,
          route: req.route?.path || req.path,
          statusCode: res.statusCode,
          duration,
          startTime,
          endTime,
          startMemory,
          endMemory,
          middlewareTimes,
          userAgent: req.get('User-Agent'),
          ip: req.ip,
          contentLength: res.get('content-length')
        });

        // Log slow requests
        if (duration > this.config.slowRequestThreshold) {
          console.warn(`Slow request detected: ${req.method} ${req.path} - ${duration.toFixed(2)}ms`);
        }
      });

      next();
    };
  }

  // Individual middleware tracking
  trackMiddleware(name, middlewareFunc) {
    return async (req, res, next) => {
      if (!req.trackingId) return middlewareFunc(req, res, next);

      const startTime = performance.now();

      try {
        await middlewareFunc(req, res, () => {
          const duration = performance.now() - startTime;
          req.trackMiddleware?.(name);

          // Track middleware-specific metrics
          this.recordMiddlewareMetrics(name, duration, 'success');
          next();
        });
      } catch (error) {
        const duration = performance.now() - startTime;
        this.recordMiddlewareMetrics(name, duration, 'error');
        throw error;
      }
    };
  }

  recordRequestMetrics(data) {
    // Update request counters
    const routeKey = `${data.method}:${data.route}`;
    const current = this.metrics.requests.get(routeKey) || {
      count: 0,
      totalDuration: 0,
      errors: 0,
      statusCodes: new Map()
    };

    current.count++;
    current.totalDuration += data.duration;

    if (data.statusCode >= 400) {
      current.errors++;
    }

    const statusCount = current.statusCodes.get(data.statusCode) || 0;
    current.statusCodes.set(data.statusCode, statusCount + 1);

    this.metrics.requests.set(routeKey, current);

    // Record timing distribution
    this.metrics.timing.total.push(data.duration);

    // Keep only last 1000 timings to prevent memory growth
    if (this.metrics.timing.total.length > 1000) {
      this.metrics.timing.total = this.metrics.timing.total.slice(-1000);
    }
  }

  recordMiddlewareMetrics(name, duration, status) {
    const current = this.metrics.timing.middleware.get(name) || {
      count: 0,
      totalDuration: 0,
      errors: 0,
      timings: []
    };

    current.count++;
    current.totalDuration += duration;
    current.timings.push(duration);

    if (status === 'error') {
      current.errors++;
    }

    // Keep only last 100 timings per middleware
    if (current.timings.length > 100) {
      current.timings = current.timings.slice(-100);
    }

    this.metrics.timing.middleware.set(name, current);
  }

  // Generate comprehensive metrics report
  getMetricsReport() {
    const report = {
      requests: {},
      middleware: {},
      system: {
        uptime: process.uptime(),
        memory: process.memoryUsage(),
        nodeVersion: process.version
      },
      timestamp: new Date().toISOString()
    };

    // Request metrics
    for (const [route, data] of this.metrics.requests.entries()) {
      const avgDuration = data.count > 0 ? data.totalDuration / data.count : 0;
      const errorRate = data.count > 0 ? (data.errors / data.count) * 100 : 0;

      report.requests[route] = {
        count: data.count,
        averageResponseTime: Math.round(avgDuration * 100) / 100,
        errorRate: Math.round(errorRate * 100) / 100,
        statusCodes: Object.fromEntries(data.statusCodes)
      };
    }

    // Middleware metrics
    for (const [name, data] of this.metrics.timing.middleware.entries()) {
      const avgDuration = data.count > 0 ? data.totalDuration / data.count : 0;
      const p95 = this.calculatePercentile(data.timings, 0.95);
      const errorRate = data.count > 0 ? (data.errors / data.count) * 100 : 0;

      report.middleware[name] = {
        count: data.count,
        averageTime: Math.round(avgDuration * 100) / 100,
        p95Time: Math.round(p95 * 100) / 100,
        errorRate: Math.round(errorRate * 100) / 100
      };
    }

    return report;
  }

  calculatePercentile(values, percentile) {
    if (values.length === 0) return 0;

    const sorted = [...values].sort((a, b) => a - b);
    const index = Math.ceil(sorted.length * percentile) - 1;
    return sorted[index] || 0;
  }

  setupReporting() {
    // Report metrics every minute
    setInterval(() => {
      const report = this.getMetricsReport();
      console.log('Middleware Metrics:', JSON.stringify(report, null, 2));

      // Reset counters to prevent memory growth
      this.resetCounters();
    }, 60000);
  }

  resetCounters() {
    // Keep data but reset some counters to prevent unbounded growth
    this.metrics.timing.total = this.metrics.timing.total.slice(-100);

    for (const [name, data] of this.metrics.timing.middleware.entries()) {
      data.timings = data.timings.slice(-50);
    }
  }
}

// Usage
const metrics = new MiddlewareMetrics({
  sampleRate: 0.1, // Sample 10% of requests in production
  slowRequestThreshold: 500 // Alert on requests over 500ms
});

app.use(metrics.trackRequests());

// Track specific middleware
app.use('/api', metrics.trackMiddleware('authentication', authMiddleware));
app.use('/api', metrics.trackMiddleware('rate-limiting', rateLimiter));

This monitoring system provides the visibility needed to optimize middleware performance in production. It tracks the metrics that matter: response times, error rates, and resource usage, while preventing memory leaks through bounded data structures and periodic cleanup.

Effective production monitoring requires integrating with APM tools, logging aggregators, and alerting systems. SRE principles emphasize measuring service level indicators, while observability best practices focus on correlation across logs, metrics, and traces.

The patterns shown here - proper initialization, error boundaries, comprehensive authentication, and performance monitoring - form the foundation of middleware that can handle production loads reliably. The next section will cover testing strategies that ensure these patterns work correctly under all conditions.

Building middleware is only half the battle. The other half is making sure it doesn't shit the bed when someone else tries to use it, and actually getting it into developers' hands without them wanting to murder you.

Modern software testing principles emphasize the testing pyramid: many unit tests, some integration tests, and few end-to-end tests. For middleware, this translates to isolated unit tests with mocked dependencies, integration tests with real services, and contract tests that verify API compatibility across versions.

Testing Strategies That Actually Work

Testing middleware is a special kind of hell. Unit tests pass, integration tests pass, then production breaks because nobody tested what happens when Redis has a bad day and your rate limiter starts accepting every request.

The Three-Layer Testing Approach

Layer 1: Unit Tests test individual middleware functions in isolation. Layer 2: Integration Tests test middleware with real or near-real dependencies. Layer 3: Contract Tests ensure middleware maintains its API contract across versions.

// Layer 1: Unit Testing with Mocked Dependencies
const request = require('supertest');
const express = require('express');

describe('Rate Limiting Middleware', () => {
  let app;
  let mockRedis;

  beforeEach(() => {
    app = express();
    mockRedis = {
      incr: jest.fn(),
      expire: jest.fn(),
      ping: jest.fn().mockResolvedValue('PONG')
    };

    const rateLimiter = createRateLimiter({
      limit: 5,
      windowMs: 60000,
      redisClient: mockRedis
    });

    app.use(rateLimiter);
    app.get('/test', (req, res) => res.json({ success: true }));
  });

  test('allows requests under the limit', async () => {
    mockRedis.incr.mockResolvedValue(1);

    const response = await request(app)
      .get('/test')
      .expect(200);

    expect(response.body).toEqual({ success: true });
    expect(mockRedis.incr).toHaveBeenCalledWith(
      expect.stringMatching(/^ratelimit:.*/)
    );
  });

  test('rejects requests over the limit', async () => {
    mockRedis.incr.mockResolvedValue(6); // Over the limit of 5

    const response = await request(app)
      .get('/test')
      .expect(429);

    expect(response.body.error).toBe('Rate limit exceeded');
    expect(response.body.code).toBe('RATE_LIMITED');
  });

  test('handles Redis connection failures gracefully', async () => {
    mockRedis.incr.mockRejectedValue(new Error('Redis connection failed'));

    const rateLimiter = createRateLimiter({
      limit: 5,
      failOpen: true,
      redisClient: mockRedis
    });

    app = express();
    app.use(rateLimiter);
    app.get('/test', (req, res) => res.json({ success: true }));

    // Should allow request when Redis fails and failOpen is true
    await request(app)
      .get('/test')
      .expect(200);
  });

  test('respects time windows correctly', async () => {
    const now = Date.now();
    const windowStart = Math.floor(now / 60000) * 60000;

    mockRedis.incr.mockResolvedValue(1);

    await request(app)
      .get('/test')
      .expect(200);

    expect(mockRedis.incr).toHaveBeenCalledWith(
      `ratelimit:default:${windowStart}`
    );
    expect(mockRedis.expire).toHaveBeenCalledWith(
      `ratelimit:default:${windowStart}`,
      60
    );
  });
});

Integration Testing with Test Containers

Integration tests need real dependencies to catch issues that mocks can't reveal. Test containers provide isolated, reproducible environments for integration testing.

Container-based testing solves the "works on my machine" problem by providing consistent test environments. Testcontainers supports multiple databases, message brokers, and caching systems, enabling realistic integration tests without complex setup.

// Layer 2: Integration Testing with Real Redis
const { GenericContainer } = require('testcontainers');
const Redis = require('ioredis');

describe('Rate Limiter Integration Tests', () => {
  let redisContainer;
  let redisClient;
  let rateLimiter;
  let app;

  beforeAll(async () => {
    // Start Redis container
    redisContainer = await new GenericContainer('redis:7-alpine')
      .withExposedPorts(6379)
      .start();

    const redisPort = redisContainer.getMappedPort(6379);
    redisClient = new Redis({
      host: 'localhost',
      port: redisPort,
      retryDelayOnFailover: 100,
      maxRetriesPerRequest: 1
    });

    // Wait for Redis to be ready
    await redisClient.ping();
  });

  afterAll(async () => {
    await redisClient.disconnect();
    await redisContainer.stop();
  });

  beforeEach(() => {
    app = express();
    rateLimiter = createRateLimiter({
      limit: 3,
      windowMs: 1000, // 1 second for faster tests
      redisClient
    });

    app.use(rateLimiter);
    app.get('/test', (req, res) => res.json({ success: true }));
  });

  test('enforces rate limits across multiple requests', async () => {
    // First 3 requests should succeed
    for (let i = 0; i < 3; i++) {
      await request(app)
        .get('/test')
        .expect(200);
    }

    // 4th request should be rate limited
    await request(app)
      .get('/test')
      .expect(429);
  });

  test('resets limits after window expires', async () => {
    // Fill the rate limit
    for (let i = 0; i < 3; i++) {
      await request(app).get('/test').expect(200);
    }

    // Should be rate limited
    await request(app).get('/test').expect(429);

    // Wait for window to reset
    await new Promise(resolve => setTimeout(resolve, 1100));

    // Should work again
    await request(app).get('/test').expect(200);
  });

  test('handles concurrent requests correctly', async () => {
    const requests = Array.from({ length: 10 }, () =>
      request(app).get('/test')
    );

    const responses = await Promise.all(requests);
    const successful = responses.filter(r => r.status === 200);
    const rateLimited = responses.filter(r => r.status === 429);

    expect(successful.length).toBe(3);
    expect(rateLimited.length).toBe(7);
  });
});

Property-Based Testing for Edge Cases

Property-based testing generates random inputs to find edge cases you wouldn't think to test manually. This is especially valuable for middleware that handles diverse request patterns.

Property-based testing differs from example-based testing by generating hundreds of test cases automatically. Fast-check for JavaScript follows the same principles as QuickCheck for Haskell, helping discover edge cases in input validation, serialization, and state transitions.

const fc = require('fast-check');

describe('Middleware Property-Based Tests', () => {
  test('input sanitization handles all possible inputs', () => {
    fc.assert(
      fc.property(
        fc.record({
          username: fc.string(),
          password: fc.string(),
          extra: fc.anything()
        }),
        (input) => {
          const sanitized = sanitizeUserInput(input);

          // Properties that should always hold
          expect(typeof sanitized.username).toBe('string');
          expect(typeof sanitized.password).toBe('string');
          expect(sanitized.password).toBe('[REDACTED]'); // Always redacted
          expect(sanitized).not.toHaveProperty('__proto__'); // No prototype pollution
        }
      )
    );
  });

  test('rate limiter handles various key generation patterns', () => {
    fc.assert(
      fc.property(
        fc.record({
          ip: fc.ipV4(),
          userAgent: fc.string(),
          method: fc.constantFrom('GET', 'POST', 'PUT', 'DELETE'),
          path: fc.string()
        }),
        (requestData) => {
          const key = generateRateLimitKey(requestData);

          // Key properties
          expect(typeof key).toBe('string');
          expect(key.length).toBeGreaterThan(0);
          expect(key.length).toBeLessThan(250); // Redis key limit
          expect(key).not.toContain(' '); // No spaces
          expect(key).not.toContain('
'); // No newlines
        }
      )
    );
  });
});

Performance Testing Under Load

Middleware performance characteristics only emerge under realistic load conditions. Load testing reveals memory leaks, connection pool exhaustion, and race conditions that don't appear in unit tests.

// Load testing with k6 (external tool, but here's the pattern)
const loadTestScript = `
import http from 'k6/http';
import { check } from 'k6';

export let options = {
  stages: [
    { duration: '30s', target: 100 },  // Ramp up
    { duration: '60s', target: 500 },  // Stay at 500 RPS
    { duration: '30s', target: 0 },    // Ramp down
  ],
};

export default function() {
  let response = http.get('http://localhost:3000/api/test');

  check(response, {
    'status is 200': (r) => r.status === 200,
    'response time < 500ms': (r) => r.timings.duration < 500,
  });
}
`;

// Memory leak detection during load testing
class MemoryMonitor {
  constructor() {
    this.samples = [];
    this.isMonitoring = false;
  }

  startMonitoring(intervalMs = 1000) {
    this.isMonitoring = true;

    const collectSample = () => {
      if (!this.isMonitoring) return;

      const usage = process.memoryUsage();
      this.samples.push({
        timestamp: Date.now(),
        heapUsed: usage.heapUsed,
        heapTotal: usage.heapTotal,
        external: usage.external,
        rss: usage.rss
      });

      setTimeout(collectSample, intervalMs);
    };

    collectSample();
  }

  stopMonitoring() {
    this.isMonitoring = false;
  }

  detectMemoryLeak() {
    if (this.samples.length < 10) return false;

    const recent = this.samples.slice(-10);
    const trend = this.calculateTrend(recent.map(s => s.heapUsed));

    // Memory leak if heap usage is consistently increasing
    return trend > 1024 * 1024; // 1MB growth trend
  }

  calculateTrend(values) {
    const n = values.length;
    const sumX = (n * (n - 1)) / 2;
    const sumY = values.reduce((a, b) => a + b, 0);
    const sumXY = values.reduce((sum, val, index) => sum + (index * val), 0);
    const sumXX = (n * (n - 1) * (2 * n - 1)) / 6;

    return (n * sumXY - sumX * sumY) / (n * sumXX - sumX * sumX);
  }
}

// Usage in tests
describe('Memory Leak Detection', () => {
  let server;
  let monitor;

  beforeEach(() => {
    monitor = new MemoryMonitor();
    server = app.listen(3000);
    monitor.startMonitoring();
  });

  afterEach((done) => {
    monitor.stopMonitoring();
    server.close(done);
  });

  test('middleware does not leak memory under load', async () => {
    // Simulate load (this will expose memory leaks real quick)
    const requests = Array.from({ length: 1000 }, () =>
      request(app).get('/test')
    );

    await Promise.all(requests);

    // Allow garbage collection (pray to the GC gods)
    global.gc && global.gc();
    await new Promise(resolve => setTimeout(resolve, 1000));

    expect(monitor.detectMemoryLeak()).toBe(false);
  }, 30000); // 30 second timeout because these tests are slow as hell
});

Publishing to npm: Making Your Middleware Available

Publishing middleware to npm requires more than just running npm publish. You need docs that don't suck, a versioning strategy that won't break everyone's builds, and the mental fortitude to answer GitHub issues from developers who didn't read the README.

The npm ecosystem hosts over 2 million packages, making discoverability crucial. Successful middleware packages follow npm best practices for naming, tagging, and documentation. Semantic versioning communicates breaking changes, while comprehensive README files improve adoption rates.

Package Configuration and Metadata

{
  "name": "express-smart-rate-limit",
  "version": "1.0.0",
  "description": "Production-ready rate limiting middleware with Redis support and graceful failover",
  "main": "lib/index.js",
  "types": "lib/index.d.ts",
  "files": [
    "lib/",
    "README.md",
    "CHANGELOG.md"
  ],
  "scripts": {
    "build": "tsc",
    "test": "jest",
    "test:integration": "jest --testPathPattern=integration",
    "test:coverage": "jest --coverage",
    "lint": "eslint src/",
    "prepublishOnly": "npm run build && npm run test"
  },
  "keywords": [
    "express",
    "middleware",
    "rate-limit",
    "redis",
    "security",
    "api",
    "throttle"
  ],
  "author": "Your Name <your.email@example.com>",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/yourusername/express-smart-rate-limit.git"
  },
  "bugs": {
    "url": "https://github.com/yourusername/express-smart-rate-limit/issues"
  },
  "homepage": "https://github.com/yourusername/express-smart-rate-limit#readme",
  "peerDependencies": {
    "express": ">=4.0.0",
    "ioredis": ">=4.0.0"
  },
  "devDependencies": {
    "@types/express": "^4.17.17",
    "@types/node": "^18.0.0",
    "typescript": "^5.0.0",
    "jest": "^29.0.0",
    "supertest": "^6.0.0",
    "testcontainers": "^8.0.0"
  },
  "engines": {
    "node": ">=18.0.0"
  }
}

TypeScript Definitions for Better Developer Experience

Modern middleware should include TypeScript definitions, even if written in JavaScript. This provides better IDE support and catches integration errors early.

TypeScript adoption in Node.js has grown significantly, with 2023 surveys showing 78% usage. Declaration files enable type checking, IntelliSense, and refactoring support for JavaScript packages. DefinitelyTyped provides community-maintained types for popular packages.

// types/index.d.ts
import { Request, Response, NextFunction } from 'express';

export interface RateLimitOptions {
  /**
   * Maximum number of requests allowed within the time window
   * @default 100
   */
  limit?: number;

  /**
   * Time window in milliseconds
   * @default 60000 (1 minute)
   */
  windowMs?: number;

  /**
   * Whether to allow requests when Redis is unavailable
   * @default false
   */
  failOpen?: boolean;

  /**
   * Function to generate rate limit keys
   * @default Uses IP address
   */
  keyGenerator?: (req: Request) => string;

  /**
   * Custom error handler
   */
  onLimitReached?: (req: Request, res: Response) => void;

  /**
   * Redis client configuration or instance
   */
  redis?: RedisOptions | RedisClient;
}

export interface RedisOptions {
  host?: string;
  port?: number;
  password?: string;
  db?: number;
}

export interface RedisClient {
  incr(key: string): Promise<number>;
  expire(key: string, seconds: number): Promise<number>;
  ping(): Promise<string>;
}

/**
 * Creates a rate limiting middleware for Express applications
 *
 * @example
 * ```javascript
 * const rateLimiter = createRateLimiter({
 *   limit: 100,
 *   windowMs: 60000,
 *   redis: { host: 'localhost', port: 6379 }
 * });
 *
 * app.use('/api', rateLimiter);
 * ```
 */
export function createRateLimiter(options?: RateLimitOptions):
  (req: Request, res: Response, next: NextFunction) => Promise<void>;

/**
 * Extended Request interface with rate limit information
 */
declare global {
  namespace Express {
    interface Request {
      rateLimit?: {
        limit: number;
        current: number;
        remaining: number;
        resetTime: number;
      };
    }
  }
}

Documentation That Developers Actually Use

Good documentation explains not just what the middleware does, but why and how to use it effectively in different scenarios.

## Express Smart Rate Limit

Production-ready rate limiting middleware with Redis support, graceful failover, and comprehensive error handling.

### Features

- ✅ Redis-backed distributed rate limiting
- ✅ Graceful failover when Redis is unavailable
- ✅ Configurable time windows and limits
- ✅ TypeScript support with full type definitions
- ✅ Comprehensive test suite with 95%+ coverage
- ✅ Memory leak protection and performance optimization

### Quick Start

```javascript
const express = require('express');
const { createRateLimiter } = require('express-smart-rate-limit');

const app = express();

const rateLimiter = createRateLimiter({
  limit: 100,           // 100 requests
  windowMs: 60000,      // per minute
  redis: {
    host: 'localhost',
    port: 6379
  }
});

app.use('/api', rateLimiter);

Configuration Options

Basic Options

Advanced Options

const rateLimiter = createRateLimiter({
  // Custom key generation
  keyGenerator: (req) => `${req.ip}:${req.user?.id}`,

  // Custom error handling
  onLimitReached: (req, res) => {
    res.status(429).json({
      error: 'Too many requests',
      retryAfter: 60
    });
  },

  // Redis configuration
  redis: {
    host: process.env.REDIS_HOST,
    port: parseInt(process.env.REDIS_PORT),
    password: process.env.REDIS_PASSWORD,
    retryDelayOnFailover: 100
  }
});

Production Deployment

Docker Compose Example

version: '3.8'
services:
  app:
    build: .
    environment:
      - REDIS_HOST=redis
      - REDIS_PORT=6379
    depends_on:
      - redis

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data

volumes:
  redis_data:

Kubernetes Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-server
spec:
  replicas: 3
  selector:
    matchLabels:
      app: api-server
  template:
    metadata:
      labels:
        app: api-server
    spec:
      containers:
      - name: api
        image: your-api:latest
        env:
        - name: REDIS_HOST
          value: \"redis-service\"
        - name: REDIS_PORT
          value: \"6379\"

Performance

Benchmarks on MacBook M1 Pro (Node.js 18.17.0):

• Without rate limiting: 45,000 req/sec
• With in-memory rate limiting: 42,000 req/sec (-7%)
• With Redis rate limiting: 38,000 req/sec (-15%)
• Memory usage: ~2MB additional for 10,000 active keys

Error Handling

The middleware handles Redis failures gracefully:

// Fail closed (reject requests when Redis is down)
const strictLimiter = createRateLimiter({
  failOpen: false  // default
});

// Fail open (allow requests when Redis is down)
const resilientLimiter = createRateLimiter({
  failOpen: true
});

Migration Guide

From express-rate-limit

// Before
const rateLimit = require('express-rate-limit');
const limiter = rateLimit({
  windowMs: 15 * 60 * 1000,
  max: 100
});

// After
const { createRateLimiter } = require('express-smart-rate-limit');
const limiter = createRateLimiter({
  windowMs: 15 * 60 * 1000,
  limit: 100  // renamed from 'max'
});

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Run tests: npm test
4. Submit a pull request

License

MIT © [Your Name]

Semantic Versioning and Release Management

Professional packages follow semantic versioning and maintain detailed changelogs:

## Changelog

All notable changes to this project will be documented in this file.

### [1.2.0] - 2025-09-13

#### Added
- Support for custom key generators
- TypeScript definitions for better IDE support
- Graceful shutdown handling

#### Changed
- Improved error messages for better debugging
- Updated Redis client to ioredis v5

#### Fixed
- Memory leak in key cleanup process
- Race condition in window reset logic

### [1.1.1] - 2025-08-15

#### Fixed
- Connection pool exhaustion under high load
- Incorrect rate limit headers in some edge cases

### [1.1.0] - 2025-07-20

#### Added
- Support for custom error handlers
- Configurable failover behavior

#### Deprecated
- `redisOptions` parameter (use `redis` instead)

### [1.0.0] - 2025-06-10

#### Added
- Initial release
- Redis-backed rate limiting
- Express.js middleware interface
- Comprehensive test suite

Publishing middleware successfully means not just throwing code over the wall and disappearing. The difference between middleware that gets adopted and middleware that gets ignored is whether other developers can actually use it without wanting to track you down and ask what the hell you were thinking.

Successful open source projects follow community guidelines for maintainer responsibilities, code of conduct, and contribution workflows. Package maintenance strategies include security updates, dependency management, and deprecation policies for long-term sustainability.