0http-bun 1.2.1 → 1.3.0

package/lib/middleware/prometheus.js

@@ -0,0 +1,491 @@
+// Lazy load prom-client to improve startup performance
+let promClient = null
+function loadPromClient() {
+  if (!promClient) {
+    try {
+      promClient = require('prom-client')
+    } catch (error) {
+      throw new Error(
+        'prom-client is required for Prometheus middleware. Install it with: bun install prom-client',
+      )
+    }
+  }
+  return promClient
+}
+
+// Security: Limit label cardinality
+const MAX_LABEL_VALUE_LENGTH = 100
+const MAX_ROUTE_SEGMENTS = 10
+
+/**
+ * Sanitize label values to prevent high cardinality
+ */
+function sanitizeLabelValue(value) {
+  if (typeof value !== 'string') {
+    value = String(value)
+  }
+
+  // Truncate long values
+  if (value.length > MAX_LABEL_VALUE_LENGTH) {
+    value = value.substring(0, MAX_LABEL_VALUE_LENGTH)
+  }
+
+  // Replace invalid characters
+  return value.replace(/[^a-zA-Z0-9_-]/g, '_')
+}
+
+/**
+ * Validate route pattern to prevent injection attacks
+ */
+function validateRoute(route) {
+  if (typeof route !== 'string' || route.length === 0) {
+    return '/unknown'
+  }
+
+  // Limit route complexity
+  const segments = route.split('/').filter(Boolean)
+  if (segments.length > MAX_ROUTE_SEGMENTS) {
+    return '/' + segments.slice(0, MAX_ROUTE_SEGMENTS).join('/')
+  }
+
+  return sanitizeLabelValue(route)
+}
+
+/**
+ * Default Prometheus metrics for HTTP requests
+ */
+function createDefaultMetrics() {
+  const client = loadPromClient()
+
+  // HTTP request duration histogram
+  const httpRequestDuration = new client.Histogram({
+    name: 'http_request_duration_seconds',
+    help: 'Duration of HTTP requests in seconds',
+    labelNames: ['method', 'route', 'status_code'],
+    buckets: [0.001, 0.005, 0.015, 0.05, 0.1, 0.2, 0.3, 0.4, 0.5, 1, 2, 5, 10],
+  })
+
+  // HTTP request counter
+  const httpRequestTotal = new client.Counter({
+    name: 'http_requests_total',
+    help: 'Total number of HTTP requests',
+    labelNames: ['method', 'route', 'status_code'],
+  })
+
+  // HTTP request size histogram
+  const httpRequestSize = new client.Histogram({
+    name: 'http_request_size_bytes',
+    help: 'Size of HTTP requests in bytes',
+    labelNames: ['method', 'route'],
+    buckets: [1, 10, 100, 1000, 10000, 100000, 1000000, 10000000],
+  })
+
+  // HTTP response size histogram
+  const httpResponseSize = new client.Histogram({
+    name: 'http_response_size_bytes',
+    help: 'Size of HTTP responses in bytes',
+    labelNames: ['method', 'route', 'status_code'],
+    buckets: [1, 10, 100, 1000, 10000, 100000, 1000000, 10000000],
+  })
+
+  // Active HTTP connections gauge
+  const httpActiveConnections = new client.Gauge({
+    name: 'http_active_connections',
+    help: 'Number of active HTTP connections',
+  })
+
+  return {
+    httpRequestDuration,
+    httpRequestTotal,
+    httpRequestSize,
+    httpResponseSize,
+    httpActiveConnections,
+  }
+}
+
+/**
+ * Extract route pattern from request
+ * This function attempts to extract a meaningful route pattern from the request
+ * for use in Prometheus metrics labels
+ */
+function extractRoutePattern(req) {
+  try {
+    // If route pattern is available from router context
+    if (req.ctx && req.ctx.route) {
+      return validateRoute(req.ctx.route)
+    }
+
+    // If params exist, try to reconstruct the pattern
+    if (req.params && Object.keys(req.params).length > 0) {
+      const url = new URL(req.url, 'http://localhost')
+      let pattern = url.pathname
+
+      // Replace parameter values with parameter names
+      Object.entries(req.params).forEach(([key, value]) => {
+        if (typeof key === 'string' && typeof value === 'string') {
+          const escapedValue = value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+          pattern = pattern.replace(
+            new RegExp(`/${escapedValue}(?=/|$)`),
+            `/:${sanitizeLabelValue(key)}`,
+          )
+        }
+      })
+
+      return validateRoute(pattern)
+    }
+
+    // Try to normalize common patterns
+    const url = new URL(req.url, 'http://localhost')
+    let pathname = url.pathname
+
+    // Replace UUIDs, numbers, and other common ID patterns
+    pathname = pathname
+      .replace(
+        /\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi,
+        '/:id',
+      )
+      .replace(/\/\d+/g, '/:id')
+      .replace(/\/[a-zA-Z0-9_-]{20,}/g, '/:token')
+
+    return validateRoute(pathname)
+  } catch (error) {
+    // Fallback for malformed URLs
+    return '/unknown'
+  }
+}
+
+/**
+ * Get request size in bytes - optimized for performance
+ */
+function getRequestSize(req) {
+  try {
+    const contentLength = req.headers.get('content-length')
+    if (contentLength) {
+      const size = parseInt(contentLength, 10)
+      return size >= 0 && size <= 100 * 1024 * 1024 ? size : 0 // Max 100MB
+    }
+
+    // Fast estimation based on headers only
+    let size = 0
+    const url = req.url || ''
+    size += req.method.length + url.length + 12 // HTTP/1.1 + spaces
+
+    // Quick header size estimation
+    if (req.headers && typeof req.headers.forEach === 'function') {
+      let headerCount = 0
+      req.headers.forEach((value, key) => {
+        if (headerCount < 50) {
+          // Limit header processing for performance
+          size += key.length + value.length + 4 // ": " + "\r\n"
+          headerCount++
+        }
+      })
+    }
+
+    return Math.min(size, 1024 * 1024) // Cap at 1MB for estimation
+  } catch (error) {
+    return 0
+  }
+}
+
+/**
+ * Get response size in bytes - optimized for performance
+ */
+function getResponseSize(response) {
+  try {
+    // Check content-length header first (fastest)
+    const contentLength = response.headers?.get('content-length')
+    if (contentLength) {
+      const size = parseInt(contentLength, 10)
+      return size >= 0 && size <= 100 * 1024 * 1024 ? size : 0 // Max 100MB
+    }
+
+    // Try to estimate from response body if available
+    if (
+      response._bodyForLogger &&
+      typeof response._bodyForLogger === 'string'
+    ) {
+      return Math.min(
+        Buffer.byteLength(response._bodyForLogger, 'utf8'),
+        1024 * 1024,
+      )
+    }
+
+    // Fast estimation for headers only
+    let size = 15 // "HTTP/1.1 200 OK\r\n"
+
+    if (response.headers && typeof response.headers.forEach === 'function') {
+      let headerCount = 0
+      response.headers.forEach((value, key) => {
+        if (headerCount < 20) {
+          // Limit for performance
+          size += key.length + value.length + 4 // ": " + "\r\n"
+          headerCount++
+        }
+      })
+    }
+
+    return Math.min(size, 1024) // Cap header estimation at 1KB
+  } catch (error) {
+    return 0
+  }
+}
+
+/**
+ * Creates a Prometheus metrics middleware
+ * @param {Object} options - Prometheus middleware configuration
+ * @param {Object} options.metrics - Custom metrics object (optional)
+ * @param {Array<string>} options.excludePaths - Paths to exclude from metrics
+ * @param {boolean} options.collectDefaultMetrics - Whether to collect default Node.js metrics
+ * @param {Function} options.normalizeRoute - Custom route normalization function
+ * @param {Function} options.extractLabels - Custom label extraction function
+ * @param {Array<string>} options.skipMethods - HTTP methods to skip from metrics
+ * @returns {Function} Middleware function
+ */
+function createPrometheusMiddleware(options = {}) {
+  const {
+    metrics: customMetrics,
+    excludePaths = ['/health', '/ping', '/favicon.ico', '/metrics'],
+    collectDefaultMetrics = true,
+    normalizeRoute = extractRoutePattern,
+    extractLabels,
+    skipMethods = [],
+  } = options
+
+  // Collect default Node.js metrics
+  if (collectDefaultMetrics) {
+    const client = loadPromClient()
+    client.collectDefaultMetrics({
+      timeout: 5000,
+      gcDurationBuckets: [0.001, 0.01, 0.1, 1, 2, 5],
+      eventLoopMonitoringPrecision: 5,
+    })
+  }
+
+  // Use custom metrics or create default ones
+  const metrics = customMetrics || createDefaultMetrics()
+
+  return async function prometheusMiddleware(req, next) {
+    const startHrTime = process.hrtime()
+
+    // Skip metrics collection for excluded paths (performance optimization)
+    const url = req.url || ''
+    let pathname
+    try {
+      // Handle both full URLs and pathname-only URLs
+      if (url.startsWith('http')) {
+        pathname = new URL(url).pathname
+      } else {
+        pathname = url.split('?')[0] // Fast pathname extraction
+      }
+    } catch (error) {
+      pathname = url.split('?')[0] // Fallback to simple splitting
+    }
+
+    if (excludePaths.some((path) => pathname.startsWith(path))) {
+      return next()
+    }
+
+    // Skip metrics collection for specified methods
+    const method = req.method?.toUpperCase() || 'GET'
+    if (skipMethods.includes(method)) {
+      return next()
+    }
+
+    // Increment active connections
+    if (metrics.httpActiveConnections) {
+      metrics.httpActiveConnections.inc()
+    }
+
+    try {
+      // Get request size (lazy evaluation)
+      let requestSize = 0
+
+      // Execute the request
+      const response = await next()
+
+      // Calculate duration (high precision)
+      const duration = process.hrtime(startHrTime)
+      const durationInSeconds = duration[0] + duration[1] * 1e-9
+
+      // Extract route pattern (cached/optimized)
+      const route = normalizeRoute(req)
+      const statusCode = sanitizeLabelValue(
+        response?.status?.toString() || 'unknown',
+      )
+
+      // Create base labels with sanitized values
+      let labels = {
+        method: sanitizeLabelValue(method),
+        route: route,
+        status_code: statusCode,
+      }
+
+      // Add custom labels if extractor provided
+      if (extractLabels && typeof extractLabels === 'function') {
+        try {
+          const customLabels = extractLabels(req, response)
+          if (customLabels && typeof customLabels === 'object') {
+            // Sanitize custom labels
+            Object.entries(customLabels).forEach(([key, value]) => {
+              if (typeof key === 'string' && key.length <= 50) {
+                labels[sanitizeLabelValue(key)] = sanitizeLabelValue(
+                  String(value),
+                )
+              }
+            })
+          }
+        } catch (error) {
+          // Ignore custom label extraction errors
+        }
+      }
+
+      // Record metrics efficiently
+      if (metrics.httpRequestDuration) {
+        metrics.httpRequestDuration.observe(
+          {
+            method: labels.method,
+            route: labels.route,
+            status_code: labels.status_code,
+          },
+          durationInSeconds,
+        )
+      }
+
+      if (metrics.httpRequestTotal) {
+        metrics.httpRequestTotal.inc({
+          method: labels.method,
+          route: labels.route,
+          status_code: labels.status_code,
+        })
+      }
+
+      if (metrics.httpRequestSize) {
+        requestSize = getRequestSize(req)
+        if (requestSize > 0) {
+          metrics.httpRequestSize.observe(
+            {method: labels.method, route: labels.route},
+            requestSize,
+          )
+        }
+      }
+
+      if (metrics.httpResponseSize) {
+        const responseSize = getResponseSize(response)
+        if (responseSize > 0) {
+          metrics.httpResponseSize.observe(
+            {
+              method: labels.method,
+              route: labels.route,
+              status_code: labels.status_code,
+            },
+            responseSize,
+          )
+        }
+      }
+
+      return response
+    } catch (error) {
+      // Record error metrics
+      const duration = process.hrtime(startHrTime)
+      const durationInSeconds = duration[0] + duration[1] * 1e-9
+      const route = normalizeRoute(req)
+      const sanitizedMethod = sanitizeLabelValue(method)
+
+      if (metrics.httpRequestDuration) {
+        metrics.httpRequestDuration.observe(
+          {method: sanitizedMethod, route: route, status_code: '500'},
+          durationInSeconds,
+        )
+      }
+
+      if (metrics.httpRequestTotal) {
+        metrics.httpRequestTotal.inc({
+          method: sanitizedMethod,
+          route: route,
+          status_code: '500',
+        })
+      }
+
+      throw error
+    } finally {
+      // Decrement active connections
+      if (metrics.httpActiveConnections) {
+        metrics.httpActiveConnections.dec()
+      }
+    }
+  }
+}
+
+/**
+ * Creates a metrics endpoint handler that serves Prometheus metrics
+ * @param {Object} options - Metrics endpoint configuration
+ * @param {string} options.endpoint - The endpoint path (default: '/metrics')
+ * @param {Object} options.registry - Custom Prometheus registry
+ * @returns {Function} Request handler function
+ */
+function createMetricsHandler(options = {}) {
+  const client = loadPromClient()
+  const {endpoint = '/metrics', registry = client.register} = options
+
+  return async function metricsHandler(req) {
+    const url = new URL(req.url, 'http://localhost')
+
+    if (url.pathname === endpoint) {
+      try {
+        const metrics = await registry.metrics()
+        return new Response(metrics, {
+          status: 200,
+          headers: {
+            'Content-Type': registry.contentType,
+            'Cache-Control': 'no-cache, no-store, must-revalidate',
+            Pragma: 'no-cache',
+            Expires: '0',
+          },
+        })
+      } catch (error) {
+        return new Response('Error collecting metrics', {
+          status: 500,
+          headers: {'Content-Type': 'text/plain'},
+        })
+      }
+    }
+
+    return null // Let other middleware handle the request
+  }
+}
+
+/**
+ * Simple helper to create both middleware and metrics endpoint
+ * @param {Object} options - Combined configuration options
+ * @returns {Object} Object containing middleware and handler functions
+ */
+function createPrometheusIntegration(options = {}) {
+  const middleware = createPrometheusMiddleware(options)
+  const metricsHandler = createMetricsHandler(options)
+  const client = loadPromClient()
+
+  return {
+    middleware,
+    metricsHandler,
+    // Expose the registry for custom metrics
+    registry: client.register,
+    // Expose prom-client for creating custom metrics
+    promClient: client,
+  }
+}
+
+module.exports = {
+  createPrometheusMiddleware,
+  createMetricsHandler,
+  createPrometheusIntegration,
+  createDefaultMetrics,
+  extractRoutePattern,
+  // Export lazy loader functions to maintain compatibility
+  get promClient() {
+    return loadPromClient()
+  },
+  get register() {
+    return loadPromClient().register
+  },
+}

