In this tutorial we will look at Rust h2 with some simple examples.

What is h2?

It is a HTTP 2.0 client & server implementation for Rust.

It is a Tokio aware, HTTP/2.0 client & server implementation for Rust.

Here are its features:

  • Client and server HTTP/2.0 implementation.
  • Implements the full HTTP/2.0 specification.
  • Passes h2spec.
  • Focus on performance and correctness.
  • Built on Tokio.

This crate is intended to only be an implementation of the HTTP/2.0 specification. It does not handle:

  • Managing TCP connections
  • HTTP 1.0 upgrade
  • TLS
  • Any feature not described by the HTTP/2.0 specification.

Step 1: Install it

To use h2, first add this to your Cargo.toml:

[dependencies]
h2 = "0.3"

Next, add this to your crate:

extern crate h2;

use h2::server::Connection;

fn main() {
    // ...
}

Examples

Here are full examples:

akamai.rs

use h2::client;
use http::{Method, Request};
use tokio::net::TcpStream;
use tokio_rustls::TlsConnector;

use rustls::Session;
use webpki::DNSNameRef;

use std::error::Error;
use std::net::ToSocketAddrs;

const ALPN_H2: &str = "h2";

#[tokio::main]
pub async fn main() -> Result<(), Box<dyn Error>> {
    let _ = env_logger::try_init();

    let tls_client_config = std::sync::Arc::new({
        let mut c = rustls::ClientConfig::new();
        c.root_store
            .add_server_trust_anchors(&webpki_roots::TLS_SERVER_ROOTS);
        c.alpn_protocols.push(ALPN_H2.as_bytes().to_owned());
        c
    });

    // Sync DNS resolution.
    let addr = "http2.akamai.com:443"
        .to_socket_addrs()
        .unwrap()
        .next()
        .unwrap();

    println!("ADDR: {:?}", addr);

    let tcp = TcpStream::connect(&addr).await?;
    let dns_name = DNSNameRef::try_from_ascii_str("http2.akamai.com").unwrap();
    let connector = TlsConnector::from(tls_client_config);
    let res = connector.connect(dns_name, tcp).await;
    let tls = res.unwrap();
    {
        let (_, session) = tls.get_ref();
        let negotiated_protocol = session.get_alpn_protocol();
        assert_eq!(
            Some(ALPN_H2.as_bytes()),
            negotiated_protocol.as_ref().map(|x| &**x)
        );
    }

    println!("Starting client handshake");
    let (mut client, h2) = client::handshake(tls).await?;

    println!("building request");
    let request = Request::builder()
        .method(Method::GET)
        .uri("https://http2.akamai.com/")
        .body(())
        .unwrap();

    println!("sending request");
    let (response, other) = client.send_request(request, true).unwrap();

    tokio::spawn(async move {
        if let Err(e) = h2.await {
            println!("GOT ERR={:?}", e);
        }
    });

    println!("waiting on response : {:?}", other);
    let (_, mut body) = response.await?.into_parts();
    println!("processing body");
    while let Some(chunk) = body.data().await {
        println!("RX: {:?}", chunk?);
    }
    Ok(())
}

client.rs

use h2::client;
use http::{HeaderMap, Request};

use std::error::Error;

use tokio::net::TcpStream;

#[tokio::main]
pub async fn main() -> Result<(), Box<dyn Error>> {
    let _ = env_logger::try_init();

    let tcp = TcpStream::connect("127.0.0.1:5928").await?;
    let (mut client, h2) = client::handshake(tcp).await?;

    println!("sending request");

    let request = Request::builder()
        .uri("https://http2.akamai.com/")
        .body(())
        .unwrap();

    let mut trailers = HeaderMap::new();
    trailers.insert("zomg", "hello".parse().unwrap());

    let (response, mut stream) = client.send_request(request, false).unwrap();

    // send trailers
    stream.send_trailers(trailers).unwrap();

    // Spawn a task to run the conn...
    tokio::spawn(async move {
        if let Err(e) = h2.await {
            println!("GOT ERR={:?}", e);
        }
    });

    let response = response.await?;
    println!("GOT RESPONSE: {:?}", response);

    // Get the body
    let mut body = response.into_body();

    while let Some(chunk) = body.data().await {
        println!("GOT CHUNK = {:?}", chunk?);
    }

    if let Some(trailers) = body.trailers().await? {
        println!("GOT TRAILERS: {:?}", trailers);
    }

    Ok(())
}

server.rs

use std::error::Error;

use bytes::Bytes;
use h2::server::{self, SendResponse};
use h2::RecvStream;
use http::Request;
use tokio::net::{TcpListener, TcpStream};

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error + Send + Sync>> {
    let _ = env_logger::try_init();

    let listener = TcpListener::bind("127.0.0.1:5928").await?;

    println!("listening on {:?}", listener.local_addr());

    loop {
        if let Ok((socket, _peer_addr)) = listener.accept().await {
            tokio::spawn(async move {
                if let Err(e) = serve(socket).await {
                    println!("  -> err={:?}", e);
                }
            });
        }
    }
}

async fn serve(socket: TcpStream) -> Result<(), Box<dyn Error + Send + Sync>> {
    let mut connection = server::handshake(socket).await?;
    println!("H2 connection bound");

    while let Some(result) = connection.accept().await {
        let (request, respond) = result?;
        tokio::spawn(async move {
            if let Err(e) = handle_request(request, respond).await {
                println!("error while handling request: {}", e);
            }
        });
    }

    println!("~~~~~~~~~~~ H2 connection CLOSE !!!!!! ~~~~~~~~~~~");
    Ok(())
}

async fn handle_request(
    mut request: Request<RecvStream>,
    mut respond: SendResponse<Bytes>,
) -> Result<(), Box<dyn Error + Send + Sync>> {
    println!("GOT request: {:?}", request);

    let body = request.body_mut();
    while let Some(data) = body.data().await {
        let data = data?;
        println!("<<<< recv {:?}", data);
        let _ = body.flow_control().release_capacity(data.len());
    }

    let response = http::Response::new(());
    let mut send = respond.send_response(response, false)?;
    println!(">>>> send");
    send.send_data(Bytes::from_static(b"hello "), false)?;
    send.send_data(Bytes::from_static(b"world\n"), true)?;

    Ok(())
}

Reference

Read more here;

Categorized in: