Source code
Revision control
Copy as Markdown
Other Tools
#![warn(
missing_debug_implementations,
missing_docs,
rust_2018_idioms,
unreachable_pub
)]
#![forbid(unsafe_code)]
// `rustdoc::broken_intra_doc_links` is checked on CI
//! Definition of the core `Service` trait to Tower
//!
//! The [`Service`] trait provides the necessary abstractions for defining
//! request / response clients and servers. It is simple but powerful and is
//! used as the foundation for the rest of Tower.
use std::future::Future;
use std::task::{Context, Poll};
/// An asynchronous function from a `Request` to a `Response`.
///
/// The `Service` trait is a simplified interface making it easy to write
/// network applications in a modular and reusable way, decoupled from the
/// underlying protocol. It is one of Tower's fundamental abstractions.
///
/// # Functional
///
/// A `Service` is a function of a `Request`. It immediately returns a
/// `Future` representing the eventual completion of processing the
/// request. The actual request processing may happen at any time in the
/// future, on any thread or executor. The processing may depend on calling
/// other services. At some point in the future, the processing will complete,
/// and the `Future` will resolve to a response or error.
///
/// At a high level, the `Service::call` function represents an RPC request. The
/// `Service` value can be a server or a client.
///
/// # Server
///
/// An RPC server *implements* the `Service` trait. Requests received by the
/// server over the network are deserialized and then passed as an argument to the
/// server value. The returned response is sent back over the network.
///
/// As an example, here is how an HTTP request is processed by a server:
///
/// ```rust
/// # use std::pin::Pin;
/// # use std::task::{Poll, Context};
/// # use std::future::Future;
/// # use tower_service::Service;
/// use http::{Request, Response, StatusCode};
///
/// struct HelloWorld;
///
/// impl Service<Request<Vec<u8>>> for HelloWorld {
/// type Response = Response<Vec<u8>>;
/// type Error = http::Error;
/// type Future = Pin<Box<dyn Future<Output = Result<Self::Response, Self::Error>>>>;
///
/// fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
/// Poll::Ready(Ok(()))
/// }
///
/// fn call(&mut self, req: Request<Vec<u8>>) -> Self::Future {
/// // create the body
/// let body: Vec<u8> = "hello, world!\n"
/// .as_bytes()
/// .to_owned();
/// // Create the HTTP response
/// let resp = Response::builder()
/// .status(StatusCode::OK)
/// .body(body)
/// .expect("Unable to create `http::Response`");
///
/// // create a response in a future.
/// let fut = async {
/// Ok(resp)
/// };
///
/// // Return the response as an immediate future
/// Box::pin(fut)
/// }
/// }
/// ```
///
/// # Client
///
/// A client consumes a service by using a `Service` value. The client may
/// issue requests by invoking `call` and passing the request as an argument.
/// It then receives the response by waiting for the returned future.
///
/// As an example, here is how a Redis request would be issued:
///
/// ```rust,ignore
/// let client = redis::Client::new()
/// .connect("127.0.0.1:6379".parse().unwrap())
/// .unwrap();
///
/// let resp = client.call(Cmd::set("foo", "this is the value of foo")).await?;
///
/// // Wait for the future to resolve
/// println!("Redis response: {:?}", resp);
/// ```
///
/// # Middleware / Layer
///
/// More often than not, all the pieces needed for writing robust, scalable
/// network applications are the same no matter the underlying protocol. By
/// unifying the API for both clients and servers in a protocol agnostic way,
/// it is possible to write middleware that provide these pieces in a
/// reusable way.
///
/// Take timeouts as an example:
///
/// ```rust
/// use tower_service::Service;
/// use tower_layer::Layer;
/// use futures::FutureExt;
/// use std::future::Future;
/// use std::task::{Context, Poll};
/// use std::time::Duration;
/// use std::pin::Pin;
/// use std::fmt;
/// use std::error::Error;
///
/// // Our timeout service, which wraps another service and
/// // adds a timeout to its response future.
/// pub struct Timeout<T> {
/// inner: T,
/// timeout: Duration,
/// }
///
/// impl<T> Timeout<T> {
/// pub fn new(inner: T, timeout: Duration) -> Timeout<T> {
/// Timeout {
/// inner,
/// timeout
/// }
/// }
/// }
///
/// // The error returned if processing a request timed out
/// #[derive(Debug)]
/// pub struct Expired;
///
/// impl fmt::Display for Expired {
/// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
/// write!(f, "expired")
/// }
/// }
///
/// impl Error for Expired {}
///
/// // We can implement `Service` for `Timeout<T>` if `T` is a `Service`
/// impl<T, Request> Service<Request> for Timeout<T>
/// where
/// T: Service<Request>,
/// T::Future: 'static,
/// T::Error: Into<Box<dyn Error + Send + Sync>> + 'static,
/// T::Response: 'static,
/// {
/// // `Timeout` doesn't modify the response type, so we use `T`'s response type
/// type Response = T::Response;
/// // Errors may be either `Expired` if the timeout expired, or the inner service's
/// // `Error` type. Therefore, we return a boxed `dyn Error + Send + Sync` trait object to erase
/// // the error's type.
/// type Error = Box<dyn Error + Send + Sync>;
/// type Future = Pin<Box<dyn Future<Output = Result<Self::Response, Self::Error>>>>;
///
/// fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
/// // Our timeout service is ready if the inner service is ready.
/// // This is how backpressure can be propagated through a tree of nested services.
/// self.inner.poll_ready(cx).map_err(Into::into)
/// }
///
/// fn call(&mut self, req: Request) -> Self::Future {
/// // Create a future that completes after `self.timeout`
/// let timeout = tokio::time::sleep(self.timeout);
///
/// // Call the inner service and get a future that resolves to the response
/// let fut = self.inner.call(req);
///
/// // Wrap those two futures in another future that completes when either one completes
/// //
/// // If the inner service is too slow the `sleep` future will complete first
/// // And an error will be returned and `fut` will be dropped and not polled again
/// //
/// // We have to box the errors so the types match
/// let f = async move {
/// tokio::select! {
/// res = fut => {
/// res.map_err(|err| err.into())
/// },
/// _ = timeout => {
/// Err(Box::new(Expired) as Box<dyn Error + Send + Sync>)
/// },
/// }
/// };
///
/// Box::pin(f)
/// }
/// }
///
/// // A layer for wrapping services in `Timeout`
/// pub struct TimeoutLayer(Duration);
///
/// impl TimeoutLayer {
/// pub fn new(delay: Duration) -> Self {
/// TimeoutLayer(delay)
/// }
/// }
///
/// impl<S> Layer<S> for TimeoutLayer {
/// type Service = Timeout<S>;
///
/// fn layer(&self, service: S) -> Timeout<S> {
/// Timeout::new(service, self.0)
/// }
/// }
/// ```
///
/// The above timeout implementation is decoupled from the underlying protocol
/// and is also decoupled from client or server concerns. In other words, the
/// same timeout middleware could be used in either a client or a server.
///
/// # Backpressure
///
/// Calling a `Service` which is at capacity (i.e., it is temporarily unable to process a
/// request) should result in an error. The caller is responsible for ensuring
/// that the service is ready to receive the request before calling it.
///
/// `Service` provides a mechanism by which the caller is able to coordinate
/// readiness. `Service::poll_ready` returns `Ready` if the service expects that
/// it is able to process a request.
///
/// # Be careful when cloning inner services
///
/// Services are permitted to panic if `call` is invoked without obtaining `Poll::Ready(Ok(()))`
/// from `poll_ready`. You should therefore be careful when cloning services for example to move
/// them into boxed futures. Even though the original service is ready, the clone might not be.
///
/// Therefore this kind of code is wrong and might panic:
///
/// ```rust
/// # use std::pin::Pin;
/// # use std::task::{Poll, Context};
/// # use std::future::Future;
/// # use tower_service::Service;
/// #
/// struct Wrapper<S> {
/// inner: S,
/// }
///
/// impl<R, S> Service<R> for Wrapper<S>
/// where
/// S: Service<R> + Clone + 'static,
/// R: 'static,
/// {
/// type Response = S::Response;
/// type Error = S::Error;
/// type Future = Pin<Box<dyn Future<Output = Result<Self::Response, Self::Error>>>>;
///
/// fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
/// Poll::Ready(Ok(()))
/// }
///
/// fn call(&mut self, req: R) -> Self::Future {
/// let mut inner = self.inner.clone();
/// Box::pin(async move {
/// // `inner` might not be ready since its a clone
/// inner.call(req).await
/// })
/// }
/// }
/// ```
///
/// You should instead use [`std::mem::replace`] to take the service that was ready:
///
/// ```rust
/// # use std::pin::Pin;
/// # use std::task::{Poll, Context};
/// # use std::future::Future;
/// # use tower_service::Service;
/// #
/// struct Wrapper<S> {
/// inner: S,
/// }
///
/// impl<R, S> Service<R> for Wrapper<S>
/// where
/// S: Service<R> + Clone + 'static,
/// R: 'static,
/// {
/// type Response = S::Response;
/// type Error = S::Error;
/// type Future = Pin<Box<dyn Future<Output = Result<Self::Response, Self::Error>>>>;
///
/// fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
/// Poll::Ready(Ok(()))
/// }
///
/// fn call(&mut self, req: R) -> Self::Future {
/// let clone = self.inner.clone();
/// // take the service that was ready
/// let mut inner = std::mem::replace(&mut self.inner, clone);
/// Box::pin(async move {
/// inner.call(req).await
/// })
/// }
/// }
/// ```
pub trait Service<Request> {
/// Responses given by the service.
type Response;
/// Errors produced by the service.
type Error;
/// The future response value.
type Future: Future<Output = Result<Self::Response, Self::Error>>;
/// Returns `Poll::Ready(Ok(()))` when the service is able to process requests.
///
/// If the service is at capacity, then `Poll::Pending` is returned and the task
/// is notified when the service becomes ready again. This function is
/// expected to be called while on a task. Generally, this can be done with
/// a simple `futures::future::poll_fn` call.
///
/// If `Poll::Ready(Err(_))` is returned, the service is no longer able to service requests
/// and the caller should discard the service instance.
///
/// Once `poll_ready` returns `Poll::Ready(Ok(()))`, a request may be dispatched to the
/// service using `call`. Until a request is dispatched, repeated calls to
/// `poll_ready` must return either `Poll::Ready(Ok(()))` or `Poll::Ready(Err(_))`.
///
/// Note that `poll_ready` may reserve shared resources that are consumed in a subsequent
/// invocation of `call`. Thus, it is critical for implementations to not assume that `call`
/// will always be invoked and to ensure that such resources are released if the service is
/// dropped before `call` is invoked or the future returned by `call` is dropped before it
/// is polled.
fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>;
/// Process the request and return the response asynchronously.
///
/// This function is expected to be callable off task. As such,
/// implementations should take care to not call `poll_ready`.
///
/// Before dispatching a request, `poll_ready` must be called and return
/// `Poll::Ready(Ok(()))`.
///
/// # Panics
///
/// Implementations are permitted to panic if `call` is invoked without
/// obtaining `Poll::Ready(Ok(()))` from `poll_ready`.
fn call(&mut self, req: Request) -> Self::Future;
}
impl<'a, S, Request> Service<Request> for &'a mut S
where
S: Service<Request> + 'a,
{
type Response = S::Response;
type Error = S::Error;
type Future = S::Future;
fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), S::Error>> {
(**self).poll_ready(cx)
}
fn call(&mut self, request: Request) -> S::Future {
(**self).call(request)
}
}
impl<S, Request> Service<Request> for Box<S>
where
S: Service<Request> + ?Sized,
{
type Response = S::Response;
type Error = S::Error;
type Future = S::Future;
fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), S::Error>> {
(**self).poll_ready(cx)
}
fn call(&mut self, request: Request) -> S::Future {
(**self).call(request)
}
}