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
16use std::future::Future;
17use 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 const 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 const 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/// self.inner.poll_ready(cx)
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/// self.inner.poll_ready(cx)
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/// ```
311pub 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 #[must_use = "futures do nothing unless you `.await` or poll them"]
355 fn call(&mut self, req: Request) -> Self::Future;
356}
357
358impl<'a, S, Request> Service<Request> for &'a mut S
359where
360 S: Service<Request> + 'a,
361{
362 type Response = S::Response;
363 type Error = S::Error;
364 type Future = S::Future;
365
366 fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), S::Error>> {
367 (**self).poll_ready(cx)
368 }
369
370 fn call(&mut self, request: Request) -> S::Future {
371 (**self).call(req:request)
372 }
373}
374
375impl<S, Request> Service<Request> for Box<S>
376where
377 S: Service<Request> + ?Sized,
378{
379 type Response = S::Response;
380 type Error = S::Error;
381 type Future = S::Future;
382
383 fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), S::Error>> {
384 (**self).poll_ready(cx)
385 }
386
387 fn call(&mut self, request: Request) -> S::Future {
388 (**self).call(req:request)
389 }
390}
391