portok 1.0.0

package/bench/baseline.bench.mjs

@@ -0,0 +1,73 @@
+/**
+ * Baseline Benchmark
+ * Compares direct server performance vs proxied performance
+ */
+
+import autocannon from 'autocannon';
+import { createMockServer, startDaemon, getFreePort, formatNumber } from './run.mjs';
+
+export async function run({ duration, adminToken }) {
+  const shortDuration = Math.max(2, Math.floor(duration / 2));
+
+  // Setup mock server for direct test
+  const mockServer = await createMockServer();
+
+  // Test 1: Direct to mock server
+  const directResult = await autocannon({
+    url: `http://127.0.0.1:${mockServer.port}/`,
+    connections: 100,
+    pipelining: 10,
+    duration: shortDuration,
+  });
+
+  const directRps = Math.round(directResult.requests.average);
+  const directLatency = directResult.latency.average;
+
+  // Setup proxy
+  const proxyPort = await getFreePort();
+  const daemon = await startDaemon(proxyPort, mockServer.port);
+
+  try {
+    // Test 2: Through proxy
+    const proxiedResult = await autocannon({
+      url: `http://127.0.0.1:${proxyPort}/`,
+      connections: 100,
+      pipelining: 10,
+      duration: shortDuration,
+    });
+
+    const proxiedRps = Math.round(proxiedResult.requests.average);
+    const proxiedLatency = proxiedResult.latency.average;
+
+    // Calculate overhead
+    const rpsOverhead = ((directRps - proxiedRps) / directRps * 100).toFixed(1);
+    const latencyOverhead = ((proxiedLatency - directLatency) / directLatency * 100).toFixed(1);
+
+    return {
+      direct: {
+        rps: directRps,
+        latencyMs: directLatency,
+      },
+      proxied: {
+        rps: proxiedRps,
+        latencyMs: proxiedLatency,
+      },
+      overhead: {
+        rpsPercent: parseFloat(rpsOverhead),
+        latencyPercent: parseFloat(latencyOverhead),
+      },
+      display: {
+        'Direct RPS': formatNumber(directRps),
+        'Proxied RPS': formatNumber(proxiedRps),
+        'RPS Overhead': `${rpsOverhead}%`,
+        'Direct Latency': `${directLatency.toFixed(2)}ms`,
+        'Proxied Latency': `${proxiedLatency.toFixed(2)}ms`,
+        'Latency Overhead': `${latencyOverhead}%`,
+      },
+    };
+  } finally {
+    daemon.kill('SIGTERM');
+    await mockServer.close();
+  }
+}
+

package/bench/connections.bench.mjs

@@ -0,0 +1,70 @@
+/**
+ * Connections Benchmark
+ * Tests scaling with increasing concurrent connections
+ */
+
+import autocannon from 'autocannon';
+import { createMockServer, startDaemon, getFreePort, formatNumber } from './run.mjs';
+
+export async function run({ duration, adminToken }) {
+  // Setup
+  const mockServer = await createMockServer();
+  const proxyPort = await getFreePort();
+  const daemon = await startDaemon(proxyPort, mockServer.port);
+
+  const connectionLevels = [10, 50, 100, 250, 500];
+  const results = {};
+  const shortDuration = Math.max(2, Math.floor(duration / connectionLevels.length));
+
+  try {
+    for (const connections of connectionLevels) {
+      const result = await autocannon({
+        url: `http://127.0.0.1:${proxyPort}/`,
+        connections,
+        pipelining: 1,
+        duration: shortDuration,
+      });
+
+      results[connections] = {
+        rps: Math.round(result.requests.average),
+        latencyAvg: result.latency.average,
+        latencyP99: result.latency.p99,
+        errors: result.errors,
+      };
+    }
+
+    // Get memory usage from metrics
+    let memoryMB = 0;
+    try {
+      const metricsRes = await fetch(`http://127.0.0.1:${proxyPort}/__metrics`, {
+        headers: { 'x-admin-token': adminToken },
+      });
+      if (metricsRes.ok) {
+        const metrics = await metricsRes.json();
+        memoryMB = metrics.memoryMB || process.memoryUsage().heapUsed / 1024 / 1024;
+      }
+    } catch {
+      memoryMB = process.memoryUsage().heapUsed / 1024 / 1024;
+    }
+
+    // Build display object
+    const display = {};
+    for (const [conn, data] of Object.entries(results)) {
+      display[`${conn} conn`] = `${formatNumber(data.rps)} rps, p99=${data.latencyP99}ms`;
+    }
+
+    return {
+      levels: results,
+      memoryMB: memoryMB.toFixed(1),
+      peak: {
+        connections: Object.entries(results).reduce((a, b) => results[a]?.rps > results[b[0]]?.rps ? a : b[0], '10'),
+        rps: Math.max(...Object.values(results).map(r => r.rps)),
+      },
+      display,
+    };
+  } finally {
+    daemon.kill('SIGTERM');
+    await mockServer.close();
+  }
+}
+

