giong_http/lib.rs
1//! # giong-http
2//!
3//! A small, strict HTTP/1.1 server for the [giong] thread-per-core
4//! runtime.
5//!
6//! ```no_run
7//! use giong::net::TcpListener;
8//! use giong_http::{Request, Response, Server};
9//!
10//! async fn handler(req: Request) -> Response {
11//! match (req.method(), req.path()) {
12//! ("GET", "/health") => Response::text("ok"),
13//! ("POST", "/echo") => Response::new(200).body(req.body().to_vec()),
14//! _ => Response::new(404),
15//! }
16//! }
17//!
18//! fn main() -> std::io::Result<()> {
19//! giong::Builder::new()
20//! .shutdown_on_signals(true)
21//! .shutdown_grace(std::time::Duration::from_secs(10))
22//! .build()?
23//! .run(|_worker| async {
24//! // One listener per worker; the kernel spreads connections.
25//! let listener = TcpListener::bind("0.0.0.0:8080").expect("bind");
26//! Server::new().serve(listener, handler).await;
27//! })
28//! }
29//! ```
30//!
31//! ## What it does
32//!
33//! * HTTP/1.1 and HTTP/1.0, keep-alive, pipelining (responses to pipelined
34//! requests are sent in one write).
35//! * Request bodies with `Content-Length` or chunked encoding, fully received
36//! before the handler runs; `Expect: 100-continue`.
37//! * Limits on head and body size, timeouts for idle connections, slow
38//! requests and slow readers.
39//! * Graceful shutdown: requests in progress are answered, idle connections
40//! close.
41//! * Strict parsing. Requests that a proxy in front might read differently
42//! (two lengths, a length plus chunked encoding, whitespace before a colon,
43//! bare line feeds, folded headers) are rejected with `400`.
44//!
45//! ## What it does not do (yet)
46//!
47//! HTTP/2, streaming bodies, compression, routing.
48//!
49//! ## HTTPS
50//!
51//! With the `tls` feature, [`Server::serve_tls`] serves the same handlers over
52//! TLS, using the `giong-tls` crate (rustls).
53
54#![warn(missing_docs)]
55
56mod chunked;
57mod date;
58#[cfg(test)]
59mod fuzz_tests;
60mod parse;
61mod request;
62mod response;
63mod server;
64
65pub use request::Request;
66pub use response::{Body, Response};
67pub use server::{Server, Transport};