h11r

A fast, typed Sans-I/O HTTP/1.1 engine with a Rust core and Python API.

h11r is a low-level HTTP/1.1 protocol engine with a transport-independent Rust core and a typed Python API. Applications own their network I/O: send methods produce wire bytes, while received peer bytes become immutable Python events. The library enforces message framing, connection state, and protocol errors while your code keeps control of transport, runtime, and application policy.

Use it to build HTTP/1.1 clients, servers, proxies, protocol adapters, or test tools. It is not a ready-made HTTP client that opens connections and sends requests for you.

h11r is currently alpha software. Its public API may change during alpha development.

Why h11r

• Low protocol-layer overhead. The checked-in benchmarks show higher throughput than h11 across five equivalent HTTP/1.1 workloads. See the results.
• A Python-native, typed API. Work with immutable event objects, Python exceptions, and precise type information in editors and type checkers.
• Your transport and runtime. The library does not choose sockets, TLS, concurrency, cancellation, or back-pressure policy.
• More control when you need it. Start with ordinary request and response bytes, then opt into streaming bodies, buffer-preserving writes, pipelining, or protocol handoff.

Quick Start

For Python, add h11r to a uv-managed project:

uv add h11r

Or install it with pip:

pip install h11r

For Rust, add the protocol core and use its docs.rs API:

cargo add h11r

Create a client-role connection, serialize one bodyless request, and parse a complete response:

import h11r

client = h11r.Connection(h11r.Role.CLIENT)
request_bytes = client.send_request(
    "GET",
    "/hello",
    [("Host", "example.test")],
)
request_bytes += client.end_of_message()

client.receive_data(b"HTTP/1.1 200 OK\r\nContent-Length: 17\r\n\r\nHello from h11r!\n")

status_code = None
response_body = bytearray()

while True:
    event = client.next_event()

    match event:
        case h11r.Response(status_code=code):
            status_code = code
        case h11r.Data(data=chunk):
            response_body.extend(chunk)
        case h11r.EndOfMessage():
            break

print(status_code, bytes(response_body))

Output:

200 b'Hello from h11r!\n'

In a real client, your transport writes request_bytes and supplies each read to receive_data(). The first tutorial keeps the same client-side flow and makes that boundary visible before adding a socket.

Learn and Integrate

• Start with the first client tutorial, which serializes a request and parses a simulated response.
• Continue with the client/server round trip to move bytes through a real local stream and reuse the connection.
• Read the protocol model before connecting h11r to your own transport adapter.
• Use advanced patterns only when you need streaming, buffer-preserving writes, pipelining, or protocol handoff.

Use the runnable examples when you need a specific integration:

Performance

The chart compares protocol-layer throughput for h11r and h11 0.16.0 across five equivalent Python HTTP/1.1 workloads that reuse their connections. Each workload uses public APIs and includes protocol state transitions. It does not include socket, TLS, or asynchronous runtime overhead. Higher is faster.

The results were produced by the pyperf benchmark. The raw pyperf result used to render the chart is included for reproduction and inspection. The measurement environment is recorded in the chart. Results will vary with hardware and Python version.

Scope and compatibility

Each Connection maintains one endpoint's view of an HTTP/1.1 connection. Higher-level clients, servers, proxies, and test tools decide how to schedule I/O and apply application policy.

It supports client and server roles, HTTP/1.0 peers, Content-Length and chunked framing, keep-alive cycles, informational responses, trailers, and protocol handoff after Upgrade. Header and trailer section byte size and field count have independent limits; application body limits remain the caller's responsibility. Local API misuse is reported separately from remote protocol errors.

The Python package supports GIL-enabled CPython 3.11 through 3.14 and free-threaded CPython 3.14t. CI also exercises CPython 3.15 and 3.15t while they are prereleases. Independent Connection instances may run in parallel. Operations on one connection still have protocol order and must be serialized by its caller.

Relationship to h11

h11r is an independent Sans-I/O HTTP/1.1 protocol engine with a Rust core and a typed Python API. It performs no network I/O and does not depend on the Python h11 package at runtime. h11r and h11 occupy the same protocol-engine layer, but their public APIs differ, so switching between them requires adapting application integration code.

The Rust core uses httparse for request and response heads and trailer fields. h11r implements framing, buffering and resource limits, wire serialization, and its public Rust and Python APIs.

Interoperability tests verify representative h11r-client/h11-server and h11-client/h11r-server exchanges at the HTTP wire boundary. They provide evidence for those exchanges, not an API-compatibility or exhaustive wire-compatibility guarantee. h11 remains a mature pure-Python library with its own established API and ecosystem.

Contributing

See CONTRIBUTING.md for development and release guidance.

License

MIT