ferrings 0.1.0

package/benchmark/compare.js

@@ -0,0 +1,178 @@
+'use strict';
+
+const fs = require('node:fs');
+const http = require('node:http');
+const path = require('node:path');
+const { performance } = require('node:perf_hooks');
+const { UringHttpServer } = require('../');
+
+const BODY = 'ok\n';
+const DURATION_MS = Number(process.env.DURATION_MS || 5000);
+const CONCURRENCY = Number(process.env.CONCURRENCY || 128);
+const QUEUE_DEPTH = Number(process.env.QUEUE_DEPTH || 256);
+const REPORT_PATH = process.env.REPORT_PATH;
+
+function requestOnce(port) {
+  const startedAt = performance.now();
+  return new Promise((resolve, reject) => {
+    const req = http.get({ host: '127.0.0.1', port, path: '/', agent: false }, (res) => {
+      res.resume();
+      res.on('end', () => resolve(performance.now() - startedAt));
+    });
+    req.on('error', reject);
+  });
+}
+
+async function runLoad(port) {
+  let completed = 0;
+  let stopped = false;
+  const latencies = [];
+  const endAt = performance.now() + DURATION_MS;
+
+  async function worker() {
+    while (!stopped) {
+      latencies.push(await requestOnce(port));
+      completed += 1;
+      if (performance.now() >= endAt) stopped = true;
+    }
+  }
+
+  await Promise.all(Array.from({ length: CONCURRENCY }, worker));
+  latencies.sort((a, b) => a - b);
+
+  return {
+    requests: completed,
+    rps: Math.round((completed * 1000) / DURATION_MS),
+    p50Ms: percentile(latencies, 0.5),
+    p95Ms: percentile(latencies, 0.95),
+    p99Ms: percentile(latencies, 0.99)
+  };
+}
+
+function percentile(values, quantile) {
+  if (values.length === 0) return 0;
+  const index = Math.min(values.length - 1, Math.floor(values.length * quantile));
+  return Number(values[index].toFixed(3));
+}
+
+async function withNodeServer() {
+  const server = http.createServer((_, res) => {
+    res.setHeader('connection', 'close');
+    res.end(BODY);
+  });
+
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+  const port = server.address().port;
+  try {
+    return await runLoad(port);
+  } finally {
+    await new Promise((resolve) => server.close(resolve));
+  }
+}
+
+async function withUringServer() {
+  const server = new UringHttpServer({
+    host: '127.0.0.1',
+    port: 0,
+    queueDepth: QUEUE_DEPTH,
+    responseBody: BODY,
+    bufferCount: 4096,
+    bufferSize: 2048
+  });
+
+  const info = server.start();
+  try {
+    return {
+      ...(await runLoad(info.port)),
+      serverInfo: summarizeServerInfo(server.info())
+    };
+  } finally {
+    server.stop();
+  }
+}
+
+function summarizeServerInfo(info) {
+  if (!info) return null;
+  return {
+    backend: info.backend,
+    backlog: info.backlog,
+    queueDepth: info.queueDepth,
+    bufferCount: info.bufferCount,
+    bufferSize: info.bufferSize,
+    tcpNoDelay: info.tcpNoDelay,
+    reusePort: info.reusePort,
+    tcpDeferAcceptSeconds: info.tcpDeferAcceptSeconds,
+    socketRecvBufferSize: info.socketRecvBufferSize,
+    socketSendBufferSize: info.socketSendBufferSize,
+    multishotAccept: info.multishotAccept,
+    multishotRecv: info.multishotRecv,
+    providedBufferRing: info.providedBufferRing,
+    recvBundle: info.recvBundle,
+    recvCopyEvents: info.recvCopyEvents,
+    recvCopyBytes: info.recvCopyBytes,
+    eventBatchSize: info.eventBatchSize,
+    sendBufferCount: info.sendBufferCount,
+    sendBufferSize: info.sendBufferSize,
+    registeredSendBuffer: info.registeredSendBuffer,
+    fixedSendBufferMisses: info.fixedSendBufferMisses,
+    fixedSendBufferMissBytes: info.fixedSendBufferMissBytes,
+    zeroCopySend: info.zeroCopySend,
+    zeroCopyReceive: info.zeroCopyReceive,
+    zcrxReady: info.zcrxReady
+  };
+}
+
+function baseReport() {
+  return {
+    mode: 'http-fixed-response',
+    status: 'running',
+    startedAt: new Date().toISOString(),
+    finishedAt: null,
+    config: {
+      durationMs: DURATION_MS,
+      concurrency: CONCURRENCY,
+      queueDepth: QUEUE_DEPTH
+    },
+    results: [],
+    error: null
+  };
+}
+
+function writeReport(report) {
+  if (!REPORT_PATH) return;
+  fs.mkdirSync(path.dirname(REPORT_PATH), { recursive: true });
+  fs.writeFileSync(REPORT_PATH, `${JSON.stringify(report, null, 2)}\n`);
+  console.log(`HTTP benchmark report written: ${REPORT_PATH}`);
+}
+
+function errorForReport(error) {
+  return {
+    name: error && error.name ? error.name : 'Error',
+    message: error && error.message ? error.message : String(error),
+    stack: error && error.stack ? error.stack : undefined
+  };
+}
+
+(async () => {
+  const report = baseReport();
+  try {
+    console.log(report.config);
+    const nodeResult = await withNodeServer();
+    report.results.push({ caseName: 'node:http', result: nodeResult });
+    console.log('node:http', nodeResult);
+    const ferringsResult = await withUringServer();
+    report.results.push({ caseName: 'ferrings', result: ferringsResult });
+    console.log('ferrings', ferringsResult);
+    report.status = 'passed';
+  } catch (error) {
+    report.status = 'failed';
+    report.error = errorForReport(error);
+    throw error;
+  } finally {
+    report.finishedAt = new Date().toISOString();
+    writeReport(report);
+  }
+})().catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
+});

