# rload
`rload` is a Rust HTTP load generator with wrk-compatible CLI semantics,
Nginx access-log replay, and structured JSONL request replay.
Official website: [wenhaozhao.github.io/rload](https://wenhaozhao.github.io/rload/)
The current vertical slice provides:
- non-blocking HTTP/1.1 GET requests over HTTP or HTTPS using fixed worker threads;
- TLS SNI, Mozilla root certificate validation, and encrypted connection reuse;
- ordered, cyclic replay of `GET` and `HEAD` requests from Nginx common or combined access logs;
- exact per-method latency/error summaries and HTTP status-code counts;
- bounded URI Top-20 heavy-hitter estimates with explicit maximum error;
- persistent connections with request-count or duration limits;
- socket-error accounting and connection recovery during duration-limited runs;
- `Content-Length`, chunked, and connection-close response framing;
- completed request, response body byte, status error, and average latency output.
Lua and LuaJIT compatibility are explicitly out of scope.
## Comparison with wrk
The comparison baseline is wrk 4.2.0. Performance figures below come from
paired runs using the same URL, server, thread count, connection count, and
duration on macOS arm64. They are regression evidence for this environment,
not a guarantee that either client will reach the same throughput on every
machine.
### Performance and accuracy
| Throughput | Reference client | RPS MAE 0.986% across 15 paired runs at 10/100/400 connections | Equivalent within the 3% gate |
| Average latency | Reference client | MAE 1.171% | Equivalent within the 3% gate |
| P50 / P75 latency | Reference percentiles | MAE 1.064% / 0.961% | Equivalent within the 3% gate |
| P90 latency | Reference percentile | MAE 0.944% | Equivalent within the 5% gate |
| P99 with 1 ms delay + deterministic jitter | Reference percentile | Median absolute error 0.567% | Passes the 5% gate |
| Zero-delay loopback P99 | Sensitive to scheduler noise | Median absolute error 5.128% | Narrowly exceeds the 5% gate; not claimed as unconditional parity |
| Static-path RSS | Reference process | Fresh 100-connection run: wrk ~3.47 MiB, rload ~3.55 MiB | Comparable in the measured run |
| Access-log replay throughput | No native access-log replay | 100k: +1.68%; 500k: -1.81% versus paired static runs | Replay overhead remained within the configured 10% gate |
| Access-log replay memory | No native access-log replay | RSS scaling slope 248.7 B per loaded entry | Passed the configured 0–256 B/entry gate |
The formal accuracy methodology, raw result directories, and gate definitions
are documented in [`benchmarks/VALIDATION_2026-07-11.md`](benchmarks/VALIDATION_2026-07-11.md)
and [`benchmarks/ACCURACY.md`](benchmarks/ACCURACY.md). The zero-delay P99
result is intentionally called out rather than rounded into a pass.
### Functional coverage
| HTTP/1.1 static request load | Yes | Yes |
| HTTP and HTTPS with connection reuse | Yes | Yes, including TLS verification and SNI |
| Worker threads, connections, duration, request count | Yes | Yes; core CLI forms are compatible |
| Timeout and latency reporting | Yes | Yes; `--latency` is accepted and latency is always printed |
| HTTP status and socket-error statistics | Yes | Yes, with connect/read/write/timeout categories |
| Curl-style method, headers, and request body | Via Lua scripting | Yes for the documented curl-compatible subset |
| Lua/LuaJIT request scripting | Yes | Intentionally not supported in the first release line |
| Nginx access-log replay | No native mode | Yes; common/combined logs, `GET`/`HEAD`, sequential/shuffle/random order; unsupported-method skipping planned for 0.2.0 |
| JSONL request replay | No native mode | Yes; methods, headers, UTF-8 bodies, and per-record limits |
| Replay seed and method/URI whitelists | No native mode | Yes; deterministic seed plus intersection filters |
| Replay frequency/timestamp pacing/burst profiles | Custom scripting only | Planned 0.2.0 features, not implemented yet |
| Automatic target inference from access-log entries | No native mode | Future candidate only; target URL is currently explicit |
| GUI configuration interface | No native mode | Future optional feature layered on the rload engine |
The result is intentionally a wrk-compatible load generator rather than a
drop-in replacement for every wrk extension: core command-line behavior and
static HTTP load are covered, while Lua compatibility is outside the first
release scope. The additional replay modes are the main functional expansion
provided by rload. A future GUI, if built, will be a configuration and
observability layer over the same engine; it will not replace the standalone
CLI or duplicate load-generation logic.
## Build and install
The current release baseline is validated with stable Rust 1.96.1 on macOS
arm64. The runtime uses portable Rust crates, but Linux and Windows remain
release candidates until the same test and package gates run in 0.2.0 CI on
those platforms. Windows CI will additionally cover PowerShell invocation,
path handling, and socket recovery.
Build or install directly from this checkout:
```sh
cargo build --release --manifest-path r-wrk/Cargo.toml
cargo install --path r-wrk
rload --help
```
When already inside the crate directory, omit the manifest/path prefixes.
Rload is licensed under `MIT OR Apache-2.0`; see `LICENSE-MIT` and
`LICENSE-APACHE`. Third-party attribution notices are documented separately
where required by dependencies.
## Usage
```sh
cargo run --release -- --requests 10 http://127.0.0.1:8080/
cargo run --release -- --threads 2 --connections 10 --duration 30s http://127.0.0.1:8080/
cargo run --release -- --threads 2 --connections 10 --duration 30s https://example.com/
cargo run --release -- -d 30s -X POST -H 'Content-Type: application/json' \
--data '{"id":1}' https://example.com/api/items
cargo run --release -- --threads 2 --connections 10 --duration 30s \
--access-log /var/log/nginx/access.log https://staging.example.com/
cargo run --release -- --requests 1000 --access-log ./access.log \
--replay-order shuffle --seed 42 https://staging.example.com/
cargo run --release -- --duration 30s --request-file ./requests.jsonl \
--replay-order shuffle --seed 42 https://staging.example.com/
```
Ordinary requests use a curl-compatible subset while preserving wrk's option
meanings: `-X/--request`, repeatable `-H/--header`, repeatable `--data`, and
`--data-binary @FILE`. The short `-d` remains the wrk duration option; it never
means request data. Multiple `--data` values are joined with `&`, and specifying
data without `-X` selects POST. Binary files are sent byte-for-byte. The same
managed-header, URI, and 512 KiB body limits used by JSONL apply here.
Common wrk command lines remain valid: compact `-t2`, `-c100`, `-n1000`,
`-d30s`, and `-T2s` forms are accepted; times support bare seconds plus `s`, `m`, and `h`;
`-T/--timeout` controls connection/request timeout,
and `--latency` is accepted as a compatibility flag (the latency distribution
is always printed). With no explicit load options, the wrk-compatible defaults
are a 10-second run with two worker threads and ten connections.
During a duration-limited run, a request timeout, reset, or premature EOF is
counted as a socket error and the affected connection is rebuilt while time
remains. Request-count-limited runs still return an error for these failures so
a permanently unavailable target cannot make a finite run wait forever.
Socket errors are reported using wrk-style `connect`, `read`, `write`, and
`timeout` categories; failure and recovery are isolated to the affected
connection. If a duration-limited target remains unresponsive for the whole
run, the command still returns a valid summary with zero completed requests and
the accumulated timeout count after the configured duration expires. The same
bounded behavior applies when every connection attempt is refused: attempts are
counted as `connect` errors and the run ends normally at its duration limit. If
the target becomes available again before that limit, affected connections
resume sending requests without restarting the load-test process.
Access-log replay reads the quoted Nginx `$request` field, preserves its
origin-form URI (including the query string), and cycles through the log in
order until the request-count or duration limit is reached. Empty logs,
malformed request lines, and methods other than `GET` or `HEAD` fail with the
source line number in 0.1.1. In 0.2.0, unsupported methods will be skipped and
reported by total and method-specific counters in the final summary; they will
not be sent or included in request latency/throughput statistics. Request bodies
and original timestamp pacing are not yet supported.
Replay order is `sequential` by default. `shuffle` visits every entry exactly
once per round and reshuffles before the next round; `random` independently
samples an entry for every request and can repeat entries. `--seed` makes either
randomized allocation sequence reproducible. With multiple connections, the
allocation sequence remains deterministic but network arrival order can vary.
URI Top-20 counts use a bounded Space-Saving estimate. For each entry, the true
request count is between `estimated_requests - maximum_error` and
`estimated_requests`; the reported error is therefore a one-sided maximum
overcount, not a symmetric confidence interval.
Structured request replay accepts one JSON object per line:
```json
{"method":"POST","uri":"/api/items","headers":{"content-type":"application/json"},"body":"{\"id\":1}"}
```
Supported methods are `GET`, `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE`, and
`OPTIONS`. Bodies are UTF-8 strings. `Host`, `Connection`, and `Content-Length`
are managed by the engine and must not appear in the JSON headers. JSONL and
access-log inputs are mutually exclusive; both support the same replay-order
options. Each JSONL record is limited to 1 MiB, with an 8 KiB URI, 64 KiB of
headers, and a 512 KiB UTF-8 body. `Transfer-Encoding`, `Trailer`, and `Expect`
are also rejected because this release sends fixed-length request bodies
without an HTTP/1.1 continue handshake.
Replay inputs can be reduced with method and URI whitelists:
```sh
--allowed-methods GET,POST --allowed-uris '/api/*,/health'
```
URI patterns use a small deterministic glob syntax where `*` matches any
sequence and every other character is literal. Method and URI filters form an
intersection. Filtered entries are counted in the summary, and a whitelist that
excludes the entire input is an error. Whitelist options are not valid for an
ordinary single request. At most 32 URI patterns may be supplied, each no longer
than 256 bytes, which bounds wildcard matching work for large logs.
### Optional replay features
The following capabilities are recorded for later evaluation and are not part
of the current implementation or acceptance scope:
- replay frequency control with a fixed global request rate;
- original access-log timestamp pacing and playback-speed scaling, including
explicit handling for second-only versus sub-second timestamps;
- per-stage or burst rate profiles, such as a baseline rate followed by a timed
spike and recovery;
- target inference for custom Nginx log formats that explicitly record scheme,
host, and port; this remains a future candidate and is not scheduled for
0.2.0.
Burst profiles control when requests are sent and are independent of replay
selection order. `sequential`, `shuffle`, and `random` choose which request is
selected; a burst/stage profile controls the rate at which selected requests
are issued.
Until one of these optional modes is implemented, access-log replay remains a
maximum-throughput workload: each connection sends its next request as soon as
the previous response completes.
Measure replay overhead against the static-request path with:
```sh
ENTRIES=100000 CONNECTIONS=100 DURATION=5 ./benchmarks/replay.sh
REPLAY_ORDER=shuffle SEED=42 ./benchmarks/replay.sh
./benchmarks/replay_matrix.sh
```
The repeatable benchmark uses at least three paired runs with alternating order
and reports median throughput loss, its range, total RSS growth, and bytes per
loaded log entry. The matrix additionally validates the RSS slope between 100k
and 500k entries. Current gates are at most 10% throughput loss and between 0
and 256 bytes of incremental RSS per entry.
The 2026-07-11 sequential-replay acceptance matrix passed both scales. At 100k
entries, median throughput difference was +1.68% and incremental RSS was 252.5
B/entry. At 500k entries, the corresponding throughput difference was -1.81%
and the measured RSS scaling slope was 248.7 B/entry. These local results are
regression evidence rather than a cross-platform memory guarantee.
Run the tests and lints with:
```sh
cargo test
cargo clippy --all-targets -- -D warnings
```
Run the complete local release gate with:
```sh
./scripts/release-check.sh
```
## Benchmarking
Run the repeatable local comparison against wrk with:
```sh
./benchmarks/run.sh
```
Override `DURATION`, `THREADS`, `CONNECTIONS`, or `RUNS` through environment
variables. `DELAY_US` adds a fixed server delay and `JITTER_US` adds deterministic
uniform jitter, which makes tail-latency comparisons repeatable. Raw command
output, CPU time, maximum RSS, and environment details are written under
`benchmarks/results/`.
Analyze one or more result directories with:
```sh
python3 benchmarks/accuracy.py benchmarks/results/<timestamp> [...]
```
The checker reports paired relative bias, mean absolute error, standard
deviation, a 95% confidence interval, and range. It enforces 3% MAE for
throughput and central latency, 5% MAE for P90, and 5% median absolute error for
P99. At least three paired runs are required. See
[`benchmarks/ACCURACY.md`](benchmarks/ACCURACY.md) for the methodology.