Trait hyper::client::Service

pub trait Service where
    <Self::Future as Future>::Item == Self::Response,
    <Self::Future as Future>::Error == Self::Error, {
    type Request;
    type Response;
    type Error;
    type Future: Future;
    fn call(&self, req: Self::Request) -> Self::Future;
}

An asynchronous function from 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 Tokio's fundamental abstractions.

Functional

A Service is a function from 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 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 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:

impl Service for HelloWorld {
    type Request = http::Request;
    type Response = http::Response;
    type Error = http::Error;
    type Future = Box<Future<Item = Self::Response, Error = http::Error>>;

    fn call(&self, req: http::Request) -> Self::Future {
        // Create the HTTP response
        let resp = http::Response::ok()
            .with_body(b"hello world\n");

        // Return the response as an immediate future
        futures::finished(resp).boxed()
    }
}

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:

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"));

// Wait for the future to resolve
println!("Redis response: {:?}", await(resp));

Middleware

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.

For example, take timeouts as an example:

use tokio::Service;
use futures::Future;
use std::time::Duration;

// Not yet implemented, but soon :)
use tokio::timer::{Timer, Expired};

pub struct Timeout<T> {
    upstream: T,
    delay: Duration,
    timer: Timer,
}

impl<T> Timeout<T> {
    pub fn new(upstream: T, delay: Duration) -> Timeout<T> {
        Timeout {
            upstream: upstream,
            delay: delay,
            timer: Timer::default(),
        }
    }
}

impl<T> Service for Timeout<T>
    where T: Service,
          T::Error: From<Expired>,
{
    type Request = T::Request;
    type Response = T::Response;
    type Error = T::Error;
    type Future = Box<Future<Item = Self::Response, Error = Self::Error>>;

    fn call(&self, req: Self::Req) -> Self::Future {
        let timeout = self.timer.timeout(self.delay)
            .and_then(|timeout| Err(Self::Error::from(timeout)));

        self.upstream.call(req)
            .select(timeout)
            .map(|(v, _)| v)
            .map_err(|(e, _)| e)
            .boxed()
    }
}

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.

Associated Types

type Request

Requests handled by the service.

type Response

Responses given by the service.

type Error

Errors produced by the service.

type Future: Future

The future response value.

Loading content...

Required methods

fn call(&self, req: Self::Request) -> Self::Future

Process the request and return the response asynchronously.

Loading content...

Implementations on Foreign Types

impl<R, S, E> Service for ClientProxy<R, S, E> where
    E: From<Error>, 

type Request = R

type Response = S

type Error = E

type Future = Response<S, E>

fn call(&self, request: R) -> <ClientProxy<R, S, E> as Service>::Future

impl<T, P> Service for ClientService<T, P> where
    P: ClientProto<T>,
    T: 'static, 

type Request = <P as ClientProto<T>>::Request

type Response = <P as ClientProto<T>>::Response

type Error = Error

type Future = ClientFuture<T, P>

fn call(
    &self,
    req: <P as ClientProto<T>>::Request
) -> <ClientService<T, P> as Service>::Future

impl<T, P> Service for ClientService<T, P> where
    P: ClientProto<T>,
    T: 'static, 

type Request = <P as ClientProto<T>>::Request

type Response = <P as ClientProto<T>>::Response

type Error = Error

type Future = ClientFuture<T, P>

fn call(
    &self,
    req: <P as ClientProto<T>>::Request
) -> <ClientService<T, P> as Service>::Future

impl<S> Service for Rc<S> where
    S: Service + ?Sized, 

type Request = <S as Service>::Request

type Response = <S as Service>::Response

type Error = <S as Service>::Error

type Future = <S as Service>::Future

fn call(&self, request: <S as Service>::Request) -> <S as Service>::Future

impl<S> Service for Arc<S> where
    S: Service + ?Sized, 

type Request = <S as Service>::Request

type Response = <S as Service>::Response

type Error = <S as Service>::Error

type Future = <S as Service>::Future

fn call(&self, request: <S as Service>::Request) -> <S as Service>::Future

impl<S> Service for Box<S> where
    S: Service + ?Sized, 

type Request = <S as Service>::Request

type Response = <S as Service>::Response

type Error = <S as Service>::Error

type Future = <S as Service>::Future

fn call(&self, request: <S as Service>::Request) -> <S as Service>::Future

Loading content...

Implementors

impl Service for HttpConnector

type Request = Uri

type Response = TcpStream

type Error = Error

type Future = HttpConnecting

fn call(&self, uri: Uri) -> Self::Future

impl<C, B> Service for Client<C, B> where
    C: Connect,
    B: Stream<Error = Error> + 'static,
    B::Item: AsRef<[u8]>, 

type Request = Request<B>

type Response = Response

type Error = Error

type Future = FutureResponse

fn call(&self, req: Self::Request) -> Self::Future

Loading content...