# Tower Tower is a library of modular and reusable components for building robust networking clients and servers. [![Crates.io][crates-badge]][crates-url] [![Documentation][docs-badge]][docs-url] [![Documentation (master)][docs-master-badge]][docs-master-url] [![MIT licensed][mit-badge]][mit-url] [![Build Status][actions-badge]][actions-url] [![Discord chat][discord-badge]][discord-url] [crates-badge]: https://img.shields.io/crates/v/tower.svg [crates-url]: https://crates.io/crates/tower [docs-badge]: https://docs.rs/tower/badge.svg [docs-url]: https://docs.rs/tower [docs-master-badge]: https://img.shields.io/badge/docs-master-blue [docs-master-url]: https://tower-rs.github.io/tower/tower [mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg [mit-url]: LICENSE [actions-badge]: https://github.com/tower-rs/tower/workflows/CI/badge.svg [actions-url]:https://github.com/tower-rs/tower/actions?query=workflow%3ACI [discord-badge]: https://img.shields.io/discord/500028886025895936?logo=discord&label=discord&logoColor=white [discord-url]: https://discord.gg/EeF3cQw ## Overview Tower aims to make it as easy as possible to build robust networking clients and servers. It is protocol agnostic, but is designed around a request / response pattern. If your protocol is entirely stream based, Tower may not be a good fit. 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 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][all_layers] 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. * [`kube`]: Kubernetes client and futures controller runtime. [`kube::Client`] makes use of the Tower ecosystem: [`tower`], [`tower-http`], and [`tower-test`]. See [here][kube-example-minimal] and [here][kube-example-trace] for examples of using [`kube`] with 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/ [`kube`]: https://crates.io/crates/kube [`kube::Client`]: https://docs.rs/kube/latest/kube/struct.Client.html [kube-example-minimal]: https://github.com/clux/kube-rs/blob/master/examples/custom_client.rs [kube-example-trace]: https://github.com/clux/kube-rs/blob/master/examples/custom_client_trace.rs [`tower-http`]: https://crates.io/crates/tower-http 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 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][all_layers] for a complete list of all middleware provided by Tower. [`Service`]: https://docs.rs/tower/latest/tower/trait.Service.html [`Layer`]: https://docs.rs/tower/latest/tower/trait.Layer.html [all_layers]: https://docs.rs/tower/latest/tower/#modules [timeouts]: https://docs.rs/tower/latest/tower/timeout/ [rate limiting]: https://docs.rs/tower/latest/tower/limit/rate [load balancing]: https://docs.rs/tower/latest/tower/balance/ [`ServiceBuilder`]: https://docs.rs/tower/latest/tower/struct.ServiceBuilder.html [utilities]: https://docs.rs/tower/latest/tower/trait.ServiceExt.html [`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`]: https://docs.rs/tower/latest/tower/retry [open a PR]: https://github.com/tower-rs/tower/compare ## 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. ## License This project is licensed under the [MIT license](LICENSE). ### Contribution Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Tower by you, shall be licensed as MIT, without any additional terms or conditions.