bungate

🚀 Bungate

The Lightning-Fast HTTP Gateway & Load Balancer for the Modern Web

Bungate is a next-generation HTTP gateway and load balancer that harnesses the incredible speed of Bun to deliver unparalleled performance for modern web applications. Built from the ground up with TypeScript, it provides enterprise-grade features with zero-config simplicity.

⚡ Why Bungate?

• 🔥 Blazing Fast: Built on Bun - up to 4x faster than Node.js alternatives
• 🎯 Zero Config: Works out of the box with sensible defaults
• 🧠 Smart Load Balancing: Multiple algorithms: round-robin, least-connections, random, weighted, ip-hash, p2c (power-of-two-choices), latency, weighted-least-connections
• 🛡️ Production Ready: Circuit breakers, health checks, and auto-failover
• 🔐 Built-in Authentication: JWT, API keys, JWKS, and OAuth2 support out of the box
• 🎨 Developer Friendly: Full TypeScript support with intuitive APIs
• 📊 Observable: Built-in metrics, logging, and monitoring
• 🔧 Extensible: Powerful middleware system for custom logic

See benchmarks comparing Bungate with Nginx and Envoy in the benchmark directory.

🚀 Quick Start

Get up and running in less than 60 seconds:

# Install Bungate
bun add bungate

# Create your gateway
touch gateway.ts

import { BunGateway } from 'bungate'

// Create a production-ready gateway with zero config
const gateway = new BunGateway({
  server: { port: 3000 },
  metrics: { enabled: true }, // Enable Prometheus metrics
})

// Add intelligent load balancing
gateway.addRoute({
  pattern: '/api/*',
  loadBalancer: {
    strategy: 'least-connections',
    targets: [
      { url: 'http://api1.example.com' },
      { url: 'http://api2.example.com' },
      { url: 'http://api3.example.com' },
    ],
    healthCheck: {
      enabled: true,
      interval: 30000,
      timeout: 5000,
      path: '/health',
    },
  },
})

// Add rate limiting and single target for public routes
gateway.addRoute({
  pattern: '/public/*',
  target: 'http://backend.example.com',
  rateLimit: {
    max: 1000,
    windowMs: 60000,
    keyGenerator: (req) => req.headers.get('x-forwarded-for') || 'unknown',
  },
})

// Start the gateway
await gateway.listen()
console.log('🚀 Bungate running on http://localhost:3000')

That's it! Your high-performance gateway is now handling traffic with:

• ✅ Automatic load balancing
• ✅ Health monitoring
• ✅ Rate limiting
• ✅ Circuit breaker protection
• ✅ Prometheus metrics
• ✅ Cluster mode support
• ✅ Structured logging

🌟 Key Features

🚀 Performance & Scalability

• High Throughput: Handle thousands of requests per second
• Low Latency: Minimal overhead routing with optimized request processing
• Memory Efficient: Optimized for high-concurrent workloads
• Auto-scaling: Dynamic target management and health monitoring
• Cluster Mode: Multi-process clustering for maximum CPU utilization

🎯 Load Balancing Strategies

• Round Robin: Equal distribution across all targets
• Weighted: Distribute based on server capacity and weights
• Least Connections: Route to the least busy server
• IP Hash: Consistent routing based on client IP for session affinity
• Random: Randomized distribution for even load
• Power of Two Choices (p2c): Pick the better of two random targets by load/latency
• Latency: Prefer the target with the lowest average response time
• Weighted Least Connections: Prefer targets with fewer connections normalized by weight
• Sticky Sessions: Session affinity with cookie-based persistence

🛡️ Reliability & Resilience

• Circuit Breaker Pattern: Automatic failure detection and recovery
• Health Checks: Active monitoring with custom validation
• Timeout Management: Route-level and global timeout controls
• Auto-failover: Automatic traffic rerouting on service failures
• Graceful Degradation: Fallback responses and cached data support

🔧 Advanced Features

• Authentication & Authorization: JWT, API keys, JWKS, OAuth2/OIDC support
• Middleware System: Custom request/response processing pipeline
• Path Rewriting: URL transformation and routing rules
• Rate Limiting: Flexible rate limiting with custom key generation
• CORS Support: Full cross-origin resource sharing configuration
• Request/Response Hooks: Comprehensive lifecycle event handling

📊 Monitoring & Observability

• Prometheus Metrics: Out-of-the-box performance metrics
• Structured Logging: JSON logging with request tracing
• Health Endpoints: Built-in health check APIs
• Real-time Statistics: Live performance monitoring
• Custom Metrics: Application-specific metric collection

