hugo-balancer 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hugo-huy2004
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,71 @@
-# Temporary Holding Version
+# hugo-balancer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A layer-7 load balancer for HTTP and WebSocket in plain Node, with a self-healing local cluster and a load tester. Zero dependencies.
+
+```
+npm install hugo-balancer
+```
+
+## Three commands
+
+```bash
+# 1. Balance existing servers
+LB_API=127.0.0.1:5011,127.0.0.1:5012,127.0.0.1:5013 npx hugo-balancer start
+
+# 2. Run N copies of your server + the balancer, restart crashed copies, roll restarts on HUP
+npx hugo-balancer cluster server.js
+kill -HUP <pid>          # zero-downtime: one copy at a time, N−1 always serving
+
+# 3. Load-test it
+npx hugo-balancer bench --url http://localhost:8080 --paths /api/a,/api/b --c 32 --d 20 --json out.json
+```
+
+## What it does
+
+| Concern | Behaviour |
+|---|---|
+| Choosing a backend | `p2c-ewma` (default): two random backends, keep the one with lower latency × (in flight + 1); also `least-conn`, `round-robin`, `random` |
+| Stateful tier | Paths in `LB_REALTIME_PATHS` (default `/socket.io`) go to the `realtime` pool in failover mode: always the first healthy copy |
+| Dead backends | Active health checks (`rise`/`fall`) plus passive ejection after 3 consecutive errors, doubling up to 60 s |
+| Retries | On another backend: always when the connection was refused (never reached the server, so POST is safe); for GET/HEAD/OPTIONS also on a broken connection or 502/503 |
+| Slow backends | No response headers within `LB_HEADER_TIMEOUT_MS` → 504; latency feeds the p2c score so slow copies are avoided early |
+| Bodies | Up to 1 MB buffered for retries; larger uploads stream straight through (one attempt) |
+| WebSocket | Upgrade forwarded, TCP piped both ways |
+| Tracing | `X-Forwarded-For/Proto/Host`, `X-Request-Id`, `X-LB-Retried` |
+| Stats | `GET /__lb/stats` from loopback only: per-backend up, ejected, in flight, EWMA, totals |
+
+## Configuration
+
+| Variable | Default | |
+|---|---|---|
+| `LB_PORT` | `8080` | listen port |
+| `LB_API` | — | api backends `host:port,…` (required for `start`) |
+| `LB_REALTIME` | — | realtime backends; empty = no realtime pool |
+| `LB_REALTIME_PATHS` | `/socket.io` | path prefixes routed to the realtime pool |
+| `LB_ALGO` | `p2c-ewma` | `p2c-ewma` · `least-conn` · `round-robin` · `random` |
+| `LB_HEALTH_PATH` | `/healthz` | must answer 200 when the copy can serve |
+| `LB_HC_INTERVAL_MS` / `LB_HC_TIMEOUT_MS` | `1000` / `800` | health check cadence |
+| `LB_HEADER_TIMEOUT_MS` | `30000` | wait for response headers |
+| `LB_MAX_RETRIES` | `2` | extra attempts per request |
+| `LB_CLIENT_IP_HEADER` | — | trust this header for the client IP (only when every connection comes through that proxy) |
+
+`cluster` also reads `LB_API_COUNT` (3), `LB_API_BASE_PORT` (5011), `LB_RT_PORT` (5021) and `LB_RT_COUNT` (1, or 0 for none). Each copy starts with `ROLE` (`api` | `realtime`), `PORT` and `INSTANCE_ID` in its environment.
+
+**Your server, for zero-downtime restarts:** on SIGTERM, answer the health path with 503, wait a couple of health-check intervals, then close. Set `server.keepAliveTimeout` above 30 s so idle pooled connections are closed by the balancer first.
+
+## From code
+
+```js
+const { createLoadBalancer, readConfig } = require('hugo-balancer');
+
+const lb = createLoadBalancer({ ...readConfig(), api: ['127.0.0.1:5011', '127.0.0.1:5012'], realtimePaths: ['/socket.io', '/rooms'] });
+await lb.listen(8080);
+lb.stats();     // same as /__lb/stats
+await lb.close();
+```
+
+The selection algorithms are exported too (`createPool`, `pick`, `recordLatency`, `recordFailure`, `recordHealth`) for simulations.
+
+## License
+
+MIT

