Struct Server 

pub struct Server<Addr: Address, A = DefaultAcceptor> { /* private fields */ }

HTTP server.

Implementations

impl<A: Address> Server<A>

pub fn bind(addr: A) -> Self

Create a server that will bind to provided address.

Examples found in repository

examples/timeouts.rs (line 24)

async fn main() {
    let app = Router::new().route("/", get(|| async { "Hello, world!" }));

    let addr = SocketAddr::from(([127, 0, 0, 1], 3000));

    let mut server = Server::bind(addr).first_request_timeout(Duration::from_secs(10));

    let mut http1 = server.http_builder().http1();
    http1.header_read_timeout(Duration::from_secs(10));

    let mut http2 = server.http_builder().http2();
    http2.keep_alive_interval(Duration::from_secs(30));
    http2.keep_alive_timeout(Duration::from_secs(10));

    println!("listening on {addr}");
    server.serve(app.into_make_service()).await.unwrap();
}

pub fn from_listener(listener: A::Listener) -> Self

Create a server from an existing AddrListener.

impl<A: Address, Acc> Server<A, Acc>

pub fn acceptor<Acceptor>(self, acceptor: Acceptor) -> Server<A, Acceptor>

Overwrite acceptor.

Examples found in repository

examples/async_sni.rs (line 41)

async fn main() {
    let app = Router::new().route("/", get(|| async { "Hello, world!" }));

    let acceptor = AsyncSniAcceptor::new(CertificateStore::example());
    let addr = SocketAddr::from(([127, 0, 0, 1], 3000));

    println!("listening on {addr}");
    println!("try: curl -k --resolve localhost:3000:127.0.0.1 https://localhost:3000/");
    println!("try: curl -k --resolve other.test:3000:127.0.0.1 https://other.test:3000/");

    axum_server::bind(addr)
        .acceptor(acceptor)
        .serve(app.into_make_service())
        .await
        .unwrap();
}

examples/acme.rs (line 68)

async fn main() {
    let domains = env::var("ACME_DOMAINS")
        .expect("set ACME_DOMAINS to a comma-separated list of domains")
        .split(',')
        .map(str::to_owned)
        .collect::<Vec<_>>();

    let cache = env::var("ACME_CACHE").unwrap_or_else(|_| "./acme-cache".to_owned());
    let port = env::var("ACME_PORT")
        .ok()
        .and_then(|port| port.parse().ok())
        .unwrap_or(443);
    let production = env::var("ACME_PRODUCTION").is_ok_and(|value| value == "1");

    let mut config = AcmeConfig::new(domains)
        .cache(DirCache::new(cache))
        .directory_lets_encrypt(production);

    if let Ok(contact) = env::var("ACME_CONTACT") {
        config = config.contact([format!("mailto:{contact}")]);
    }

    let mut state = config.state();
    let acceptor = Acceptor::new(&state);

    // Polling the state is what acquires and renews the certificates.
    tokio::spawn(async move {
        while let Some(event) = state.next().await {
            match event {
                Ok(event) => println!("acme: {event:?}"),
                Err(error) => eprintln!("acme error: {error:?}"),
            }
        }
    });

    let app = Router::new().route("/", get(|| async { "Hello, world!" }));
    let addr = SocketAddr::from(([0, 0, 0, 0], port));

    println!("listening on https://{addr}");
    if !production {
        println!("using the Let's Encrypt staging directory");
    }

    axum_server::bind(addr)
        .acceptor(acceptor)
        .serve(app.into_make_service())
        .await
        .unwrap();
}

pub fn map<Acceptor, F>(self, acceptor: F) -> Server<A, Acceptor>

where F: FnOnce(Acc) -> Acceptor,

Map acceptor.

pub fn get_ref(&self) -> &Acc

Returns a reference to the acceptor.

pub fn get_mut(&mut self) -> &mut Acc

Returns a mutable reference to the acceptor.

pub fn http_builder(&mut self) -> &mut Builder<TokioExecutor>

Returns a mutable reference to the Http builder.

Examples found in repository

examples/timeouts.rs (line 26)

async fn main() {
    let app = Router::new().route("/", get(|| async { "Hello, world!" }));

    let addr = SocketAddr::from(([127, 0, 0, 1], 3000));

    let mut server = Server::bind(addr).first_request_timeout(Duration::from_secs(10));

    let mut http1 = server.http_builder().http1();
    http1.header_read_timeout(Duration::from_secs(10));

    let mut http2 = server.http_builder().http2();
    http2.keep_alive_interval(Duration::from_secs(30));
    http2.keep_alive_timeout(Duration::from_secs(10));

    println!("listening on {addr}");
    server.serve(app.into_make_service()).await.unwrap();
}

