| #![warn( | |
| missing_debug_implementations, | |
| missing_docs, | |
| rust_2018_idioms, | |
| unreachable_pub | |
| )] | |
| #![forbid(unsafe_code)] | |
| #![allow(elided_lifetimes_in_paths, clippy::type_complexity)] | |
| #![cfg_attr(test, allow(clippy::float_cmp))] | |
| #![cfg_attr(docsrs, feature(doc_cfg))] | |
| // `rustdoc::broken_intra_doc_links` is checked on CI | |
| //! `async fn(Request) -> Result<Response, Error>` | |
| //! | |
| //! # Overview | |
| //! | |
| //! Tower is a library of modular and reusable components for building | |
| //! robust networking clients and servers. | |
| //! | |
| //! Tower provides a simple core abstraction, the [`Service`] trait, which | |
| //! represents an asynchronous function taking a request and returning either a | |
| //! response or an error. This abstraction can be used to model both clients and | |
| //! servers. | |
| //! | |
| //! Generic components, like [timeouts], [rate limiting], and [load balancing], | |
| //! can be modeled as [`Service`]s that wrap some inner service and apply | |
| //! additional behavior before or after the inner service is called. This allows | |
| //! implementing these components in a protocol-agnostic, composable way. Typically, | |
| //! such services are referred to as _middleware_. | |
| //! | |
| //! An additional abstraction, the [`Layer`] trait, is used to compose | |
| //! middleware with [`Service`]s. If a [`Service`] can be thought of as an | |
| //! asynchronous function from a request type to a response type, a [`Layer`] is | |
| //! a function taking a [`Service`] of one type and returning a [`Service`] of a | |
| //! different type. The [`ServiceBuilder`] type is used to add middleware to a | |
| //! service by composing it with multiple [`Layer`]s. | |
| //! | |
| //! ## The Tower Ecosystem | |
| //! | |
| //! Tower is made up of the following crates: | |
| //! | |
| //! * [`tower`] (this crate) | |
| //! * [`tower-service`] | |
| //! * [`tower-layer`] | |
| //! * [`tower-test`] | |
| //! | |
| //! Since the [`Service`] and [`Layer`] traits are important integration points | |
| //! for all libraries using Tower, they are kept as stable as possible, and | |
| //! breaking changes are made rarely. Therefore, they are defined in separate | |
| //! crates, [`tower-service`] and [`tower-layer`]. This crate contains | |
| //! re-exports of those core traits, implementations of commonly-used | |
| //! middleware, and [utilities] for working with [`Service`]s and [`Layer`]s. | |
| //! Finally, the [`tower-test`] crate provides tools for testing programs using | |
| //! Tower. | |
| //! | |
| //! # Usage | |
| //! | |
| //! Tower provides an abstraction layer, and generic implementations of various | |
| //! middleware. This means that the `tower` crate on its own does *not* provide | |
| //! a working implementation of a network client or server. Instead, Tower's | |
| //! [`Service` trait][`Service`] provides an integration point between | |
| //! application code, libraries providing middleware implementations, and | |
| //! libraries that implement servers and/or clients for various network | |
| //! protocols. | |
| //! | |
| //! Depending on your particular use case, you might use Tower in several ways: | |
| //! | |
| //! * **Implementing application logic** for a networked program. You might | |
| //! use the [`Service`] trait to model your application's behavior, and use | |
| //! the middleware [provided by this crate](#modules) and by other libraries | |
| //! to add functionality to clients and servers provided by one or more | |
| //! protocol implementations. | |
| //! * **Implementing middleware** to add custom behavior to network clients and | |
| //! servers in a reusable manner. This might be general-purpose middleware | |
| //! (and if it is, please consider releasing your middleware as a library for | |
| //! other Tower users!) or application-specific behavior that needs to be | |
| //! shared between multiple clients or servers. | |
| //! * **Implementing a network protocol**. Libraries that implement network | |
| //! protocols (such as HTTP) can depend on `tower-service` to use the | |
| //! [`Service`] trait as an integration point between the protocol and user | |
| //! code. For example, a client for some protocol might implement [`Service`], | |
| //! allowing users to add arbitrary Tower middleware to those clients. | |
| //! Similarly, a server might be created from a user-provided [`Service`]. | |
| //! | |
| //! Additionally, when a network protocol requires functionality already | |
| //! provided by existing Tower middleware, a protocol implementation might use | |
| //! Tower middleware internally, as well as as an integration point. | |
| //! | |
| //! ## Library Support | |
| //! | |
| //! A number of third-party libraries support Tower and the [`Service`] trait. | |
| //! The following is an incomplete list of such libraries: | |
| //! | |
| //! * [`hyper`]: A fast and correct low-level HTTP implementation. | |
| //! * [`tonic`]: A [gRPC-over-HTTP/2][grpc] implementation built on top of | |
| //! [`hyper`]. See [here][tonic-examples] for examples of using [`tonic`] with | |
| //! Tower. | |
| //! * [`warp`]: A lightweight, composable web framework. See | |
| //! [here][warp-service] for details on using [`warp`] with Tower. | |
| //! * [`tower-lsp`] and its fork, [`lspower`]: implementations of the [Language | |
| //! Server Protocol][lsp] based on Tower. | |
| //! | |
| //! [`hyper`]: https://crates.io/crates/hyper | |
| //! [`tonic`]: https://crates.io/crates/tonic | |
| //! [tonic-examples]: https://github.com/hyperium/tonic/tree/master/examples/src/tower | |
| //! [grpc]: https://grpc.io | |
| //! [`warp`]: https://crates.io/crates/warp | |
| //! [warp-service]: https://docs.rs/warp/0.2.5/warp/fn.service.html | |
| //! [`tower-lsp`]: https://crates.io/crates/tower-lsp | |
| //! [`lspower`]: https://crates.io/crates/lspower | |
| //! [lsp]: https://microsoft.github.io/language-server-protocol/ | |
| //! | |
| //! If you're the maintainer of a crate that supports Tower, we'd love to add | |
| //! your crate to this list! Please [open a PR] adding a brief description of | |
| //! your library! | |
| //! | |
| //! ## Getting Started | |
| //! | |
| //! If you're brand new to Tower and want to start with the basics, we recommend you | |
| //! check out some of our [guides]. | |
| //! | |
| //! The various middleware implementations provided by this crate are feature | |
| //! flagged, so that users can only compile the parts of Tower they need. By | |
| //! default, all the optional middleware are disabled. | |
| //! | |
| //! To get started using all of Tower's optional middleware, add this to your | |
| //! `Cargo.toml`: | |
| //! | |
| //! ```toml | |
| //! tower = { version = "0.4", features = ["full"] } | |
| //! ``` | |
| //! | |
| //! Alternatively, you can only enable some features. For example, to enable | |
| //! only the [`retry`] and [`timeout`][timeouts] middleware, write: | |
| //! | |
| //! ```toml | |
| //! tower = { version = "0.4", features = ["retry", "timeout"] } | |
| //! ``` | |
| //! | |
| //! See [here](#modules) for a complete list of all middleware provided by | |
| //! Tower. | |
| //! | |
| //! | |
| //! ## Supported Rust Versions | |
| //! | |
| //! Tower will keep a rolling MSRV (minimum supported Rust version) policy of **at | |
| //! least** 6 months. When increasing the MSRV, the new Rust version must have been | |
| //! released at least six months ago. The current MSRV is 1.49.0. | |
| //! | |
| //! [`Service`]: crate::Service | |
| //! [`Layer`]: crate::Layer | |
| //! [timeouts]: crate::timeout | |
| //! [rate limiting]: crate::limit::rate | |
| //! [load balancing]: crate::balance | |
| //! [`ServiceBuilder`]: crate::ServiceBuilder | |
| //! [utilities]: crate::ServiceExt | |
| //! [`tower`]: https://crates.io/crates/tower | |
| //! [`tower-service`]: https://crates.io/crates/tower-service | |
| //! [`tower-layer`]: https://crates.io/crates/tower-layer | |
| //! [`tower-test`]: https://crates.io/crates/tower-test | |
| //! [`retry`]: crate::retry | |
| //! [open a PR]: https://github.com/tower-rs/tower/compare | |
| //! [guides]: https://github.com/tower-rs/tower/tree/master/guides | |
| #[macro_use] | |
| pub(crate) mod macros; | |
| #[cfg(feature = "balance")] | |
| #[cfg_attr(docsrs, doc(cfg(feature = "balance")))] | |
| pub mod balance; | |
| #[cfg(feature = "buffer")] | |
| #[cfg_attr(docsrs, doc(cfg(feature = "buffer")))] | |
| pub mod buffer; | |
| #[cfg(feature = "discover")] | |
| #[cfg_attr(docsrs, doc(cfg(feature = "discover")))] | |
| pub mod discover; | |
| #[cfg(feature = "filter")] | |
| #[cfg_attr(docsrs, doc(cfg(feature = "filter")))] | |
| pub mod filter; | |
| #[cfg(feature = "hedge")] | |
| #[cfg_attr(docsrs, doc(cfg(feature = "hedge")))] | |
| pub mod hedge; | |
| #[cfg(feature = "limit")] | |
| #[cfg_attr(docsrs, doc(cfg(feature = "limit")))] | |
| pub mod limit; | |
| #[cfg(feature = "load")] | |
| #[cfg_attr(docsrs, doc(cfg(feature = "load")))] | |
| pub mod load; | |
| #[cfg(feature = "load-shed")] | |
| #[cfg_attr(docsrs, doc(cfg(feature = "load-shed")))] | |
| pub mod load_shed; | |
| #[cfg(feature = "make")] | |
| #[cfg_attr(docsrs, doc(cfg(feature = "make")))] | |
| pub mod make; | |
| #[cfg(feature = "ready-cache")] | |
| #[cfg_attr(docsrs, doc(cfg(feature = "ready-cache")))] | |
| pub mod ready_cache; | |
| #[cfg(feature = "reconnect")] | |
| #[cfg_attr(docsrs, doc(cfg(feature = "reconnect")))] | |
| pub mod reconnect; | |
| #[cfg(feature = "retry")] | |
| #[cfg_attr(docsrs, doc(cfg(feature = "retry")))] | |
| pub mod retry; | |
| #[cfg(feature = "spawn-ready")] | |
| #[cfg_attr(docsrs, doc(cfg(feature = "spawn-ready")))] | |
| pub mod spawn_ready; | |
| #[cfg(feature = "steer")] | |
| #[cfg_attr(docsrs, doc(cfg(feature = "steer")))] | |
| pub mod steer; | |
| #[cfg(feature = "timeout")] | |
| #[cfg_attr(docsrs, doc(cfg(feature = "timeout")))] | |
| pub mod timeout; | |
| #[cfg(feature = "util")] | |
| #[cfg_attr(docsrs, doc(cfg(feature = "util")))] | |
| pub mod util; | |
| pub mod builder; | |
| pub mod layer; | |
| #[cfg(feature = "util")] | |
| #[cfg_attr(docsrs, doc(cfg(feature = "util")))] | |
| #[doc(inline)] | |
| pub use self::util::{service_fn, ServiceExt}; | |
| #[doc(inline)] | |
| pub use crate::builder::ServiceBuilder; | |
| #[cfg(feature = "make")] | |
| #[cfg_attr(docsrs, doc(cfg(feature = "make")))] | |
| #[doc(inline)] | |
| pub use crate::make::MakeService; | |
| #[doc(inline)] | |
| pub use tower_layer::Layer; | |
| #[doc(inline)] | |
| pub use tower_service::Service; | |
| #[allow(unreachable_pub)] | |
| mod sealed { | |
| pub trait Sealed<T> {} | |
| } | |
| /// Alias for a type-erased error type. | |
| pub type BoxError = Box<dyn std::error::Error + Send + Sync>; |