hyper/server/mod.rs
1//! HTTP Server
2//!
3//! A `Server` is created to listen on a port, parse HTTP requests, and hand
4//! them off to a `Service`.
5//!
6//! There are two levels of APIs provide for constructing HTTP servers:
7//!
8//! - The higher-level [`Server`](Server) type.
9//! - The lower-level [`conn`](conn) module.
10//!
11//! # Server
12//!
13//! The [`Server`](Server) is main way to start listening for HTTP requests.
14//! It wraps a listener with a [`MakeService`](crate::service), and then should
15//! be executed to start serving requests.
16//!
17//! [`Server`](Server) accepts connections in both HTTP1 and HTTP2 by default.
18//!
19//! ## Examples
20//!
21//! ```no_run
22//! use std::convert::Infallible;
23//! use std::net::SocketAddr;
24//! use hyper::{Body, Request, Response, Server};
25//! use hyper::service::{make_service_fn, service_fn};
26//!
27//! async fn handle(_req: Request<Body>) -> Result<Response<Body>, Infallible> {
28//! Ok(Response::new(Body::from("Hello World")))
29//! }
30//!
31//! # #[cfg(feature = "runtime")]
32//! #[tokio::main]
33//! async fn main() {
34//! // Construct our SocketAddr to listen on...
35//! let addr = SocketAddr::from(([127, 0, 0, 1], 3000));
36//!
37//! // And a MakeService to handle each connection...
38//! let make_service = make_service_fn(|_conn| async {
39//! Ok::<_, Infallible>(service_fn(handle))
40//! });
41//!
42//! // Then bind and serve...
43//! let server = Server::bind(&addr).serve(make_service);
44//!
45//! // And run forever...
46//! if let Err(e) = server.await {
47//! eprintln!("server error: {}", e);
48//! }
49//! }
50//! # #[cfg(not(feature = "runtime"))]
51//! # fn main() {}
52//! ```
53//!
54//! If you don't need the connection and your service implements `Clone` you can use
55//! [`tower::make::Shared`] instead of `make_service_fn` which is a bit simpler:
56//!
57//! ```no_run
58//! # use std::convert::Infallible;
59//! # use std::net::SocketAddr;
60//! # use hyper::{Body, Request, Response, Server};
61//! # use hyper::service::{make_service_fn, service_fn};
62//! # use tower::make::Shared;
63//! # async fn handle(_req: Request<Body>) -> Result<Response<Body>, Infallible> {
64//! # Ok(Response::new(Body::from("Hello World")))
65//! # }
66//! # #[cfg(feature = "runtime")]
67//! #[tokio::main]
68//! async fn main() {
69//! // Construct our SocketAddr to listen on...
70//! let addr = SocketAddr::from(([127, 0, 0, 1], 3000));
71//!
72//! // Shared is a MakeService that produces services by cloning an inner service...
73//! let make_service = Shared::new(service_fn(handle));
74//!
75//! // Then bind and serve...
76//! let server = Server::bind(&addr).serve(make_service);
77//!
78//! // And run forever...
79//! if let Err(e) = server.await {
80//! eprintln!("server error: {}", e);
81//! }
82//! }
83//! # #[cfg(not(feature = "runtime"))]
84//! # fn main() {}
85//! ```
86//!
87//! Passing data to your request handler can be done like so:
88//!
89//! ```no_run
90//! use std::convert::Infallible;
91//! use std::net::SocketAddr;
92//! use hyper::{Body, Request, Response, Server};
93//! use hyper::service::{make_service_fn, service_fn};
94//! # #[cfg(feature = "runtime")]
95//! use hyper::server::conn::AddrStream;
96//!
97//! #[derive(Clone)]
98//! struct AppContext {
99//! // Whatever data your application needs can go here
100//! }
101//!
102//! async fn handle(
103//! context: AppContext,
104//! addr: SocketAddr,
105//! req: Request<Body>
106//! ) -> Result<Response<Body>, Infallible> {
107//! Ok(Response::new(Body::from("Hello World")))
108//! }
109//!
110//! # #[cfg(feature = "runtime")]
111//! #[tokio::main]
112//! async fn main() {
113//! let context = AppContext {
114//! // ...
115//! };
116//!
117//! // A `MakeService` that produces a `Service` to handle each connection.
118//! let make_service = make_service_fn(move |conn: &AddrStream| {
119//! // We have to clone the context to share it with each invocation of
120//! // `make_service`. If your data doesn't implement `Clone` consider using
121//! // an `std::sync::Arc`.
122//! let context = context.clone();
123//!
124//! // You can grab the address of the incoming connection like so.
125//! let addr = conn.remote_addr();
126//!
127//! // Create a `Service` for responding to the request.
128//! let service = service_fn(move |req| {
129//! handle(context.clone(), addr, req)
130//! });
131//!
132//! // Return the service to hyper.
133//! async move { Ok::<_, Infallible>(service) }
134//! });
135//!
136//! // Run the server like above...
137//! let addr = SocketAddr::from(([127, 0, 0, 1], 3000));
138//!
139//! let server = Server::bind(&addr).serve(make_service);
140//!
141//! if let Err(e) = server.await {
142//! eprintln!("server error: {}", e);
143//! }
144//! }
145//! # #[cfg(not(feature = "runtime"))]
146//! # fn main() {}
147//! ```
148//!
149//! [`tower::make::Shared`]: https://docs.rs/tower/latest/tower/make/struct.Shared.html
150
151pub mod accept;
152pub mod conn;
153#[cfg(feature = "tcp")]
154mod tcp;
155
156pub use self::server::Server;
157
158cfg_feature! {
159 #![any(feature = "http1", feature = "http2")]
160
161 pub(crate) mod server;
162 pub use self::server::Builder;
163
164 mod shutdown;
165}
166
167cfg_feature! {
168 #![not(any(feature = "http1", feature = "http2"))]
169
170 mod server_stub;
171 use server_stub as server;
172}