Skip to content

feat(h2): compio H2 implementation - #775

Closed
johnnyshields wants to merge 12 commits into
compio-rs:masterfrom
johnnyshields:compio-h2-final-final
Closed

johnnyshields wants to merge 12 commits into
compio-rs:masterfrom
johnnyshields:compio-h2-final-final

Conversation

@johnnyshields

@johnnyshields johnnyshields commented Mar 17, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Add compio-h2, a native HTTP/2 client and server implementation for compio. The h2 crate (hyperium/h2) and compio-quic were the primary references for protocol behavior and API design, but this is 100% original, ground-up written code — no source was copied or derived from any existing implementation.

Benchmarks below--this is highly optimized and runs ~8x faster than tokio's hyperium/h2.

This is a precursor to releasing compio-grpc, which I also have WIP for. I will raise a PR for it after H2 is merged.

FYI this work depends upon #771 -- it will still run without it, but it will just be 3200x more slow.

How is it tested?

  • Confirmity: I've checked this against h2spec (see scripts/conformance) and also checked it against a number of other Go/Rust/Python sources such as CVE PoCs. Ultimately I ported everything to Rust tests cases (see tests/security.rs) and kept only h2spec, as it is the most thorough.
  • Load / Benchmarking: See benches/ as well as scripts/conformance/h2load.sh.
  • Fuzz Testing: See fuzz/ -- this actually caught a few real bugs especially in the Huffman table.
  • Memory: See scripts/memleak/soak.sh, also the Asan work here: feat(ci): add asan memory leak test and suppression list #772. I also have separate work for Miri mem checking which I'll contribute as a separate PR and do it across all crates.

Why a full new implementation?

I analyzed every existing Rust HTTP/2 implementation and found none with components we could use directly:

  • hyperium/h2 — The established Rust HTTP/2 implementation. Tightly coupled to tokio (tokio::io::AsyncRead/AsyncWrite, tokio_util::codec). Its frame parsing and HPACK modules are internal (pub(crate)) and cannot be used independently. compio's completion-based I/O model (buffer ownership transfers to the kernel) is fundamentally incompatible with the readiness-based model (poll + ReadBuf) used by tokio and h2.

  • h2-sans-io — A minimal, sans-I/O HTTP/2 frame codec targeting WASM and async-free environments. Covers basic frame parsing and flow control but does not provide stream state machines, connection management, or a full HPACK implementation.

  • fluke-hpack — A standalone HPACK crate forked from hpack-rs. Lacks Huffman encoding, never-indexed/sensitivity support, header list size enforcement, and two-phase table size updates. compio-h2's custom HPACK module provides all of these with O(1) FNV hash lookups and a bytes::Bytes zero-copy pipeline.

  • loona (formerly fluke) — A full HTTP/1+2 implementation built on io_uring with a custom buffer management layer. The most mature completion-based HTTP/2 implementation in Rust but is tightly coupled to its own I/O framework.

What's included

  • Full HTTP/2 frame codec: DATA, HEADERS, CONTINUATION, SETTINGS, PING, GOAWAY, RST_STREAM, PRIORITY, WINDOW_UPDATE with RFC 9113 stream-ID validation
  • Unknown frame types silently ignored per RFC 9113 §4.1
  • HEADERS/CONTINUATION splitting on write and assembly on read with flood protection
  • HPACK header compression (RFC 7541) with compile-time Huffman decode table via build.rs
  • HPACK encoder with O(1) FNV hash-based dynamic table lookup, two-phase size updates, skip indexing for volatile headers
  • HPACK decoder with 5-byte integer continuation limit, table size validation against SETTINGS, header list size enforcement
  • Build.rs-generated static table lookup using length-bucketed match dispatch
  • Per-stream and connection-level flow control with configurable initial window sizes
  • Send-side flow control backpressure with pending data queue
  • Connection-level WINDOW_UPDATE sent when receive window half-consumed
  • Stream-level WINDOW_UPDATE with threshold-based batching (50% of initial window) to reduce write stalls
  • WINDOW_UPDATE piggyback: encoded after pending data sends for TCP write batching
  • INITIAL_WINDOW_SIZE delta applied to all open streams on SETTINGS change
  • MAX_FRAME_SIZE and MAX_CONCURRENT_STREAMS enforcement (REFUSED_STREAM on limit)
  • flow_controlled_len tracking for RFC 7540 §6.9.1 padding compliance
  • Direct state machine access architecture (like compio-quic) — no channels, Rc<RefCell<ConnShared>> for thread-per-core
  • ClientBuilder and ServerBuilder with fluent API for all HTTP/2 settings
  • Client SendRequest handle with send_request(), ready(), and shutdown()
  • Client ResponseFuture for awaiting response headers
  • Server ServerConnection with accept(), shutdown(), and abrupt_shutdown()
  • SendStream with data sending, trailer support, capacity reservation, and RST_STREAM
  • RecvStream with cancel-safe data() and trailers() methods
  • RecvFlowControl for application-managed receive window updates
  • Configurable PING/PONG keepalive with interval and timeout settings
  • Two-phase GOAWAY graceful shutdown with connection lifecycle tracking (Open/Closing/Closed)
  • RST_STREAM flood protection with configurable rate limits and GOAWAY(EnhanceYourCalm)
  • Max send buffer size limit (default 400 KiB) to prevent unbounded memory growth
  • Settings state machine (Synced/WaitingAck) with queued changes
  • Pseudo-header validation: ordering, required fields, CONNECT exemption, no duplicates
  • Structured H2Error type with reason(), is_io(), is_reset(), is_connection(), is_go_away(), is_remote(), is_library() helpers
  • FrameError and HpackError for granular error reporting
  • Write buffer batching with persistent Vec and read buffer reuse with persistent BytesMut
  • TLS support via tls feature gate with connect/accept wrappers, ALPN h2 validation, and native-tls/rustls sub-features forwarding to compio-tls
  • Cancel safety documentation on all public async methods
  • GOAWAY sent on truncated/invalid connection preface (RFC 9113 §3.4)
  • h2spec conformance: passes all 147/147 h2spec tests in strict mode

