Getting Started with a Server

Let’s start by making a “Hello, World!” server, and expand from there.

First, we need to declare our dependencies, let’s add the following to our Cargo.toml:

[dependencies]
hyper = { version = "1", features = ["full"] }
tokio = { version = "1", features = ["full"] }
http-body-util = "0.1"
hyper-util = { version = "0.1", features = ["full"] }

Next, we need to add some imports in our main.rs file:

# extern crate tokio;
# extern crate hyper;
# extern crate http_body_util;
# extern crate hyper_util;
use std::convert::Infallible;
use std::net::SocketAddr;

use http_body_util::Full;
use hyper::body::Bytes;
use hyper::server::conn::http1;
use hyper::service::service_fn;
use hyper::{Request, Response};
use hyper_util::rt::TokioIo;
use tokio::net::TcpListener;
# fn main() {}

Creating a Service

A Service lets us define how our server will respond to incoming requests. It represents an async function that takes a Request and returns a Future. When the processing of this future is complete, it will resolve to a Response or an error.

Hyper provides a utility for creating a Service from a function that should serve most use cases: service_fn. We will use this to create a service from our hello function below when we’re ready to start our server.

# extern crate hyper;
# extern crate http_body_util;
# use std::convert::Infallible;
# use http_body_util::Full;
# use hyper::body::Bytes;
# use hyper::{Request, Response};
# fn main() {}
async fn hello(_: Request<hyper::body::Incoming>) -> Result<Response<Full<Bytes>>, Infallible> {
    Ok(Response::new(Full::new(Bytes::from("Hello, World!"))))
}

Using this function as a service, we tell our server to respond to all requests with a default 200 OK status. The response Body will contain our friendly greeting as a single chunk of bytes, and the Content-Length header will be set automatically.

Starting the Server

Lastly, we need to hook up our hello service into a running Hyper server.

We’ll dive in to the specifics of some of these things in another guide.

# extern crate tokio;
# extern crate hyper;
# extern crate http_body_util;
# extern crate hyper_util;
# mod no_run {
# use std::convert::Infallible;
# use std::net::SocketAddr;
# 
# use http_body_util::Full;
# use hyper::body::Bytes;
# use hyper::server::conn::http1;
# use hyper::service::service_fn;
# use hyper::{Request, Response};
# use hyper_util::rt::TokioIo;
# use tokio::net::TcpListener;
# async fn hello(
#     _: Request<hyper::body::Incoming>,
# ) -> Result<Response<Full<Bytes>>, Infallible> {
#     Ok(Response::new(Full::new(Bytes::from("Hello World!"))))
# }
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    let addr = SocketAddr::from(([127, 0, 0, 1], 3000));

    // We create a TcpListener and bind it to 127.0.0.1:3000
    let listener = TcpListener::bind(addr).await?;

    // We start a loop to continuously accept incoming connections
    loop {
        let (stream, _) = listener.accept().await?;

        // Use an adapter to access something implementing `tokio::io` traits as if they implement
        // `hyper::rt` IO traits.
        let io = TokioIo::new(stream);

        // Spawn a tokio task to serve multiple connections concurrently
        tokio::task::spawn(async move {
            // Finally, we bind the incoming connection to our `hello` service
            if let Err(err) = http1::Builder::new()
                // `service_fn` converts our function in a `Service`
                .serve_connection(io, service_fn(hello))
                .await
            {
                eprintln!("Error serving connection: {:?}", err);
            }
        });
    }
}
# }
# fn main() {}

To see all the snippets put together, check out the full example!

Also, if service_fn doesn’t meet your requirements and you’d like to implement Service yourself, see this example.

HTTP/2

This example uses the http1 module to create a server that speaks HTTP/1. In case you want to use HTTP/2, you can use the http2 module with a few changes to the http1 server. The http2 builder requires an executor to run. Executor should implement the hyper::rt::Executor trait.

To implement the Executor, check out the runtime example. To see the full example with HTTP/2, check out the full example!