http-net 0.5.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.
• 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, all allocation-free: 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.5"

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

[dependencies]
http-net = { version = "0.5", 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. 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/

What is not here yet

• TLS: plain http:// only.
• respond_head_only (one vectored write for head and body) and the optimisation pass with published comparisons: v0.6.0. 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, and a Transfer-Encoding other than chunked is refused with 501.

Performance

Criterion medians for 0.5.0 in WSL Ubuntu on a Windows x86_64 machine (Rust stable, release profile), from cargo bench pinned to one core, run alternately with a 0.4.0 build so machine load falls on both. Every 0.5 difference from 0.4 is within run-to-run noise. The machine had other load, so absolute numbers are on the slow side:

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.