pub trait Service<Req> {
type Response;
type Error;
type Future: Future;
fn poll_ready(&self, ctx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>;
fn call(&self, req: Req) -> Self::Future;
fn poll_shutdown(&self, ctx: &mut Context<'_>, is_error: bool) -> Poll<()> { ... }
fn map<F, Res>(self, f: F) -> Map<Self, F, Req, Res>
where
F: FnMut(Self::Response) -> Res,
{ ... }
fn map_err<F, E>(self, f: F) -> MapErr<Self, Req, F, E>
where
F: Fn(Self::Error) -> E,
{ ... }
}
Expand description
An asynchronous function from Request
to a Response
.
Service
represents a service that represanting interation, taking requests and giving back
replies. You can think about service as a function with one argument and result as a return
type. In general form it looks like async fn(Req) -> Result<Res, Err>
. Service
trait just generalizing form of this function. Each parameter described as an assotiated type.
Services provides a symmetric and uniform API, same abstractions represents
clients and servers. Services describe only transforamtion
operation
which encorouge to simplify api surface and phrases value transformation
.
That leads to simplier design of each service. That also allows better testability
and better composition.
Services could be represented in several different forms. In general,
Service is a type that implements Service
trait.
struct MyService;
impl Service for MyService {
type Request = u8;
type Response = u64;
type Error = MyError;
type Future = Pin<Box<Future<Output=Result<Self::Response, Self::Error>>>;
fn poll_ready(&self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> { ... }
fn call(&self, req: Self::Request) -> Self::Future { ... }
}
Service can have mutable state that influence computation.
This service could be rewritten as a simple function:
async fn my_service(req: u8) -> Result<u64, MyError>;
Responses given by the service.
Errors produced by the service.
The future response value.
Returns Ready
when the service is able to process requests.
If the service is at capacity, then 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.
This is a best effort implementation. False positives are permitted.
It is permitted for the service to return Ready
from a poll_ready
call and the next invocation of call
results in an error.
There are several notes to consider:
-
.poll_ready()
might be called on different task from actual service call.
-
In case of chained services, .poll_ready()
get called for all services at once.
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
. If the
service is at capacity and the request is unable to be handled, the
returned Future
should resolve to an error.
Calling call
without calling poll_ready
is permitted. The
implementation must be resilient to this fact.
Shutdown service.
Returns Ready
when the service is properly shutdowned. This method might be called
after it returns Ready
.
Map this service’s output to a different type, returning a new service
of the resulting type.
This function is similar to the Option::map
or Iterator::map
where
it will change the type of the underlying service.
Note that this function consumes the receiving service and returns a
wrapped version of it, similar to the existing map
methods in the
standard library.
Map this service’s error to a different error, returning a new service.
This function is similar to the Result::map_err
where it will change
the error type of the underlying service. This is useful for example to
ensure that services have the same error type.
Note that this function consumes the receiving service and returns a
wrapped version of it.
impl<F, Fut, Req, Res, Err, FShut> Service<Req> for FnService<F, Fut, Req, Res, Err, FShut> where
F: Fn(Req) -> Fut,
FShut: FnOnce(),
Fut: Future<Output = Result<Res, Err>>,
impl<F, Fut, Req, Res, Err, FShut> Service<Req> for FnServiceFactory<F, Fut, Req, Res, Err, (), FShut> where
F: Fn(Req) -> Fut,
FShut: FnOnce(),
Fut: Future<Output = Result<Res, Err>>,
impl<T, Req, F, R, In, Out, Err> Service<In> for Apply<T, Req, F, R, In, Out, Err> where
T: Service<Req, Error = Err>,
F: Fn(In, &T) -> R,
R: Future<Output = Result<Out, Err>>,
impl<V1, V2, V3, V1R, V2R, V3R> Service<Variant3<V1R, V2R, V3R>> for VariantService3<V1, V2, V3, V1R, V2R, V3R> where
V1: Service<V1R>,
V2: Service<V2R, Response = <V1 as Service<V1R>>::Response, Error = <V1 as Service<V1R>>::Error>,
V3: Service<V3R, Response = <V1 as Service<V1R>>::Response, Error = <V1 as Service<V1R>>::Error>,
impl<V1, V2, V3, V4, V1R, V2R, V3R, V4R> Service<Variant4<V1R, V2R, V3R, V4R>> for VariantService4<V1, V2, V3, V4, V1R, V2R, V3R, V4R> where
V1: Service<V1R>,
V2: Service<V2R, Response = <V1 as Service<V1R>>::Response, Error = <V1 as Service<V1R>>::Error>,
V3: Service<V3R, Response = <V1 as Service<V1R>>::Response, Error = <V1 as Service<V1R>>::Error>,
V4: Service<V4R, Response = <V1 as Service<V1R>>::Response, Error = <V1 as Service<V1R>>::Error>,
impl<V1, V2, V3, V4, V5, V1R, V2R, V3R, V4R, V5R> Service<Variant5<V1R, V2R, V3R, V4R, V5R>> for VariantService5<V1, V2, V3, V4, V5, V1R, V2R, V3R, V4R, V5R> where
V1: Service<V1R>,
V2: Service<V2R, Response = <V1 as Service<V1R>>::Response, Error = <V1 as Service<V1R>>::Error>,
V3: Service<V3R, Response = <V1 as Service<V1R>>::Response, Error = <V1 as Service<V1R>>::Error>,
V4: Service<V4R, Response = <V1 as Service<V1R>>::Response, Error = <V1 as Service<V1R>>::Error>,
V5: Service<V5R, Response = <V1 as Service<V1R>>::Response, Error = <V1 as Service<V1R>>::Error>,
impl<V1, V2, V3, V4, V5, V6, V1R, V2R, V3R, V4R, V5R, V6R> Service<Variant6<V1R, V2R, V3R, V4R, V5R, V6R>> for VariantService6<V1, V2, V3, V4, V5, V6, V1R, V2R, V3R, V4R, V5R, V6R> where
V1: Service<V1R>,
V2: Service<V2R, Response = <V1 as Service<V1R>>::Response, Error = <V1 as Service<V1R>>::Error>,
V3: Service<V3R, Response = <V1 as Service<V1R>>::Response, Error = <V1 as Service<V1R>>::Error>,
V4: Service<V4R, Response = <V1 as Service<V1R>>::Response, Error = <V1 as Service<V1R>>::Error>,
V5: Service<V5R, Response = <V1 as Service<V1R>>::Response, Error = <V1 as Service<V1R>>::Error>,
V6: Service<V6R, Response = <V1 as Service<V1R>>::Response, Error = <V1 as Service<V1R>>::Error>,
impl<V1, V2, V3, V4, V5, V6, V7, V1R, V2R, V3R, V4R, V5R, V6R, V7R> Service<Variant7<V1R, V2R, V3R, V4R, V5R, V6R, V7R>> for VariantService7<V1, V2, V3, V4, V5, V6, V7, V1R, V2R, V3R, V4R, V5R, V6R, V7R> where
V1: Service<V1R>,
V2: Service<V2R, Response = <V1 as Service<V1R>>::Response, Error = <V1 as Service<V1R>>::Error>,
V3: Service<V3R, Response = <V1 as Service<V1R>>::Response, Error = <V1 as Service<V1R>>::Error>,
V4: Service<V4R, Response = <V1 as Service<V1R>>::Response, Error = <V1 as Service<V1R>>::Error>,
V5: Service<V5R, Response = <V1 as Service<V1R>>::Response, Error = <V1 as Service<V1R>>::Error>,
V6: Service<V6R, Response = <V1 as Service<V1R>>::Response, Error = <V1 as Service<V1R>>::Error>,
V7: Service<V7R, Response = <V1 as Service<V1R>>::Response, Error = <V1 as Service<V1R>>::Error>,
impl<V1, V2, V3, V4, V5, V6, V7, V8, V1R, V2R, V3R, V4R, V5R, V6R, V7R, V8R> Service<Variant8<V1R, V2R, V3R, V4R, V5R, V6R, V7R, V8R>> for VariantService8<V1, V2, V3, V4, V5, V6, V7, V8, V1R, V2R, V3R, V4R, V5R, V6R, V7R, V8R> where
V1: Service<V1R>,
V2: Service<V2R, Response = <V1 as Service<V1R>>::Response, Error = <V1 as Service<V1R>>::Error>,
V3: Service<V3R, Response = <V1 as Service<V1R>>::Response, Error = <V1 as Service<V1R>>::Error>,
V4: Service<V4R, Response = <V1 as Service<V1R>>::Response, Error = <V1 as Service<V1R>>::Error>,
V5: Service<V5R, Response = <V1 as Service<V1R>>::Response, Error = <V1 as Service<V1R>>::Error>,
V6: Service<V6R, Response = <V1 as Service<V1R>>::Response, Error = <V1 as Service<V1R>>::Error>,
V7: Service<V7R, Response = <V1 as Service<V1R>>::Response, Error = <V1 as Service<V1R>>::Error>,
V8: Service<V8R, Response = <V1 as Service<V1R>>::Response, Error = <V1 as Service<V1R>>::Error>,