pub fn http1_only(self) -> Self

Only accepts HTTP/1.

Note that HTTP/1 protocol upgrades (for example WebSockets) are not supported when this is used; the default protocol-detecting mode does support them.

pub fn http2_only(self) -> Self

Only accepts HTTP/2.

pub fn handle(self, handle: Handle<A>) -> Self

Provide a handle for additional utilities.

To share shutdown and connection counting between servers listening on different address types, build each server’s handle from one Control with Handle::with_control.

Examples found in repository

examples/shutdown.rs (line 24)

async fn main() {
    let app = Router::new().route("/", get(|| async { "Hello, world!" }));

    let handle = Handle::new();

    // Spawn a task to shutdown server.
    tokio::spawn(shutdown(handle.clone()));

    let addr = SocketAddr::from(([127, 0, 0, 1], 3000));
    println!("listening on {}", addr);
    axum_server::bind(addr)
        .handle(handle)
        .serve(app.into_make_service())
        .await
        .unwrap();

    println!("server is shut down");
}

examples/graceful_shutdown.rs (line 27)

async fn main() {
    let app = Router::new().route("/", get(|| async { "Hello, world!" }));

    let handle = Handle::new();

    // Spawn a task to gracefully shutdown server.
    tokio::spawn(graceful_shutdown(handle.clone()));

    let addr = SocketAddr::from(([127, 0, 0, 1], 3000));
    println!("listening on {}", addr);
    axum_server::bind(addr)
        .handle(handle)
        .serve(app.into_make_service())
        .await
        .unwrap();

    println!("server is shut down");
}

examples/multiple_listeners.rs (line 16)

async fn main() -> io::Result<()> {
    let app = Router::new().route("/", get(|| async { "Hello, world!" }));

    // One control handle drains every listener below.
    let control = Control::new();
    let mut servers = JoinSet::new();

    let tcp_handle = Handle::<SocketAddr>::with_control(control.clone());
    let tcp =
        axum_server::bind(SocketAddr::from(([127, 0, 0, 1], 3000))).handle(tcp_handle.clone());
    let tcp_service = app.clone().into_make_service();

    servers.spawn(async move { tcp.serve(tcp_service).await });

    #[cfg(unix)]
    let unix_handle = {
        use std::os::unix::net::SocketAddr;

        let path = std::env::temp_dir().join("axum-server-multiple-listeners.sock");
        let _ = std::fs::remove_file(&path);

        let handle = Handle::with_control(control.clone());
        let unix = axum_server::bind(SocketAddr::from_pathname(path)?).handle(handle.clone());
        let service = app.clone().into_make_service();

        servers.spawn(async move { unix.serve(service).await });

        handle
    };

    println!("tcp: http://{}/", tcp_handle.listening().await.unwrap());
    #[cfg(unix)]
    println!(
        "unix: {:?}",
        unix_handle
            .listening()
            .await
            .unwrap()
            .as_pathname()
            .unwrap()
    );

    let shutdown = control.clone();
    tokio::spawn(async move {
        let _ = tokio::signal::ctrl_c().await;
        shutdown.graceful_shutdown(Some(Duration::from_secs(10)));
    });

    // A failing listener stops the others instead of leaving them running.
    while let Some(result) = servers.join_next().await {
        match result {
            Ok(Ok(())) => {}
            Ok(Err(error)) => {
                eprintln!("server error: {error}");
                control.shutdown();
            }
            Err(error) => {
                eprintln!("server task failed: {error}");
                control.shutdown();
            }
        }
    }

    #[cfg(unix)]
    let _ = std::fs::remove_file(std::env::temp_dir().join("axum-server-multiple-listeners.sock"));

    Ok(())
}

pub fn first_request_timeout(self, timeout: impl Into<Option<Duration>>) -> Self

Set a timeout for the first request on a connection.

If the client does not send a complete first request within this duration, the connection is closed. This bounds the time a newly accepted connection can occupy resources before the HTTP protocol is determined, which is otherwise not covered by http_builder timeouts.

The timeout starts after the connection acceptor finishes. For a TLS server this means the TLS handshake is bounded by the acceptor’s own handshake timeout instead.

None disables the timeout. The default is None.

Examples found in repository

examples/timeouts.rs (line 24)

async fn main() {
    let app = Router::new().route("/", get(|| async { "Hello, world!" }));

    let addr = SocketAddr::from(([127, 0, 0, 1], 3000));

    let mut server = Server::bind(addr).first_request_timeout(Duration::from_secs(10));

    let mut http1 = server.http_builder().http1();
    http1.header_read_timeout(Duration::from_secs(10));

    let mut http2 = server.http_builder().http2();
    http2.keep_alive_interval(Duration::from_secs(30));
    http2.keep_alive_timeout(Duration::from_secs(10));

    println!("listening on {addr}");
    server.serve(app.into_make_service()).await.unwrap();
}

