🚀 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.

Landing page: https://bungate.21no.de
Full Documentation: docs/DOCUMENTATION.md

---

⚡ 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 - 8+ algorithms including round-robin, least-connections, weighted, ip-hash, p2c, latency
• 🛡️ Production Ready - Circuit breakers, health checks, auto-failover
• 🔐 Built-in Auth - JWT, API keys, JWKS, OAuth2 support out of the box
• 🔒 Enterprise Security - TLS 1.3, input validation, security headers, OWASP Top 10 protection
• 🎨 Developer Friendly - Full TypeScript support with intuitive APIs
• 📊 Observable - Built-in Prometheus metrics, structured logging, monitoring
• 🔧 Extensible - Powerful middleware system for custom logic
• ⚡ Cluster Mode - Multi-process scaling with zero-downtime restarts

See benchmarks comparing Bungate with Nginx and Envoy.

---

🚀 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 },
})

// 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,
      path: '/health',
    },
  },
})

// Add rate limiting
gateway.addRoute({
  pattern: '/public/*',
  target: 'http://backend.example.com',
  rateLimit: {
    max: 1000,
    windowMs: 60000,
  },
})

// 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

👉 Full Quick Start Guide

---

🌟 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
• 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
• Least Connections - Route to the least busy server
• IP Hash - Consistent routing for session affinity
• Random - Randomized distribution
• Power of Two Choices (P2C) - Pick better of two random targets
• Latency - Prefer the fastest server
• Weighted Least Connections - Combine capacity with load awareness
• Sticky Sessions - Cookie-based session persistence

👉 Load Balancing Guide

🛡️ 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

🔐 Built-in Authentication

• JWT - Full JWT support with HS256, RS256, and more
• JWKS - JSON Web Key Set for dynamic key management
• API Keys - Simple key-based authentication
• OAuth2/OIDC - Integration with external identity providers
• Custom Validation - Extensible authentication logic

👉 Authentication Guide

🔒 Enterprise Security

• TLS/HTTPS - Full TLS 1.3 support with automatic HTTP redirect
• Input Validation - Comprehensive validation and sanitization
• Security Headers - HSTS, CSP, X-Frame-Options, and more
• Session Management - Cryptographically secure session IDs
• Trusted Proxies - IP validation and forwarded header verification
• Request Size Limits - Protection against DoS attacks
• JWT Key Rotation - Zero-downtime key rotation support

👉 Security Guide | TLS Configuration

📊 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

---

🔒 Quick Start with TLS/HTTPS

For production deployments with HTTPS:

import { BunGateway } from 'bungate'

const gateway = new BunGateway({
  server: { port: 443 },
  security: {
    tls: {
      enabled: true,
      cert: './cert.pem',
      key: './key.pem',
      minVersion: 'TLSv1.3',
      redirectHTTP: true,
      redirectPort: 80,
    },
  },
})

gateway.addRoute({
  pattern: '/api/*',
  target: 'http://backend:3000',
  auth: {
    secret: process.env.JWT_SECRET,
    jwtOptions: {
      algorithms: ['HS256'],
      issuer: 'https://auth.example.com',
    },
  },
})

await gateway.listen()
console.log('🔒 Secure gateway running on https://localhost')

👉 TLS Configuration Guide

---

⚡ 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,
  },
})

gateway.addRoute({
  pattern: '/api/*',
  loadBalancer: {
    strategy: 'least-connections',
    targets: [
      { url: 'http://api-server-1:8080' },
      { url: 'http://api-server-2:8080' },
    ],
  },
})

await gateway.listen()
console.log('Cluster started with 4 workers')

Features:

• ✅ Zero-downtime rolling restarts (SIGUSR2)
• ✅ Dynamic scaling (scale up/down at runtime)
• ✅ Automatic worker respawn
• ✅ Graceful shutdown
• ✅ Signal-based control

👉 Clustering Guide

---

📦 Installation

Prerequisites

• Bun >= 1.2.18 (Install Bun)

Install Bungate

# Using Bun (recommended)
bun add bungate

# Using npm
npm install bungate

# Using yarn
yarn add bungate

---

📚 Documentation

📖 Complete Documentation

Getting Started:

• Quick Start Guide - Get up and running in 5 minutes
• Examples - Real-world use cases and patterns

Core Features:

• Load Balancing - 8+ strategies and configuration
• Clustering - Multi-process scaling
• Authentication - JWT, API keys, OAuth2

Security:

• Security Guide - Enterprise security features
• TLS Configuration - HTTPS setup

Reference:

• API Reference - Complete API documentation
• Troubleshooting - Common issues and solutions

---

🏗️ Real-World Examples

Microservices Gateway

import { BunGateway } from 'bungate'

const gateway = new BunGateway({
  server: { port: 8080 },
  cluster: { enabled: true, workers: 4 },
  auth: {
    secret: process.env.JWT_SECRET,
    excludePaths: ['/health', '/auth/*'],
  },
  cors: {
    origin: ['https://myapp.com', 'https://admin.myapp.com'],
    credentials: true,
  },
})

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

// Payment service with circuit breaker
gateway.addRoute({
  pattern: '/payments/*',
  target: 'http://payment-service:3002',
  circuitBreaker: {
    enabled: true,
    failureThreshold: 3,
  },
})

await gateway.listen()

👉 More Examples

---

🔧 Advanced Features

Custom Middleware

gateway.addRoute({
  pattern: '/api/*',
  target: 'http://backend:3000',
  middlewares: [
    async (req, next) => {
      // Custom logic before request
      console.log('Request:', req.method, req.url)
      const response = await next()
      // Custom logic after response
      console.log('Response:', response.status)
      return response
    },
  ],
})

Circuit Breaker with Fallback

gateway.addRoute({
  pattern: '/api/*',
  target: 'http://backend:3000',
  circuitBreaker: {
    enabled: true,
    failureThreshold: 5,
    timeout: 10000,
    resetTimeout: 30000,
  },
  hooks: {
    onError: async (req, error) => {
      // Return cached data or fallback response
      return new Response(
        JSON.stringify({ cached: true, data: getCachedData() }),
        { status: 200 },
      )
    },
  },
})

Rate Limiting by User

gateway.addRoute({
  pattern: '/api/*',
  target: 'http://backend:3000',
  auth: {
    secret: process.env.JWT_SECRET,
    jwtOptions: { algorithms: ['HS256'] },
  },
  rateLimit: {
    max: 1000,
    windowMs: 60000,
    keyGenerator: (req) => (req as any).user?.id || 'anonymous',
  },
})

---

📊 Benchmarks

Bungate delivers exceptional performance:

• 18K+ requests/second with load balancing
• Single-digit millisecond average latency
• Sub-30ms 99th percentile response times
• Lower memory footprint vs alternatives

See detailed benchmark results comparing Bungate with Nginx and Envoy.

---

🤝 Contributing

Contributions are welcome! Please check out our contributing guidelines (if available).

Reporting Issues

Found a bug or have a feature request?

• 🐛 Report Issues
• 💬 Discussions

---

📄 License

MIT Licensed - see LICENSE for details.

---

🌟 Star History

If you find Bungate useful, please consider giving it a star on GitHub!

---

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

🏠 Homepage | 📚 Documentation | 🐛 Issues | 💬 Discussions

⭐ Star on GitHub ⭐