package/bin/hugo-balancer.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+// hugo-balancer start                  load balancer configured by LB_* variables (LB_API required)
+// hugo-balancer cluster <server.js>    N copies of your server + the load balancer, self-healing, HUP = rolling restart
+// hugo-balancer bench --url <url> …    load test: throughput, latency percentiles, which copy answered
+const path = require('path');
+const { createLoadBalancer, readConfig, runCluster, bench } = require('..');
+const { parseArgs } = require('../src/bench');
+
+const [cmd = 'start', ...rest] = process.argv.slice(2);
+const fail = (msg) => { console.error(`hugo-balancer: ${msg}`); process.exit(1); };
+
+if (cmd === 'start') {
+  const cfg = readConfig();
+  if (!cfg.api.length) fail('set LB_API to the api backends, e.g. LB_API=127.0.0.1:5011,127.0.0.1:5012');
+  const lb = createLoadBalancer(cfg);
+  lb.listen().then((port) => console.log(`[lb] :${port} algo=${cfg.algo} api=[${cfg.api}] realtime=[${cfg.realtime}]`));
+  const stop = () => lb.close().then(() => process.exit(0));
+  process.on('SIGTERM', stop);
+  process.on('SIGINT', stop);
+} else if (cmd === 'cluster') {
+  if (!rest[0]) fail('usage: hugo-balancer cluster <server.js>');
+  runCluster(path.resolve(rest[0]));
+} else if (cmd === 'bench') {
+  const args = parseArgs(rest);
+  bench(args).then((r) => {
+    const { timeline, ...summary } = r;
+    console.log(JSON.stringify(summary, null, 2));
+    const bad = timeline.map((t, s) => (t.err ? `${s}s:${t.err}` : null)).filter(Boolean);
+    console.log(`seconds with errors: ${bad.length ? bad.join(' ') : 'none'}`);
+    if (args.json) require('fs').writeFileSync(args.json, JSON.stringify({ args, ...r }, null, 2));
+  });
+} else {
+  fail(`unknown command "${cmd}" — use start, cluster or bench`);
+}

package/index.js

@@ -0,0 +1,6 @@
+const { createLoadBalancer, readConfig } = require('./src/proxy');
+const { runCluster } = require('./src/cluster');
+const { bench } = require('./src/bench');
+const balancer = require('./src/balancer');
+
+module.exports = { createLoadBalancer, readConfig, runCluster, bench, ...balancer };

package/package.json

@@ -1,6 +1,18 @@
 {
   "name": "hugo-balancer",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Layer-7 load balancer for HTTP and WebSocket in plain Node: p2c-EWMA, least-conn and round-robin, health checks, outlier ejection, safe retries, a self-healing local cluster with rolling restarts, and a load tester. Zero dependencies",
+  "keywords": ["load-balancer", "reverse-proxy", "proxy", "websocket", "p2c", "ewma", "least-connections", "health-check", "circuit-breaker", "cluster", "rolling-restart", "benchmark"],
+  "homepage": "https://github.com/Hugo-huy2004/FINAL_PROJECT_HUGOMUSIC/tree/main/packages/balancer#readme",
+  "repository": { "type": "git", "url": "git+https://github.com/Hugo-huy2004/FINAL_PROJECT_HUGOMUSIC.git", "directory": "packages/balancer" },
+  "author": "Hugo-huy2004",
+  "license": "MIT",
+  "main": "index.js",
+  "bin": { "hugo-balancer": "bin/hugo-balancer.js" },
+  "files": ["index.js", "src", "bin", "README.md", "LICENSE"],
+  "engines": { "node": ">=18" },
+  "scripts": {
+    "test": "node checks/lb.check.js",
+    "prepublishOnly": "npm test"
+  }
+}

package/src/balancer.js

