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 //! Definition of the core `Service` trait to Tower
11 //!
12 //! The [`Service`] trait provides the necessary abstractions for defining
13 //! request / response clients and servers. It is simple but powerful and is
14 //! used as the foundation for the rest of Tower.
15 
16 use std::future::Future;
17 use std::task::{Context, Poll};
18 
19 /// An asynchronous function from a `Request` to a `Response`.
20 ///
21 /// The `Service` trait is a simplified interface making it easy to write
22 /// network applications in a modular and reusable way, decoupled from the
23 /// underlying protocol. It is one of Tower's fundamental abstractions.
24 ///
25 /// # Functional
26 ///
27 /// A `Service` is a function of a `Request`. It immediately returns a
28 /// `Future` representing the eventual completion of processing the
29 /// request. The actual request processing may happen at any time in the
30 /// future, on any thread or executor. The processing may depend on calling
31 /// other services. At some point in the future, the processing will complete,
32 /// and the `Future` will resolve to a response or error.
33 ///
34 /// At a high level, the `Service::call` function represents an RPC request. The
35 /// `Service` value can be a server or a client.
36 ///
37 /// # Server
38 ///
39 /// An RPC server *implements* the `Service` trait. Requests received by the
40 /// server over the network are deserialized and then passed as an argument to the
41 /// server value. The returned response is sent back over the network.
42 ///
43 /// As an example, here is how an HTTP request is processed by a server:
44 ///
45 /// ```rust
46 /// # use std::pin::Pin;
47 /// # use std::task::{Poll, Context};
48 /// # use std::future::Future;
49 /// # use tower_service::Service;
50 /// use http::{Request, Response, StatusCode};
51 ///
52 /// struct HelloWorld;
53 ///
54 /// impl Service<Request<Vec<u8>>> for HelloWorld {
55 ///     type Response = Response<Vec<u8>>;
56 ///     type Error = http::Error;
57 ///     type Future = Pin<Box<dyn Future<Output = Result<Self::Response, Self::Error>>>>;
58 ///
59 ///     fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
60 ///         Poll::Ready(Ok(()))
61 ///     }
62 ///
63 ///     fn call(&mut self, req: Request<Vec<u8>>) -> Self::Future {
64 ///         // create the body
65 ///         let body: Vec<u8> = "hello, world!\n"
66 ///             .as_bytes()
67 ///             .to_owned();
68 ///         // Create the HTTP response
69 ///         let resp = Response::builder()
70 ///             .status(StatusCode::OK)
71 ///             .body(body)
72 ///             .expect("Unable to create `http::Response`");
73 ///
74 ///         // create a response in a future.
75 ///         let fut = async {
76 ///             Ok(resp)
77 ///         };
78 ///
79 ///         // Return the response as an immediate future
80 ///         Box::pin(fut)
81 ///     }
82 /// }
83 /// ```
84 ///
85 /// # Client
86 ///
87 /// A client consumes a service by using a `Service` value. The client may
88 /// issue requests by invoking `call` and passing the request as an argument.
89 /// It then receives the response by waiting for the returned future.
90 ///
91 /// As an example, here is how a Redis request would be issued:
92 ///
93 /// ```rust,ignore
94 /// let client = redis::Client::new()
95 ///     .connect("127.0.0.1:6379".parse().unwrap())
96 ///     .unwrap();
97 ///
98 /// let resp = client.call(Cmd::set("foo", "this is the value of foo")).await?;
99 ///
100 /// // Wait for the future to resolve
101 /// println!("Redis response: {:?}", resp);
102 /// ```
103 ///
104 /// # Middleware / Layer
105 ///
106 /// More often than not, all the pieces needed for writing robust, scalable
107 /// network applications are the same no matter the underlying protocol. By
108 /// unifying the API for both clients and servers in a protocol agnostic way,
109 /// it is possible to write middleware that provide these pieces in a
110 /// reusable way.
111 ///
112 /// Take timeouts as an example:
113 ///
114 /// ```rust
115 /// use tower_service::Service;
116 /// use tower_layer::Layer;
117 /// use futures::FutureExt;
118 /// use std::future::Future;
119 /// use std::task::{Context, Poll};
120 /// use std::time::Duration;
121 /// use std::pin::Pin;
122 /// use std::fmt;
123 /// use std::error::Error;
124 ///
125 /// // Our timeout service, which wraps another service and
126 /// // adds a timeout to its response future.
127 /// pub struct Timeout<T> {
128 ///     inner: T,
129 ///     timeout: Duration,
130 /// }
131 ///
132 /// impl<T> Timeout<T> {
133 ///     pub fn new(inner: T, timeout: Duration) -> Timeout<T> {
134 ///         Timeout {
135 ///             inner,
136 ///             timeout
137 ///         }
138 ///     }
139 /// }
140 ///
141 /// // The error returned if processing a request timed out
142 /// #[derive(Debug)]
143 /// pub struct Expired;
144 ///
145 /// impl fmt::Display for Expired {
146 ///     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
147 ///         write!(f, "expired")
148 ///     }
149 /// }
150 ///
151 /// impl Error for Expired {}
152 ///
153 /// // We can implement `Service` for `Timeout<T>` if `T` is a `Service`
154 /// impl<T, Request> Service<Request> for Timeout<T>
155 /// where
156 ///     T: Service<Request>,
157 ///     T::Future: 'static,
158 ///     T::Error: Into<Box<dyn Error + Send + Sync>> + 'static,
159 ///     T::Response: 'static,
160 /// {
161 ///     // `Timeout` doesn't modify the response type, so we use `T`'s response type
162 ///     type Response = T::Response;
163 ///     // Errors may be either `Expired` if the timeout expired, or the inner service's
164 ///     // `Error` type. Therefore, we return a boxed `dyn Error + Send + Sync` trait object to erase
165 ///     // the error's type.
166 ///     type Error = Box<dyn Error + Send + Sync>;
167 ///     type Future = Pin<Box<dyn Future<Output = Result<Self::Response, Self::Error>>>>;
168 ///
169 ///     fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
170 ///         // Our timeout service is ready if the inner service is ready.
171 ///         // This is how backpressure can be propagated through a tree of nested services.
172 ///        self.inner.poll_ready(cx).map_err(Into::into)
173 ///     }
174 ///
175 ///     fn call(&mut self, req: Request) -> Self::Future {
176 ///         // Create a future that completes after `self.timeout`
177 ///         let timeout = tokio::time::sleep(self.timeout);
178 ///
179 ///         // Call the inner service and get a future that resolves to the response
180 ///         let fut = self.inner.call(req);
181 ///
182 ///         // Wrap those two futures in another future that completes when either one completes
183 ///         //
184 ///         // If the inner service is too slow the `sleep` future will complete first
185 ///         // And an error will be returned and `fut` will be dropped and not polled again
186 ///         //
187 ///         // We have to box the errors so the types match
188 ///         let f = async move {
189 ///             tokio::select! {
190 ///                 res = fut => {
191 ///                     res.map_err(|err| err.into())
192 ///                 },
193 ///                 _ = timeout => {
194 ///                     Err(Box::new(Expired) as Box<dyn Error + Send + Sync>)
195 ///                 },
196 ///             }
197 ///         };
198 ///
199 ///         Box::pin(f)
200 ///     }
201 /// }
202 ///
203 /// // A layer for wrapping services in `Timeout`
204 /// pub struct TimeoutLayer(Duration);
205 ///
206 /// impl TimeoutLayer {
207 ///     pub fn new(delay: Duration) -> Self {
208 ///         TimeoutLayer(delay)
209 ///     }
210 /// }
211 ///
212 /// impl<S> Layer<S> for TimeoutLayer {
213 ///     type Service = Timeout<S>;
214 ///
215 ///     fn layer(&self, service: S) -> Timeout<S> {
216 ///         Timeout::new(service, self.0)
217 ///     }
218 /// }
219 /// ```
220 ///
221 /// The above timeout implementation is decoupled from the underlying protocol
222 /// and is also decoupled from client or server concerns. In other words, the
223 /// same timeout middleware could be used in either a client or a server.
224 ///
225 /// # Backpressure
226 ///
227 /// Calling a `Service` which is at capacity (i.e., it is temporarily unable to process a
228 /// request) should result in an error. The caller is responsible for ensuring
229 /// that the service is ready to receive the request before calling it.
230 ///
231 /// `Service` provides a mechanism by which the caller is able to coordinate
232 /// readiness. `Service::poll_ready` returns `Ready` if the service expects that
233 /// it is able to process a request.
234 ///
235 /// # Be careful when cloning inner services
236 ///
237 /// Services are permitted to panic if `call` is invoked without obtaining `Poll::Ready(Ok(()))`
238 /// from `poll_ready`. You should therefore be careful when cloning services for example to move
239 /// them into boxed futures. Even though the original service is ready, the clone might not be.
240 ///
241 /// Therefore this kind of code is wrong and might panic:
242 ///
243 /// ```rust
244 /// # use std::pin::Pin;
245 /// # use std::task::{Poll, Context};
246 /// # use std::future::Future;
247 /// # use tower_service::Service;
248 /// #
249 /// struct Wrapper<S> {
250 ///     inner: S,
251 /// }
252 ///
253 /// impl<R, S> Service<R> for Wrapper<S>
254 /// where
255 ///     S: Service<R> + Clone + 'static,
256 ///     R: 'static,
257 /// {
258 ///     type Response = S::Response;
259 ///     type Error = S::Error;
260 ///     type Future = Pin<Box<dyn Future<Output = Result<Self::Response, Self::Error>>>>;
261 ///
262 ///     fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
263 ///         Poll::Ready(Ok(()))
264 ///     }
265 ///
266 ///     fn call(&mut self, req: R) -> Self::Future {
267 ///         let mut inner = self.inner.clone();
268 ///         Box::pin(async move {
269 ///             // `inner` might not be ready since its a clone
270 ///             inner.call(req).await
271 ///         })
272 ///     }
273 /// }
274 /// ```
275 ///
276 /// You should instead use [`std::mem::replace`] to take the service that was ready:
277 ///
278 /// ```rust
279 /// # use std::pin::Pin;
280 /// # use std::task::{Poll, Context};
281 /// # use std::future::Future;
282 /// # use tower_service::Service;
283 /// #
284 /// struct Wrapper<S> {
285 ///     inner: S,
286 /// }
287 ///
288 /// impl<R, S> Service<R> for Wrapper<S>
289 /// where
290 ///     S: Service<R> + Clone + 'static,
291 ///     R: 'static,
292 /// {
293 ///     type Response = S::Response;
294 ///     type Error = S::Error;
295 ///     type Future = Pin<Box<dyn Future<Output = Result<Self::Response, Self::Error>>>>;
296 ///
297 ///     fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
298 ///         Poll::Ready(Ok(()))
299 ///     }
300 ///
301 ///     fn call(&mut self, req: R) -> Self::Future {
302 ///         let clone = self.inner.clone();
303 ///         // take the service that was ready
304 ///         let mut inner = std::mem::replace(&mut self.inner, clone);
305 ///         Box::pin(async move {
306 ///             inner.call(req).await
307 ///         })
308 ///     }
309 /// }
310 /// ```
311 pub trait Service<Request> {
312     /// Responses given by the service.
313     type Response;
314 
315     /// Errors produced by the service.
316     type Error;
317 
318     /// The future response value.
319     type Future: Future<Output = Result<Self::Response, Self::Error>>;
320 
321     /// Returns `Poll::Ready(Ok(()))` when the service is able to process requests.
322     ///
323     /// If the service is at capacity, then `Poll::Pending` is returned and the task
324     /// is notified when the service becomes ready again. This function is
325     /// expected to be called while on a task. Generally, this can be done with
326     /// a simple `futures::future::poll_fn` call.
327     ///
328     /// If `Poll::Ready(Err(_))` is returned, the service is no longer able to service requests
329     /// and the caller should discard the service instance.
330     ///
331     /// Once `poll_ready` returns `Poll::Ready(Ok(()))`, a request may be dispatched to the
332     /// service using `call`. Until a request is dispatched, repeated calls to
333     /// `poll_ready` must return either `Poll::Ready(Ok(()))` or `Poll::Ready(Err(_))`.
334     ///
335     /// Note that `poll_ready` may reserve shared resources that are consumed in a subsequent
336     /// invocation of `call`. Thus, it is critical for implementations to not assume that `call`
337     /// will always be invoked and to ensure that such resources are released if the service is
338     /// dropped before `call` is invoked or the future returned by `call` is dropped before it
339     /// is polled.
poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>340     fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>;
341 
342     /// Process the request and return the response asynchronously.
343     ///
344     /// This function is expected to be callable off task. As such,
345     /// implementations should take care to not call `poll_ready`.
346     ///
347     /// Before dispatching a request, `poll_ready` must be called and return
348     /// `Poll::Ready(Ok(()))`.
349     ///
350     /// # Panics
351     ///
352     /// Implementations are permitted to panic if `call` is invoked without
353     /// obtaining `Poll::Ready(Ok(()))` from `poll_ready`.
call(&mut self, req: Request) -> Self::Future354     fn call(&mut self, req: Request) -> Self::Future;
355 }
356 
357 impl<'a, S, Request> Service<Request> for &'a mut S
358 where
359     S: Service<Request> + 'a,
360 {
361     type Response = S::Response;
362     type Error = S::Error;
363     type Future = S::Future;
364 
poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), S::Error>>365     fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), S::Error>> {
366         (**self).poll_ready(cx)
367     }
368 
call(&mut self, request: Request) -> S::Future369     fn call(&mut self, request: Request) -> S::Future {
370         (**self).call(request)
371     }
372 }
373 
374 impl<S, Request> Service<Request> for Box<S>
375 where
376     S: Service<Request> + ?Sized,
377 {
378     type Response = S::Response;
379     type Error = S::Error;
380     type Future = S::Future;
381 
poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), S::Error>>382     fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), S::Error>> {
383         (**self).poll_ready(cx)
384     }
385 
call(&mut self, request: Request) -> S::Future386     fn call(&mut self, request: Request) -> S::Future {
387         (**self).call(request)
388     }
389 }
390