http-net 0.3.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.
• 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 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.3"

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

[dependencies]
http-net = { version = "0.3", 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, 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 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.
• Interim responses other than 100 Continue from the server (for example 103 Early Hints), sending Expect: 100-continue from the client, trailers exposed and sent, a cached Date, and total deadlines in the blocking server and client: v0.4.0. The server already answers Expect: 100-continue; the blocking adapter's timeouts apply to each connect, read, and write.
• Client pipelining, the allocation-free Tier-3 writer and stateless parsers, spans for zero-copy copy-out, and a standalone chunked decoder: v0.5.0. The server already serves pipelined requests in order. See the roadmap and the planned items in docs/API.md.
• 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.3.0 on Windows x86_64 (Rust stable, release profile), from cargo bench, measured back to back with a 0.2.0 build on the same machine (the largest consistent difference from 0.2.0 is about +2%, on the head and pipelined benchmarks; the rest are within run-to-run noise):

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.