package/bench/keepalive.bench.mjs

@@ -0,0 +1,248 @@
+/**
+ * Keep-Alive Benchmark
+ * Validates that proxy overhead is minimal with keep-alive enabled.
+ * 
+ * Expected results:
+ * - Keep-alive should be at least 50% faster than no-keepalive
+ * - Proxied RPS should be at least 20% of direct RPS
+ * 
+ * Can be run standalone or via bench/run.mjs:
+ *   node bench/keepalive.bench.mjs --quick
+ *   npm run bench
+ */
+
+import autocannon from 'autocannon';
+import { spawn } from 'node:child_process';
+import http from 'node:http';
+
+// =============================================================================
+// Utilities (used when running standalone)
+// =============================================================================
+
+function formatNumber(n) {
+  return n.toLocaleString('en-US', { maximumFractionDigits: 2 });
+}
+
+async function getFreePort() {
+  return new Promise((resolve, reject) => {
+    const server = http.createServer();
+    server.listen(0, '127.0.0.1', () => {
+      const port = server.address().port;
+      server.close(() => resolve(port));
+    });
+    server.on('error', reject);
+  });
+}
+
+async function waitFor(condition, timeout = 10000) {
+  const start = Date.now();
+  while (Date.now() - start < timeout) {
+    if (await condition()) return true;
+    await new Promise(r => setTimeout(r, 100));
+  }
+  throw new Error('Timeout waiting for condition');
+}
+
+async function createMockServer(port = 0) {
+  const server = http.createServer((req, res) => {
+    if (req.url === '/health') {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end('{"status":"healthy"}');
+      return;
+    }
+    res.writeHead(200, { 'Content-Type': 'text/plain' });
+    res.end('OK');
+  });
+
+  await new Promise(resolve => server.listen(port, '127.0.0.1', resolve));
+  return {
+    port: server.address().port,
+    close: () => new Promise(resolve => server.close(resolve)),
+  };
+}
+
+async function startDaemonWithKA(listenPort, targetPort, adminToken, keepAlive = true) {
+  const proc = spawn('node', ['portokd.mjs'], {
+    env: {
+      ...process.env,
+      LISTEN_PORT: String(listenPort),
+      INITIAL_TARGET_PORT: String(targetPort),
+      ADMIN_TOKEN: adminToken,
+      STATE_FILE: `/tmp/portok-keepalive-bench-${Date.now()}-${Math.random()}.json`,
+      DRAIN_MS: '1000',
+      ROLLBACK_WINDOW_MS: '60000',
+      ROLLBACK_CHECK_EVERY_MS: '5000',
+      ROLLBACK_FAIL_THRESHOLD: '3',
+      // Keep-alive settings
+      UPSTREAM_KEEPALIVE: keepAlive ? '1' : '0',
+      UPSTREAM_MAX_SOCKETS: '1024',
+      UPSTREAM_KEEPALIVE_MSECS: '2000',
+      // Benchmark mode
+      DISABLE_ADMIN_METRICS_IN_HOT_PATH: '1',
+      VERBOSE_ERRORS: '0',
+    },
+    stdio: 'pipe',
+  });
+
+  await waitFor(async () => {
+    try {
+      const res = await fetch(`http://127.0.0.1:${listenPort}/__status`, {
+        headers: { 'x-admin-token': adminToken },
+      });
+      return res.ok;
+    } catch {
+      return false;
+    }
+  });
+
+  return proc;
+}
+
+// =============================================================================
+// Main run function (called by bench/run.mjs)
+// =============================================================================
+
+export async function run({ duration, adminToken }) {
+  const shortDuration = Math.max(2, Math.floor(duration / 2));
+  const CONNECTIONS = 100;
+  const PIPELINING = 10;
+
+  // Setup mock server
+  const mockServer = await createMockServer();
+
+  // Test 1: Direct to mock server (baseline)
+  const directResult = await autocannon({
+    url: `http://127.0.0.1:${mockServer.port}/`,
+    connections: CONNECTIONS,
+    pipelining: PIPELINING,
+    duration: shortDuration,
+  });
+  const directRps = Math.round(directResult.requests.average);
+  const directLatency = directResult.latency.average;
+
+  // Test 2: Through proxy WITH keep-alive
+  const proxyPortKA = await getFreePort();
+  const daemonKA = await startDaemonWithKA(proxyPortKA, mockServer.port, adminToken, true);
+
+  const proxiedKAResult = await autocannon({
+    url: `http://127.0.0.1:${proxyPortKA}/`,
+    connections: CONNECTIONS,
+    pipelining: PIPELINING,
+    duration: shortDuration,
+  });
+  const proxiedKARps = Math.round(proxiedKAResult.requests.average);
+  const proxiedKALatency = proxiedKAResult.latency.average;
+
+  daemonKA.kill('SIGTERM');
+
+  // Test 3: Through proxy WITHOUT keep-alive
+  const proxyPortNoKA = await getFreePort();
+  const daemonNoKA = await startDaemonWithKA(proxyPortNoKA, mockServer.port, adminToken, false);
+
+  const proxiedNoKAResult = await autocannon({
+    url: `http://127.0.0.1:${proxyPortNoKA}/`,
+    connections: CONNECTIONS,
+    pipelining: PIPELINING,
+    duration: shortDuration,
+  });
+  const proxiedNoKARps = Math.round(proxiedNoKAResult.requests.average);
+  const proxiedNoKALatency = proxiedNoKAResult.latency.average;
+
+  daemonNoKA.kill('SIGTERM');
+  await mockServer.close();
+
+  // Calculate improvement
+  const kaImprovement = ((proxiedKARps - proxiedNoKARps) / proxiedNoKARps * 100);
+  const kaRpsOverhead = ((directRps - proxiedKARps) / directRps * 100);
+
+  return {
+    direct: {
+      rps: directRps,
+      latencyMs: directLatency,
+    },
+    proxiedKeepAlive: {
+      rps: proxiedKARps,
+      latencyMs: proxiedKALatency,
+    },
+    proxiedNoKeepAlive: {
+      rps: proxiedNoKARps,
+      latencyMs: proxiedNoKALatency,
+    },
+    improvement: {
+      keepAliveVsNoKeepAlive: `${kaImprovement.toFixed(1)}%`,
+      rpsOverhead: `${kaRpsOverhead.toFixed(1)}%`,
+    },
+    display: {
+      'Direct RPS': formatNumber(directRps),
+      'Proxied (KA) RPS': formatNumber(proxiedKARps),
+      'Proxied (no KA) RPS': formatNumber(proxiedNoKARps),
+      'KA Improvement': `${kaImprovement.toFixed(1)}%`,
+      'KA Latency': `${proxiedKALatency.toFixed(2)}ms`,
+      'No-KA Latency': `${proxiedNoKALatency.toFixed(2)}ms`,
+    },
+  };
+}
+
+// =============================================================================
+// Standalone execution
+// =============================================================================
+
+const isMain = import.meta.url === `file://${process.argv[1]}`;
+
+if (isMain) {
+  const args = process.argv.slice(2);
+  const isQuick = args.includes('--quick');
+  const isJson = args.includes('--json');
+  const duration = isQuick ? 3 : 10;
+  const adminToken = 'bench-token-keepalive';
+
+  function log(msg) {
+    if (!isJson) console.log(msg);
+  }
+
+  log('');
+  log('╔══════════════════════════════════════════════════════════════╗');
+  log('║              KEEP-ALIVE BENCHMARK VALIDATION                  ║');
+  log('╠══════════════════════════════════════════════════════════════╣');
+  log(`║  Duration: ${duration}s, Connections: 100, Pipelining: 10`.padEnd(63) + '║');
+  log(`║  Node: ${process.version}`.padEnd(63) + '║');
+  log('╚══════════════════════════════════════════════════════════════╝');
+  log('');
+
+  try {
+    const results = await run({ duration, adminToken });
+
+    // Validation
+    const rpsPass = results.proxiedKeepAlive.rps >= results.direct.rps * 0.20;
+    const kaEffective = results.proxiedKeepAlive.rps >= results.proxiedNoKeepAlive.rps * 1.5;
+    const latencyPass = results.proxiedKeepAlive.latencyMs < results.proxiedNoKeepAlive.latencyMs;
+    const allPassed = rpsPass && kaEffective && latencyPass;
+
+    if (isJson) {
+      console.log(JSON.stringify({ ...results, validation: { rpsPass, kaEffective, latencyPass, allPassed } }, null, 2));
+    } else {
+      log('╔══════════════════════════════════════════════════════════════╗');
+      log('║                        RESULTS                               ║');
+      log('╠══════════════════════════════════════════════════════════════╣');
+      for (const [key, value] of Object.entries(results.display)) {
+        log(`║  ${key}:`.padEnd(28) + `${value}`.padStart(33) + '║');
+      }
+      log('╠══════════════════════════════════════════════════════════════╣');
+      log('║  VALIDATION:                                                 ║');
+      log(`║    RPS >= 20% of direct:        ${rpsPass ? 'PASS ✓' : 'FAIL ✗'}                        ║`);
+      log(`║    KA >= 50% faster than no-KA: ${kaEffective ? 'PASS ✓' : 'FAIL ✗'}                        ║`);
+      log(`║    KA latency < no-KA:          ${latencyPass ? 'PASS ✓' : 'FAIL ✗'}                        ║`);
+      log('╚══════════════════════════════════════════════════════════════╝');
+
+      if (!allPassed) {
+        log('\n⚠️  Some validations failed.');
+        process.exit(1);
+      }
+    }
+
+    process.exit(0);
+  } catch (err) {
+    console.error('Benchmark failed:', err);
+    process.exit(1);
+  }
+}

