Trait ServiceExt
trait ServiceExt<Request>: tower_service::Service<Request>
An extension trait for Services that provides a variety of convenient
adapters
Provided Methods
fn ready(self: &mut Self) -> Ready<'_, Self, Request> where Self: SizedYields a mutable reference to the service when it is ready to accept a request.
fn ready_oneshot(self: Self) -> ReadyOneshot<Self, Request> where Self: SizedYields the service when it is ready to accept a request.
fn oneshot(self: Self, req: Request) -> Oneshot<Self, Request> where Self: SizedConsume this
Service, calling it with the provided request once it is ready.fn call_all<S>(self: Self, reqs: S) -> CallAll<Self, S> where Self: Sized, S: futures_core::Stream<Item = Request>Process all requests from the given
Stream, and produce aStreamof their responses.This is essentially
Stream<Item = Request>+Self=>Stream<Item = Response>. See the documentation forCallAllfor details.fn and_then<F>(self: Self, f: F) -> AndThen<Self, F> where Self: Sized, F: CloneExecutes a new future after this service's future resolves. This does not alter the behaviour of the
poll_readymethod.This method can be used to change the
Responsetype of the service into a different type. You can use this method to chain along a computation once the service's response has been resolved.Example
# use ; # use ; # # ; # # # # # # # async # #fn map_response<F, Response>(self: Self, f: F) -> MapResponse<Self, F> where Self: Sized, F: FnOnce(<Self as >::Response) -> Response + CloneMaps this service's response value to a different value. This does not alter the behaviour of the
poll_readymethod.This method can be used to change the
Responsetype of the service into a different type. It is similar to theResult::mapmethod. You can use this method to chain along a computation once the service's response has been resolved.Example
# use ; # use ; # # ; # # # # # # #fn map_err<F, Error>(self: Self, f: F) -> MapErr<Self, F> where Self: Sized, F: FnOnce(<Self as >::Error) -> Error + CloneMaps this service's error value to a different value. This does not alter the behaviour of the
poll_readymethod.This method can be used to change the
Errortype of the service into a different type. It is similar to theResult::map_errmethod.Example
# use ; # use ; # # ; # # # # # # #fn map_result<F, Response, Error>(self: Self, f: F) -> MapResult<Self, F> where Self: Sized, Error: From<<Self as >::Error>, F: FnOnce(Result<<Self as >::Response, <Self as >::Error>) -> Result<Response, Error> + CloneMaps this service's result type (
Result<Self::Response, Self::Error>) to a different value, regardless of whether the future succeeds or fails.This is similar to the
map_responseandmap_errcombinators, except that the same function is invoked when the service's future completes, whether it completes successfully or fails. This function takes theResultreturned by the service's future, and returns aResult.Like the standard library's
Result::and_then, this method can be used to implement control flow based onResultvalues. For example, it may be used to implement error recovery, by turning someErrresponses from the service intoOkresponses. Similarly, some successful responses from the service could be rejected, by returning anErrconditionally, depending on the value inside the [Ok.] Finally, this method can also be used to implement behaviors that must run when a service's future completes, regardless of whether it succeeded or failed.This method can be used to change the
Responsetype of the service into a different type. It can also be used to change theErrortype of the service. However, because themap_resultfunction is not applied to the errors returned by the service'spoll_readymethod, it must be possible to convert the service'sErrortype into the error type returned by themap_resultfunction. This is trivial when the function returns the same error type as the service, but in other cases, it can be useful to useBoxErrorto erase differing error types.Examples
Recovering from certain errors:
# use ; # use ; # # ; # # # # # # # # #Rejecting some
Okresponses:# use ; # use ; # # ; # # # # type DbError = String; # type AppError = String; # # # #Performing an action that must be run for both successes and failures:
# use TryFrom; # use ; # use ; # # ; # # # # #fn map_request<F, NewRequest>(self: Self, f: F) -> MapRequest<Self, F> where Self: Sized, F: FnMut(NewRequest) -> RequestComposes a function in front of the service.
This adapter produces a new service that passes each value through the given function
fbefore sending it toself.Example
# use TryFrom; # use ; # use ; # # ; # # # # #fn filter<F, NewRequest>(self: Self, filter: F) -> crate::filter::Filter<Self, F> where Self: Sized, F: crate::filter::Predicate<NewRequest>Composes this service with a
Filterthat conditionally accepts or rejects requests based on a predicate.This adapter produces a new service that passes each value through the given function
predicatebefore sending it toself.Example
# use TryFrom; # use ; # use ; # # ; # # # # # # # # #fn filter_async<F, NewRequest>(self: Self, filter: F) -> crate::filter::AsyncFilter<Self, F> where Self: Sized, F: crate::filter::AsyncPredicate<NewRequest>Composes this service with an
AsyncFilterthat conditionally accepts or rejects requests based on an [async predicate].This adapter produces a new service that passes each value through the given function
predicatebefore sending it toself.Example
# use TryFrom; # use ; # use ; # # ; # # # # # # # # #fn then<F, Response, Error, Fut>(self: Self, f: F) -> Then<Self, F> where Self: Sized, Error: From<<Self as >::Error>, F: FnOnce(Result<<Self as >::Response, <Self as >::Error>) -> Fut + Clone, Fut: Future<Output = Result<Response, Error>>Composes an asynchronous function after this service.
This takes a function or closure returning a future, and returns a new
Servicethat chains that function after this service'sFuture. The newService's future will consist of this service's future, followed by the future returned by calling the chained function with the future'sOutputtype. The chained function is called regardless of whether this service's future completes with a successful response or with an error.This method can be thought of as an equivalent to the
futurescrate'sFutureExt::thencombinator, but acting onServices that return futures, rather than on an individual future. Similarly to that combinator,ServiceExt::thencan be used to implement asynchronous error recovery, by calling some asynchronous function with errors returned by this service. Alternatively, it may also be used to call a fallible async function with the successful response of this service.This method can be used to change the
Responsetype of the service into a different type. It can also be used to change theErrortype of the service. However, because thethenfunction is not applied to the errors returned by the service'spoll_readymethod, it must be possible to convert the service'sErrortype into the error type returned by thethenfuture. This is trivial when the function returns the same error type as the service, but in other cases, it can be useful to useBoxErrorto erase differing error types.Examples
# use ; # use ; # # ; # # # type Record = ; # type DbError = ; # # # #fn map_future<F, Fut, Response, Error>(self: Self, f: F) -> MapFuture<Self, F> where Self: Sized, F: FnMut(<Self as >::Future) -> Fut, Error: From<<Self as >::Error>, Fut: Future<Output = Result<Response, Error>>Composes a function that transforms futures produced by the service.
This takes a function or closure returning a future computed from the future returned by the service's
callmethod, as opposed to the responses produced by the future.Examples
# use ; # use ; # # ; # # # type Record = ; # type DbError = crateBoxError; # # # #Note that normally you wouldn't implement timeouts like this and instead use
Timeout.fn boxed(self: Self) -> BoxService<Request, <Self as >::Response, <Self as >::Error> where Self: Sized + Send + 'static, <Self as >::Future: Send + 'staticConvert the service into a
Service+Sendtrait object.See
BoxServicefor more details.If
Selfimplements theClonetrait, theboxed_clonemethod can be used instead, to produce a boxed service which will also implementClone.Example
use ; # # ; # ; # let service = service_fn; let service: = service .map_request .map_response .boxed; # let service = assert_service; # # where S:fn boxed_clone(self: Self) -> BoxCloneService<Request, <Self as >::Response, <Self as >::Error> where Self: Clone + Sized + Send + 'static, <Self as >::Future: Send + 'staticConvert the service into a
Service+Clone+Sendtrait object.This is similar to the
boxedmethod, but it requires thatSelfimplementClone, and the returned boxed service implementsClone. SeeBoxCloneServicefor more details.Example
use ; # # ; # ; # let service = service_fn; let service: = service .map_request .map_response .boxed_clone; // The boxed service can still be cloned. service.clone; # let service = assert_service; # # where S:
Implementors
impl<T, Request> ServiceExt for PendingRequests<S, C>impl<T, Request> ServiceExt for LoadShed<S>impl<T, Request> ServiceExt for MapErr<S, F>impl<T, Request> ServiceExt for Timpl<T, Request> ServiceExt for Buffer<Req, F>impl<T, Request> ServiceExt for Balance<D, Req>impl<T, Request> ServiceExt for Constant<T, M>impl<T, Request> ServiceExt for MapRequest<S, F>impl<T, Request> ServiceExt for Shared<S>impl<T, Request> ServiceExt for MapResult<S, F>impl<T, Request> ServiceExt for Reconnect<M, Target>impl<T, Request> ServiceExt for MapFuture<S, F>impl<T, Request> ServiceExt for Retry<P, S>impl<T, Request> ServiceExt for AsyncFilter<T, U>impl<T, Request> ServiceExt for Steer<S, F, Req>impl<T, Request> ServiceExt for SpawnReady<S>impl<T, Request> ServiceExt for Filter<T, U>impl<T, Request> ServiceExt for BoxCloneService<T, U, E>impl<T, Request> ServiceExt for BoxService<T, U, E>impl<T, Request> ServiceExt for IntoService<M, Request>impl<T, Request> ServiceExt for Either<A, B>impl<T, Request> ServiceExt for Timeout<T>impl<T, Request> ServiceExt for RateLimit<T>impl<T, Request> ServiceExt for ServiceFn<T>impl<T, Request> ServiceExt for BoxCloneSyncService<T, U, E>impl<T, Request> ServiceExt for AndThen<S, F>impl<T, Request> ServiceExt for PeakEwma<S, C>impl<T, Request> ServiceExt for MapResponse<S, F>impl<T, Request> ServiceExt for Hedge<S, P>impl<T, Request> ServiceExt for ConcurrencyLimit<T>impl<T, Request> ServiceExt for FutureService<F, S>impl<T, Request> ServiceExt for Then<S, F>impl<T, Request> ServiceExt for MakeBalance<S, Req>impl<T, Request> ServiceExt for UnsyncBoxService<T, U, E>impl<T, Request> ServiceExt for Optional<T>impl<T, Request> ServiceExt for AsService<'a, M, Request>