🎨 Developer Experience

• TypeScript First: Full type safety and IntelliSense support
• Zero Dependencies: Minimal footprint with essential features only
• Hot Reload: Development mode with automatic restarts
• Rich Documentation: Comprehensive examples and API documentation
• Testing Support: Built-in utilities for testing and development

🏗️ Real-World Examples

🌐 Microservices Gateway

Perfect for microservices architectures with intelligent routing:

import { BunGateway } from 'bungate'

const gateway = new BunGateway({
  server: { port: 8080 },
  cors: {
    origin: ['https://myapp.com', 'https://admin.myapp.com'],
    credentials: true,
  },
})

// User service with JWT authentication
gateway.addRoute({
  pattern: '/users/*',
  target: 'http://user-service:3001',
  auth: {
    secret: process.env.JWT_SECRET || 'your-secret-key',
    jwtOptions: {
      algorithms: ['HS256'],
      issuer: 'https://auth.myapp.com',
      audience: 'https://api.myapp.com',
    },
    optional: false,
    excludePaths: ['/users/register', '/users/login'],
  },
  rateLimit: {
    max: 100,
    windowMs: 60000,
    keyGenerator: (req) =>
      (req as any).user?.id || req.headers.get('x-forwarded-for') || 'unknown',
  },
})

// Payment service with circuit breaker
gateway.addRoute({
  pattern: '/payments/*',
  target: 'http://payment-service:3002',
  circuitBreaker: {
    enabled: true,
    failureThreshold: 3,
    timeout: 5000,
    resetTimeout: 5000,
  },
  hooks: {
    onError(req, error): Promise<Response> {
      // Fallback to cached payment status
      return getCachedPaymentStatus(req.url)
    },
  },
})

🔄 High-Performance Cluster Mode

Scale horizontally with multi-process clustering:

import { BunGateway } from 'bungate'

const gateway = new BunGateway({
  server: { port: 3000 },
  cluster: {
    enabled: true,
    workers: 4, // Number of worker processes
    restartWorkers: true,
    maxRestarts: 10,
    shutdownTimeout: 30000,
  },
})

// High-traffic API endpoints
gateway.addRoute({
  pattern: '/api/v1/*',
  loadBalancer: {
    targets: [
      { url: 'http://api-server-1:8080', weight: 2 },
      { url: 'http://api-server-2:8080', weight: 2 },
      { url: 'http://api-server-3:8080', weight: 1 },
    ],
    strategy: 'least-connections',
    healthCheck: {
      enabled: true,
      interval: 5000,
      timeout: 2000,
      path: '/health',
    },
  },
})

// Start cluster
await gateway.listen(3000)
console.log('Cluster started with 4 workers')

Advanced usage: Cluster lifecycle and operations

Bungate’s cluster manager powers zero-downtime restarts, dynamic scaling, and safe shutdowns in production. You can control it via signals or programmatically.

• Zero-downtime rolling restart: send SIGUSR2 to the master process
  • The manager spawns a replacement worker first, then gracefully stops the old one
• Graceful shutdown: send SIGTERM or SIGINT
  • Workers receive SIGTERM and are given up to shutdownTimeout to exit before being force-killed

Programmatic controls (available when using the ClusterManager directly):

import { ClusterManager, BunGateLogger } from 'bungate'

const logger = new BunGateLogger({ level: 'info' })

const cluster = new ClusterManager(
  {
    enabled: true,
    workers: 4,
    restartWorkers: true,
    restartDelay: 1000, // base delay used for exponential backoff with jitter
    maxRestarts: 10, // lifetime cap per worker
    respawnThreshold: 5, // sliding window cap
    respawnThresholdTime: 60_000, // within this time window
    shutdownTimeout: 30_000,
    // Set to false when embedding in tests to avoid process.exit(0)
    exitOnShutdown: true,
  },
  logger,
  './gateway.ts', // worker entry (executed with Bun)
)

await cluster.start()

// Dynamic scaling
await cluster.scaleUp(2) // add 2 workers
await cluster.scaleDown(1) // remove 1 worker
await cluster.scaleTo(6) // set exact worker count

// Operational visibility
console.log(cluster.getWorkerCount())
console.log(cluster.getWorkerInfo()) // includes id, restarts, pid, etc.

// Broadcast a POSIX signal to all workers (e.g., for log-level reloads)
cluster.broadcastSignal('SIGHUP')

// Target a single worker
cluster.sendSignalToWorker(1, 'SIGHUP')