Benchmarks

Run on Linux (WSL2), AMD Ryzen, cargo bench -p compio-h2.

HPACK codec

Benchmark Time Throughput
hpack_encode/small (5 headers) 440 ns 112.7 MiB/s
hpack_encode/large (20 headers) 3.94 µs 103.5 MiB/s
hpack_encode/small_reuse (5 headers, warm table) 154 ns 322.2 MiB/s
hpack_decode/small (5 headers) 566 ns 87.6 MiB/s
hpack_decode/large (20 headers) 5.32 µs 76.7 MiB/s
hpack_decode/small_reuse (5 headers, warm table) 658 ns 75.3 MiB/s

Huffman codec

Benchmark Time Throughput
huffman/encode/short (15 bytes) 27.8 ns 515.3 MiB/s
huffman/encode/long (84 bytes) 140 ns 598.3 MiB/s
huffman/decode/short (12 bytes) 51.9 ns 220.6 MiB/s
huffman/decode/long (60 bytes) 328 ns 183.3 MiB/s

Frame codec

Benchmark Time Throughput
frame_header/encode (9 bytes) 1.31 ns —
frame_header/decode (9 bytes) 796 ps —
frame/encode/DATA 1KB 48.4 ns 19.7 GiB/s
frame/decode/DATA 1KB 30.5 ns 31.6 GiB/s
frame/encode/SETTINGS 12.6 ns 683.3 MiB/s
frame/decode/SETTINGS 10.4 ns 827.9 MiB/s
frame/encode/HEADERS (HPACK, 60 bytes) 12.9 ns 4.41 GiB/s
frame/decode/HEADERS (HPACK, 60 bytes) 47.5 ns 1.20 GiB/s

RPC latency (compio-h2 vs tokio h2 crate)

Both sides configured with 1MB initial connection and stream windows. h2 crate uses multi-threaded tokio.

After zerocopy threshold fix: #771

Benchmark compio-h2 h2 crate Speedup
Handshake 74 µs 90 µs 1.2x
Request/response 100B 14.8 µs (12.9 MiB/s) 128 µs (1.5 MiB/s) 8.7x
Request/response 1KB 14.7 µs (133 MiB/s) 126 µs (15.5 MiB/s) 8.6x
Request/response 64KB 27 µs (4.5 GiB/s) 182 µs (686 MiB/s) 6.7x

compio-h2 achieves 6–9x lower latency than the h2 crate across all payload sizes, driven by the direct state machine access architecture (no channel overhead) and completion-based I/O.

Before zerocopy threshold fix: #771

io_uring send_zerocopy requires an extra CQE for buffer-release notification. For small writes, this triggered a ~40ms TCP delayed-ACK stall. The fix adds a ZEROCOPY_THRESHOLD (8KB) in compio-net — writes below this size use regular send instead.

*h2 crate numbers are different b/c I ran on a different machine

Benchmark compio-h2 h2 crate
Handshake 71.3 µs 63.1 µs
Request/response 100B 25.4 µs 68.5 µs
Request/response 1KB 105.3 µs 71.6 µs
Request/response 64KB 88.6 ms 101.1 µs

The 64KB result (88.6ms vs 27µs) shows the dramatic impact of the zerocopy stall — a 3,200x improvement after the fix.