package/benchmark/first-slice.js

@@ -0,0 +1,232 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { capabilities } = require('../');
+
+const DURATION_MS = String(process.env.DURATION_MS || 1000);
+const CONCURRENCY = String(process.env.CONCURRENCY || 128);
+const QUEUE_DEPTH = String(process.env.QUEUE_DEPTH || 256);
+const SYSCALL_REQUESTS = String(process.env.SYSCALL_REQUESTS || 200);
+const SYSCALL_CONCURRENCY = String(process.env.SYSCALL_CONCURRENCY || 32);
+const SYSCALL_CASES =
+  process.env.SYSCALL_CASES ||
+  'node-http,ferrings-http,node-tcp,ferrings-tcp-facade,ferrings-tcp-facade-batch,ferrings-native-tcp';
+const REPORT_PATH = process.env.REPORT_PATH;
+
+const report = {
+  mode: 'first-slice',
+  status: 'running',
+  startedAt: new Date().toISOString(),
+  finishedAt: null,
+  config: {
+    durationMs: Number(DURATION_MS),
+    concurrency: Number(CONCURRENCY),
+    queueDepth: Number(QUEUE_DEPTH),
+    syscallRequests: Number(SYSCALL_REQUESTS),
+    syscallConcurrency: Number(SYSCALL_CONCURRENCY),
+    syscallCases: SYSCALL_CASES.split(',').map((name) => name.trim()).filter(Boolean)
+  },
+  capabilities: capabilities(),
+  results: [],
+  summary: {},
+  error: null
+};
+
+try {
+  console.log({ mode: report.mode, ...report.config });
+  report.results.push(
+    runBenchmark('HTTP fixed response latency', 'compare.js', {
+      DURATION_MS,
+      CONCURRENCY,
+      QUEUE_DEPTH
+    })
+  );
+  report.results.push(
+    runBenchmark('TCP echo latency matrix', 'tcp-echo.js', {
+      DURATION_MS,
+      CONCURRENCY,
+      QUEUE_DEPTH
+    })
+  );
+  report.results.push(runSyscallBenchmark());
+  report.summary = buildSummary(report);
+  report.status = 'passed';
+} catch (error) {
+  report.status = 'failed';
+  report.error = errorForReport(error);
+  if (error && error.childResult) {
+    report.results.push(error.childResult);
+  }
+  throw error;
+} finally {
+  report.finishedAt = new Date().toISOString();
+  writeReport(report);
+}
+
+function runSyscallBenchmark() {
+  const strace = spawnSync('strace', ['-V'], { encoding: 'utf8' });
+  if (strace.error || strace.status !== 0) {
+    return {
+      label: 'Syscalls per connection',
+      script: 'syscalls.js',
+      status: 'skipped',
+      skippedReason: 'strace is not available',
+      report: null
+    };
+  }
+  return runBenchmark('Syscalls per connection', 'syscalls.js', {
+    REQUESTS: SYSCALL_REQUESTS,
+    CONCURRENCY: SYSCALL_CONCURRENCY,
+    QUEUE_DEPTH,
+    CASES: SYSCALL_CASES
+  });
+}
+
+function runBenchmark(label, script, extraEnv) {
+  console.log(`\n== ${label} ==`);
+  const childReportPath = path.join(
+    os.tmpdir(),
+    `ferrings-first-slice-${process.pid}-${path.basename(script, '.js')}-${Date.now()}.json`
+  );
+  const childResult = {
+    label,
+    script,
+    status: 'running',
+    report: null
+  };
+  const result = spawnSync(process.execPath, [path.join(__dirname, script)], {
+    cwd: path.join(__dirname, '..'),
+    env: {
+      ...process.env,
+      ...extraEnv,
+      REPORT_PATH: childReportPath
+    },
+    stdio: 'inherit'
+  });
+  childResult.report = readChildReport(childReportPath);
+  childResult.status = result.status === 0 ? 'passed' : 'failed';
+  if (result.error) {
+    result.error.childResult = childResult;
+    throw result.error;
+  }
+  if (result.status !== 0) {
+    const error = new Error(`${script} exited with status ${result.status ?? 1}`);
+    error.childResult = childResult;
+    throw error;
+  }
+  return childResult;
+}
+
+function readChildReport(childReportPath) {
+  try {
+    if (!fs.existsSync(childReportPath)) {
+      return null;
+    }
+    return JSON.parse(fs.readFileSync(childReportPath, 'utf8'));
+  } catch (error) {
+    return {
+      status: 'unreadable',
+      error: errorForReport(error)
+    };
+  } finally {
+    fs.rmSync(childReportPath, { force: true });
+  }
+}
+
+function buildSummary(output) {
+  const httpReport = childReport(output, 'compare.js');
+  const tcpReport = childReport(output, 'tcp-echo.js');
+  const syscallsReport = childReport(output, 'syscalls.js');
+  return {
+    httpLatency: compareResults(
+      resultByCase(httpReport, 'node:http'),
+      resultByCase(httpReport, 'ferrings')
+    ),
+    tcpNativeLatency: compareResults(
+      resultByCase(tcpReport, 'node:net echo'),
+      resultByCase(tcpReport, 'ferrings native tcp echo')
+    ),
+    tcpFacadeLatency: compareResults(
+      resultByCase(tcpReport, 'node:net echo'),
+      resultByCase(tcpReport, 'ferrings tcp facade echo')
+    ),
+    tcpFacadeBatchLatency: compareResults(
+      resultByCase(tcpReport, 'node:net echo'),
+      resultByCase(tcpReport, 'ferrings tcp facade batch echo')
+    ),
+    httpSyscalls: compareResults(
+      resultByCase(syscallsReport, 'node-http'),
+      resultByCase(syscallsReport, 'ferrings-http'),
+      'syscallsPerConnection'
+    ),
+    tcpNativeSyscalls: compareResults(
+      resultByCase(syscallsReport, 'node-tcp'),
+      resultByCase(syscallsReport, 'ferrings-native-tcp'),
+      'syscallsPerConnection'
+    ),
+    tcpFacadeSyscalls: compareResults(
+      resultByCase(syscallsReport, 'node-tcp'),
+      resultByCase(syscallsReport, 'ferrings-tcp-facade'),
+      'syscallsPerConnection'
+    ),
+    tcpFacadeBatchSyscalls: compareResults(
+      resultByCase(syscallsReport, 'node-tcp'),
+      resultByCase(syscallsReport, 'ferrings-tcp-facade-batch'),
+      'syscallsPerConnection'
+    )
+  };
+}
+
+function childReport(output, script) {
+  const entry = output.results.find((result) => result.script === script);
+  return entry && entry.report && entry.report.status === 'passed' ? entry.report : null;
+}
+
+function resultByCase(child, caseName) {
+  if (!child || !Array.isArray(child.results)) return null;
+  const entry = child.results.find((result) => result.caseName === caseName);
+  return entry ? entry.result : null;
+}
+
+function compareResults(baseline, candidate, metric = 'p99Ms') {
+  if (!baseline || !candidate) {
+    return null;
+  }
+  const baselineMetric = Number(baseline[metric]);
+  const candidateMetric = Number(candidate[metric]);
+  return {
+    baseline,
+    candidate,
+    metric,
+    baselineValue: baselineMetric,
+    candidateValue: candidateMetric,
+    delta: finiteNumber(candidateMetric - baselineMetric),
+    ratio: finiteNumber(candidateMetric / baselineMetric),
+    rpsRatio: finiteNumber(Number(candidate.rps) / Number(baseline.rps))
+  };
+}
+
+function finiteNumber(value) {
+  return Number.isFinite(value) ? Number(value.toFixed(3)) : null;
+}
+
+function writeReport(output) {
+  if (REPORT_PATH) {
+    fs.mkdirSync(path.dirname(REPORT_PATH), { recursive: true });
+    fs.writeFileSync(REPORT_PATH, `${JSON.stringify(output, null, 2)}\n`);
+    console.log(`first-slice benchmark report written: ${REPORT_PATH}`);
+  } else {
+    console.log(JSON.stringify(output.summary, null, 2));
+  }
+}
+
+function errorForReport(error) {
+  return {
+    name: error && error.name ? error.name : 'Error',
+    message: error && error.message ? error.message : String(error),
+    stack: error && error.stack ? error.stack : undefined
+  };
+}

