0http-bun 1.2.1 → 1.2.2

package/README.md

@@ -206,11 +206,14 @@ Bun.serve({
 
 0http-bun includes a comprehensive middleware system with built-in middlewares for common use cases:
 
+> 📦 **Note**: Starting with v1.2.2, some middleware dependencies are optional. Install only what you need: `jose` (JWT), `pino` (Logger), `prom-client` (Prometheus).
+
 - **[Body Parser](./lib/middleware/README.md#body-parser)** - Automatic request body parsing (JSON, form data, text)
 - **[CORS](./lib/middleware/README.md#cors)** - Cross-Origin Resource Sharing with flexible configuration
 - **[JWT Authentication](./lib/middleware/README.md#jwt-authentication)** - JSON Web Token authentication and authorization
 - **[Logger](./lib/middleware/README.md#logger)** - Request logging with multiple output formats
 - **[Rate Limiting](./lib/middleware/README.md#rate-limiting)** - Flexible rate limiting with sliding window support
+- **[Prometheus Metrics](./lib/middleware/README.md#prometheus-metrics)** - Export metrics for monitoring and alerting
 
 ### Quick Example
 

package/lib/middleware/README.md

@@ -2,6 +2,30 @@
 
 0http-bun provides a comprehensive middleware system with built-in middlewares for common use cases. All middleware functions are TypeScript-ready and follow the standard middleware pattern.
 
+## Dependency Installation
+
+⚠️ **Important**: Starting with v1.2.2, middleware dependencies are now **optional** and must be installed separately when needed. This reduces the framework's footprint and improves startup performance through lazy loading.
+
+Install only the dependencies you need:
+
+```bash
+# For JWT Authentication middleware
+bun install jose
+
+# For Logger middleware
+bun install pino
+
+# For Prometheus Metrics middleware
+bun install prom-client
+```
+
+**Benefits of Lazy Loading:**
+
+- 📦 **Smaller Bundle**: Only install what you use
+- ⚡ **Faster Startup**: Dependencies loaded only when middleware is used
+- 💾 **Lower Memory**: Reduced initial memory footprint
+- 🔧 **Better Control**: Explicit dependency management
+
 ## Table of Contents
 
 - [Middleware Pattern](#middleware-pattern)
@@ -10,6 +34,7 @@
   - [CORS](#cors)
   - [JWT Authentication](#jwt-authentication)
   - [Logger](#logger)
+  - [Prometheus Metrics](#prometheus-metrics)
   - [Rate Limiting](#rate-limiting)
 - [Creating Custom Middleware](#creating-custom-middleware)
 
@@ -50,6 +75,7 @@ import {
   createLogger,
   createJWTAuth,
   createRateLimit,
+  createPrometheusIntegration,
 } from '0http-bun/lib/middleware'
 ```
 
@@ -65,6 +91,9 @@ const {
   createJWTAuth,
   createLogger,
   createRateLimit,
+  createPrometheusMiddleware,
+  createMetricsHandler,
+  createPrometheusIntegration,
 } = require('0http-bun/lib/middleware')
 ```
 
@@ -78,6 +107,9 @@ import {
   createJWTAuth,
   createLogger,
   createRateLimit,
+  createPrometheusMiddleware,
+  createMetricsHandler,
+  createPrometheusIntegration,
 } from '0http-bun/lib/middleware'
 
 // Import types
@@ -94,6 +126,8 @@ import type {
 
 Automatically parses request bodies based on Content-Type header.
 
+> ✅ **No additional dependencies required** - Uses Bun's built-in parsing capabilities.
+
 ```javascript
 const {createBodyParser} = require('0http-bun/lib/middleware')
 
@@ -142,6 +176,8 @@ router.use(createBodyParser(bodyParserOptions))
 
 Cross-Origin Resource Sharing middleware with flexible configuration.
 
+> ✅ **No additional dependencies required** - Built-in CORS implementation.
+
 ```javascript
 const {createCORS} = require('0http-bun/lib/middleware')
 
@@ -194,6 +230,8 @@ router.use(createCORS(corsOptions))
 
 JSON Web Token authentication and authorization middleware with support for static secrets, JWKS endpoints, and API key authentication.
 
+> 📦 **Required dependency**: `bun install jose`
+
 #### Basic JWT with Static Secret
 
 ```javascript
@@ -445,6 +483,9 @@ router.get('/api/profile', (req) => {
 
 Request logging middleware with customizable output formats.
 
+> 📦 **Required dependency for structured logging**: `bun install pino`  
+> ✅ **Simple logger** (`simpleLogger`) has no dependencies - uses `console.log`
+
 ```javascript
 const {createLogger, simpleLogger} = require('0http-bun/lib/middleware')
 
@@ -503,10 +544,228 @@ router.use(createLogger(loggerOptions))
 - `tiny` - Minimal output
 - `dev` - Development-friendly colored output
 
+### Prometheus Metrics
+
+Comprehensive Prometheus metrics integration for monitoring and observability with built-in security and performance optimizations.
+
+> 📦 **Required dependency**: `bun install prom-client`
+
+```javascript
+const {
+  createPrometheusMiddleware,
+  createMetricsHandler,
+  createPrometheusIntegration,
+} = require('0http-bun/lib/middleware')
+
+// Simple setup with default metrics
+const prometheus = createPrometheusIntegration()
+
+router.use(prometheus.middleware)
+router.get('/metrics', prometheus.metricsHandler)
+```
+
+#### Default Metrics Collected
+
+The Prometheus middleware automatically collects:
+
+- **HTTP Request Duration** - Histogram of request durations in seconds (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 Count** - Counter of total requests by method, route, and status
+- **HTTP Request Size** - Histogram of request body sizes (buckets: 1B, 10B, 100B, 1KB, 10KB, 100KB, 1MB, 10MB)
+- **HTTP Response Size** - Histogram of response body sizes (buckets: 1B, 10B, 100B, 1KB, 10KB, 100KB, 1MB, 10MB)
+- **Active Connections** - Gauge of currently active HTTP connections
+- **Node.js Metrics** - Memory usage, CPU, garbage collection (custom buckets), event loop lag (5ms precision)
+
+#### Advanced Configuration
+
+```javascript
+const {
+  createPrometheusMiddleware,
+  createMetricsHandler,
+  createPrometheusIntegration,
+} = require('0http-bun/lib/middleware')
+
+const prometheus = createPrometheusIntegration({
+  // Control default Node.js metrics collection
+  collectDefaultMetrics: true,
+
+  // Exclude paths from metrics collection (optimized for performance)
+  excludePaths: ['/health', '/ping', '/favicon.ico'],
+
+  // Skip certain HTTP methods
+  skipMethods: ['OPTIONS'],
+
+  // Custom route normalization with security controls
+  normalizeRoute: (req) => {
+    const url = new URL(req.url, 'http://localhost')
+    return url.pathname
+      .replace(/\/users\/\d+/, '/users/:id')
+      .replace(/\/api\/v\d+/, '/api/:version')
+  },
+
+  // Add custom labels with automatic sanitization
+  extractLabels: (req, response) => {
+    return {
+      user_type: req.headers.get('x-user-type') || 'anonymous',
+      api_version: req.headers.get('x-api-version') || 'v1',
+    }
+  },
+
+  // Use custom metrics object instead of default metrics
+  metrics: customMetricsObject,
+})
+```
+
+#### Custom Business Metrics
+
+```javascript
+const {
+  createPrometheusIntegration,
+} = require('0http-bun/lib/middleware')
+
+// Get the prometheus client from the integration
+const prometheus = createPrometheusIntegration()
+const {promClient} = prometheus
+
+// Create custom metrics
+const orderCounter = new promClient.Counter({
+  name: 'orders_total',
+  help: 'Total number of orders processed',
+  labelNames: ['status', 'payment_method'],
+})
+
+const orderValue = new promClient.Histogram({
+  name: 'order_value_dollars',
+  help: 'Value of orders in dollars',
+  labelNames: ['payment_method'],
+  buckets: [10, 50, 100, 500, 1000, 5000],
+})
+
+// Use in your routes
+router.post('/orders', async (req) => {
+  const order = await processOrder(req.body)
+
+  // Record custom metrics
+  orderCounter.inc({
+    status: order.status,
+    payment_method: order.payment_method,
+  })
+
+  if (order.status === 'completed') {
+    orderValue.observe(
+      {
+        payment_method: order.payment_method,
+      },
+      order.amount,
+    )
+  }
+
+  return Response.json(order)
+})
+```
+
+#### Metrics Endpoint Options
+
+```javascript
+const {createMetricsHandler} = require('0http-bun/lib/middleware')
+
+// Custom metrics endpoint
+const metricsHandler = createMetricsHandler({
+  endpoint: '/custom-metrics', // Default: '/metrics'
+  registry: customRegistry, // Default: promClient.register
+})
+
+router.get('/custom-metrics', metricsHandler)
+```
+
+#### Route Normalization & Security
+
+The middleware automatically normalizes routes and implements security measures to prevent high cardinality and potential attacks:
+
+```javascript
+// URLs like these:
+// /users/123, /users/456, /users/789
+// Are normalized to: /users/:id
+
+// /products/abc-123, /products/def-456
+// Are normalized to: /products/:slug
+
+// /api/v1/data, /api/v2/data
+// Are normalized to: /api/:version/data
+
+// Route sanitization examples:
+// /users/:id → _users__id (special characters replaced with underscores)
+// /api/v1/orders → _api_v1_orders
+// Very long tokens → _api__token (pattern-based normalization)
+```
+
+**Route Sanitization:**
+
+- Special characters (`/`, `:`, etc.) are replaced with underscores (`_`) for Prometheus compatibility
+- UUIDs are automatically normalized to `:id` patterns
+- Long tokens (>20 characters) are normalized to `:token` patterns
+- Numeric IDs are normalized to `:id` patterns
+- Route complexity is limited to 10 segments maximum
+
+**Security Features:**
+
+- **Label Sanitization**: Removes potentially dangerous characters from metric labels and truncates values to 100 characters
+- **Cardinality Limits**: Prevents memory exhaustion from too many unique metric combinations
+- **Route Complexity Limits**: Caps the number of route segments to 10 to prevent DoS attacks
+- **Size Limits**: Limits request/response body size processing (up to 100MB) to prevent memory issues
+- **Header Processing Limits**: Caps the number of headers processed per request (50 for requests, 20 for responses)
+- **URL Processing**: Handles both full URLs and pathname-only URLs with proper fallback handling
+
+#### Performance Optimizations
+
+- **Fast Path for Excluded Routes**: Bypasses all metric collection for excluded paths with smart URL parsing
+- **Lazy Evaluation**: Only processes metrics when actually needed
+- **Efficient Size Calculation**: Optimized request/response size measurement with capping at 1MB estimation
+- **Error Handling**: Graceful handling of malformed URLs and invalid data with fallback mechanisms
+- **Header Count Limits**: Prevents excessive header processing overhead (50 request headers, 20 response headers)
+- **Smart URL Parsing**: Handles both full URLs and pathname-only URLs efficiently
+
+#### Production Considerations
+
+- **Performance**: Adds <1ms overhead per request with optimized fast paths
+- **Memory**: Metrics stored in memory with cardinality controls; use recording rules for high cardinality
+- **Security**: Built-in protections against label injection and cardinality bombs
+- **Cardinality**: Automatic limits prevent high cardinality issues
+- **Monitoring**: Consider protecting `/metrics` endpoint in production
+
+#### Integration with Monitoring
+
+```yaml
+# prometheus.yml
+scrape_configs:
+  - job_name: '0http-bun-app'
+    static_configs:
+      - targets: ['localhost:3000']
+    scrape_interval: 15s
+    metrics_path: /metrics
+```
+
+#### Troubleshooting
+
+**Common Issues:**
+
+- **High Memory Usage**: Check for high cardinality metrics. Route patterns should be normalized (e.g., `/users/:id` not `/users/12345`)
+- **Missing Metrics**: Ensure paths aren't in `excludePaths` and HTTP methods aren't in `skipMethods`
+- **Route Sanitization**: Routes are automatically sanitized (special characters become underscores: `/users/:id` → `_users__id`)
+- **URL Parsing Errors**: The middleware handles both full URLs and pathname-only URLs with graceful fallback
+
+**Performance Tips:**
+
+- Use `excludePaths` for health checks and static assets
+- Consider using `skipMethods` for OPTIONS requests
+- Monitor memory usage in production for metric cardinality
+- Use Prometheus recording rules for high-cardinality aggregations
+
 ### Rate Limiting
 
 Configurable rate limiting middleware with multiple store options.
 
+> ✅ **No additional dependencies required** - Uses built-in memory store.
+
 ```javascript
 const {createRateLimit, MemoryStore} = require('0http-bun/lib/middleware')
 
@@ -794,8 +1053,8 @@ Apply middleware only to specific paths:
 
 ```typescript
 // API-only middleware
-router.use('/api/*', jwtAuth({secret: 'api-secret'}))
-router.use('/api/*', rateLimit({max: 1000}))
+router.use('/api/*', createJWTAuth({secret: 'api-secret'}))
+router.use('/api/*', createRateLimit({max: 1000}))
 
 // Admin-only middleware
 router.use('/admin/*', adminAuthMiddleware)
@@ -867,4 +1126,24 @@ router.get('/api/public/status', () => Response.json({status: 'ok'}))
 router.get('/api/protected/data', (req) => Response.json({user: req.user}))
 ```
 
+## Dependency Summary
+
+For your convenience, here's a quick reference of which dependencies you need to install for each middleware:
+
+| Middleware              | Dependencies Required | Install Command           |
+| ----------------------- | --------------------- | ------------------------- |
+| **Body Parser**         | ✅ None               | Built-in                  |
+| **CORS**                | ✅ None               | Built-in                  |
+| **Rate Limiting**       | ✅ None               | Built-in                  |
+| **Logger** (simple)     | ✅ None               | Built-in                  |
+| **Logger** (structured) | 📦 `pino`             | `bun install pino`        |
+| **JWT Authentication**  | 📦 `jose`             | `bun install jose`        |
+| **Prometheus Metrics**  | 📦 `prom-client`      | `bun install prom-client` |
+
+**Install all optional dependencies at once:**
+
+```bash
+bun install pino jose prom-client
+```
+
 This middleware stack provides a solid foundation for most web applications with security, logging, and performance features built-in.

package/lib/middleware/index.d.ts

@@ -1,5 +1,4 @@
-import {RequestHandler, ZeroRequest, StepFunction} from '../../common'
-import {Logger} from 'pino'
+import {RequestHandler, ZeroRequest} from '../../common'
 
 // Logger middleware types
 export interface LoggerOptions {
@@ -234,3 +233,68 @@ export function createMultipartParser(
 export function createBodyParser(options?: BodyParserOptions): RequestHandler
 export function hasBody(req: ZeroRequest): boolean
 export function shouldParse(req: ZeroRequest, type: string): boolean
+
+// Prometheus metrics middleware types
+export interface PrometheusMetrics {
+  httpRequestDuration: any // prom-client Histogram
+  httpRequestTotal: any // prom-client Counter
+  httpRequestSize: any // prom-client Histogram
+  httpResponseSize: any // prom-client Histogram
+  httpActiveConnections: any // prom-client Gauge
+}
+
+export interface PrometheusMiddlewareOptions {
+  /** Custom metrics object to use instead of default metrics */
+  metrics?: PrometheusMetrics
+  /** Paths to exclude from metrics collection (default: ['/health', '/ping', '/favicon.ico', '/metrics']) */
+  excludePaths?: string[]
+  /** Whether to collect default Node.js metrics (default: true) */
+  collectDefaultMetrics?: boolean
+  /** Custom route normalization function */
+  normalizeRoute?: (req: ZeroRequest) => string
+  /** Custom label extraction function */
+  extractLabels?: (
+    req: ZeroRequest,
+    response: Response,
+  ) => Record<string, string>
+  /** HTTP methods to skip from metrics collection */
+  skipMethods?: string[]
+}
+
+export interface MetricsHandlerOptions {
+  /** The endpoint path for metrics (default: '/metrics') */
+  endpoint?: string
+  /** Custom Prometheus registry to use */
+  registry?: any // prom-client Registry
+}
+
+export interface PrometheusIntegration {
+  /** The middleware function */
+  middleware: RequestHandler
+  /** The metrics handler function */
+  metricsHandler: RequestHandler
+  /** The Prometheus registry */
+  registry: any // prom-client Registry
+  /** The prom-client module */
+  promClient: any
+}
+
+export function createPrometheusMiddleware(
+  options?: PrometheusMiddlewareOptions,
+): RequestHandler
+export function createMetricsHandler(
+  options?: MetricsHandlerOptions,
+): RequestHandler
+export function createPrometheusIntegration(
+  options?: PrometheusMiddlewareOptions & MetricsHandlerOptions,
+): PrometheusIntegration
+export function createDefaultMetrics(): PrometheusMetrics
+export function extractRoutePattern(req: ZeroRequest): string
+
+// Simple interface exports for common use cases
+export const logger: typeof createLogger
+export const jwtAuth: typeof createJWTAuth
+export const rateLimit: typeof createRateLimit
+export const cors: typeof createCORS
+export const bodyParser: typeof createBodyParser
+export const prometheus: typeof createPrometheusIntegration

package/lib/middleware/index.js

@@ -4,6 +4,7 @@ const jwtAuthModule = require('./jwt-auth')
 const rateLimitModule = require('./rate-limit')
 const corsModule = require('./cors')
 const bodyParserModule = require('./body-parser')
+const prometheusModule = require('./prometheus')
 
 module.exports = {
   // Simple interface for common use cases (matches test expectations)
@@ -12,6 +13,7 @@ module.exports = {
   rateLimit: rateLimitModule.createRateLimit,
   cors: corsModule.createCORS,
   bodyParser: bodyParserModule.createBodyParser,
+  prometheus: prometheusModule.createPrometheusIntegration,
 
   // Complete factory functions for advanced usage
   createLogger: loggerModule.createLogger,
@@ -42,4 +44,11 @@ module.exports = {
   createBodyParser: bodyParserModule.createBodyParser,
   hasBody: bodyParserModule.hasBody,
   shouldParse: bodyParserModule.shouldParse,
+
+  // Prometheus metrics middleware
+  createPrometheusMiddleware: prometheusModule.createPrometheusMiddleware,
+  createMetricsHandler: prometheusModule.createMetricsHandler,
+  createPrometheusIntegration: prometheusModule.createPrometheusIntegration,
+  createDefaultMetrics: prometheusModule.createDefaultMetrics,
+  extractRoutePattern: prometheusModule.extractRoutePattern,
 }

package/lib/middleware/jwt-auth.js

@@ -1,4 +1,17 @@
-const {jwtVerify, createRemoteJWKSet, errors} = require('jose')
+// Lazy load jose to improve startup performance
+let joseLib = null
+function loadJose() {
+  if (!joseLib) {
+    try {
+      joseLib = require('jose')
+    } catch (error) {
+      throw new Error(
+        'jose is required for JWT middleware. Install it with: bun install jose',
+      )
+    }
+  }
+  return joseLib
+}
 
 /**
  * Creates JWT authentication middleware
@@ -60,6 +73,7 @@ function createJWTAuth(options = {}) {
       keyLike = jwks
     }
   } else if (jwksUri) {
+    const {createRemoteJWKSet} = loadJose()
     keyLike = createRemoteJWKSet(new URL(jwksUri))
   } else if (typeof secret === 'function') {
     keyLike = secret
@@ -143,6 +157,7 @@ function createJWTAuth(options = {}) {
       }
 
       // Verify JWT token
+      const {jwtVerify} = loadJose()
       const {payload, protectedHeader} = await jwtVerify(
         token,
         keyLike,
@@ -302,16 +317,19 @@ function handleAuthError(error, handlers = {}, req) {
     message = 'Invalid API key'
   } else if (error.message === 'JWT verification not configured') {
     message = 'JWT verification not configured'
-  } else if (error instanceof errors.JWTExpired) {
-    message = 'Token expired'
-  } else if (error instanceof errors.JWTInvalid) {
-    message = 'Invalid token format'
-  } else if (error instanceof errors.JWKSNoMatchingKey) {
-    message = 'Token signature verification failed'
-  } else if (error.message.includes('audience')) {
-    message = 'Invalid token audience'
-  } else if (error.message.includes('issuer')) {
-    message = 'Invalid token issuer'
+  } else {
+    const {errors} = loadJose()
+    if (error instanceof errors.JWTExpired) {
+      message = 'Token expired'
+    } else if (error instanceof errors.JWTInvalid) {
+      message = 'Invalid token format'
+    } else if (error instanceof errors.JWKSNoMatchingKey) {
+      message = 'Token signature verification failed'
+    } else if (error.message.includes('audience')) {
+      message = 'Invalid token audience'
+    } else if (error.message.includes('issuer')) {
+      message = 'Invalid token issuer'
+    }
   }
 
   return new Response(JSON.stringify({error: message}), {

package/lib/middleware/logger.js

@@ -1,6 +1,20 @@
-const pino = require('pino')
 const crypto = require('crypto')
 
+// Lazy load pino to improve startup performance
+let pino = null
+function loadPino() {
+  if (!pino) {
+    try {
+      pino = require('pino')
+    } catch (error) {
+      throw new Error(
+        'pino is required for logger middleware. Install it with: bun install pino',
+      )
+    }
+  }
+  return pino
+}
+
 /**
  * Creates a logging middleware using Pino logger
  * @param {Object} options - Logger configuration options
@@ -27,9 +41,10 @@ function createLogger(options = {}) {
   } = options
 
   // Build final pino options with proper precedence
+  const pinoLib = loadPino()
   const finalPinoOptions = {
     level: level || pinoOptions.level || process.env.LOG_LEVEL || 'info',
-    timestamp: pino.stdTimeFunctions.isoTime,
+    timestamp: pinoLib.stdTimeFunctions.isoTime,
     formatters: {
       level: (label) => ({level: label.toUpperCase()}),
     },
@@ -41,7 +56,7 @@ function createLogger(options = {}) {
         ...(logBody && req.body ? {body: req.body} : {}),
       }),
       // Default res serializer removed to allow logResponse to handle it fully
-      err: pino.stdSerializers.err,
+      err: pinoLib.stdSerializers.err,
       // Merge in custom serializers if provided
       ...(serializers || {}),
     },
@@ -49,7 +64,7 @@ function createLogger(options = {}) {
   }
 
   // Use injected logger if provided (for tests), otherwise create a new one
-  const logger = injectedLogger || pino(finalPinoOptions)
+  const logger = injectedLogger || pinoLib(finalPinoOptions)
 
   return function loggerMiddleware(req, next) {
     const startTime = process.hrtime.bigint()

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "0http-bun",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "0http for Bun",
   "main": "index.js",
   "scripts": {
@@ -11,9 +11,7 @@
   },
   "dependencies": {
     "fast-querystring": "^1.1.2",
-    "trouter": "^4.0.0",
-    "jose": "^6.0.11",
-    "pino": "^9.7.0"
+    "trouter": "^4.0.0"
   },
   "repository": {
     "type": "git",
@@ -28,11 +26,14 @@
     "lib/"
   ],
   "devDependencies": {
-    "0http-bun": "^1.1.2",
-    "bun-types": "^1.2.15",
+    "0http-bun": "^1.2.1",
+    "bun-types": "^1.2.16",
     "mitata": "^1.0.34",
     "prettier": "^3.5.3",
-    "typescript": "^5.8.3"
+    "typescript": "^5.8.3",
+    "jose": "^6.0.11",
+    "pino": "^9.7.0",
+    "prom-client": "^15.1.3"
   },
   "keywords": [
     "http",