7 releases
0.0.6 | Jul 1, 2024 |
---|---|
0.0.5 | May 20, 2024 |
0.0.4 | Jan 24, 2024 |
0.0.3 | Oct 23, 2023 |
0.0.0 | Mar 6, 2019 |
#8 in HTTP client
52,684 downloads per month
Used in 49 crates
(24 directly)
635KB
14K
SLoC
h3
An async HTTP/3 implementation.
This crate provides an HTTP/3 implementation that is generic over a provided QUIC transport. This allows the project to focus on just HTTP/3, while letting users pick their QUIC implementation based on their specific needs. It includes client and server APIs. Check the original design for more details.
Status
The h3
crate is still very experimental. While the client and servers do work, there may still be bugs. And the API could change as we continue to explore. That said, we eagerly welcome contributions, trying it out in test environments, and using at your own risk.
The eventual goal is to use h3
as an internal dependency of hyper.
Duvet
This create uses the duvet crate to check compliance of the spec.
The generated report displays the current status of the requirements of the spec.
Get more information about this tool in the contributing document.
Features
- HTTP/3 client and server implementation
- Async only API
- QUIC transport abstraction via traits in the
quic
module - Runtime independent (h3 does not spawn tasks and works with any runtime)
- Supported QUIC implementations to date are Quinn (h3-quinn) and s2n-quic (s2n-quic-h3)
Overview
- h3 HTTP/3 implementation
- h3-quinn QUIC transport implementation based on Quinn
Getting Started
The examples directory can help get started in two ways:
- There are ready-to-use
client
andserver
binaries to interact with other HTTP/3 peers. Check the README in that directory. - The source code of those examples can help teach how to use
h3
as either a client or a server.
Server
let (endpoint, mut incoming) = h3_quinn::quinn::Endpoint::server(server_config, "[::]:443".parse()?)?;
while let Some((req, stream)) = h3_conn.accept().await? {
loop {
match h3_conn.accept().await {
Ok(Some((req, mut stream))) => {
let resp = http::Response::builder().status(Status::OK).body(())?;
stream.send_response(resp).await?;
stream.send_data(Bytes::new("It works!")).await?;
stream.finish().await?;
}
Ok(None) => {
break;
}
Err(err) => {
match err.get_error_level() {
ErrorLevel::ConnectionError => break,
ErrorLevel::StreamError => continue,
}
}
}
}
}
endpoint.wait_idle();
You can find a full server example in examples/server.rs
Client
let addr: SocketAddr = "[::1]:443".parse()?;
let quic = h3_quinn::Connection::new(client_endpoint.connect(addr, "server")?.await?);
let (mut driver, mut send_request) = h3::client::new(quinn_conn).await?;
let drive = async move {
future::poll_fn(|cx| driver.poll_close(cx)).await?;
Ok::<(), Box<dyn std::error::Error>>(())
};
let request = async move {
let req = http::Request::builder().uri(dest).body(())?;
let mut stream = send_request.send_request(req).await?;
stream.finish().await?;
let resp = stream.recv_response().await?;
while let Some(mut chunk) = stream.recv_data().await? {
let mut out = tokio::io::stdout();
out.write_all_buf(&mut chunk).await?;
out.flush().await?;
}
Ok::<_, Box<dyn std::error::Error>>(())
};
let (req_res, drive_res) = tokio::join!(request, drive);
req_res?;
drive_res?;
client_endpoint.wait_idle().await;
You can find a full client example in examples/client.rs
QUIC Generic
As mentioned, the goal of this library is to be generic over a QUIC implementation. To that effect, integrations with QUIC libraries exist:
h3-quinn
: in this same repository.s2n-quic-h3
Interoperability
This crate as well as the quic implementations are tested (quinn, s2n-quic) for interoperability and performance in the quic-interop-runner. You can see the results at (https://interop.seemann.io/).
License
h3 is provided under the MIT license. See LICENSE.
Dependencies
~3–9MB
~75K SLoC