Real server + real HTTP requests
Measure public paths.
Run node-http-server and the HTTP driver in separate Node processes, validate every loopback response, and record throughput plus p50, p95, and p99 latency.
Published measurement
Inspect the latest canonical Ubuntu run.
Loading benchmarks/latest.json from the published site…
| Generated | Package | Node | Platform | Measured / scenario | Warmup / scenario | Clients |
|---|
| Scenario | Requests | Requests/sec | p50 ms | p95 ms | p99 ms |
|---|
Local fallback: run
npm run benchmark for a current measurement on your machine. Use node benchmark/run.js --json for structured local evidence.Commands and profiles
Select a bounded run.
| Command | Profile | Output |
|---|---|---|
npm run benchmark | 250 measured requests + 25 warmups per scenario, 10 concurrent clients. | Readable scenario table. |
npm run benchmark:smoke | 8 measured requests + 2 warmups per scenario, 2 concurrent clients. | Short readable verification table. |
node benchmark/run.js --json | Standard profile. | One structured JSON document for storage or analysis. |
shell · custom measured run
node benchmark/run.js \
--requests 1000 \
--warmup 100 \
--concurrency 25 \
--json| Option | Standard | Smoke | Contract |
|---|---|---|---|
--requests <count> | 250 | 8 | Measured requests for each scenario; positive integer. |
--warmup <count> | 25 | 2 | Validated warmup requests for each scenario; non-negative integer. |
--concurrency <count> | 10 | 2 | Concurrent HTTP clients; positive integer up to the measured request count. |
--json | off | off | Emit structured result data to standard output. |
--smoke | off | on | Select the short profile; explicit numeric options take precedence. |
Execution model
Exercise the shipped public paths.
| Stage | What happens | Engineering value |
|---|---|---|
| Fixture setup | Creates temporary text, binary, and SPA files. | Known bytes make response validation exact. |
| Server start | The parent forks benchmark/server.js; the child creates a public Server instance on 127.0.0.1 with an OS-assigned port. | Separate event loops isolate server work from client measurement. |
| Warmup | Sends and validates the selected warmup count. | Connection and runtime startup occur before the measurement window. |
| Measurement | The parent process drives concurrent loopback requests through Node's HTTP client and a keep-alive agent. | Results represent actual request, routing, file, compression, and hook work. |
| Validation | Checks the expected status, headers, and exact response bytes for every request. | Each validated response contributes to the latency and throughput summary. |
| Cleanup | IPC carries a bounded close handshake; the parent destroys the client agent and removes temporary files. | Each run leaves a clean workspace. |
Process contract: IPC carries readiness, the selected port, and shutdown state. The harness uses Node built-ins and node-http-server itself.
Public-path inventory
Five validated server workloads.
| ID | Request path | Accepted response |
|---|---|---|
static-get-small | GET /small.txt | 200, content length, exact bytes. |
static-head-small | HEAD /small.txt | 200, content length, empty response body. |
static-range-large | GET /large.bin with a byte range. | 206, content range, exact 64 KiB slice from a 1 MiB file. |
spa-fallback-gzip | GET /dashboard/settings with HTML and gzip negotiation. | 200, gzip and Vary headers, exact decompressed SPA document. |
dynamic-hook | GET /dynamic handled by onRequest. | 200, JSON content type, exact hook response. |
Result contract
Read throughput and the latency distribution together.
| Field | Meaning | Use |
|---|---|---|
requestsPerSecond | Validated measured requests divided by scenario wall time. | Compare completed work per second. |
latencyMilliseconds.p50 | Median measured request latency. | Understand the common request. |
latencyMilliseconds.p95 | 95th-percentile measured request latency. | Track slower requests near the tail. |
latencyMilliseconds.p99 | 99th-percentile measured request latency. | Track the high tail. |
durationMilliseconds | Scenario wall time after warmup. | Audit the throughput calculation and run cost. |
JSON output also records the package version, generation time, Node version, platform, architecture, and effective request profile.
Comparison discipline
Keep the environment equivalent.
- Record the environment.Keep package, Node, operating system, architecture, and request profile with every result.
- Control host load.Use the same machine and an idle system for comparable runs.
- Repeat the run.Collect several samples and compare the distribution across runs.
- Compare by scenario.Review throughput and p50/p95/p99 together for the same scenario ID.
- Verify behavior first.Run
npm test; the benchmark then validates every measured response again.