@Berrysoft

Copy link
Copy Markdown
Member

Wow, that's a huge PR.

First of all, I would like to kindly, politely, and ask you with no offense: Is this work done by yourself manually, or partially/totally done with the help of LLM? Don't get me wrong - everyone uses copilot-like tools. Just want to make sure how did this huge work complete.

And you're partially right on the comments of h2. Yes it is poll-based, and hyper doesn't want to make tokio optional. However, hyper is runtime-agnostic. Our project cyper works well with it. That's why we have our own h3 implementation but no h2. I'm sure it will gain performance if we could rewrite the whole HTTP stack with compio, but it is too complex.

My basic attitude: if this project is not vibed, we welcome you join our organization, and maintain it separately (that is, opening a new repo in compio-rs, and work independently); if this project is vibed, you can still maintain and even publish it yourself, but be better with your own identifier on the prefix or suffix of the name. This PR is too large to review, I'm afraid.

The final decision will be given after a discussion with all of our maintainers. The above is my own opinion.

@johnnyshields
johnnyshields force-pushed the compio-h2-final-final branch from eacc973 to c449fe2 Compare March 17, 2026 09:17
@johnnyshields

Copy link
Copy Markdown
Contributor Author

@Berrysoft I did this with the help of Claude Code (Opus 4.6), but no, this project was not willy-nilly "one-shot vibed". You can read the code for yourself, this was several weeks of careful optimization, bench-marking, and fuzzing, conformance with 146 public specs, CVEs (plus ~100 others I didn't commit) and ~300+ unit tests. In the process I identified #771. It was 300+ commits including AI-assisted hardening passes after each one.

AI assisted coding is clearly the future. Of course there are anti-patterns and "junk" ways of using AI, but there is also a way we can use it to produce high-quality, high-performance code. I believe this PR represents the latter, but please judge for yourself.

I have GRPC mostly ready as well.

@johnnyshields

johnnyshields commented Mar 17, 2026 •

Copy link
Copy Markdown
Contributor Author

Also, I should introduce myself properly. I am the CTO/Founder of TableCheck (~300 person company) based in Tokyo, Japan. I've been a coder for 20+ years, my first professional job was in algorithmic trading where we used C++, but I've built my own company mainly on Ruby. I'm now considering what high-throughput architectures can be used for new projects and found Compio in the process. I've also been working on a high-perf webserver (https://github.com/johnnyshields/mahalo) and a bunch of other things.

@johnnyshields
johnnyshields force-pushed the compio-h2-final-final branch from 3f3cf1e to 5e3cd93 Compare March 17, 2026 13:44
@Berrysoft

Copy link
Copy Markdown
Member

Hello, @johnnyshields . Sorry for this late reply, and unfortunately, the maintainers of compio would not like this PR to be accepted into the project.

  • This reimplementation of h2 is large, and will be unmaintainable for us to address bugs and CVEs. We are an unprofitable organization, and will reconsider our decision if TableCheck would like to give us full sponsor.
  • This project is complete enough to be an independent one. If you want to publish it yourself, we strongly suggest you add your own identifier to the name, e.g., the company name "TableCheck".
  • The reason that we implement compio-quic (with h3 support) and compio-ws is because they are just async wrappers around other functional crates. They don't reimplement all stacks so that we are able to maintain.

Anyway we thank your contribution, and will continue consider your suggestions on the performance of compio-net. We will continue our discussion on send_zerocopy.

@johnnyshields

Copy link
Copy Markdown
Contributor Author

OK, it's no problem! I'll release it independently, as well as GRPC which will use it as a dependency.

I did this work in my free time, not as part of my company, and it wouldn't make sense for TableCheck to sponsor Compio at this time. (But maybe in the future if we start actually using Compio in our stack!)

If you change your mind in the future, please let me know! I'm happy to contribute this at any time.

@johnnyshields
johnnyshields force-pushed the compio-h2-final-final branch from f89944f to 0866e61 Compare March 17, 2026 16:05
@johnnyshields

johnnyshields commented Mar 17, 2026 •

Copy link
Copy Markdown
Contributor Author

@Berrysoft FYI I think this test run has surfaced a Windows ARM test hang in compio-net--it wouldn't be due to these changes. Raised here: #776

@johnnyshields
johnnyshields force-pushed the compio-h2-final-final branch from e7cc941 to b02ddc4 Compare March 18, 2026 13:30
@George-Miao

Copy link
Copy Markdown
Member

We do appreciate all of your effort and interest in the project, and would love to work with you in future (I'm impressed by #771's results). However, as @Berrysoft explained, this PR is too large to merge into main compio repo. I'll close this for now, feel free to reply here or open an issue should you encounter any other problems.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants