Crate tower_async
source ·Expand description
async fn(Request) -> Result<Response, Error>
Fork
Tower Async is a fork of https://github.com/tower-rs/tower
and makes use of async traits
to simplify things and make it more easier
to integrate async functions into middleware.
This fork is made entirely with the needs of the author in mind, and thus might not yet contain all features you might need.
Come join us at discord at https://discord.com/channels/1114459060050333696/1123537825929900113
or tag @glendc
at Tokio’s Tower discord instead.
Where suitable we’ll keep in sync (manually) with Tower and if the opportunity arises we’ll contribute back “upstream” as well. Given however how big the diversange we aren’t sure how likely that is.
Overview
Tower Async 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 Async 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.
Difference with Tokio’s official Tower Ecosystem?
- Make use of
Async Traits
(RFC-3185: Static async fn in traits) instead of requiring the user to manually implement Futures;- Which in fact forces users to Box Services that rely on futures which cannot be named,
e.g. those returned by
async functions
that the user might have to face by using common utility functions from the wider Tokio ecosystem;
- Which in fact forces users to Box Services that rely on futures which cannot be named,
e.g. those returned by
- Drop the notion of
poll_ready
(See the FAQ). - Use
&self
forService::call
instead of&mut self
:- this to simplify its usage;
- makes it clear that the user is responsible for proper state sharing;
- makes it more compatible with the ecosystem (e.g.
hyper
(v1) also takes services by&self
);
Bridging to Tokio’s official Tower Ecosystem
You can make use of the tower-async-bridge
crate as found in this repo in the ./tower-async-bridge directory,
and published at crates.io under the same name.
At a high level it allows you to:
- Turn a
tower::Service
into atower_async::Service
(requires theinto_async
feature); - Turn a
tower_async::Service
into atower::Service
; - Use a
tower_async::Layer
within atower
environment (e.g.tower::ServiceBuilder
); - Use a
tower::Layer
within atower_async
environment (e.g.tower_async::ServiceBuilder
) (requires theinto_async
feature);
Please check the crate’s unit tests and examples to see specifically how to use the crate in order to achieve this.
Furthermore we also urge you to only use this kind of approach for transition purposes and not as a permanent way of life.
Best in our opinion is to use one or the other and not to combine the two. But if you do absolutely must
use one combined with the other, tower-async-bridge
should allow you to do exactly that.
The Tower Async Ecosystem
Tower Async is made up of the following crates:
tower-async
(this crate)tower-async-bridge
tower-async-service
tower-async-layer
- [
tower-async-test
] - [
tower-async-http
]
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-async-service
and tower-async-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.
tower-async-bridge
is there to bridge Tokio’s official Tower ecosystem
with this (Aync Trait) version (Fork).
Testing Layer
s can be done with unit tests very easily suing [tower-async-test
].
Finally in case you are using tower-async
for HTTP purposes (e.g. an HTTP web server),
then you might find it useful to also make use of [tower-async-http
] as it provides you
with builder extensions and middleware specifically tailored for http purposes.
Usage
Tower provides an abstraction layer, and generic implementations of various
middleware. This means that the tower-async
crate on its own does not provide
a working implementation of a network client or server. Instead, Tower’s
Service
trait 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 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-async-service
to use theService
trait as an integration point between the protocol and user code. For example, a client for some protocol might implementService
, allowing users to add arbitrary Tower middleware to those clients. Similarly, a server might be created from a user-providedService
.Additionally, when a network protocol requires functionality already provided by existing Tower middleware, a protocol implementation might use Tower middleware internally, as well as an integration point.
Library Support
Following are some libraries that make use of Tower Async (instead of Tower)
and the Service
trait:
rama
: A proxy framework to anonymise your network traffic.
If you’re the maintainer of a crate that supports Tower Async, 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
:
tower-async = { version = "0.2", features = ["full"] }
Alternatively, you can only enable some features. For example,
to enable only the timeout
middleware, write:
tower-async = { version = "0.2", features = ["timeout"] }
See here for a complete list of all middleware provided by Tower.
Browse the examples at tower-async-http/examples
to see some examples
on how to use tower-async
and its sibling crates. While these are focussed on http examples,
note that:
tower-async
can work for any request-response flow (akin totower
);- you can also use
tower-async
with http web services without making use of thetower-async-http
crate, it only is there to provide extra middleware for http-specific purposes, but this is all optional.
The documentation also contains some smaller examples and of course the codebase can be read as well, together with its unit tests.
Supported Rust Versions
Tower Async requires nightly Rust for the time being and has no backwards compatibility promises for the time being.
Once async traits
are stabilized we’ll start supporting stable rust once again,
and we can start working towards backwards compatibility.
Read https://blog.rust-lang.org/inside-rust/2023/05/03/stabilizing-async-fn-in-trait.html for more information on this roadmap by the Rust Language Core Team.
Modules
- Builder types to compose layers and services
- filter
filter
Conditionally dispatch requests to the inner service based on the result of a predicate. - A collection of
Layer
based tower services - limit
limit
A middleware that limits the number of in-flight requests. - make
make
Trait aliases for Services that produce specific types of Responses. - retry
retry
Middleware for retrying “failed” requests. - timeout
timeout
Middleware that applies a timeout to requests. - util
util
Various utility types and functions that are generally used with Tower.
Structs
- Declaratively construct
Service
values.
Traits
- Decorates a
Service
, transforming either the request or the response. - MakeService
make
Creates newService
values. - An asynchronous function from a
Request
to aResponse
. - ServiceExt
util
An extension trait forService
s that provides a variety of convenient adapters
Functions
- service_fn
util
Returns a newServiceFn
with the given closure.
Type Aliases
- Alias for a type-erased error type.