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