// Graceful shutdown (will exit process if exitOnShutdown !== false)
// await (cluster as any).gracefulShutdown() // internal in gateway use; prefer SIGTERM

Notes:

• Each worker receives CLUSTER_WORKER=true and CLUSTER_WORKER_ID=<n> environment variables.
• Restart policy uses exponential backoff with jitter and a sliding window threshold to prevent flapping.
• Defaults: shutdownTimeout 30s, respawnThreshold 5 within 60s, restartDelay 1s, maxRestarts 10.

Configuration reference (cluster):

• enabled (boolean): enable multi-process mode
• workers (number): worker process count (defaults to CPU cores)
• restartWorkers (boolean): auto-respawn crashed workers
• restartDelay (ms): base delay for backoff
• maxRestarts (number): lifetime restarts per worker
• respawnThreshold (number): max restarts within time window
• respawnThresholdTime (ms): sliding window size
• shutdownTimeout (ms): grace period before force-kill
• exitOnShutdown (boolean): if true (default), master exits after shutdown; set false in tests/embedded

🔄 Advanced Load Balancing

Distribute traffic intelligently across multiple backends:

// E-commerce platform with weighted distribution
gateway.addRoute({
  pattern: '/products/*',
  loadBalancer: {
    strategy: 'weighted',
    targets: [
      { url: 'http://products-primary:3000', weight: 70 },
      { url: 'http://products-secondary:3001', weight: 20 },
      { url: 'http://products-cache:3002', weight: 10 },
    ],
    healthCheck: {
      enabled: true,
      path: '/health',
      interval: 15000,
      timeout: 5000,
      expectedStatus: 200,
    },
  },
})

// Session-sticky load balancing for stateful apps
gateway.addRoute({
  pattern: '/app/*',
  loadBalancer: {
    strategy: 'ip-hash',
    targets: [
      { url: 'http://app-server-1:3000' },
      { url: 'http://app-server-2:3000' },
      { url: 'http://app-server-3:3000' },
    ],
    stickySession: {
      enabled: true,
      cookieName: 'app-session',
      ttl: 3600000, // 1 hour
    },
  },
})

🛡️ Enterprise Security

Production-grade security with multiple layers:

// API Gateway with comprehensive security
gateway.addRoute({
  pattern: '/api/v1/*',
  target: 'http://api-backend:3000',
  auth: {
    // JWT authentication
    secret: process.env.JWT_SECRET,
    jwtOptions: {
      algorithms: ['HS256', 'RS256'],
      issuer: 'https://auth.myapp.com',
      audience: 'https://api.myapp.com',
    },
    // API key authentication (fallback)
    apiKeys: async (key, req) => {
      const validKeys = await getValidApiKeys()
      return validKeys.includes(key)
    },
    apiKeyHeader: 'x-api-key',
    optional: false,
    excludePaths: ['/api/v1/health', '/api/v1/public/*'],
  },
  middlewares: [
    // Request validation
    async (req, next) => {
      if (req.method === 'POST' || req.method === 'PUT') {
        const body = await req.json()
        const validation = validateRequestBody(body)
        if (!validation.valid) {
          return new Response(JSON.stringify(validation.errors), {
            status: 400,
            headers: { 'Content-Type': 'application/json' },
          })
        }
      }
      return next()
    },
  ],
  rateLimit: {
    max: 1000,
    windowMs: 60000,
    keyGenerator: (req) =>
      (req as any).user?.id ||
      req.headers.get('x-api-key') ||
      req.headers.get('x-forwarded-for') ||
      'unknown',
    message: 'API rate limit exceeded',
  },
  proxy: {
    headers: {
      'X-Gateway-Version': '1.0.0',
      'X-Request-ID': () => crypto.randomUUID(),
    },
  },
})

🔐 Built-in Authentication

Bungate provides comprehensive authentication support out of the box:

JWT Authentication

// Gateway-level JWT authentication (applies to all routes)
const gateway = new BunGateway({
  server: { port: 3000 },
  auth: {
    secret: process.env.JWT_SECRET,
    jwtOptions: {
      algorithms: ['HS256', 'RS256'],
      issuer: 'https://auth.myapp.com',
      audience: 'https://api.myapp.com',
    },
    excludePaths: ['/health', '/metrics', '/auth/login', '/auth/register'],
  },
})

