node-loadtest

High-performance HTTP load testing CLI for Node.js, powered by undici dispatch().

npx node-loadtest https://api.example.com -n 10000 -c 100
# or with global install
hlt https://api.example.com -n 10000 -c 100

---

Features

• Extreme Throughput: Direct access to undici.Pool.dispatch() raw request dispatching.
• Zero Per-Request Garbage: Pre-allocated reusable request handler slots. No per-request allocations or result arrays.
• Microsecond Precision Latency: Monotonic process.hrtime.bigint() timing with high-dynamic-range histogram (hdr-histogram-js) measuring p50, p75, p90, p95, p99, and p99.9 percentiles.
• Coordinated Omission Correction: Automatic Gil Tene Coordinated Omission correction for rate-paced benchmarks, accurately capturing queue-time latency under saturation.
• High-Precision Rate Pacing: Sub-millisecond setImmediate + hrtime event loop scheduling that prevents setTimeout drift and clumping at high TPS (>1,000 req/s).
• Connection Warm-Up Phase: Discard connection setup and TLS handshake outliers with -W, --warmup <seconds> before recording benchmark metrics.
• Multi-Core / Worker Threads Scaling: Scale test generation across multiple CPU cores with -w, --workers <number>. Aggregates HDR histograms seamlessly without cross-thread lock contention.
• Worker Fault Tolerance: Resilient multi-worker execution that aggregates partial snapshots and tracks worker errors rather than aborting.
• HTTP/2 Multiplexing Support: Automatic ALPN HTTP/2 negotiation for HTTPS endpoints (--no-h2 to force HTTP/1.1), avoiding TCP head-of-line blocking.
• HTTP/1.1 Pipelining: Increase saturation over high-latency links via --pipelining <n> (e.g. 4 or 8).
• Fast Buffer Pre-Encoding: Pre-encodes headers into flat arrays and string bodies into native Node Buffers, eliminating string parsing on the hot path.
• Full Connection Control: Configurable connection pooling (--connections) and HTTP pipelining depth (--pipelining).
• Comprehensive Metrics: Status code distribution, error breakdown, throughput (req/s), and bandwidth (MB/s).
• Graceful Shutdown: Thread-safe interception of SIGINT / SIGTERM across both main and worker threads to drain in-flight requests and snapshot metrics.
• Multiple Output Formats: Styled ANSI terminal report or machine-readable JSON (-o json).
• Embedded Self-Benchmark: Verify load tester capabilities against a local zero-latency loopback server.

---

Install

npm install -g node-loadtest
# or run directly with npx
npx node-loadtest https://api.example.com -n 1000 -c 50

Requires Node.js >= 20.

---

Usage

hlt <url> [options]

Options

Flag	Description	Default
-n, --requests <number>	Total number of requests	200
-c, --concurrency <number>	Concurrent requests	50
-d, --duration <seconds>	Run for duration in seconds (overrides -n)	—
-W, --warmup <seconds>	Warm-up duration in seconds before recording metrics	0
--max-requests <number>	Hard safety limit for total requests in duration mode	—
-r, --rate <number>	Target requests per second (TPS / RPS limit)	—
-w, --workers <number>	Number of worker threads for multi-core scaling	1
--correct-latency	Enable Coordinated Omission latency correction (enabled by default with -r)	true with -r
--no-correct-latency	Disable Coordinated Omission latency correction	false
--no-h2	Disable HTTP/2 support (defaults to enabled for HTTPS)	false
-H, --header <header>	Add request header ("K: V"), repeatable	—
-m, --method <method>	HTTP method (GET, POST, PUT, DELETE, etc.)	GET (or POST if -b)
-b, --body <body>	Request body string	—
-t, --timeout <ms>	Request timeout in milliseconds	20000
-o, --output <format>	Output format: text or json	text
--connections <number>	Pool connection count	same as concurrency
--pipelining <number>	Pipeline depth per connection	1

---

Examples

1. Simple High-Concurrency Benchmark

hlt https://localhost:3000/api -n 100000 -c 500

2. Multi-Core Scaling Across CPU Threads

Scale test generation across 4 worker threads:

hlt https://localhost:3000/api -n 500000 -c 500 -w 4

3. HTTP Pipelining on Supported Servers

