#![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` //! //! # 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 {} } /// Alias for a type-erased error type. pub type BoxError = Box;