axum_server/
lib.rs

1//! axum-server is a [hyper] server implementation designed to be used with [axum] framework.
2//!
3//! # Features
4//!
5//! - HTTP/1 and HTTP/2
6//! - HTTPS through [rustls] or [openssl].
7//! - High performance through [hyper].
8//! - Using [tower] make service API.
9//! - Very good [axum] compatibility. Likely to work with future [axum] releases.
10//!
11//! # Guide
12//!
13//! axum-server can [`serve`] items that implement [`MakeService`] with some additional [trait
14//! bounds](crate::service::MakeService). Make services that are [created] using [`axum`]
15//! complies with those trait bounds out of the box. Therefore it is more convenient to use this
16//! crate with [`axum`].
17//!
18//! All examples in this crate uses [`axum`]. If you want to use this crate without [`axum`] it is
19//! highly recommended to learn how [tower] works.
20//!
21//! [`Server::bind`] or [`bind`] function can be called to create a server that will bind to
22//! provided [`SocketAddr`] when [`serve`] is called.
23//!
24//! A [`Handle`] can be passed to [`Server`](Server::handle) for additional utilities like shutdown
25//! and graceful shutdown. To share shutdown across servers listening on different address types,
26//! build each handle with [`Handle::with_control`] from one [`Control`].
27//!
28//! [`bind_rustls`] can be called by providing [`RustlsConfig`] to create a HTTPS [`Server`] that
29//! will bind on provided [`SocketAddr`]. [`RustlsConfig`] can be cloned, reload methods can be
30//! used on clone to reload tls configuration.
31//!
32//! # Cargo features
33//!
34//! * `tls-rustls` - activate [rustls] support with the `aws-lc-rs` provider.
35//!   TLS 1.2 and TLS 1.3 are enabled.
36//! * `tls-rustls-no-provider` - activate [rustls] support without selecting a
37//!   cryptography provider. Enable a provider through `rustls` (for example
38//!   the `ring` feature) or install one at runtime.
39//! * `tls-rustls-encrypted-keys` - additionally support encrypted PKCS#8
40//!   private keys in [`RustlsConfig`].
41//! * `tls-rustls-acme` - additionally support automatic certificates through
42//!   [rustls-acme] (ACME, for example Let's Encrypt). Implies `tls-rustls`.
43//! * `tls-openssl` - activate [openssl] support.
44//!
45//! # Example
46//!
47//! A simple hello world application can be served like:
48//!
49//! ```rust,no_run
50//! use axum::{routing::get, Router};
51//! use std::net::SocketAddr;
52//!
53//! #[tokio::main]
54//! async fn main() {
55//!     let app = Router::new().route("/", get(|| async { "Hello, world!" }));
56//!
57//!     let addr = SocketAddr::from(([127, 0, 0, 1], 3000));
58//!     println!("listening on {}", addr);
59//!     axum_server::bind(addr)
60//!         .serve(app.into_make_service())
61//!         .await
62//!         .unwrap();
63//! }
64//! ```
65//!
66//! You can find more examples in [repository].
67//!
68//! [axum]: https://crates.io/crates/axum
69//! [bind]: crate::bind
70//! [bind_rustls]: crate::bind_rustls
71//! [created]: https://docs.rs/axum/0.8/axum/struct.Router.html#method.into_make_service
72//! [hyper]: https://crates.io/crates/hyper
73//! [openssl]: https://crates.io/crates/openssl
74//! [repository]: https://github.com/programatik29/axum-server/tree/master/examples
75//! [rustls]: https://crates.io/crates/rustls
76//! [rustls-acme]: https://crates.io/crates/rustls-acme
77//! [tower]: https://crates.io/crates/tower
78//! [`axum`]: https://docs.rs/axum/0.8
79//! [`serve`]: crate::server::Server::serve
80//! [`MakeService`]: https://docs.rs/tower/0.5/tower/make/trait.MakeService.html
81//! [`RustlsConfig`]: crate::tls_rustls::RustlsConfig
82//! [`SocketAddr`]: std::net::SocketAddr
83
84#![forbid(unsafe_code)]
85#![warn(
86    clippy::await_holding_lock,
87    clippy::cargo_common_metadata,
88    clippy::dbg_macro,
89    clippy::doc_markdown,
90    clippy::enum_glob_use,
91    clippy::inefficient_to_string,
92    clippy::mem_forget,
93    clippy::mutex_integer,
94    clippy::needless_continue,
95    clippy::todo,
96    clippy::unimplemented,
97    clippy::wildcard_imports,
98    future_incompatible,
99    missing_docs,
100    missing_debug_implementations,
101    unreachable_pub
102)]
103#![cfg_attr(docsrs, feature(doc_cfg))]
104
105mod connection;
106mod handle;
107mod notify_once;
108mod server;
109
110pub mod accept;
111pub mod service;
112
113pub use self::{
114    // addr_incoming_config::AddrIncomingConfig,
115    connection::ConnectionShutdown,
116    handle::{Control, Handle},
117    // http_config::HttpConfig,
118    server::{bind, from_tcp, AddrListener, Address, Server},
119};
120
121#[cfg(unix)]
122pub use self::server::from_unix;
123
124#[cfg(any(feature = "tls-rustls-no-provider", feature = "tls-openssl"))]
125#[cfg_attr(docsrs, doc(cfg(any(feature = "tls-rustls", feature = "tls-openssl"))))]
126pub mod tls;
127
128#[cfg(feature = "tls-rustls-no-provider")]
129#[cfg_attr(docsrs, doc(cfg(feature = "tls-rustls")))]
130pub mod tls_rustls;
131
132#[doc(inline)]
133#[cfg(feature = "tls-rustls-no-provider")]
134pub use self::tls_rustls::{bind_rustls, from_tcp_rustls};
135
136#[doc(inline)]
137#[cfg(all(feature = "tls-rustls-no-provider", unix))]
138pub use self::tls_rustls::from_unix_rustls;
139
140#[cfg(feature = "tls-rustls-acme")]
141#[cfg_attr(docsrs, doc(cfg(feature = "tls-rustls-acme")))]
142pub mod acme;
143
144#[cfg(feature = "tls-openssl")]
145#[cfg_attr(docsrs, doc(cfg(feature = "tls-openssl")))]
146pub mod tls_openssl;
147
148#[doc(inline)]
149#[cfg(feature = "tls-openssl")]
150pub use self::tls_openssl::bind_openssl;
axum_server/lib.rs

axum_server/
lib.rs