@@ -0,0 +1,114 @@
+// Backend selection — pure computation, no I/O, so every rule is unit-tested (checks/lb.check.js).
+//
+// Algorithms (pick one per pool to compare them under load):
+//   random       baseline.
+//   round-robin  one backend after another; counts requests, blind to how heavy each one is.
+//   least-conn   the backend with the fewest requests in flight; good when durations differ wildly
+//                (an audio stream held for minutes next to a JSON call of a few ms).
+//   p2c-ewma     power of two choices + peak-EWMA latency: draw two backends at random, keep the one with the
+//                lower latency × (in-flight + 1). Two comparisons are enough to get close to optimal, and a
+//                backend that starts slowing down is avoided before it fails.
+//
+// Each pool has a mode: 'balance' (share the load) or 'failover' (always the first healthy backend in order —
+// for a stateful tier whose state lives in one process).
+//
+// Two ways a bad backend is detected:
+//   active   a health check polls the health path; `rise` passes bring it up, `fall` failures take it down.
+//   passive  outlier ejection: `ejectAfter` consecutive errors eject it for ejectBaseMs, doubling on every
+//            repeat up to ejectMaxMs.
+
+const EWMA_ALPHA = 0.3;
+
+function createBackend(addr) {
+  const [host, port] = addr.split(':');
+  return {
+    addr, host, port: Number(port),
+    up: true,            // set by the active health check; starts up so there is no 503 at boot
+    hcOk: 0, hcFail: 0,  // consecutive health-check passes / failures
+    inflight: 0,         // requests / connections in progress
+    ewmaMs: 0,           // time to response headers (TTFB), peak EWMA
+    errors: 0,           // consecutive connection errors (passive)
+    ejections: 0, ejectedUntil: 0,
+    requests: 0, failures: 0, // totals, for the stats endpoint
+  };
+}
+
+function createPool(name, addrs, { mode = 'balance', algo = 'p2c-ewma', rise = 2, fall = 2, ejectAfter = 3, ejectBaseMs = 5000, ejectMaxMs = 60000, rand = Math.random } = {}) {
+  return { name, mode, algo, rise, fall, ejectAfter, ejectBaseMs, ejectMaxMs, rand, rr: 0, backends: addrs.map(createBackend) };
+}
+
+const available = (pool, now) => pool.backends.filter((b) => b.up && b.ejectedUntil <= now);
+
+// p2c-ewma score. An unmeasured backend (ewmaMs = 0) counts as fastest, so it gets tried.
+const cost = (b) => (b.ewmaMs || 1) * (b.inflight + 1);
+
+/** Pick a backend, skipping those in `exclude` (already tried for this request). null when none is available. */
+function pick(pool, { exclude = new Set(), now = Date.now() } = {}) {
+  const list = available(pool, now).filter((b) => !exclude.has(b));
+  if (!list.length) return null;
+  if (pool.mode === 'failover') return list[0];
+  switch (pool.algo) {
+    case 'random':
+      return list[Math.floor(pool.rand() * list.length)];
+    case 'round-robin':
+      return list[pool.rr++ % list.length];
+    case 'least-conn': {
+      const min = Math.min(...list.map((b) => b.inflight));
+      const ties = list.filter((b) => b.inflight === min);
+      return ties[Math.floor(pool.rand() * ties.length)];
+    }
+    case 'p2c-ewma': {
+      if (list.length === 1) return list[0];
+      const i = Math.floor(pool.rand() * list.length);
+      let j = Math.floor(pool.rand() * (list.length - 1));
+      if (j >= i) j += 1; // two DIFFERENT backends
+      return cost(list[i]) <= cost(list[j]) ? list[i] : list[j];
+    }
+    default:
+      throw new Error(`Unknown algorithm: ${pool.algo}`);
+  }
+}
+
+// Peak EWMA: a higher sample is taken at once (react fast when a backend slows down); a lower one decays slowly.
+function recordLatency(b, ms) {
+  b.ewmaMs = b.ewmaMs === 0 || ms > b.ewmaMs ? ms : b.ewmaMs * (1 - EWMA_ALPHA) + ms * EWMA_ALPHA;
+}
+
+function recordSuccess(b) {
+  b.errors = 0;
+}
+
+/** A connection error or 502/503. Returns true when this failure ejected the backend. */
+function recordFailure(pool, b, now = Date.now()) {
+  b.failures += 1;
+  b.errors += 1;
+  if (b.errors < pool.ejectAfter) return false;
+  b.errors = 0;
+  b.ejectedUntil = now + Math.min(pool.ejectMaxMs, pool.ejectBaseMs * 2 ** b.ejections);
+  b.ejections += 1;
+  return true;
+}
+
+/** Result of one active health check. Returns 'up' | 'down' when the state changes, null otherwise. */
+function recordHealth(pool, b, ok) {
+  if (ok) {
+    b.hcFail = 0;
+    b.hcOk += 1;
+    if (!b.up && b.hcOk >= pool.rise) {
+      b.up = true;
+      b.ejections = 0; // truly recovered → forget past ejections
+      b.ejectedUntil = 0;
+      return 'up';
+    }
+  } else {
+    b.hcOk = 0;
+    b.hcFail += 1;
+    if (b.up && b.hcFail >= pool.fall) {
+      b.up = false;
+      return 'down';
+    }
+  }
+  return null;
+}
+
+module.exports = { createPool, pick, recordLatency, recordSuccess, recordFailure, recordHealth, available };

