feat: Enhance load balancing strategies with power-of-two-choices, latency, and weighted least connections; update README for new features

Author: jkyberneees

README.md

@@ -15,7 +15,7 @@
 
 - **🔥 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**: 5 load balancing algorithms: `round-robin`, `least-connections`, `random`, `weighted`, `ip-hash`
+- **🧠 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
@@ -107,6 +107,9 @@ console.log('🚀 Bungate running on http://localhost:3000')
 - **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**

src/interfaces/load-balancer.ts

@@ -69,6 +69,10 @@ export interface LoadBalancerConfig {
     | 'random' // Randomly selects a target
     | 'weighted' // Uses target weights for distribution
     | 'ip-hash' // Routes based on client IP hash for session affinity
+    | 'p2c' // Power of two choices: pick best of two random targets
+    | 'power-of-two-choices' // Alias for p2c
+    | 'latency' // Chooses target with the lowest avg response time
+    | 'weighted-least-connections' // Least connections normalized by weight
 
   /**
    * List of backend targets to load balance across
@@ -113,6 +117,11 @@ export interface LoadBalancerConfig {
      * @example 'OK' or 'healthy'
      */
     expectedBody?: string
+    /**
+     * HTTP method to use for health checks
+     * @default 'GET'
+     */
+    method?: 'GET' | 'HEAD'
   }
 
   /**

src/load-balancer/http-load-balancer.ts

@@ -151,6 +151,18 @@ export class HttpLoadBalancer implements LoadBalancer {
       return null
     }
 
+    // Fast path: only one healthy target
+    if (healthyTargets.length === 1) {
+      const only = healthyTargets[0]!
+      this.recordRequest(only.url)
+      this.logger.logLoadBalancing(this.config.strategy, only.url, {
+        reason: 'single-healthy',
+        duration: Date.now() - startTime,
+        healthyTargets: 1,
+      })
+      return only
+    }
+
     // Check for sticky session first
     if (this.config.stickySession?.enabled) {
       const stickyTarget = this.getStickyTarget(request)
@@ -184,6 +196,16 @@ export class HttpLoadBalancer implements LoadBalancer {
         case 'ip-hash':
           selectedTarget = this.selectIpHash(request, healthyTargets)
           break
+        case 'p2c':
+        case 'power-of-two-choices':
+          selectedTarget = this.selectPowerOfTwoChoices(healthyTargets)
+          break
+        case 'latency':
+          selectedTarget = this.selectByLatency(healthyTargets)
+          break
+        case 'weighted-least-connections':
+          selectedTarget = this.selectWeightedLeastConnections(healthyTargets)
+          break
         default:
           selectedTarget = this.selectRoundRobin(healthyTargets)
       }
@@ -378,7 +400,8 @@ export class HttpLoadBalancer implements LoadBalancer {
     const target = this.targets.get(url)
     if (target) {
       target.totalResponseTime += responseTime
-      target.averageResponseTime = target.totalResponseTime / target.requests
+      const reqs = target.requests || 1 // avoid division by zero before first selectTarget
+      target.averageResponseTime = target.totalResponseTime / reqs
 
       if (isError) {
         target.errors++
@@ -478,6 +501,69 @@ export class HttpLoadBalancer implements LoadBalancer {
     return targets[index]! // Guaranteed to exist due to length check
   }
 
+  private selectPowerOfTwoChoices(
+    targets: LoadBalancerTarget[],
+  ): LoadBalancerTarget {
+    // Sample two distinct targets at random and choose the better one by connections then latency
+    const i = Math.floor(Math.random() * targets.length)
+    let j = Math.floor(Math.random() * targets.length)
+    if (j === i) j = (j + 1) % targets.length
+    const a = targets[i]!
+    const b = targets[j]!
+    return this.betterByLoadThenLatency(a, b)
+  }
+
+  private selectByLatency(targets: LoadBalancerTarget[]): LoadBalancerTarget {
+    // Choose the target with the smallest averageResponseTime; fallback to round-robin if missing data
+    let best = targets[0]!
+    let bestLatency = best.averageResponseTime ?? Number.POSITIVE_INFINITY
+    for (let k = 1; k < targets.length; k++) {
+      const t = targets[k]!
+      const lat = t.averageResponseTime ?? Number.POSITIVE_INFINITY
+      if (lat < bestLatency) {
+        best = t
+        bestLatency = lat
+      }
+    }
+    if (!isFinite(bestLatency)) {
+      // No latency data available yet
+      return this.selectRoundRobin(targets)
+    }
+    return best
+  }
+
+  private selectWeightedLeastConnections(
+    targets: LoadBalancerTarget[],
+  ): LoadBalancerTarget {
+    // Choose by minimal (connections + 1) / weight
+    return targets.reduce((best, curr) => {
+      const bestScore =
+        (Math.max(0, best.connections ?? 0) + 1) / Math.max(1, best.weight ?? 1)
+      const currScore =
+        (Math.max(0, curr.connections ?? 0) + 1) / Math.max(1, curr.weight ?? 1)
+      if (currScore < bestScore) return curr
+      if (currScore === bestScore) return this.betterByLatency(best, curr)
+      return best
+    })
+  }
+
+  private betterByLatency(a: LoadBalancerTarget, b: LoadBalancerTarget) {
+    const la = a.averageResponseTime ?? Number.POSITIVE_INFINITY
+    const lb = b.averageResponseTime ?? Number.POSITIVE_INFINITY
+    return la <= lb ? a : b
+  }
+
+  private betterByLoadThenLatency(
+    a: LoadBalancerTarget,
+    b: LoadBalancerTarget,
+  ) {
+    const ca = a.connections ?? 0
+    const cb = b.connections ?? 0
+    if (ca < cb) return a
+    if (cb < ca) return b
+    return this.betterByLatency(a, b)
+  }
+
   private recordRequest(url: string): void {
     this.totalRequests++
     const target = this.targets.get(url)
@@ -552,10 +638,21 @@ export class HttpLoadBalancer implements LoadBalancer {
   }
 
   private getClientId(request: Request): string {
-    // In real scenario, would extract actual client IP
-    // For now, use a combination of headers as identifier
-    const userAgent = request.headers.get('user-agent') ?? ''
-    const accept = request.headers.get('accept') ?? ''
+    // Prefer real client IP headers commonly set by proxies/CDNs; fallback to UA+Accept
+    const headers = request.headers
+    const xff = headers.get('x-forwarded-for') || headers.get('X-Forwarded-For')
+    if (xff) {
+      const ip = xff.split(',')[0]!.trim()
+      if (ip) return ip
+    }
+    const realIp =
+      headers.get('x-real-ip') ||
+      headers.get('cf-connecting-ip') ||
+      headers.get('x-client-ip') ||
+      ''
+    if (realIp) return realIp
+    const userAgent = headers.get('user-agent') ?? ''
+    const accept = headers.get('accept') ?? ''
     return userAgent + accept
   }
 
@@ -596,7 +693,7 @@ export class HttpLoadBalancer implements LoadBalancer {
 
           const response = await fetch(url.toString(), {
             signal: controller.signal,
-            method: 'GET',
+            method: healthCheckConfig.method ?? 'GET',
           })
 
           clearTimeout(timeoutId)

test/cluster/fixtures/worker.ts

@@ -3,5 +3,5 @@
 process.on('SIGTERM', () => process.exit(0))
 
 // Keep alive for a very long time (about 1 billion ms ~ 11.5 days)
-const KEEP_ALIVE_INTERVAL = 1 << 30;
+const KEEP_ALIVE_INTERVAL = 1 << 30
 setInterval(() => {}, KEEP_ALIVE_INTERVAL)

test/e2e/random-loadbalancer.test.ts

@@ -271,11 +271,17 @@ describe('Random Load Balancer E2E Tests', () => {
     // Each server should get roughly 1/3 of requests (allow generous variance for randomness)
     const expectedPerServer = requestCount / 3
     expect(serverCounts['echo-1'] || 0).toBeGreaterThan(expectedPerServer * 0.3) // At least 30% of expected
-    expect(serverCounts['echo-1'] || 0).toBeLessThan(expectedPerServer * 1.7) // At most 170% of expected
+    expect(serverCounts['echo-1'] || 0).toBeLessThanOrEqual(
+      expectedPerServer * 1.7,
+    ) // At most 170% of expected
     expect(serverCounts['echo-2'] || 0).toBeGreaterThan(expectedPerServer * 0.3)
-    expect(serverCounts['echo-2'] || 0).toBeLessThan(expectedPerServer * 1.7)
+    expect(serverCounts['echo-2'] || 0).toBeLessThanOrEqual(
+      expectedPerServer * 1.7,
+    )
     expect(serverCounts['echo-3'] || 0).toBeGreaterThan(expectedPerServer * 0.3)
-    expect(serverCounts['echo-3'] || 0).toBeLessThan(expectedPerServer * 1.7)
+    expect(serverCounts['echo-3'] || 0).toBeLessThanOrEqual(
+      expectedPerServer * 1.7,
+    )
   })
 
   test('should randomly distribute requests between two servers', async () => {
@@ -309,9 +315,13 @@ describe('Random Load Balancer E2E Tests', () => {
     // Each server should get roughly half of requests (allow variance for randomness)
     const expectedPerServer = requestCount / 2
     expect(serverCounts['echo-1'] || 0).toBeGreaterThan(expectedPerServer * 0.3) // At least 30% of expected
-    expect(serverCounts['echo-1'] || 0).toBeLessThan(expectedPerServer * 1.7) // At most 170% of expected
+    expect(serverCounts['echo-1'] || 0).toBeLessThanOrEqual(
+      expectedPerServer * 1.7,
+    ) // At most 170% of expected
     expect(serverCounts['echo-2'] || 0).toBeGreaterThan(expectedPerServer * 0.3)
-    expect(serverCounts['echo-2'] || 0).toBeLessThan(expectedPerServer * 1.7)
+    expect(serverCounts['echo-2'] || 0).toBeLessThanOrEqual(
+      expectedPerServer * 1.7,
+    )
   })
 
   test('should show randomness across multiple test runs', async () => {