// Route-level JWT authentication (overrides gateway settings)
gateway.addRoute({
  pattern: '/admin/*',
  target: 'http://admin-service:3000',
  auth: {
    secret: process.env.ADMIN_JWT_SECRET,
    jwtOptions: {
      algorithms: ['RS256'],
      issuer: 'https://auth.myapp.com',
      audience: 'https://admin.myapp.com',
    },
    optional: false,
  },
})

JWKS (JSON Web Key Set) Authentication

gateway.addRoute({
  pattern: '/secure/*',
  target: 'http://secure-service:3000',
  auth: {
    jwksUri: 'https://auth.myapp.com/.well-known/jwks.json',
    jwtOptions: {
      algorithms: ['RS256'],
      issuer: 'https://auth.myapp.com',
      audience: 'https://api.myapp.com',
    },
  },
})

API Key Authentication

gateway.addRoute({
  pattern: '/api/public/*',
  target: 'http://public-api:3000',
  auth: {
    // Static API keys
    apiKeys: ['key1', 'key2', 'key3'],
    apiKeyHeader: 'x-api-key',

    // Dynamic API key validation
    apiKeyValidator: async (key, req) => {
      const user = await validateApiKey(key)
      if (user) {
        // Attach user info to request
        ;(req as any).user = user
        return true
      }
      return false
    },
  },
})

Mixed Authentication (JWT + API Key)

gateway.addRoute({
  pattern: '/api/hybrid/*',
  target: 'http://hybrid-service:3000',
  auth: {
    // JWT authentication
    secret: process.env.JWT_SECRET,
    jwtOptions: {
      algorithms: ['HS256'],
      issuer: 'https://auth.myapp.com',
    },

    // API key fallback
    apiKeys: async (key, req) => {
      return await isValidApiKey(key)
    },
    apiKeyHeader: 'x-api-key',

    // Custom token extraction
    getToken: (req) => {
      return (
        req.headers.get('authorization')?.replace('Bearer ', '') ||
        req.headers.get('x-access-token') ||
        new URL(req.url).searchParams.get('token')
      )
    },

    // Custom error handling
    unauthorizedResponse: {
      status: 401,
      body: { error: 'Authentication required', code: 'AUTH_REQUIRED' },
      headers: { 'Content-Type': 'application/json' },
    },
  },
})

OAuth2 / OpenID Connect

gateway.addRoute({
  pattern: '/oauth/*',
  target: 'http://oauth-service:3000',
  auth: {
    jwksUri: 'https://accounts.google.com/.well-known/jwks.json',
    jwtOptions: {
      algorithms: ['RS256'],
      issuer: 'https://accounts.google.com',
      audience: 'your-google-client-id',
    },

    // Custom validation
    onError: (error, req) => {
      console.error('OAuth validation failed:', error)
      return new Response('OAuth authentication failed', { status: 401 })
    },
  },
})

📦 Installation & Setup

Prerequisites

• Bun >= 1.2.18 (Install Bun)

Installation

# Using Bun (recommended)
bun add bungate

# Using npm
npm install bungate

# Using yarn
yarn add bungate

🚀 Getting Started

Basic Setup

# Create a new project
mkdir my-gateway && cd my-gateway
bun init

# Install BunGate
bun add bungate

# Create your gateway
touch gateway.ts

Configuration Examples

Simple Gateway with Auth

import { BunGateway, BunGateLogger } from 'bungate'

const logger = new BunGateLogger({
  level: 'info',
  format: 'pretty',
  enableRequestLogging: true,
})

const gateway = new BunGateway({
  server: { port: 3000 },

  // Global authentication
  auth: {
    secret: process.env.JWT_SECRET,
    jwtOptions: {
      algorithms: ['HS256'],
      issuer: 'https://auth.myapp.com',
    },
    excludePaths: ['/health', '/metrics', '/auth/*'],
  },

  // Enable metrics
  metrics: { enabled: true },
  // Enable logging
  logger,
})

// Add authenticated routes
gateway.addRoute({
  pattern: '/api/users/*',
  target: 'http://user-service:3001',
  rateLimit: {
    max: 100,
    windowMs: 60000,
  },
})

// Add public routes with API key authentication
gateway.addRoute({
  pattern: '/api/public/*',
  target: 'http://public-service:3002',
  auth: {
    apiKeys: ['public-key-1', 'public-key-2'],
    apiKeyHeader: 'x-api-key',
  },
})

await gateway.listen()
console.log('🚀 Bungate running on http://localhost:3000')

📄 License

MIT Licensed - see LICENSE for details.

Built with ❤️ by 21no.de for the JavaScript Community

🏠 Homepage | 📚 Documentation | 🐛 Issues | 💬 Discussions