package/src/bench.js

@@ -0,0 +1,61 @@
+// Load generator for load-balancing experiments (no external tool needed):
+//   hugo-balancer bench --url http://localhost:8080 --paths /api/a,/api/b --c 32 --d 20 [--json out.json]
+// C keep-alive connections run in parallel for D seconds, each cycling through the paths. Reports throughput,
+// p50/p95/p99/max latency, status codes, network errors, and which copy answered (X-Instance header).
+const http = require('http');
+
+function parseArgs(argv) {
+  const a = { url: 'http://localhost:8080', paths: '/', c: 32, d: 20, json: '' };
+  for (let i = 0; i < argv.length; i += 2) a[argv[i].replace(/^--/, '')] = argv[i + 1];
+  return { ...a, c: Number(a.c), d: Number(a.d), paths: a.paths.split(',') };
+}
+
+const pct = (sorted, p) => sorted.length ? sorted[Math.min(sorted.length - 1, Math.floor(p * sorted.length))] : 0;
+
+async function bench({ url, paths, c, d }, { onTick } = {}) {
+  const { hostname, port } = new URL(url);
+  const agent = new http.Agent({ keepAlive: true, maxSockets: c });
+  const lat = [];
+  const status = {};
+  const instances = {};
+  const timeline = []; // errors per second — shows whether killing a copy mid-run caused any
+  let errors = 0;
+  let i = 0;
+  const start = Date.now();
+  const end = start + d * 1000;
+
+  const one = () => new Promise((resolve) => {
+    const path = paths[i++ % paths.length];
+    const t0 = process.hrtime.bigint();
+    const sec = Math.floor((Date.now() - start) / 1000);
+    timeline[sec] ??= { ok: 0, err: 0 };
+    const req = http.get({ hostname, port, path, agent }, (res) => {
+      res.resume();
+      res.on('end', () => {
+        lat.push(Number(process.hrtime.bigint() - t0) / 1e6);
+        status[res.statusCode] = (status[res.statusCode] || 0) + 1;
+        const inst = res.headers['x-instance'] || '-';
+        instances[inst] = (instances[inst] || 0) + 1;
+        timeline[sec][res.statusCode < 500 ? 'ok' : 'err'] += 1;
+        resolve();
+      });
+    });
+    req.on('error', () => { errors += 1; timeline[sec].err += 1; resolve(); });
+  });
+
+  const tick = onTick && setInterval(() => onTick(Date.now() - start), 1000);
+  await Promise.all(Array.from({ length: c }, async () => { while (Date.now() < end) await one(); }));
+  clearInterval(tick);
+  agent.destroy();
+
+  lat.sort((x, y) => x - y);
+  const total = lat.length + errors;
+  const r1 = (x) => Math.round(x * 10) / 10;
+  return {
+    requests: total, rps: Math.round(total / d), errors, status, instances,
+    latencyMs: { p50: r1(pct(lat, 0.5)), p95: r1(pct(lat, 0.95)), p99: r1(pct(lat, 0.99)), max: r1(lat.at(-1) || 0) },
+    timeline: timeline.map((t) => t || { ok: 0, err: 0 }),
+  };
+}
+
+module.exports = { bench, parseArgs };

package/src/cluster.js

