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 
151 pub mod accept;
152 pub mod conn;
153 #[cfg(feature = "tcp")]
154 mod tcp;
155 
156 pub use self::server::Server;
157 
158 cfg_feature! {
159     #![any(feature = "http1", feature = "http2")]
160 
161     #[cfg_attr(feature = "deprecated", allow(deprecated))]
162     pub(crate) mod server;
163     pub use self::server::Builder;
164 
165     mod shutdown;
166 }
167 
168 cfg_feature! {
169     #![not(any(feature = "http1", feature = "http2"))]
170 
171     mod server_stub;
172     use server_stub as server;
173 }
174