http-net 0.9.0

The model

• A ServerConn is the server side of one connection. Bytes go in with feed (or read_buf + commit); poll reports a ServerEvent: a request head, body runs, the end of the request, or what it needs next. respond writes a Response into your output buffer; respond_head_only writes just the head, so a large body goes out with it in one vectored write, uncopied.
• A ClientConn is the mirror image: send_request writes a Request, poll reports the response as **ClientEvent**s.
• RequestHead and ResponseHead are zero-copy views of a parsed head.
• Limits bounds every buffer; HttpError says exactly what was refused and which status to answer with, and Response::from_error builds that answer.
• Both connections carry trailers (reported on request, sent with end_body_with_trailers) and interim responses (send_informational for 103 Early Hints; reported to the client on request), and the client can send Expect: 100-continue and hold its body back. Progress, set_keep_alive, and requests_served give drivers what they need for deadlines and load shedding; DateCache formats Date once per second.
• Method and MethodSet classify methods (safe, idempotent, a bit set for routers and Allow); reason_phrase and the status constants cover the whole IANA status registry.
• The client pipelines idempotent requests up to a configured depth; both connections can be reset, pooled, and shrunk while idle, and the server can wipe consumed input so credentials do not linger.
• Tier 3 for gateways and proxies (the parsers, the decoder, the writer, and copying a head into reused buffers allocate nothing): spans and copied heads for passing a head to another thread, stateless head parsers, a standalone ChunkedDecoder, the Output writer with borrowed fields, forward_from with hop-by-hop removal, and HTTP/2 preface detection.
• The blocking module (feature std) drives both over std::net: a bounded thread-per-connection Server, a per-connection Connection, and get.

What it guarantees, and how each guarantee is checked:

Installation

[dependencies]
http-net = "0.9"

Without the standard library (the sans-IO core only):

[dependencies]
http-net = { version = "0.9", default-features = false }

Quick start

Serve a handler on localhost and fetch from it:

use http_net::{blocking, Response};

let server = blocking::Server::bind("127.0.0.1:0")?;
let addr = server.local_addr();
let stop = server.shutdown_handle();
let thread = std::thread::spawn(move || {
    server.serve(|req, _body| Response::text(200, &format!("you asked for {}", req.path())))
});

let resp = blocking::get(&format!("http://{addr}/hello"))?;
assert_eq!(resp.status(), 200);
assert_eq!(resp.text(), Some("you asked for /hello"));

stop.shutdown();
thread.join().unwrap()?;
# Ok::<(), Box<dyn std::error::Error>>(())

The server runs one thread per connection, at most 64 at once (the next is answered 503), with a 10 s read timeout and a 30 s deadline per request (first byte to end of body; a late request gets 408), answers Expect: 100-continue itself, and adds a date header to every response except that fixed 503. Requests that fail to parse are answered with the matching status (400, 413, 414, 431, 501, 505) and closed; the handler never sees them. A handler that returns a streamed or invalid response gets a 500 instead of a hung client.

The sans-IO core

The same kind of exchange with no socket at all:

use http_net::{Response, ServerConn, ServerEvent};

let mut conn = ServerConn::new();
let mut out = Vec::new();
let _ = conn.feed(b"POST /notes HTTP/1.1\r\nHost: localhost\r\nContent-Length: 5\r\n\r\nhello");
let mut body = Vec::new();
loop {
    match conn.poll()? {
        ServerEvent::Request(req) => assert_eq!(req.path(), "/notes"),
        ServerEvent::Body(chunk) => body.extend_from_slice(chunk),
        ServerEvent::RequestEnd => conn.respond(&Response::text(201, "saved"), &mut out)?,
        _ => break, // NeedInput: read more from the socket and feed it
    }
}
assert_eq!(body, b"hello");
assert!(out.starts_with(b"HTTP/1.1 201 Created\r\n"));
# Ok::<(), http_net::HttpError>(())