Pipeline 4 requests per connection:

hlt https://localhost:3000/api -n 100000 -c 100 --pipelining 4

4. Rate-Paced Test (100 TPS)

hlt https://localhost:3000/api -n 1000 -c 20 -r 100

5. Sustained Duration Test

Run for 30 seconds at 100 concurrency:

hlt https://localhost:3000/health -d 30 -c 100

6. Custom Headers & Auth Token

hlt https://localhost:3000/api \
  -n 50000 \
  -c 200 \
  -H "Authorization: Bearer my-secret-token" \
  -H "Accept: application/json"

7. POST Request with JSON Body

hlt https://localhost:3000/api \
  -m POST \
  -b '{"action":"test","active":true}' \
  -H "Content-Type: application/json" \
  -n 5000 \
  -c 50

8. Machine-Readable JSON Output

hlt https://localhost:3000/api -n 1000 -c 50 -o json > results.json

---

Sample Output

┌──────────────────────────────────────────────────────┐
│  hlt — Load Test Results                             │
├──────────────────────────────────────────────────────┤
│  Target:        http://127.0.0.1:3000/api            │
│  Method:        GET                                  │
│  Concurrency:   100                                  │
│  Duration:      2.21s                                │
│  Total Reqs:    100,000                              │
├──────────────────────────────────────────────────────┤
│  Throughput:    45,323.63 req/s                      │
│  Data:          3.53 MB (1.60 MB/s)                  │
├──────────────────────────────────────────────────────┤
│  Latency (ms)                                        │
│    p50    1.75                                       │
│    p75    2.10                                       │
│    p90    2.86                                       │
│    p95    3.39                                       │
│    p99    4.97                                       │
│    p99.9  17.79                                      │
│    min    0.10                                       │
│    max    34.56                                      │
│    mean   1.98                                       │
│    stdev  1.02                                       │
├──────────────────────────────────────────────────────┤
│  Status Codes                                        │
│    200    100,000                                    │
└──────────────────────────────────────────────────────┘

---

Self-Benchmark Mode

Test hlt against an internal zero-allocation HTTP server on loopback to benchmark machine limits:

# Default (100k requests, 100 concurrency)
hlt self-benchmark

# Multi-core self benchmark with 4 workers
hlt self-benchmark -n 500000 -c 200 -w 4

# Rate-controlled benchmark (100 TPS)
hlt self-benchmark -n 1000 -c 20 -r 100

---

Architecture & Performance Optimizations

CLI Parser (Commander.js)
       │
       ▼
Config & Options Validator (Workers, Rate, H2, Pipelining)
       │
       ▼
Load Engine (Single-thread or Multi-Worker Threads Orchestration)
       │
       ├─► Worker Thread 1 (undici.Pool.dispatch + RequestSlotHandler Pool)
       ├─► Worker Thread 2 (undici.Pool.dispatch + RequestSlotHandler Pool)
       └─► Worker Thread N ...
               │
               ▼
       Base64 Compressed HDR Histograms & Status Maps
               │
               ▼
Metrics Merger (Combines HDR Histograms + Accurate Percentiles)
               │
               ▼
Reporter (ANSI Box-Drawn Terminal or JSON)

1. dispatch() over request() / fetch(): Undici's low-level dispatch bypasses ReadableStream wrapping, Response object allocations, and header cloning.
2. Reusable Handler Slot Pool: Pre-allocates $C$ handler instances where $C$ is concurrency. Each handler is recycled with reset(), creating zero GC pressure on the hot path.
3. HTTP/2 Multiplexing: Enabled by default for HTTPS via ALPN negotiation. Multiplexes streams across connections without head-of-line blocking.
4. Header Buffer Pre-Encoding: Flat string array encoding [key, value, ...] and Buffer.from(body) avoid per-request object iteration.
5. Multi-Worker Thread Scaling: Overcomes the V8 single-thread execution limit by spawning $N$ Node.js worker_threads and merging compressed HDR histograms into unified latency percentiles.

---

Development

# Install dependencies
npm install

# Build TypeScript to dist/
npm run build

# Watch mode
npm run dev

# Run test suite
npm test

# Run self-benchmark
npm run self-benchmark

---

License

MIT © pushpendrabansal