package/lib/middleware/rate-limit.js

@@ -8,7 +8,7 @@ class MemoryStore {
     this.resetTimes = new Map()
   }
 
-  async increment(key, windowMs) {
+  increment(key, windowMs) {
     const now = Date.now()
     const windowStart = Math.floor(now / windowMs) * windowMs
     const storeKey = `${key}:${windowStart}`
@@ -82,27 +82,40 @@ function createRateLimit(options = {}) {
    * @returns {Response} Response with headers added
    */
   const addRateLimitHeaders = (response, totalHits, resetTime) => {
-    if (standardHeaders && response && response.headers) {
-      response.headers.set('X-RateLimit-Limit', max.toString())
-      response.headers.set(
-        'X-RateLimit-Remaining',
-        Math.max(0, max - totalHits).toString(),
-      )
-      response.headers.set(
-        'X-RateLimit-Reset',
-        Math.ceil(resetTime.getTime() / 1000).toString(),
-      )
-      response.headers.set('X-RateLimit-Used', totalHits.toString())
+    if (!standardHeaders || !response?.headers) return response
+
+    if (standardHeaders === 'minimal') {
+      // L-6: Only add Retry-After on 429 responses to avoid disclosing config
+      if (response.status === 429) {
+        const retryAfter = Math.ceil((resetTime.getTime() - Date.now()) / 1000)
+        response.headers.set('Retry-After', Math.max(0, retryAfter).toString())
+      }
+      return response
     }
+
+    // Full headers (standardHeaders === true)
+    response.headers.set('X-RateLimit-Limit', max.toString())
+    response.headers.set(
+      'X-RateLimit-Remaining',
+      Math.max(0, max - totalHits).toString(),
+    )
+    response.headers.set(
+      'X-RateLimit-Reset',
+      Math.ceil(resetTime.getTime() / 1000).toString(),
+    )
+    response.headers.set('X-RateLimit-Used', totalHits.toString())
     return response
   }
 
   return async function rateLimitMiddleware(req, next) {
-    // Allow test to inject a fresh store for isolation
-    const activeStore = req && req.rateLimitStore ? req.rateLimitStore : store
+    const activeStore = store
 
     const url = new URL(req.url)
-    if (excludePaths.some((path) => url.pathname.startsWith(path))) {
+    if (
+      excludePaths.some(
+        (path) => url.pathname === path || url.pathname.startsWith(path + '/'),
+      )
+    ) {
       return next()
     }
 
@@ -159,22 +172,30 @@ function createRateLimit(options = {}) {
 }
 
 /**
- * Default key generator - uses IP address
+ * Default key generator - uses connection-level IP address
+ * Checks req.ip, req.remoteAddress, and req.socket?.remoteAddress in order.
+ * NOTE: If behind a reverse proxy, provide a custom keyGenerator that
+ * reads the appropriate header after configuring your proxy to set it.
  * @param {Request} req - Request object
  * @returns {string} Rate limit key
  */
+let _unknownKeyWarned = false
+
 function defaultKeyGenerator(req) {
-  // Try to get real IP from common headers
-  const forwarded = req.headers.get('x-forwarded-for')
-  const realIp = req.headers.get('x-real-ip')
-  const cfConnectingIp = req.headers.get('cf-connecting-ip')
-
-  return (
-    cfConnectingIp ||
-    realIp ||
-    (forwarded && forwarded.split(',')[0].trim()) ||
-    'unknown'
-  )
+  // Use connection-level IP if available (set by Bun's server or upstream middleware)
+  const ip = req.ip || req.remoteAddress || req.socket?.remoteAddress
+  if (ip) return ip
+
+  // I-1: Generate unique key per request to avoid shared bucket DoS
+  if (!_unknownKeyWarned) {
+    console.warn(
+      '[0http-bun] SECURITY WARNING: Rate limiter cannot determine client IP. ' +
+        'Each request without an IP gets a unique key (no shared bucket). ' +
+        'Configure a custom keyGenerator for proper rate limiting behind proxies.',
+    )
+    _unknownKeyWarned = true
+  }
+  return `unknown:${Date.now()}:${Math.random().toString(36).slice(2)}`
 }
 
 /**
@@ -216,10 +237,32 @@ function createSlidingWindowRateLimit(options = {}) {
     max = 100,
     keyGenerator = defaultKeyGenerator,
     handler = defaultHandler,
+    maxKeys = 10000,
   } = options
 
   const requests = new Map() // key -> array of timestamps
 
+  // Periodic cleanup of stale entries
+  const cleanupInterval = setInterval(
+    () => {
+      const now = Date.now()
+      for (const [key, timestamps] of requests.entries()) {
+        const filtered = timestamps.filter((ts) => now - ts < windowMs)
+        if (filtered.length === 0) {
+          requests.delete(key)
+        } else {
+          requests.set(key, filtered)
+        }
+      }
+    },
+    Math.min(windowMs, 60000),
+  ) // Clean up at most every minute
+
+  // Allow garbage collection if reference is lost
+  if (cleanupInterval.unref) {
+    cleanupInterval.unref()
+  }
+
   return async function slidingWindowRateLimitMiddleware(req, next) {
     // Generate key and record the request immediately - let errors bubble up
     const key = await keyGenerator(req)
@@ -248,6 +291,13 @@ function createSlidingWindowRateLimit(options = {}) {
     userRequests.push(now)
     requests.set(key, userRequests)
 
+    // Enforce max keys to prevent unbounded memory growth
+    if (requests.size > maxKeys) {
+      // Remove oldest entry
+      const firstKey = requests.keys().next().value
+      requests.delete(firstKey)
+    }
+
     // Add rate limit info to context
     req.ctx = req.ctx || {}
     req.ctx.rateLimit = {

package/lib/next.js

@@ -15,12 +15,19 @@ module.exports = function next(
   const nextIndex = index + 1
 
   try {
-    return middleware(req, (err) => {
+    const result = middleware(req, (err) => {
       if (err) {
         return errorHandler(err, req)
       }
       return next(middlewares, req, nextIndex, defaultRoute, errorHandler)
     })
+
+    // Catch rejected promises from async middleware
+    if (result && typeof result.catch === 'function') {
+      return result.catch((err) => errorHandler(err, req))
+    }
+
+    return result
   } catch (err) {
     return errorHandler(err, req)
   }