Handing a connection to WebSocket

use http_net::{Response, ServerConn, ServerEvent};

let mut conn = ServerConn::new();
let _ = conn.feed(b"GET /rpc HTTP/1.1\r\nHost: 127.0.0.1:8080\r\nConnection: Upgrade\r\nUpgrade: websocket\r\n\r\n\x81\x85");
let ServerEvent::Request(req) = conn.poll()? else { unreachable!() };
assert!(req.is_upgrade());
assert!(matches!(conn.poll()?, ServerEvent::RequestEnd));

let mut out = Vec::new();
let accept = "s3pPLMBiTxaQ9kYGzzhZRbK+xOo="; // computed by the WebSocket engine
conn.respond(&Response::switching_protocols("websocket").header("sec-websocket-accept", accept), &mut out)?;
assert!(matches!(conn.poll()?, ServerEvent::Upgraded));
assert_eq!(conn.remaining_input(), b"\x81\x85"); // the first bytes of the first frame
# Ok::<(), http_net::HttpError>(())

Limits

These are the budgets of LexerSketch Studio's localhost server. Change them with Limits. The blocking server adds time budgets in ServerConfig: 10 s per read, 30 s per request, 10 s per write, 60 s to write a whole response, at most 1 s of lingering close.

Examples

cargo run --example localhost   # serve, fetch, shut down
cargo run --example sans_io     # the core with no socket
cargo run --example early_hints # 103 Early Hints, server to client, in memory
cargo run --example trailers    # trailer fields both ways, in memory
cargo run --example pipelined_client # four requests in flight, answered in order
cargo run --example passport    # copy heads out and hand them to a worker thread
cargo run --example proxy_forward    # forward a request upstream without hop-by-hop fields
cargo run --example serve -- 127.0.0.1:8080
cargo run --example get -- http://127.0.0.1:8080/
cargo run --release --example soak -- 90s 4  # mixed workload for a set time, client threads

What is not here yet

• TLS: plain http:// only.
• 1.0.0 itself: fixes only in v0.9.x, then 1.0 after the audit in docs/STABILITY-1.0.md. See the roadmap.
• An async runtime or adapter: never; drive the sans-IO core from any loop.
• Content codings (gzip and others): a body is delivered as sent. A transfer coding before chunked is refused with 501 (UnsupportedTransferEncoding); a Transfer-Encoding that does not end in a single chunked is refused with 400 (InvalidTransferEncoding).

Performance

Criterion medians for 0.6.0 in WSL Ubuntu on a Windows x86_64 machine (AMD Ryzen 9 9950X3D, Rust stable, release profile), from cargo bench pinned to one core, run alternately with a 0.5.0 build so machine load falls on both. Method, Windows numbers, and every decision behind them: docs/PERFORMANCE.md. 0.7.0 and 0.8.0 were measured against their predecessors with no measurable difference (docs/release/v0.8.0.md), so these 0.6.0 numbers stand.

Against other libraries, on identical bytes (http-net-bench): a full server exchange takes ~250 ns against hyper's ~1.4 µs (3.4 to 5.5x faster), 100,000 pipelined requests 7.3 ms against hyper's 23.6 ms, and a client exchange 95 ns against hyper's 1.24 µs. Parsing a head alone is level with httparse (~177 ns against ~172 ns with httparse's SIMD) while also validating the Host value, the target, every value byte, and the framing rules, with no unsafe code.

Feature by feature against hyper, httparse, h11, llhttp, picohttpparser, and the http crate, each cell checked: docs/PARITY.md.

These are library-only numbers: no sockets are involved. Body events borrow the input buffer, so the 1 MiB cases measure one copy into the buffer plus framing.

Contributing

See dev/DIRECTIVES.md for engineering standards and the definition of done. Before a PR: cargo fmt --all, cargo clippy --all-targets --all-features -- -D warnings, and cargo test --all-features must be clean.