[−][src]Trait actix_web::dev::Service

pub trait Service {
    type Request;
    type Response;
    type Error;
    type Future: Future;
    fn poll_ready(
        &mut self, 
        ctx: &mut Context<'_>
    ) -> Poll<Result<(), Self::Error>>;

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

    fn map<F, R>(self, f: F) -> Map<Self, F, R>
    where
        F: FnMut(Self::Response) -> R,
    { ... }

    fn map_err<F, E>(self, f: F) -> MapErr<Self, F, E>
    where
        F: Fn(Self::Error) -> E,
    { ... }
}

An asynchronous operation from Request to a Response.

The Service trait models a request/response interaction, receiving requests and returning replies. You can think about a service as a function with one argument that returns some result asynchronously. Conceptually, the operation looks like this:

ⓘThis example is not tested
async fn(Request) -> Result<Response, Err>

The Service trait just generalizes this form where each parameter is described as an associated type on the trait. Services can also have mutable state that influence computation.

Service provides a symmetric and uniform API; the same abstractions can be used to represent both clients and servers. Services describe only transformation operations which encourage simple API surfaces. This leads to simpler design of each service, improves test-ability and makes composition easier.

ⓘThis example is not tested
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(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> { ... }

     fn call(&mut self, req: Self::Request) -> Self::Future { ... }
}

Sometimes it is not necessary to implement the Service trait. For example, the above service could be rewritten as a simple function and passed to fn_service.

