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. |
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`. |
354 | 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 | |
365 | fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), S::Error>> { |
366 | (**self).poll_ready(cx) |
367 | } |
368 | |
369 | fn call(&mut self, request: Request) -> S::Future { |
370 | (**self).call(req: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 | |
382 | fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), S::Error>> { |
383 | (**self).poll_ready(cx) |
384 | } |
385 | |
386 | fn call(&mut self, request: Request) -> S::Future { |
387 | (**self).call(req:request) |
388 | } |
389 | } |
390 | |