package/benchmark/high-concurrency.js

@@ -0,0 +1,119 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const { spawnSync } = require('node:child_process');
+const path = require('node:path');
+
+const DEFAULT_DURATION_MS = '10000';
+const DEFAULT_CONCURRENCY = '512';
+const DEFAULT_QUEUE_DEPTH = '1024';
+const REPORT_PATH = process.env.REPORT_PATH;
+
+const env = {
+  ...process.env,
+  DURATION_MS: process.env.DURATION_MS || DEFAULT_DURATION_MS,
+  CONCURRENCY: process.env.CONCURRENCY || DEFAULT_CONCURRENCY,
+  QUEUE_DEPTH: process.env.QUEUE_DEPTH || DEFAULT_QUEUE_DEPTH
+};
+
+const report = {
+  mode: 'high-concurrency',
+  status: 'running',
+  startedAt: new Date().toISOString(),
+  finishedAt: null,
+  config: {
+    durationMs: Number(env.DURATION_MS),
+    concurrency: Number(env.CONCURRENCY),
+    queueDepth: Number(env.QUEUE_DEPTH)
+  },
+  results: [],
+  error: null
+};
+
+try {
+  console.log({ mode: report.mode, ...report.config });
+  report.results.push(run('HTTP fixed response', 'compare.js'));
+  report.results.push(run('TCP echo matrix', 'tcp-echo.js'));
+  report.status = 'passed';
+} catch (error) {
+  report.status = 'failed';
+  report.error = errorForReport(error);
+  if (error && error.childResult) {
+    report.results.push(error.childResult);
+  }
+  throw error;
+} finally {
+  report.finishedAt = new Date().toISOString();
+  writeReport(report);
+}
+
+function run(label, script) {
+  console.log(`\n== ${label} ==`);
+  const childResult = {
+    label,
+    script,
+    report: null
+  };
+  const childEnv = { ...env };
+  const childReportPath = REPORT_PATH
+    ? path.join(
+        os.tmpdir(),
+        `ferrings-high-${process.pid}-${path.basename(script, '.js')}-${Date.now()}.json`
+      )
+    : null;
+  if (childReportPath) {
+    childEnv.REPORT_PATH = childReportPath;
+  }
+  const result = spawnSync(
+    process.execPath,
+    [path.join(__dirname, script)],
+    {
+      cwd: path.join(__dirname, '..'),
+      env: childEnv,
+      stdio: 'inherit'
+    }
+  );
+  if (result.error) {
+    childResult.report = readChildReport(childReportPath);
+    result.error.childResult = childResult;
+    throw result.error;
+  }
+  childResult.report = readChildReport(childReportPath);
+  if (result.status !== 0) {
+    const error = new Error(`${script} exited with status ${result.status ?? 1}`);
+    error.childResult = childResult;
+    throw error;
+  }
+  return childResult;
+}
+
+function readChildReport(childReportPath) {
+  if (!childReportPath) return null;
+  if (!fs.existsSync(childReportPath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(childReportPath, 'utf8'));
+  } catch (error) {
+    return {
+      status: 'unreadable',
+      error: errorForReport(error)
+    };
+  } finally {
+    fs.rmSync(childReportPath, { force: true });
+  }
+}
+
+function writeReport(output) {
+  if (!REPORT_PATH) return;
+  fs.mkdirSync(path.dirname(REPORT_PATH), { recursive: true });
+  fs.writeFileSync(REPORT_PATH, `${JSON.stringify(output, null, 2)}\n`);
+  console.log(`high-concurrency benchmark report written: ${REPORT_PATH}`);
+}
+
+function errorForReport(error) {
+  return {
+    name: error && error.name ? error.name : 'Error',
+    message: error && error.message ? error.message : String(error),
+    stack: error && error.stack ? error.stack : undefined
+  };
+}