package/bench/latency.bench.mjs

@@ -0,0 +1,47 @@
+/**
+ * Latency Benchmark
+ * Measures latency distribution under moderate load
+ */
+
+import autocannon from 'autocannon';
+import { createMockServer, startDaemon, getFreePort } from './run.mjs';
+
+export async function run({ duration, adminToken }) {
+  // Setup
+  const mockServer = await createMockServer();
+  const proxyPort = await getFreePort();
+  const daemon = await startDaemon(proxyPort, mockServer.port);
+
+  try {
+    // Run benchmark with moderate load to get accurate latency
+    const result = await autocannon({
+      url: `http://127.0.0.1:${proxyPort}/`,
+      connections: 50,
+      pipelining: 1, // No pipelining for accurate latency
+      duration,
+    });
+
+    return {
+      p50Ms: result.latency.p50,
+      p75Ms: result.latency.p75,
+      p90Ms: result.latency.p90,
+      p95Ms: result.latency.p95 || result.latency.p90,
+      p99Ms: result.latency.p99,
+      maxMs: result.latency.max,
+      avgMs: result.latency.average,
+      minMs: result.latency.min,
+      display: {
+        'p50': `${result.latency.p50}ms`,
+        'p75': `${result.latency.p75}ms`,
+        'p90': `${result.latency.p90}ms`,
+        'p99': `${result.latency.p99}ms`,
+        'max': `${result.latency.max}ms`,
+        'avg': `${result.latency.average.toFixed(2)}ms`,
+      },
+    };
+  } finally {
+    daemon.kill('SIGTERM');
+    await mockServer.close();
+  }
+}
+

