1#![warn(
2 missing_debug_implementations,
3 missing_docs,
4 rust_2018_idioms,
5 unreachable_pub
6)]
7#![forbid(unsafe_code)]
8#![allow(elided_lifetimes_in_paths, clippy::type_complexity)]
9#![cfg_attr(test, allow(clippy::float_cmp))]
10#![cfg_attr(docsrs, feature(doc_auto_cfg, doc_cfg))]
11// `rustdoc::broken_intra_doc_links` is checked on CI
12
13//! `async fn(Request) -> Result<Response, Error>`
14//!
15//! # Overview
16//!
17//! Tower is a library of modular and reusable components for building
18//! robust networking clients and servers.
19//!
20//! Tower provides a simple core abstraction, the [`Service`] trait, which
21//! represents an asynchronous function taking a request and returning either a
22//! response or an error. This abstraction can be used to model both clients and
23//! servers.
24//!
25//! Generic components, like [`timeout`], [rate limiting], and [load balancing],
26//! can be modeled as [`Service`]s that wrap some inner service and apply
27//! additional behavior before or after the inner service is called. This allows
28//! implementing these components in a protocol-agnostic, composable way. Typically,
29//! such services are referred to as _middleware_.
30//!
31//! An additional abstraction, the [`Layer`] trait, is used to compose
32//! middleware with [`Service`]s. If a [`Service`] can be thought of as an
33//! asynchronous function from a request type to a response type, a [`Layer`] is
34//! a function taking a [`Service`] of one type and returning a [`Service`] of a
35//! different type. The [`ServiceBuilder`] type is used to add middleware to a
36//! service by composing it with multiple [`Layer`]s.
37//!
38//! ## The Tower Ecosystem
39//!
40//! Tower is made up of the following crates:
41//!
42//! * [`tower`] (this crate)
43//! * [`tower-service`]
44//! * [`tower-layer`]
45//! * [`tower-test`]
46//!
47//! Since the [`Service`] and [`Layer`] traits are important integration points
48//! for all libraries using Tower, they are kept as stable as possible, and
49//! breaking changes are made rarely. Therefore, they are defined in separate
50//! crates, [`tower-service`] and [`tower-layer`]. This crate contains
51//! re-exports of those core traits, implementations of commonly-used
52//! middleware, and [utilities] for working with [`Service`]s and [`Layer`]s.
53//! Finally, the [`tower-test`] crate provides tools for testing programs using
54//! Tower.
55//!
56//! # Usage
57//!
58//! Tower provides an abstraction layer, and generic implementations of various
59//! middleware. This means that the `tower` crate on its own does *not* provide
60//! a working implementation of a network client or server. Instead, Tower's
61//! [`Service` trait][`Service`] provides an integration point between
62//! application code, libraries providing middleware implementations, and
63//! libraries that implement servers and/or clients for various network
64//! protocols.
65//!
66//! Depending on your particular use case, you might use Tower in several ways:
67//!
68//! * **Implementing application logic** for a networked program. You might
69//! use the [`Service`] trait to model your application's behavior, and use
70//! the middleware [provided by this crate](#modules) and by other libraries
71//! to add functionality to clients and servers provided by one or more
72//! protocol implementations.
73//! * **Implementing middleware** to add custom behavior to network clients and
74//! servers in a reusable manner. This might be general-purpose middleware
75//! (and if it is, please consider releasing your middleware as a library for
76//! other Tower users!) or application-specific behavior that needs to be
77//! shared between multiple clients or servers.
78//! * **Implementing a network protocol**. Libraries that implement network
79//! protocols (such as HTTP) can depend on `tower-service` to use the
80//! [`Service`] trait as an integration point between the protocol and user
81//! code. For example, a client for some protocol might implement [`Service`],
82//! allowing users to add arbitrary Tower middleware to those clients.
83//! Similarly, a server might be created from a user-provided [`Service`].
84//!
85//! Additionally, when a network protocol requires functionality already
86//! provided by existing Tower middleware, a protocol implementation might use
87//! Tower middleware internally, as well as as an integration point.
88//!
89//! ## Library Support
90//!
91//! A number of third-party libraries support Tower and the [`Service`] trait.
92//! The following is an incomplete list of such libraries:
93//!
94//! * [`hyper`]: A fast and correct low-level HTTP implementation.
95//! * [`tonic`]: A [gRPC-over-HTTP/2][grpc] implementation built on top of
96//! [`hyper`]. See [here][tonic-examples] for examples of using [`tonic`] with
97//! Tower.
98//! * [`warp`]: A lightweight, composable web framework. See
99//! [here][warp-service] for details on using [`warp`] with Tower.
100//! * [`tower-lsp`]: implementations of the [Language
101//! Server Protocol][lsp] based on Tower.
102//!
103//! [`hyper`]: https://crates.io/crates/hyper
104//! [`tonic`]: https://crates.io/crates/tonic
105//! [tonic-examples]: https://github.com/hyperium/tonic/tree/master/examples/src/tower
106//! [grpc]: https://grpc.io
107//! [`warp`]: https://crates.io/crates/warp
108//! [warp-service]: https://docs.rs/warp/0.2.5/warp/fn.service.html
109//! [`tower-lsp`]: https://crates.io/crates/tower-lsp
110//! [lsp]: https://microsoft.github.io/language-server-protocol/
111//!
112//! If you're the maintainer of a crate that supports Tower, we'd love to add
113//! your crate to this list! Please [open a PR] adding a brief description of
114//! your library!
115//!
116//! ## Getting Started
117//!
118//! If you're brand new to Tower and want to start with the basics, we recommend you
119//! check out some of our [guides].
120//!
121//! The various middleware implementations provided by this crate are feature
122//! flagged, so that users can only compile the parts of Tower they need. By
123//! default, all the optional middleware are disabled.
124//!
125//! To get started using all of Tower's optional middleware, add this to your
126//! `Cargo.toml`:
127//!
128//! ```toml
129//! tower = { version = "0.4", features = ["full"] }
130//! ```
131//!
132//! Alternatively, you can only enable some features. For example, to enable
133//! only the [`retry`] and [`timeout`] middleware, write:
134//!
135//! ```toml
136//! tower = { version = "0.4", features = ["retry", "timeout"] }
137//! ```
138//!
139//! See [here](#modules) for a complete list of all middleware provided by
140//! Tower.
141//!
142//!
143//! ## Supported Rust Versions
144//!
145//! Tower will keep a rolling MSRV (minimum supported Rust version) policy of **at
146//! least** 6 months. When increasing the MSRV, the new Rust version must have been
147//! released at least six months ago. The current MSRV is 1.64.0.
148//!
149//! [`Service`]: crate::Service
150//! [`Layer`]: crate::Layer
151//! [rate limiting]: crate::limit::rate
152//! [load balancing]: crate::balance
153//! [`ServiceBuilder`]: crate::ServiceBuilder
154//! [utilities]: crate::ServiceExt
155//! [`tower`]: https://crates.io/crates/tower
156//! [`tower-service`]: https://crates.io/crates/tower-service
157//! [`tower-layer`]: https://crates.io/crates/tower-layer
158//! [`tower-test`]: https://crates.io/crates/tower-test
159//! [`retry`]: crate::retry
160//! [open a PR]: https://github.com/tower-rs/tower/compare
161//! [guides]: https://github.com/tower-rs/tower/tree/master/guides
162
163#[macro_use]
164pub(crate) mod macros;
165#[cfg(feature = "balance")]
166pub mod balance;
167#[cfg(feature = "buffer")]
168pub mod buffer;
169#[cfg(feature = "discover")]
170pub mod discover;
171#[cfg(feature = "filter")]
172pub mod filter;
173#[cfg(feature = "hedge")]
174pub mod hedge;
175#[cfg(feature = "limit")]
176pub mod limit;
177#[cfg(feature = "load")]
178pub mod load;
179#[cfg(feature = "load-shed")]
180pub mod load_shed;
181
182#[cfg(feature = "make")]
183pub mod make;
184#[cfg(feature = "ready-cache")]
185pub mod ready_cache;
186#[cfg(feature = "reconnect")]
187pub mod reconnect;
188#[cfg(feature = "retry")]
189pub mod retry;
190#[cfg(feature = "spawn-ready")]
191pub mod spawn_ready;
192#[cfg(feature = "steer")]
193pub mod steer;
194#[cfg(feature = "timeout")]
195pub mod timeout;
196#[cfg(feature = "util")]
197pub mod util;
198
199pub mod builder;
200pub mod layer;
201
202#[cfg(feature = "util")]
203#[doc(inline)]
204#[cfg_attr(docsrs, doc(cfg(feature = "util")))]
205pub use self::util::{service_fn, ServiceExt};
206
207#[doc(inline)]
208pub use crate::builder::ServiceBuilder;
209
210#[cfg(feature = "make")]
211#[doc(inline)]
212#[cfg_attr(docsrs, doc(cfg(feature = "make")))]
213pub use crate::make::MakeService;
214
215#[doc(inline)]
216pub use tower_layer::Layer;
217
218#[doc(inline)]
219pub use tower_service::Service;
220
221#[allow(unreachable_pub)]
222#[cfg(any(feature = "balance", feature = "discover", feature = "make"))]
223mod sealed {
224 pub trait Sealed<T> {}
225}
226
227/// Alias for a type-erased error type.
228pub type BoxError = Box<dyn std::error::Error + Send + Sync>;
229