pub fn accept_error_handler<F>(self, handler: F) -> Self

where F: Fn(Option<&A>, &Error) + Send + Sync + 'static,

Set a handler called when accepting a connection fails.

The handler receives the remote address when it is known and the error that occurred. Accept errors do not stop the server; it backs off and keeps accepting.

The handler is called from the accept loop, so keep it cheap. Use it for logging or metrics rather than blocking work.

pub async fn serve<M>(self, make_service: M) -> Result<()>

where M: MakeService<A, Request<Incoming>>, A: Send + 'static, A::Stream: Send, Acc: Accept<A::Stream, M::Service> + Clone + Send + Sync + 'static, Acc::Stream: AsyncRead + AsyncWrite + Unpin + Send, Acc::Service: SendService<Request<Incoming>> + Send, Acc::Future: Send,

Serve provided MakeService.

To create MakeService easily, Shared from tower can be used.

Errors

An error will be returned when:

• Binding to an address fails.
• make_service returns an error when poll_ready is called. This never happens on axum make services.

Examples found in repository

examples/multiple_addresses.rs (line 22)

async fn start_server(addr: SocketAddr) {
    let app = Router::new().route("/", get(|| async { "Hello, world!" }));

    axum_server::bind(addr)
        .serve(app.into_make_service())
        .await
        .unwrap();
}

examples/remote_address.rs (line 16)

async fn main() {
    let app = Router::new()
        .route("/", get(handler))
        .into_make_service_with_connect_info::<SocketAddr>();

    let addr = SocketAddr::from(([127, 0, 0, 1], 3000));

    axum_server::bind(addr).serve(app).await.unwrap();
}

examples/http_and_https.rs (line 25)

async fn http_server() {
    let app = Router::new().route("/", get(http_handler));

    let addr = SocketAddr::from(([127, 0, 0, 1], 3000));
    println!("http listening on {}", addr);
    axum_server::bind(addr)
        .serve(app.into_make_service())
        .await
        .unwrap();
}

async fn http_handler(uri: Uri) -> Redirect {
    let uri = format!("https://127.0.0.1:3443{}", uri.path());

    Redirect::temporary(&uri)
}

async fn https_server() {
    let app = Router::new().route("/", get(|| async { "Hello, world!" }));

    let config = RustlsConfig::from_pem_file(
        "examples/self-signed-certs/cert.pem",
        "examples/self-signed-certs/key.pem",
    )
    .await
    .unwrap();

    let addr = SocketAddr::from(([127, 0, 0, 1], 3443));
    println!("https listening on {}", addr);
    axum_server::bind_rustls(addr, config)
        .serve(app.into_make_service())
        .await
        .unwrap();
}

examples/hello_world.rs (line 15)

async fn main() {
    let app = Router::new().route("/", get(|| async { "Hello, world!" }));

    let addr = SocketAddr::from(([127, 0, 0, 1], 3000));
    println!("listening on {}", addr);
    axum_server::bind(addr)
        .serve(app.into_make_service())
        .await
        .unwrap();
}

examples/hello_world_unix.rs (line 15)

async fn main() {
    let app = Router::new().route("/", get(|| async { "Hello, world!" }));

    let addr = SocketAddr::from_pathname("/tmp/axum-server.sock").unwrap();
    println!("listening on {}", addr.as_pathname().unwrap().display());
    axum_server::bind(addr)
        .serve(app.into_make_service())
        .await
        .unwrap();
}

examples/from_std_listener.rs (line 17)

async fn main() {
    let app = Router::new().route("/", get(|| async { "Hello, world!" }));

    let addr = SocketAddr::from(([127, 0, 0, 1], 3000));
    let listener = TcpListener::bind(addr).unwrap();
    println!("listening on {}", addr);
    axum_server::from_tcp(listener)
        .unwrap()
        .serve(app.into_make_service())
        .await
        .unwrap();
}

Additional examples can be found in:

• examples/rustls_session.rs
• examples/shutdown.rs
• examples/rustls_server.rs
• examples/graceful_shutdown.rs
• examples/remote_address_using_tower.rs
• examples/rustls_reload.rs
• examples/from_std_listener_rustls.rs
• examples/async_sni.rs
• examples/timeouts.rs
• examples/reverse_proxy.rs
• examples/acme.rs
• examples/multiple_listeners.rs

Trait Implementations

impl<A: Address, B> Debug for Server<A, B>

where Listener<A>: Debug, Handle<A>: Debug, B: Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.