ⓘThis example is not tested
async fn my_service(req: u8) -> Result<u64, MyError>;

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 poll_ready(&mut self, ctx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>

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.

Notes

  1. .poll_ready() might be called on different task from actual service call.
  2. In case of chained services, .poll_ready() get called for all services at once.

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

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.

Loading content...

Provided methods

fn map<F, R>(self, f: F) -> Map<Self, F, R> where
    F: FnMut(Self::Response) -> R, 

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.

fn map_err<F, E>(self, f: F) -> MapErr<Self, F, E> where
    F: Fn(Self::Error) -> E, 

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. For example, this can be useful to ensure that services have the same error type.

Note that this function consumes the receiving service and returns a wrapped version of it.

Loading content...

Implementations on Foreign Types

impl<T, S, B, X, U> Service for H1ServiceHandler<T, S, B, X, U> where
    B: MessageBody,
    S: Service<Request = Request<Pin<Box<dyn Stream<Item = Result<Bytes, PayloadError>> + 'static>>>>,
    T: AsyncRead + AsyncWrite + Unpin,
    U: Service<Request = (Request<Pin<Box<dyn Stream<Item = Result<Bytes, PayloadError>> + 'static>>>, Framed<T, Codec>), Response = ()>,
    X: Service<Request = Request<Pin<Box<dyn Stream<Item = Result<Bytes, PayloadError>> + 'static>>>, Response = Request<Pin<Box<dyn Stream<Item = Result<Bytes, PayloadError>> + 'static>>>>,
    <S as Service>::Error: Into<Error>,
    <S as Service>::Response: Into<Response<B>>,
    <X as Service>::Error: Into<Error>,
    <U as Service>::Error: Display,
    <U as Service>::Error: Into<Error>, [src]

type Request = (T, Option<SocketAddr>)

type Response = ()

type Error = DispatchError

type Future = Dispatcher<T, S, B, X, U>

impl<T> Service for UpgradeHandler<T>[src]

type Request = (Request<Pin<Box<dyn Stream<Item = Result<Bytes, PayloadError>> + 'static>>>, Framed<T, Codec>)

type Response = ()

type Error = Error

type Future = Ready<Result<<UpgradeHandler<T> as Service>::Response, <UpgradeHandler<T> as Service>::Error>>

impl Service for ExpectHandler[src]

type Request = Request<Pin<Box<dyn Stream<Item = Result<Bytes, PayloadError>> + 'static>>>

type Response = Request<Pin<Box<dyn Stream<Item = Result<Bytes, PayloadError>> + 'static>>>

type Error = Error

type Future = Ready<Result<<ExpectHandler as Service>::Response, <ExpectHandler as Service>::Error>>

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

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<F, Fut, Req, Res, Err> Service for FnServiceFactory<F, Fut, Req, Res, Err, ()> where
    F: FnMut(Req) -> Fut + Clone,
    Fut: Future<Output = Result<Res, Err>>, [src]

type Request = Req

type Response = Res

type Error = Err

type Future = Fut

impl<F, Fut, Req, Res, Err> Service for FnService<F, Fut, Req, Res, Err> where
    F: FnMut(Req) -> Fut,
    Fut: Future<Output = Result<Res, Err>>, [src]

type Request = Req

type Response = Res

type Error = Err

type Future = Fut

impl<A, F, Response> Service for Map<A, F, Response> where
    A: Service,
    F: FnMut(<A as Service>::Response) -> Response + Clone, [src]

type Request = <A as Service>::Request

type Response = Response

type Error = <A as Service>::Error

type Future = MapFuture<A, F, Response>

impl<S> Service for RefCell<S> where
    S: Service, [src]

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<T, F, R, In, Out, Err> Service for Apply<T, F, R, In, Out, Err> where
    F: FnMut(In, &mut T) -> R,
    R: Future<Output = Result<Out, Err>>,
    T: Service<Error = Err>, [src]

type Request = In

type Response = Out

type Error = Err

type Future = R

impl<A, F, E> Service for MapErr<A, F, E> where
    A: Service,
    F: Fn(<A as Service>::Error) -> E + Clone, [src]

type Request = <A as Service>::Request

type Response = <A as Service>::Response

type Error = E

type Future = MapErrFuture<A, F, E>

impl<T> Service for Pipeline<T> where
    T: Service, [src]

type Request = <T as Service>::Request

type Response = <T as Service>::Response

type Error = <T as Service>::Error

type Future = <T as Service>::Future

impl<S> Service for Rc<RefCell<S>> where
    S: Service, [src]

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<'a, S> Service for &'a mut S where
    S: Service + 'a, [src]

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<T> Service for Resolver<T> where
    T: Address, 

type Request = Connect<T>

type Response = Connect<T>

type Error = ConnectError

type Future = Either<Pin<Box<dyn Future<Output = Result<<Resolver<T> as Service>::Response, <Resolver<T> as Service>::Error>> + 'static>>, Ready<Result<Connect<T>, <Resolver<T> as Service>::Error>>>

impl<T> Service for TcpConnectService<T> where
    T: 'static + Address, 

type Request = Connect<T>

type Response = TcpStream

type Error = ConnectError

type Future = TcpConnectServiceResponse<T>

impl<T> Service for OpensslConnectService<T> where
    T: 'static + Address, 

type Request = Connect<T>

type Response = SslStream<TcpStream>

type Error = ConnectError

type Future = OpensslConnectServiceResponse<T>

impl<T, U> Service for OpensslConnectorService<T, U> where
    T: Address + 'static,
    U: AsyncRead + AsyncWrite + Unpin + Debug + 'static, 

type Request = Connection<T, U>

type Response = Connection<T, SslStream<U>>

type Error = Error

type Future = Either<ConnectAsyncExt<T, U>, Ready<Result<<OpensslConnectorService<T, U> as Service>::Response, <OpensslConnectorService<T, U> as Service>::Error>>>

impl<T, U> Service for RustlsConnectorService<T, U> where
    T: Address,
    U: AsyncRead + AsyncWrite + Unpin + Debug, 

type Request = Connection<T, U>

type Response = Connection<T, TlsStream<U>>

type Error = Error

type Future = ConnectAsyncExt<T, U>

impl<T> Service for TcpConnector<T> where
    T: Address, 

type Request = Connect<T>

type Response = Connection<T, TcpStream>

type Error = ConnectError

type Future = Either<TcpConnectorResponse<T>, Ready<Result<<TcpConnector<T> as Service>::Response, <TcpConnector<T> as Service>::Error>>>

impl<T> Service for ConnectService<T> where
    T: Address, 

type Request = Connect<T>

type Response = Connection<T, TcpStream>

type Error = ConnectError

type Future = ConnectServiceResponse<T>

impl<A, B> Service for EitherService<A, B> where
    A: Service,
    B: Service<Response = <A as Service>::Response, Error = <A as Service>::Error>, [src]

type Request = Either<<A as Service>::Request, <B as Service>::Request>

type Response = <A as Service>::Response

type Error = <A as Service>::Error

type Future = Either<<A as Service>::Future, <B as Service>::Future>

impl<S> Service for InOrderService<S> where
    S: Service,
    <S as Service>::Response: 'static,
    <S as Service>::Future: 'static,
    <S as Service>::Error: 'static, [src]

type Request = <S as Service>::Request

type Response = <S as Service>::Response

type Error = InOrderError<<S as Service>::Error>

type Future = InOrderServiceResponse<S>

impl<R, E, F> Service for KeepAliveService<R, E, F> where
    F: Fn() -> E, [src]

type Request = R

type Response = R

type Error = E

type Future = Ready<Result<R, E>>

impl<T> Service for InFlightService<T> where
    T: Service, [src]

type Request = <T as Service>::Request

type Response = <T as Service>::Response

type Error = <T as Service>::Error

type Future = InFlightServiceResponse<T>

impl<S> Service for TimeoutService<S> where
    S: Service, [src]

type Request = <S as Service>::Request

type Response = <S as Service>::Response

type Error = TimeoutError<<S as Service>::Error>

type Future = TimeoutServiceResponse<S>

impl Service for LowResTimeService[src]

type Request = ()

type Response = Instant

type Error = Infallible

type Future = Ready<Result<<LowResTimeService as Service>::Response, <LowResTimeService as Service>::Error>>

impl<T> Service for AcceptorService<T> where
    T: Unpin + AsyncRead + AsyncWrite, [src]

type Request = T

type Response = TlsStream<T>

type Error = Error

type Future = AcceptorServiceFut<T>

impl<T> Service for AcceptorService<T> where
    T: 'static + Unpin + AsyncRead + AsyncWrite, [src]

type Request = T

type Response = SslStream<T>

type Error = HandshakeError<T>

type Future = AcceptorServiceResponse<T>

Loading content...

Implementors

Loading content...