feat(core): add HTTP/2 performance gates
This commit is contained in:
Zakaria El Orche
@@ -0,0 +1,44 @@
|
||||
# HTTP performance baselines
|
||||
|
||||
These numbers are regression controls, not cross-machine promises. They were measured on
|
||||
2026-08-13 under Linux 6.12/KVM, six exposed cores of an AMD Ryzen 7 1700X, Temurin 21.0.11 and
|
||||
JMH 1.37. CI uses short independent forks for allocation and sample latency so the sampling
|
||||
harness does not contaminate `gc.alloc.rate.norm`.
|
||||
|
||||
## Gated hot paths
|
||||
|
||||
| Benchmark | B/op | p50 ns | p99 ns | p999 ns | CI p99 ceiling ns |
|
||||
|---|---:|---:|---:|---:|---:|
|
||||
| h1 parse and route | 0.022 | 540 | 33,472 | 60,822 | 45,000 |
|
||||
| h2 pooled stream lifecycle | 0.010 | 530 | 2,138 | 37,724 | 2,900 |
|
||||
| h2 response encoding | 0.004 | 210 | 993 | 14,626 | 1,350 |
|
||||
| HPACK browser-request decode | 0.015 | 730 | 5,245 | 27,577 | 7,100 |
|
||||
| HPACK typical-response encode | 0.003 | 180 | 620 | 12,025 | 850 |
|
||||
| frame read/validate/discard | 0.006 | 70 | 1,999 | 90,508 | 2,700 |
|
||||
|
||||
The sub-byte allocation values occur with no collection and are JMH/GC-profiler rate
|
||||
normalization noise. The CI allocation ceiling is 0.05 B/op. A benchmark exceeding it fails; a
|
||||
baseline or ceiling change requires an explicit edit and justification here.
|
||||
|
||||
The table records the higher percentile observed across three consecutive controlled runs; this is
|
||||
important because short sample-mode runs on the shared KVM host showed visible scheduler noise.
|
||||
The p999 values expose those tails but are recorded rather than gated. The p99 ceilings are the
|
||||
worst observed p99 plus about 35% headroom.
|
||||
|
||||
## HTTP/1 historical comparison
|
||||
|
||||
The plan required a pre-Phase-1 number, but no benchmark was committed at that point. Phase 17
|
||||
reconstructed the current `RequestPipelineBenchmark.parseAndRoute` fixture against Phase 0 commit
|
||||
`db6e4a4` in a detached worktree and ran both revisions on the same host and JVM:
|
||||
|
||||
| Revision | ns/op | B/op |
|
||||
|---|---:|---:|
|
||||
| Phase 0 (`db6e4a4`) | 976.195 ± 45.924 | 224.007 |
|
||||
| Phase 17 | 1,024.602 ± 50.744 | 0.007 |
|
||||
|
||||
The hardened parser's mean is 5.0% higher and removes effectively all 224 B/op. The 99.9%
|
||||
confidence intervals overlap (`930.271–1,022.120` ns for Phase 0 and `973.858–1,075.345` ns for
|
||||
Phase 17), so this run does not establish a statistically significant latency regression. This is
|
||||
an honest reconstruction, not a claim that an absent historical run existed. Phase 17 recovered
|
||||
about 4.5% by having `RequestParser` populate `Http1HeaderMap`'s zero-copy index during the same
|
||||
validated header pass instead of rescanning every line; all security checks remain in that path.
|
||||
@@ -1100,3 +1100,45 @@ a second h2-only cleartext listener solely to satisfy a tool assumption.
|
||||
against that listener too.
|
||||
|
||||
---
|
||||
|
||||
## DEC-35 — Separate live-stream admission from final-write ownership
|
||||
|
||||
**Context.** A stream becomes closed on the wire before the asynchronous serialized writer calls
|
||||
back for its final batch. Counting that object as live rejects legal replacement streams; pooling
|
||||
it before the callback lets the next stream mutate memory still referenced by the writer.
|
||||
|
||||
**Decision.** Detach a wire-closed stream from the primitive live table immediately before its
|
||||
final batch is submitted, but retain the stream object until write completion. Bound the combined
|
||||
live and detached population to twice `MAX_CONCURRENT_STREAMS`; output congestion therefore
|
||||
remains bounded and eventually applies `REFUSED_STREAM` backpressure rather than growing memory.
|
||||
|
||||
**Consequence.** The peer can use all advertised live-stream slots while final writes drain, and
|
||||
the callback always owns the correct object generation. The closed-stream tombstone is recorded
|
||||
at detach time, so protocol error classification is unchanged.
|
||||
|
||||
**Revisit when.** If production traces show the two-generation object bound rejecting healthy
|
||||
traffic, measure writer-drain latency first; increasing the bound without evidence would only hide
|
||||
output backpressure.
|
||||
|
||||
---
|
||||
|
||||
## DEC-36 — Performance gates distinguish profiler noise, latency sampling, and load results
|
||||
|
||||
**Context.** JMH's sampling mode allocates bookkeeping records, so combining `Mode.SampleTime`
|
||||
with `GCProfiler` falsely reports allocations on otherwise allocation-free operations. End-to-end
|
||||
h2load results also show that Flash does not outperform the reference server, so the plan's
|
||||
"unmatched" wording cannot honestly become a product claim.
|
||||
|
||||
**Decision.** Run two independent forked CI passes over the same six hot paths: average-time plus
|
||||
`GCProfiler` for allocation, and sample-time without the allocation profiler for p50/p99/p999.
|
||||
Treat up to 0.05 B/op with zero observed collections as the profiler's measurement floor. Gate
|
||||
p99 with documented per-benchmark ceilings and keep h2load comparative results informational.
|
||||
|
||||
**Consequence.** CI detects real allocation and latency regressions without measuring its own
|
||||
sampling machinery. Performance documentation reports Flash and nghttpd numbers directly and
|
||||
makes no "unmatched" claim.
|
||||
|
||||
**Revisit when.** Recalibrate baselines deliberately on a controlled CI runner, or replace the
|
||||
noise floor if a profiler can distinguish harness allocation from benchmark allocation exactly.
|
||||
|
||||
---
|
||||
|
||||
@@ -78,7 +78,7 @@ Status values: `not started` / `in progress` / `blocked` / `done`.
|
||||
| 14 — h2c prior knowledge + proxy support | done | `feature/core/http2` | Independent TLS/h2c gates, pooled proxy-oriented h2 client with TLS ALPN and h2c, bidirectional h1/h2 trailer relay, shared four-direction hop-by-hop policy and certificate-backed 421 handling complete. Real grpcurl h2c interop passes. 670/670 tests green from a clean `-Pjmh` build. |
|
||||
| 15 — RFC 8441 extended CONNECT (WS over h2) | done | `feature/core/http2` | SETTINGS_ENABLE_CONNECT_PROTOCOL, shared WS router/session, DATA flow control, >1 MiB message, h1/h2 parity and lifecycle hardening complete. EX-52/53 fixed; DEC-32 recorded. 675/675 tests green from a clean `-Pjmh` build; real grpcurl interop remains green. |
|
||||
| 16 — Compliance test suite | done | `feature/core/http2` | h2spec 2.6.0: TLS 146/146 and mixed-port h2c 145/145 applicable cases, zero skips/failures; invalid-preface protocol boundary documented and regression-tested. Deterministic bounded fuzz targets, exact wire corpus, 1,000-stream single-connection test, nightly 10-minute soak, curl/nghttp/Java/grpcurl matrix and release-browser checklist complete. EX-54–56 fixed; DEC-33/34 recorded. Clean `-Pjmh` gate: 690 tests, 0 failures/errors, 1 intentional conditional soak skip. |
|
||||
| 17 — Benchmarks, allocation gates, tuning | not started | — | — |
|
||||
| 17 — Benchmarks, allocation gates, tuning | done | `feature/core/http2` | Forked JMH allocation and true sampled-p99 gates wired into CI; h1/h2/frame/HPACK/body/multiplexing/writer coverage complete. Reconstructed Phase-0 h1 baseline: 1,024.602 ns now vs 976.195 ns then with overlapping 99.9% CIs, and 0.007 vs 224.007 B/op. h2load matrix against nghttpd recorded honestly (no unmatched claim); tuning and async-profiler CPU/allocation/lock pass documented. EX-57/58 and DEC-35/36 recorded. Clean pinned-thread build: 694 tests, zero failures/errors, eight intentional conditional skips. |
|
||||
| 18 — Documentation | not started | — | — |
|
||||
|
||||
---
|
||||
@@ -855,6 +855,25 @@ connection `PROTOCOL_ERROR`. **Fix**: preface verification now distinguishes mat
|
||||
and invalid input; invalid input sends GOAWAY. The exact 24 bytes are in the regression corpus.
|
||||
**Phase**: 16.
|
||||
|
||||
### EX-57 — Wire-closed streams occupied the live concurrency table until their final write callback
|
||||
|
||||
Found by the Phase 17 h2load matrix at the advertised 64-stream concurrency. A response stream
|
||||
could be closed in protocol state while its final immutable write batch was still owned by the
|
||||
serialized writer. Keeping that object in the live table made a legal replacement stream receive
|
||||
`REFUSED_STREAM`; recycling it immediately would instead corrupt the pending write callback.
|
||||
**Fix**: detach a closed stream from live lookup before submitting its final batch, retain bounded
|
||||
object ownership until the callback, and cap live plus detached objects at twice the advertised
|
||||
live capacity. The regression test fills a one-entry table, detaches its final generation, admits
|
||||
the next stream, and proves both objects return to the pool. **Phase**: 17.
|
||||
|
||||
### EX-58 — The upstream HTTP/2 client left Nagle enabled on synchronous exchanges
|
||||
|
||||
Found while building the Phase 17 end-to-end benchmark. The proxy-oriented client sends small
|
||||
request and control frames and then synchronously waits for the response; with Nagle enabled this
|
||||
interacted with delayed ACKs and added roughly 40 ms to a local exchange. **Fix**: configure
|
||||
`TCP_NODELAY` on both cleartext and TLS sockets before protocol exchange. A socket-option
|
||||
regression test covers the shared configuration method. **Phase**: 17.
|
||||
|
||||
---
|
||||
|
||||
# PART III — The phases
|
||||
@@ -3122,11 +3141,14 @@ decisions and the rejected ones. Every claim in the project's marketing about pe
|
||||
be traceable to a number in this file.
|
||||
|
||||
### DoD
|
||||
- [ ] Allocation gates green in CI and wired to fail the build.
|
||||
- [ ] Latency baselines recorded.
|
||||
- [ ] h1 performance is not worse than the pre-Phase-1 baseline.
|
||||
- [ ] No carrier pinning anywhere.
|
||||
- [ ] `flash/docs/http2/PERFORMANCE.md` complete with the comparison against a reference server.
|
||||
- [x] Allocation gates green in CI and wired to fail the build.
|
||||
- [x] Latency baselines recorded in `BASELINES.md`; CI reads JMH's actual `p0.99` secondary
|
||||
result, not iteration-mean statistics.
|
||||
- [x] h1 performance is not statistically worse than the reconstructed pre-Phase-1 baseline:
|
||||
the 99.9% confidence intervals overlap, while allocation falls from 224.007 to 0.007 B/op.
|
||||
- [x] No carrier pinning anywhere — full 694-test clean run with
|
||||
`-Djdk.tracePinnedThreads=full`, zero pinning events.
|
||||
- [x] `flash/docs/http2/PERFORMANCE.md` complete with the comparison against nghttpd.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,99 @@
|
||||
# HTTP/2 performance
|
||||
|
||||
## Method
|
||||
|
||||
Measurements were taken on 2026-08-13 under Linux 6.12/KVM with six exposed AMD Ryzen 7 1700X
|
||||
cores, Temurin 21.0.11, JMH 1.37 and nghttp2 1.59.0. JMH component benchmarks use prepared,
|
||||
reusable protocol state and forked JVMs. `h2load` exercises the real cleartext server on loopback;
|
||||
Flash and nghttpd run on the same host in alternating order. Results are snapshots, not promises
|
||||
for different hardware.
|
||||
|
||||
No "unmatched throughput" claim is supported. nghttpd is normally faster in this matrix; Flash's
|
||||
numbers include framework routing, request-model assembly and handler dispatch that the static
|
||||
reference server does not.
|
||||
|
||||
## Component results
|
||||
|
||||
The CI-controlled allocation and percentile numbers are in `BASELINES.md`. Additional average
|
||||
time measurements from the same run were:
|
||||
|
||||
| Scenario | Result |
|
||||
|---|---:|
|
||||
| h2 responses across 1 live stream | 74.405 ns |
|
||||
| h2 responses across 8 live streams | 705.368 ns |
|
||||
| h2 responses across 64 live streams | 5,591.368 ns |
|
||||
| h2 responses across 256 live streams | 28,961.681 ns |
|
||||
| h2 POST lifecycle with 1 KiB DATA | 741.031 ns, 0.005 B/op |
|
||||
| 1 MiB streaming response | 78,681.815 ns |
|
||||
|
||||
The multiplexing benchmark reports one complete response-encoding pass across all live streams,
|
||||
not per-stream time. `Http2BodyBenchmark` separately covers the 1 KiB request-body shape and the
|
||||
1 MiB response shape. `FrameWriterBenchmark` retains the Phase 3 contention matrix and its
|
||||
per-write latency distribution.
|
||||
|
||||
## End-to-end h2load comparison
|
||||
|
||||
Each row uses at least 1,000 requests. Requested stream concurrency is capped first by Flash's
|
||||
advertised 64-stream setting and then to 4,096 aggregate active streams so the 1,000-connection
|
||||
rows remain bounded. Both requested and effective values are shown.
|
||||
|
||||
| Connections | Requested/effective streams | Flash req/s | nghttpd req/s |
|
||||
|---:|---:|---:|---:|
|
||||
| 1 | 1 / 1 | 2,136.18 | 12,786.42 |
|
||||
| 1 | 10 / 10 | 18,396.56 | 83,521.26 |
|
||||
| 1 | 100 / 64 | 17,039.55 | 66,746.76 |
|
||||
| 10 | 1 / 1 | 11,247.08 | 37,838.66 |
|
||||
| 10 | 10 / 10 | 25,055.12 | 104,964.84 |
|
||||
| 10 | 100 / 64 | 3,878.28 | 67,303.81 |
|
||||
| 100 | 1 / 1 | 5,517.94 | 42,319.09 |
|
||||
| 100 | 10 / 10 | 1,818.52 | 26,732.25 |
|
||||
| 100 | 100 / 40 | 7,042.85 | 136,585.90 |
|
||||
| 1,000 | 1 / 1 | 1,393.17 | 3,877.62 |
|
||||
| 1,000 | 10 / 4 | 10,374.83 | 40,976.05 |
|
||||
| 1,000 | 100 / 4 | 49,622.10 | 85,344.40 |
|
||||
|
||||
The matrix found a correctness issue before it produced these final numbers: closed streams still
|
||||
occupied live admission slots while their final write callback was pending. The bounded detach
|
||||
fix is recorded as EX-57 and covered by regression tests.
|
||||
|
||||
## Tuning decisions
|
||||
|
||||
| Knob | Measurement | Decision |
|
||||
|---|---|---|
|
||||
| 16 KiB / 64 KiB / 1 MiB response frame | 1 MiB stream: 104,071 / 97,996 / 98,769 ns in the non-Huffman sweep | Keep 16 KiB. The roughly 6% gain at 64 KiB does not justify 4x per-connection buffer exposure on this noisy host. |
|
||||
| 1 MiB initial receive window | 100 MiB Phase 11 transfer and the load matrix complete without flow stalls | Keep; it matches bounded receive capacity and changing it independently would not isolate a throughput claim. |
|
||||
| half-window WINDOW_UPDATE hysteresis | 1 MiB streaming and 100 MiB transfer complete with steady pooled reads | Keep; no per-frame update traffic and no demonstrated reason to weaken backpressure. |
|
||||
| 64 KiB inline body | 1 KiB inline materialization is one 1,040 B allocation; streaming steady state is ≈0 B/op | Keep the explicit one-array small-body tradeoff and stream larger bodies. |
|
||||
| 64 × 16 KiB DATA buffers | 1 MiB streaming is 78,682 ns with ≈0 B/op; h2load stays bounded | Keep; larger chunks did not produce a clear win beyond the frame-size sweep. |
|
||||
| `ScratchPool` bound | 64 objects per exposed CPU, capped at 4,096; full 1,000-connection matrix completes | Keep the capacity bound; it affects retained burst memory, not steady-state request instructions. |
|
||||
| word-at-a-time route compare | 14.289 ns versus 22.313 ns bytewise, 36.0% faster | Keep. |
|
||||
| SWAR header-end scan | 89.919 ns versus 128.460 ns scalar, 30.0% faster | Keep. |
|
||||
| `SlicePool` size 4 | Header/path/query view benchmarks remain allocation-free | Keep; size changes lifetime capacity, not lookup work, and four simultaneous borrowed views match the documented contract. |
|
||||
| runtime-value Huffman | representative response headers: 375.761 ns versus 180.129 ns at 16 KiB | Keep disabled by default; this header set is 109% slower to encode. |
|
||||
|
||||
The frame-size/Huffman factorial produced counterintuitive variation in the body-only rows, so it
|
||||
was not used to claim a Huffman body effect: Huffman only prepares headers. This is treated as
|
||||
host noise rather than reverse-engineered into a preferred result.
|
||||
|
||||
## Profiling
|
||||
|
||||
async-profiler 4.4 was run against the representative browser HPACK decode. The top CPU leaves
|
||||
were `Huffman.decode` (72.67%), `HpackHeaderBlock.accept` (7.00%), `HpackDecoder.decode` (5.00%),
|
||||
JVM byte-array copy (4.00%), `HpackHeaderBlock.copy` (4.00%), `HpackStaticTable.name` (2.00%),
|
||||
`PooledSlice.reset` (1.00%), `PooledSlice.array` (0.67%), JVM byte-arraycopy (0.67%), and
|
||||
`HpackDecoder.decodeString` (0.67%). Each belongs to decoding, bounded arena ownership, or the
|
||||
copy that makes header lifetime independent of dynamic-table eviction; none is incidental
|
||||
locking or logging.
|
||||
|
||||
The allocation profile produced no samples on the gated decode path. The realistic eight-writer
|
||||
lock profile produced no sampled contended locks; the writer benchmark measured 185.605 bursts/s,
|
||||
p50 1.2 µs, p99 5.3 µs and p999 41.6 µs. CPU, allocation and lock artifacts were generated under
|
||||
`/tmp/phase17-*` and are intentionally not committed.
|
||||
|
||||
CI runs the complete suite with `-Djdk.tracePinnedThreads=full`. The forked allocation and p99
|
||||
gates run only under the Maven `jmh` profile; the h2load comparison remains informational and
|
||||
conditional because cross-runner throughput is not a stable correctness gate.
|
||||
|
||||
The reconstructed Phase-0 HTTP/1 comparison is documented in `BASELINES.md`. Its confidence
|
||||
interval overlaps the Phase-17 result, while normalized allocation falls from 224.007 B/op to
|
||||
0.007 B/op.
|
||||
Reference in New Issue
Block a user