This is a tutorial about Hyper, the popular HTTP library for rust and it's examples.
What is hyper?
It is A fast HTTP implementation for Rust.
Here are it's main features:
- HTTP/1 and HTTP/2
- Asynchronous design
- Leading in performance
- Tested and correct
- Extensive production use
- Client and Server APIs
Installing Hyper
In your Cargo.toml declare hyper as a dependency:
[dependencies]
hyper = "0.14"Hyper Examples
Example 1: Hello Word Server
This example will explore how to create a simple hello world server with hyper.
Step 1: Add Dependencies
Start by installing hyper, add the following in your Cargo.toml:
[dependencies]
hyper = { version = "0.14", features = ["full"] }
tokio = { version = "1", features = ["full"] }Step 2: Add Imports
In your main.rs add imports as follows:
use std::convert::Infallible;
use std::net::SocketAddr;
use hyper::{Body, Request, Response, Server};
use hyper::service::{make_service_fn, service_fn};Step 3: Create a Service
Then you need to create a Service. The role of a Service is to respond to incoming requests:
async fn hello_world(_req: Request<Body>) -> Result<Response<Body>, Infallible> {
Ok(Response::new("Hello, World".into()))
}Step 4: Start the Server
You then need to start the server:
#[tokio::main]
async fn main() {
// We'll bind to 127.0.0.1:3000
let addr = SocketAddr::from(([127, 0, 0, 1], 3000));
// A Service is needed for every connection, so this
// creates one from our hello_world function.
let make_svc = make_service_fn(|_conn| async {
// service_fn converts our function into a Service
Ok::<_, Infallible>(service_fn(hello_world))
});
let server = Server::bind(&addr).serve(make_svc);
// Run this server for... forever!
if let Err(e) = server.await {
eprintln!("server error: {}", e);
}
}Full Example
Here is the full example code:
hello.rs
#![deny(warnings)]
use std::convert::Infallible;
use hyper::service::{make_service_fn, service_fn};
use hyper::{Body, Request, Response, Server};
async fn hello(_: Request<Body>) -> Result<Response<Body>, Infallible> {
Ok(Response::new(Body::from("Hello World!")))
}
#[tokio::main]
pub async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
pretty_env_logger::init();
// For every connection, we must make a Service to handle all
// incoming HTTP requests on said connection.
let make_svc = make_service_fn(|_conn| {
// This is the Service that will handle the connection.
// service_fn is a helper to convert a function that
// returns a Response into a Service.
async { Ok::<_, Infallible>(service_fn(hello)) }
});
let addr = ([127, 0, 0, 1], 3000).into();
let server = Server::bind(&addr).serve(make_svc);
println!("Listening on http://{}", addr);
server.await?;
Ok(())
}
Example 2: Echo Server
Our echo server will listen for incoming connections and send back the request body as the response body on POST requests.
Step 1: Add Dependencies
In your Cargo.toml add dependencies as follows including the futures. futures is a crate that allows easily do asynchronouse programming.
[dependencies]
hyper = { version = "0.14", features = ["full"] }
tokio = { version = "1", features = ["full"] }
futures = "0.3"Step 2: Write Code
Next add imports as follows:
use hyper::{Method, StatusCode};Then we will return the Future of a Response:
let mut response = Response::new(Body::empty());
match (req.method(), req.uri().path()) {
(&Method::GET, "/") => {
*response.body_mut() = Body::from("Try POSTing data to /echo");
},
(&Method::POST, "/echo") => {
// we'll be back
},
_ => {
*response.status_mut() = StatusCode::NOT_FOUND;
},
};
Ok(response)
}Here is the full code:
echo.rs
#![deny(warnings)]
use futures_util::TryStreamExt;
use hyper::service::{make_service_fn, service_fn};
use hyper::{Body, Method, Request, Response, Server, StatusCode};
/// This is our service handler. It receives a Request, routes on its
/// path, and returns a Future of a Response.
async fn echo(req: Request<Body>) -> Result<Response<Body>, hyper::Error> {
match (req.method(), req.uri().path()) {
// Serve some instructions at /
(&Method::GET, "/") => Ok(Response::new(Body::from(
"Try POSTing data to /echo such as: curl localhost:3000/echo -XPOST -d 'hello world'",
))),
// Simply echo the body back to the client.
(&Method::POST, "/echo") => Ok(Response::new(req.into_body())),
// Convert to uppercase before sending back to client using a stream.
(&Method::POST, "/echo/uppercase") => {
let chunk_stream = req.into_body().map_ok(|chunk| {
chunk
.iter()
.map(|byte| byte.to_ascii_uppercase())
.collect::<Vec<u8>>()
});
Ok(Response::new(Body::wrap_stream(chunk_stream)))
}
// Reverse the entire body before sending back to the client.
//
// Since we don't know the end yet, we can't simply stream
// the chunks as they arrive as we did with the above uppercase endpoint.
// So here we do .await on the future, waiting on concatenating the full body,
// then afterwards the content can be reversed. Only then can we return a Response.
(&Method::POST, "/echo/reversed") => {
let whole_body = hyper::body::to_bytes(req.into_body()).await?;
let reversed_body = whole_body.iter().rev().cloned().collect::<Vec<u8>>();
Ok(Response::new(Body::from(reversed_body)))
}
// Return the 404 Not Found for other routes.
_ => {
let mut not_found = Response::default();
*not_found.status_mut() = StatusCode::NOT_FOUND;
Ok(not_found)
}
}
}
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
let addr = ([127, 0, 0, 1], 3000).into();
let service = make_service_fn(|_| async { Ok::<_, hyper::Error>(service_fn(echo)) });
let server = Server::bind(&addr).serve(service);
println!("Listening on http://{}", addr);
server.await?;
Ok(())
}
Example 3: HTTP GET Example
The first two examples were about creating a server. This time round we create a client. This client will make a HTTP GET request to a webserver to obtain some data.
Step 1: Add dependencies
First you need to declare dependencies in your Cargo.toml:
[dependencies]
hyper = { version = "0.14", features = ["full"] }
tokio = { version = "1", features = ["full"] }Step 2: Write Code
Here is the full code:
client.rs
#![deny(warnings)]
#![warn(rust_2018_idioms)]
use std::env;
use hyper::{body::HttpBody as _, Client};
use tokio::io::{self, AsyncWriteExt as _};
// A simple type alias so as to DRY.
type Result<T> = std::result::Result<T, Box<dyn std::error::Error + Send + Sync>>;
#[tokio::main]
async fn main() -> Result<()> {
pretty_env_logger::init();
// Some simple CLI args requirements...
let url = match env::args().nth(1) {
Some(url) => url,
None => {
println!("Usage: client <url>");
return Ok(());
}
};
// HTTPS requires picking a TLS implementation, so give a better
// warning if the user tries to request an 'https' URL.
let url = url.parse::<hyper::Uri>().unwrap();
if url.scheme_str() != Some("http") {
println!("This example only works with 'http' URLs.");
return Ok(());
}
fetch_url(url).await
}
async fn fetch_url(url: hyper::Uri) -> Result<()> {
let client = Client::new();
let mut res = client.get(url).await?;
println!("Response: {}", res.status());
println!("Headers: {:#?}\n", res.headers());
// Stream the body, writing each chunk to stdout as we get it
// (instead of buffering and printing at the end).
while let Some(next) = res.data().await {
let chunk = next?;
io::stdout().write_all(&chunk).await?;
}
println!("\n\nDone!");
Ok(())
}
Example 4: Fetch JSON from the Web
This example will explore how to fetch JSON from the web using Rust Hyper.
Step 1: Add dependencies
First you need to declare dependencies in your Cargo.toml:
[dependencies]
hyper = { version = "0.14", features = ["full"] }
tokio = { version = "1", features = ["full"] }Step 2: Write Code
Here is the full code:
client_json.rs
#![deny(warnings)]
#![warn(rust_2018_idioms)]
use hyper::body::Buf;
use hyper::Client;
use serde::Deserialize;
// A simple type alias so as to DRY.
type Result<T> = std::result::Result<T, Box<dyn std::error::Error + Send + Sync>>;
#[tokio::main]
async fn main() -> Result<()> {
let url = "http://jsonplaceholder.typicode.com/users".parse().unwrap();
let users = fetch_json(url).await?;
// print users
println!("users: {:#?}", users);
// print the sum of ids
let sum = users.iter().fold(0, |acc, user| acc + user.id);
println!("sum of ids: {}", sum);
Ok(())
}
async fn fetch_json(url: hyper::Uri) -> Result<Vec<User>> {
let client = Client::new();
// Fetch the url...
let res = client.get(url).await?;
// asynchronously aggregate the chunks of the body
let body = hyper::body::aggregate(res).await?;
// try to parse as json with serde_json
let users = serde_json::from_reader(body.reader())?;
Ok(users)
}
#[derive(Deserialize, Debug)]
struct User {
id: i32,
#[allow(unused)]
name: String,
}
Reference
Read more here.