@@ -0,0 +1,115 @@
+// Run a whole cluster on one machine with one command: N copies of your server + an optional realtime copy +
+// the load balancer in front.
+//
+// Each copy gets ROLE ('api' | 'realtime'), PORT and INSTANCE_ID in its environment and must answer the health
+// path with 200 when ready.
+//   - Self-healing: a copy that dies is restarted after 1 s → 2 s → … → 30 s, so a crash loop cannot spin;
+//     a copy that stayed up 60 s starts again from 1 s.
+//   - Zero-downtime deploy: `kill -HUP <pid>` restarts the api copies one by one — SIGTERM (the copy drains
+//     itself), wait for it to exit, start the new one, wait for its health check — so N−1 copies always serve.
+const { spawn } = require('child_process');
+const http = require('http');
+const { createLoadBalancer, readConfig } = require('./proxy');
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const log = (...a) => console.log('[cluster]', ...a);
+
+function healthy(port, healthPath) {
+  return new Promise((resolve) => {
+    const req = http.get({ host: '127.0.0.1', port, path: healthPath, timeout: 1000, agent: false }, (r) => { r.resume(); resolve(r.statusCode === 200); });
+    req.on('timeout', () => req.destroy());
+    req.on('error', () => resolve(false));
+  });
+}
+
+async function waitHealthy(port, healthPath, timeoutMs = 30000) {
+  const end = Date.now() + timeoutMs;
+  while (Date.now() < end) {
+    if (await healthy(port, healthPath)) return true;
+    await sleep(300);
+  }
+  return false;
+}
+
+function createWorker(script, role, port) {
+  const w = { role, port, id: `${role}-${port}`, proc: null, restarts: 0, startedAt: 0, stopping: false };
+  w.start = () => {
+    w.startedAt = Date.now();
+    w.proc = spawn(process.execPath, [script], {
+      env: { ...process.env, ROLE: role, PORT: String(port), INSTANCE_ID: w.id },
+      stdio: ['ignore', 'inherit', 'inherit'],
+    });
+    w.proc.on('exit', async (code, signal) => {
+      if (w.stopping) return;
+      if (Date.now() - w.startedAt > 60000) w.restarts = 0;
+      const delay = Math.min(30000, 1000 * 2 ** w.restarts);
+      w.restarts += 1;
+      log(`${w.id} exited (code=${code} signal=${signal}) → restart in ${delay} ms`);
+      await sleep(delay);
+      if (!w.stopping) w.start();
+    });
+  };
+  // Graceful stop: SIGTERM, then wait until the process has fully exited.
+  w.stop = () => new Promise((resolve) => {
+    if (!w.proc || w.proc.exitCode !== null) return resolve();
+    w.stopping = true;
+    w.proc.once('exit', () => resolve());
+    w.proc.kill('SIGTERM');
+  });
+  return w;
+}
+
+/**
+ * @param {string} script path of the server entry file
+ * @param {object} [opts] apiCount (3), apiBasePort (5011), realtime (true), realtimePort (5021), plus any
+ *   createLoadBalancer option (port, realtimePaths, algo…). Defaults come from LB_* environment variables.
+ */
+async function runCluster(script, opts = {}) {
+  const env = process.env;
+  const o = {
+    ...readConfig(),
+    apiCount: Number(env.LB_API_COUNT || 3),
+    apiBasePort: Number(env.LB_API_BASE_PORT || 5011),
+    realtime: env.LB_RT_COUNT !== '0',
+    realtimePort: Number(env.LB_RT_PORT || 5021),
+    ...opts,
+  };
+  const api = Array.from({ length: o.apiCount }, (_, i) => createWorker(script, 'api', o.apiBasePort + i));
+  const rt = o.realtime ? [createWorker(script, 'realtime', o.realtimePort)] : [];
+  const workers = [...api, ...rt];
+  workers.forEach((w) => w.start());
+
+  const lb = createLoadBalancer({ ...o, api: api.map((w) => `127.0.0.1:${w.port}`), realtime: rt.map((w) => `127.0.0.1:${w.port}`) });
+  const port = await lb.listen();
+  log(`LB :${port} algo=${o.algo} — ${api.length} api + ${rt.length} realtime`);
+
+  let rolling = false;
+  process.on('SIGHUP', async () => {
+    if (rolling) return;
+    rolling = true;
+    log('rolling restart started');
+    for (const w of api) {
+      await w.stop();
+      w.stopping = false;
+      w.restarts = 0;
+      w.start();
+      const ok = await waitHealthy(w.port, o.healthPath);
+      log(`${w.id} ${ok ? 'healthy' : 'NOT healthy after 30 s — rolling restart stopped'}`);
+      if (!ok) break;
+    }
+    rolling = false;
+    log('rolling restart done');
+  });
+
+  const shutdown = async () => {
+    log('shutting down');
+    await Promise.all(workers.map((w) => w.stop()));
+    await lb.close();
+    process.exit(0);
+  };
+  process.on('SIGTERM', shutdown);
+  process.on('SIGINT', shutdown);
+  return lb;
+}
+
+module.exports = { runCluster };

package/src/proxy.js

@@ -0,0 +1,260 @@
+// Layer-7 load balancer for HTTP and WebSocket — plain Node, no dependencies. Backend choice: ./balancer.js.
+//
+// Two pools:
+//   api       stateless REST, balanced across every copy.
+//   realtime  optional; requests under `realtimePaths` (default /socket.io) go to the first healthy copy only
+//             (failover), for state that lives in one process — rooms, live sessions.
+//
+// Connection handling:
+//   - Keep-alive pool per backend (http.Agent): no TCP handshake per request.
+//   - Retry on ANOTHER backend when a request fails before any response: always when the connection was refused
+//     (the request never reached the backend, so even POST is safe); for GET/HEAD/OPTIONS also when the
+//     connection broke or the backend answered 502/503 (e.g. it is draining).
+//   - Timeout waiting for response headers → 504, so a client never hangs forever.
+//   - X-Forwarded-For/Proto/Host and X-Request-Id tell the backend the real client and trace a request across layers.
+//   - WebSocket: after the backend accepts the Upgrade, the raw TCP stream is piped both ways.
+const http = require('http');
+const net = require('net');
+const crypto = require('crypto');
+const { createPool, pick, recordLatency, recordSuccess, recordFailure, recordHealth } = require('./balancer');
+
+const IDEMPOTENT = new Set(['GET', 'HEAD', 'OPTIONS']);
+const MAX_BUFFERED_BODY = 1024 * 1024; // larger bodies (uploads) are streamed straight through: one attempt, no retry
+const HOP_BY_HOP = ['connection', 'keep-alive', 'proxy-connection', 'transfer-encoding', 'te', 'trailer', 'upgrade'];
+const LOOPBACK = ['127.0.0.1', '::1', '::ffff:127.0.0.1'];
+
+/** Configuration from environment variables (LB_*); every field can also be passed to createLoadBalancer directly. */
+function readConfig(env = process.env) {
+  const list = (v) => (v || '').split(',').map((s) => s.trim()).filter(Boolean);
+  return {
+    port: Number(env.LB_PORT || 8080),
+    api: list(env.LB_API),
+    realtime: list(env.LB_REALTIME),
+    realtimePaths: list(env.LB_REALTIME_PATHS || '/socket.io'),
+    algo: env.LB_ALGO || 'p2c-ewma',
+    healthPath: env.LB_HEALTH_PATH || '/healthz',
+    hcIntervalMs: Number(env.LB_HC_INTERVAL_MS || 1000),
+    hcTimeoutMs: Number(env.LB_HC_TIMEOUT_MS || 800),
+    headerTimeoutMs: Number(env.LB_HEADER_TIMEOUT_MS || 30000),
+    maxRetries: Number(env.LB_MAX_RETRIES || 2),
+    // Behind a tunnel or another proxy that sets the real client IP in a header. Enable only when EVERY
+    // connection arrives through it, or clients could spoof their IP.
+    clientIpHeader: (env.LB_CLIENT_IP_HEADER || '').toLowerCase(),
+  };
+}
+
+function createLoadBalancer(options, { log = console.log } = {}) {
+  const cfg = { ...readConfig({}), ...options };
+  const pools = { api: createPool('api', cfg.api, { algo: cfg.algo }) };
+  if (cfg.realtime.length) pools.realtime = createPool('realtime', cfg.realtime, { mode: 'failover' });
+
+  const agents = new Map(); // backend → its own keep-alive http.Agent
+  const agentOf = (b) => {
+    if (!agents.has(b)) agents.set(b, new http.Agent({ keepAlive: true, maxSockets: 512, timeout: 30000 }));
+    return agents.get(b);
+  };
+  const isRealtime = (url) => cfg.realtimePaths.some((p) => url === p || url.startsWith(`${p}/`) || url.startsWith(`${p}?`));
+  const poolFor = (url) => (pools.realtime && isRealtime(url) ? pools.realtime : pools.api);
+  const clientIp = (req) => (cfg.clientIpHeader && req.headers[cfg.clientIpHeader]) || req.socket.remoteAddress;
+
+  function forwardHeaders(req) {
+    const h = { ...req.headers };
+    for (const k of HOP_BY_HOP) delete h[k];
+    const prior = req.headers['x-forwarded-for'];
+    const ip = clientIp(req);
+    h['x-forwarded-for'] = cfg.clientIpHeader ? ip : prior ? `${prior}, ${ip}` : ip;
+    h['x-forwarded-proto'] = req.headers['x-forwarded-proto'] || (req.socket.encrypted ? 'https' : 'http');
+    h['x-forwarded-host'] = req.headers['x-forwarded-host'] || req.headers.host || '';
+    h['x-request-id'] = req.headers['x-request-id'] || crypto.randomUUID();
+    return h;
+  }
+
+  // ---------- HTTP ----------
+  async function handle(req, res) {
+    if (req.url === '/__lb/stats' && LOOPBACK.includes(req.socket.remoteAddress)) {
+      res.setHeader('Content-Type', 'application/json');
+      return res.end(JSON.stringify(stats(), null, 2));
+    }
+    const pool = poolFor(req.url);
+    const headers = forwardHeaders(req);
+
+    // A small body is buffered so it can be resent on retry; a big one is streamed (single attempt).
+    let body = null;
+    const len = Number(req.headers['content-length'] || 0);
+    const hasBody = len > 0 || req.headers['transfer-encoding'];
+    if (hasBody && len > 0 && len <= MAX_BUFFERED_BODY) {
+      const chunks = [];
+      for await (const c of req) chunks.push(c);
+      body = Buffer.concat(chunks);
+    }
+    const streamBody = hasBody && !body;
+
+    const tried = new Set();
+    for (let attempt = 0; ; attempt += 1) {
+      const b = pick(pool, { exclude: tried });
+      if (!b) {
+        if (!res.headersSent) res.writeHead(503, { 'Content-Type': 'application/json', 'Retry-After': '1' });
+        return res.end(JSON.stringify({ message: 'Server busy, please try again shortly' }));
+      }
+      tried.add(b);
+      const outcome = await tryBackend(pool, b, req, res, headers, body, streamBody);
+      if (outcome === 'done') return;
+      const retryable = outcome === 'refused' || (IDEMPOTENT.has(req.method) && !streamBody);
+      if (!retryable || attempt >= cfg.maxRetries) {
+        if (!res.headersSent) res.writeHead(outcome === 'timeout' ? 504 : 502, { 'Content-Type': 'application/json' });
+        return res.end(JSON.stringify({ message: 'Could not connect to server' }));
+      }
+      res.setHeader('X-LB-Retried', String(attempt + 1));
+    }
+  }
+
+  // One attempt → 'done' (response sent to the client) | 'refused' (never reached the backend) |
+  // 'failed' (broke or 502/503 before a response) | 'timeout'.
+  function tryBackend(pool, b, req, res, headers, body, streamBody) {
+    return new Promise((resolve) => {
+      const started = process.hrtime.bigint();
+      b.inflight += 1;
+      b.requests += 1;
+      let settled = false;
+      const finish = (v) => { if (!settled) { settled = true; resolve(v); } };
+      let released = false;
+      const release = () => { if (!released) { released = true; b.inflight -= 1; } };
+
+      const up = http.request({
+        host: b.host, port: b.port, method: req.method, path: req.url, headers, agent: agentOf(b),
+      });
+      const timer = setTimeout(() => { up.destroy(new Error('header timeout')); }, cfg.headerTimeoutMs);
+
+      up.on('response', (ur) => {
+        clearTimeout(timer);
+        recordLatency(b, Number(process.hrtime.bigint() - started) / 1e6);
+        // Backend down or draining (502/503): for a repeatable request, try another backend instead.
+        if ((ur.statusCode === 502 || ur.statusCode === 503) && IDEMPOTENT.has(req.method) && !streamBody) {
+          ur.resume();
+          release();
+          recordFailure(pool, b);
+          return finish('failed');
+        }
+        recordSuccess(b);
+        const out = { ...ur.headers };
+        for (const k of HOP_BY_HOP) delete out[k];
+        res.writeHead(ur.statusCode, out);
+        ur.pipe(res);
+        // A media stream stays open for minutes: it counts as in flight until the response really ends —
+        // exactly what least-conn and p2c need to know.
+        res.on('close', () => { release(); if (!ur.complete) ur.destroy(); });
+        finish('done');
+      });
+
+      up.on('error', (err) => {
+        clearTimeout(timer);
+        release();
+        if (settled) return; // failed after the response started: the client sees a broken connection
+        recordFailure(pool, b);
+        const code = err.code;
+        if (err.message === 'header timeout') return finish('timeout');
+        finish(code === 'ECONNREFUSED' || code === 'EHOSTUNREACH' || code === 'ENOTFOUND' ? 'refused' : 'failed');
+      });
+
+      // Client left midway (seek, skip): cancel the backend request too.
+      res.on('close', () => { if (!res.writableFinished) up.destroy(); });
+
+      if (streamBody) req.pipe(up);
+      else up.end(body || undefined);
+    });
+  }
+
+  // ---------- WebSocket (Upgrade) ----------
+  // Upgraded sockets leave the HTTP server (closeAllConnections cannot see them), so they are tracked to close them.
+  const tunnels = new Set();
+  function upgrade(req, socket, head) {
+    const pool = poolFor(req.url);
+    const b = pick(pool);
+    if (!b) return socket.end('HTTP/1.1 503 Service Unavailable\r\n\r\n');
+    const headers = forwardHeaders(req);
+    headers.connection = 'Upgrade';
+    headers.upgrade = req.headers.upgrade;
+    let connected = false;
+    const upstream = net.connect(b.port, b.host, () => {
+      connected = true;
+      b.inflight += 1;
+      b.requests += 1;
+      recordSuccess(b);
+      const lines = [`${req.method} ${req.url} HTTP/1.1`, ...Object.entries(headers).map(([k, v]) => `${k}: ${v}`), '', ''];
+      upstream.write(lines.join('\r\n'));
+      if (head?.length) upstream.write(head);
+      upstream.pipe(socket).pipe(upstream);
+    });
+    let closed = false;
+    const tunnel = [socket, upstream];
+    tunnels.add(tunnel);
+    const close = () => {
+      if (closed) return;
+      closed = true;
+      tunnels.delete(tunnel);
+      if (connected) b.inflight -= 1;
+      socket.destroy();
+      upstream.destroy();
+    };
+    upstream.on('error', (e) => { if (e.code === 'ECONNREFUSED') recordFailure(pool, b); close(); });
+    socket.on('error', close);
+    upstream.on('close', close);
+    socket.on('close', close);
+  }
+
+  // ---------- Active health checks ----------
+  function checkOnce(pool, b) {
+    const req = http.get({ host: b.host, port: b.port, path: cfg.healthPath, timeout: cfg.hcTimeoutMs, agent: false }, (r) => {
+      r.resume();
+      report(pool, b, r.statusCode === 200);
+    });
+    req.on('timeout', () => req.destroy(new Error('timeout')));
+    req.on('error', () => report(pool, b, false));
+  }
+  function report(pool, b, ok) {
+    const change = recordHealth(pool, b, ok);
+    if (change) log(`[lb] ${pool.name} ${b.addr} ${change.toUpperCase()}`);
+  }
+  let hcTimer = null;
+  const startHealthChecks = () => {
+    const tick = () => { for (const pool of Object.values(pools)) for (const b of pool.backends) checkOnce(pool, b); };
+    tick();
+    hcTimer = setInterval(tick, cfg.hcIntervalMs);
+  };
+
+  function stats() {
+    const now = Date.now();
+    return Object.fromEntries(Object.values(pools).map((p) => [p.name, {
+      mode: p.mode, algo: p.mode === 'failover' ? 'failover' : p.algo,
+      backends: p.backends.map((b) => ({
+        addr: b.addr, up: b.up, ejected: b.ejectedUntil > now, inflight: b.inflight,
+        ewmaMs: Math.round(b.ewmaMs * 10) / 10, requests: b.requests, failures: b.failures,
+      })),
+    }]));
+  }
+
+  const server = http.createServer((req, res) => {
+    handle(req, res).catch((e) => {
+      log(`[lb] ${e.message}`);
+      if (!res.headersSent) res.writeHead(500);
+      res.end();
+    });
+  });
+  server.on('upgrade', upgrade);
+  server.keepAliveTimeout = 65_000;
+  server.headersTimeout = 66_000;
+
+  return {
+    server, pools, stats,
+    listen: (port = cfg.port) => new Promise((r) => server.listen(port, () => { startHealthChecks(); r(server.address().port); })),
+    close: () => new Promise((r) => {
+      clearInterval(hcTimer);
+      for (const a of agents.values()) a.destroy();
+      for (const t of tunnels) for (const s of t) s.destroy();
+      server.closeAllConnections();
+      server.close(r);
+    }),
+  };
+}
+
+module.exports = { createLoadBalancer, readConfig };