tower_async_layer/
lib.rs

1#![warn(
2    missing_debug_implementations,
3    missing_docs,
4    rust_2018_idioms,
5    unreachable_pub
6)]
7#![forbid(unsafe_code)]
8// `rustdoc::broken_intra_doc_links` is checked on CI
9
10//! Layer traits and extensions.
11//!
12//! A layer decorates an service and provides additional functionality. It
13//! allows other services to be composed with the service that implements layer.
14//!
15//! A middleware implements the [`Layer`] and [`Service`] trait.
16//!
17//! [`Service`]: https://docs.rs/tower-async/*/tower_async/trait.Service.html
18
19mod identity;
20mod layer_fn;
21mod stack;
22mod tuple;
23
24pub use self::{
25    identity::Identity,
26    layer_fn::{layer_fn, LayerFn},
27    stack::Stack,
28};
29
30/// Decorates a [`Service`], transforming either the request or the response.
31///
32/// Often, many of the pieces needed for writing network applications can be
33/// reused across multiple services. The `Layer` trait can be used to write
34/// reusable components that can be applied to very different kinds of services;
35/// for example, it can be applied to services operating on different protocols,
36/// and to both the client and server side of a network transaction.
37///
38/// # Log
39///
40/// Take request logging as an example:
41///
42/// ```rust
43/// # use tower_async_service::Service;
44/// # use std::task::{Poll, Context};
45/// # use tower_async_layer::Layer;
46/// # use std::fmt;
47///
48/// pub struct LogLayer {
49///     target: &'static str,
50/// }
51///
52/// impl<S> Layer<S> for LogLayer {
53///     type Service = LogService<S>;
54///
55///     fn layer(&self, service: S) -> Self::Service {
56///         LogService {
57///             target: self.target,
58///             service
59///         }
60///     }
61/// }
62///
63/// // This service implements the Log behavior
64/// pub struct LogService<S> {
65///     target: &'static str,
66///     service: S,
67/// }
68///
69/// impl<S, Request> Service<Request> for LogService<S>
70/// where
71///     S: Service<Request>,
72///     Request: fmt::Debug,
73/// {
74///     type Response = S::Response;
75///     type Error = S::Error;
76///
77///     async fn call(&self, request: Request) -> Result<Self::Response, Self::Error> {
78///         // Insert log statement here or other functionality
79///         println!("request = {:?}, target = {:?}", request, self.target);
80///         self.service.call(request).await
81///     }
82/// }
83/// ```
84///
85/// The above log implementation is decoupled from the underlying protocol and
86/// is also decoupled from client or server concerns. In other words, the same
87/// log middleware could be used in either a client or a server.
88///
89/// [`Service`]: https://docs.rs/tower-async/*/tower_async/trait.Service.html
90pub trait Layer<S> {
91    /// The wrapped service
92    type Service;
93    /// Wrap the given service with the middleware, returning a new service
94    /// that has been decorated with the middleware.
95    fn layer(&self, inner: S) -> Self::Service;
96}
97
98impl<'a, T, S> Layer<S> for &'a T
99where
100    T: ?Sized + Layer<S>,
101{
102    type Service = T::Service;
103
104    fn layer(&self, inner: S) -> Self::Service {
105        (**self).layer(inner)
106    }
107}
tower_async_layer/lib.rs

tower_async_layer/
lib.rs