package/bench/run.mjs

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+
+/**
+ * Benchmark Runner for Portok
+ * Orchestrates all benchmarks and outputs formatted results
+ */
+
+import { spawn } from 'node:child_process';
+import http from 'node:http';
+
+// =============================================================================
+// Configuration
+// =============================================================================
+
+const DURATION = parseInt(process.env.BENCH_DURATION || '10', 10);
+const QUICK_DURATION = 3;
+const ADMIN_TOKEN = process.env.ADMIN_TOKEN || 'bench-token-12345';
+
+const args = process.argv.slice(2);
+const isQuick = args.includes('--quick');
+const isJson = args.includes('--json');
+const duration = isQuick ? QUICK_DURATION : DURATION;
+
+// =============================================================================
+// Utilities
+// =============================================================================
+
+function log(msg) {
+  if (!isJson) {
+    console.log(msg);
+  }
+}
+
+function formatNumber(n) {
+  return n.toLocaleString('en-US', { maximumFractionDigits: 2 });
+}
+
+async function getFreePort() {
+  return new Promise((resolve, reject) => {
+    const server = http.createServer();
+    server.listen(0, '127.0.0.1', () => {
+      const port = server.address().port;
+      server.close(() => resolve(port));
+    });
+    server.on('error', reject);
+  });
+}
+
+async function waitFor(condition, timeout = 10000) {
+  const start = Date.now();
+  while (Date.now() - start < timeout) {
+    if (await condition()) return true;
+    await new Promise(r => setTimeout(r, 100));
+  }
+  throw new Error('Timeout waiting for condition');
+}
+
+// =============================================================================
+// Mock Server
+// =============================================================================
+
+async function createMockServer(port = 0) {
+  const server = http.createServer((req, res) => {
+    if (req.url === '/health') {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end('{"status":"healthy"}');
+      return;
+    }
+    res.writeHead(200, { 'Content-Type': 'text/plain' });
+    res.end('OK');
+  });
+
+  await new Promise(resolve => server.listen(port, '127.0.0.1', resolve));
+  return {
+    port: server.address().port,
+    close: () => new Promise(resolve => server.close(resolve)),
+  };
+}
+
+// =============================================================================
+// Start Daemon
+// =============================================================================
+
+async function startDaemon(listenPort, targetPort) {
+  const proc = spawn('node', ['portokd.mjs'], {
+    env: {
+      ...process.env,
+      LISTEN_PORT: String(listenPort),
+      INITIAL_TARGET_PORT: String(targetPort),
+      ADMIN_TOKEN,
+      STATE_FILE: `/tmp/portok-bench-${Date.now()}.json`,
+      DRAIN_MS: '1000',
+      ROLLBACK_WINDOW_MS: '60000',
+      ROLLBACK_CHECK_EVERY_MS: '5000',
+      ROLLBACK_FAIL_THRESHOLD: '3',
+    },
+    stdio: 'pipe',
+  });
+
+  await waitFor(async () => {
+    try {
+      const res = await fetch(`http://127.0.0.1:${listenPort}/__status`, {
+        headers: { 'x-admin-token': ADMIN_TOKEN },
+      });
+      return res.ok;
+    } catch {
+      return false;
+    }
+  });
+
+  return proc;
+}
+
+// =============================================================================
+// Run Individual Benchmarks
+// =============================================================================
+
+async function runBenchmark(file) {
+  const module = await import(file);
+  return module.run({ duration, adminToken: ADMIN_TOKEN });
+}
+
+// =============================================================================
+// Output Formatting
+// =============================================================================
+
+function printBox(title, content) {
+  const width = 60;
+  const line = '═'.repeat(width);
+
+  log(`╔${line}╗`);
+  log(`║ ${title.padEnd(width - 1)}║`);
+  log(`╠${line}╣`);
+
+  for (const [key, value] of Object.entries(content)) {
+    const row = `  ${key}:`.padEnd(20) + String(value).padStart(width - 21);
+    log(`║${row}║`);
+  }
+
+  log(`╚${line}╝`);
+}
+
+function printHeader() {
+  log('');
+  log('╔══════════════════════════════════════════════════════════════╗');
+  log('║                    PORTOK BENCHMARK RESULTS                   ║');
+  log('╠══════════════════════════════════════════════════════════════╣');
+  log(`║  Duration: ${duration}s ${isQuick ? '(quick mode)' : ''}`.padEnd(63) + '║');
+  log(`║  Node: ${process.version}`.padEnd(63) + '║');
+  log(`║  Platform: ${process.platform} ${process.arch}`.padEnd(63) + '║');
+  log('╚══════════════════════════════════════════════════════════════╝');
+  log('');
+}
+
+// =============================================================================
+// Main
+// =============================================================================
+
+async function main() {
+  const results = {};
+
+  if (!isJson) {
+    printHeader();
+  }
+
+  // Run each benchmark
+  const benchmarks = [
+    { name: 'Throughput', file: './throughput.bench.mjs' },
+    { name: 'Latency', file: './latency.bench.mjs' },
+    { name: 'Connections', file: './connections.bench.mjs' },
+    { name: 'Switching', file: './switching.bench.mjs' },
+    { name: 'Baseline', file: './baseline.bench.mjs' },
+    { name: 'KeepAlive', file: './keepalive.bench.mjs' },
+  ];
+
+  for (const bench of benchmarks) {
+    log(`Running ${bench.name} benchmark...`);
+
+    try {
+      const result = await runBenchmark(bench.file);
+      results[bench.name.toLowerCase()] = result;
+
+      if (!isJson) {
+        printBox(`${bench.name} Test`, result.display || result);
+        log('');
+      }
+    } catch (err) {
+      log(`  Error: ${err.message}`);
+      results[bench.name.toLowerCase()] = { error: err.message };
+    }
+  }
+
+  // Output JSON if requested
+  if (isJson) {
+    console.log(JSON.stringify(results, null, 2));
+  } else {
+    log('╔══════════════════════════════════════════════════════════════╗');
+    log('║                      BENCHMARK COMPLETE                      ║');
+    log('╚══════════════════════════════════════════════════════════════╝');
+  }
+
+  process.exit(0);
+}
+
+main().catch(err => {
+  console.error('Benchmark failed:', err);
+  process.exit(1);
+});
+
+export { createMockServer, startDaemon, getFreePort, waitFor, formatNumber, ADMIN_TOKEN };
+