Trait hyper::client::Service
[−]
[src]
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.
Required Methods
fn call(&self, req: Self::Request) -> Self::Future
Process the request and return the response asynchronously.
Implementors
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>;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;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;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;impl Service for HttpConnector type Request = Uri; type Response = TcpStream; type Error = Error; type Future = HttpConnecting;
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;