[][src]Struct tower::ServiceBuilder

pub struct ServiceBuilder<L> { /* fields omitted */ }

Declaratively construct Service values.

ServiceBuilder provides a builder-like interface for composing layers to be applied to a Service.

Service

A Service is a trait representing an asynchronous function of a request to a response. It is similar to async fn(Request) -> Result<Response, Error>.

A Service is typically bound to a single transport, such as a TCP connection. It defines how all inbound or outbound requests are handled by that connection.

Order

The order in which layers are added impacts how requests are handled. Layers that are added first will be called with the request first. The argument to service will be last to see the request.

ServiceBuilder::new()
    .buffer(100)
    .concurrency_limit(10)
    .service(svc)

In the above example, the buffer layer receives the request first followed by concurrency_limit. buffer enables up to 100 request to be in-flight on top of the requests that have already been forwarded to the next layer. Combined with concurrency_limit, this allows up to 110 requests to be in-flight.

ServiceBuilder::new()
    .concurrency_limit(10)
    .buffer(100)
    .service(svc)

The above example is similar, but the order of layers is reversed. Now, concurrency_limit applies first and only allows 10 requests to be in-flight total.

Examples

A Service stack with a single layer:

ServiceBuilder::new()
    .concurrency_limit(5)
    .service(svc);

A Service stack with multiple layers that contain rate limiting, in-flight request limits, and a channel-backed, clonable Service:

ServiceBuilder::new()
    .buffer(5)
    .concurrency_limit(5)
    .rate_limit(5, Duration::from_secs(1))
    .service(svc);

Implementations

impl ServiceBuilder<Identity>[src]

pub fn new() -> Self[src]

Create a new ServiceBuilder.

impl<L> ServiceBuilder<L>[src]

pub fn layer<T>(self, layer: T) -> ServiceBuilder<Stack<T, L>>[src]

Add a new layer T into the ServiceBuilder.

This wraps the inner service with the service provided by a user-defined Layer. The provided layer must implement the Layer trait.

pub fn buffer<Request>(
    self,
    bound: usize
) -> ServiceBuilder<Stack<BufferLayer<Request>, L>>
[src]

This is supported on crate feature buffer only.

Buffer requests when when the next layer is not ready.

This wraps the inner service with an instance of the Buffer middleware.

pub fn concurrency_limit(
    self,
    max: usize
) -> ServiceBuilder<Stack<ConcurrencyLimitLayer, L>>
[src]

This is supported on crate feature limit only.

Limit the max number of in-flight requests.

A request is in-flight from the time the request is received until the response future completes. This includes the time spent in the next layers.

This wraps the inner service with an instance of the ConcurrencyLimit middleware.

pub fn load_shed(self) -> ServiceBuilder<Stack<LoadShedLayer, L>>[src]

This is supported on crate feature load-shed only.

Drop requests when the next layer is unable to respond to requests.

Usually, when a service or middleware does not have capacity to process a request (i.e., poll_ready returns Pending), the caller waits until capacity becomes available.

LoadShed immediately responds with an error when the next layer is out of capacity.

This wraps the inner service with an instance of the LoadShed middleware.

pub fn rate_limit(
    self,
    num: u64,
    per: Duration
) -> ServiceBuilder<Stack<RateLimitLayer, L>>
[src]

This is supported on crate feature limit only.

Limit requests to at most num per the given duration.

This wraps the inner service with an instance of the RateLimit middleware.

pub fn retry<P>(self, policy: P) -> ServiceBuilder<Stack<RetryLayer<P>, L>>[src]

This is supported on crate feature retry only.

Retry failed requests according to the given retry policy.

policy determines which failed requests will be retried. It must implement the retry::Policy trait.

This wraps the inner service with an instance of the Retry middleware.

pub fn timeout(
    self,
    timeout: Duration
) -> ServiceBuilder<Stack<TimeoutLayer, L>>
[src]

This is supported on crate feature timeout only.

Fail requests that take longer than timeout.

If the next layer takes more than timeout to respond to a request, processing is terminated and an error is returned.

This wraps the inner service with an instance of the timeout middleware.

pub fn filter<P>(self, predicate: P) -> ServiceBuilder<Stack<FilterLayer<P>, L>>[src]

This is supported on crate feature filter only.

Conditionally reject requests based on predicate.

predicate must implement the Predicate trait.

This wraps the inner service with an instance of the Filter middleware.

pub fn filter_async<P>(
    self,
    predicate: P
) -> ServiceBuilder<Stack<AsyncFilterLayer<P>, L>>
[src]

This is supported on crate feature filter only.

Conditionally reject requests based on an asynchronous predicate.

predicate must implement the AsyncPredicate trait.

This wraps the inner service with an instance of the AsyncFilter middleware.

pub fn map_request<F, R1, R2>(
    self,
    f: F
) -> ServiceBuilder<Stack<MapRequestLayer<F>, L>> where
    F: FnMut(R1) -> R2 + Clone
[src]

This is supported on crate feature util only.

Map one request type to another.

This wraps the inner service with an instance of the MapRequest middleware.

Examples

Changing the type of a request:

use tower::ServiceBuilder;
use tower::ServiceExt;

// Suppose we have some `Service` whose request type is `String`:
let string_svc = tower::service_fn(|request: String| async move {
    println!("request: {}", request);
    Ok(())
});

// ...but we want to call that service with a `usize`. What do we do?

let usize_svc = ServiceBuilder::new()
     // Add a middlware that converts the request type to a `String`:
    .map_request(|request: usize| format!("{}", request))
    // ...and wrap the string service with that middleware:
    .service(string_svc);

// Now, we can call that service with a `usize`:
usize_svc.oneshot(42).await?;

Modifying the request value:

use tower::ServiceBuilder;
use tower::ServiceExt;

// A service that takes a number and returns it:
let svc = tower::service_fn(|request: usize| async move {
   Ok(request)
});

let svc = ServiceBuilder::new()
     // Add a middleware that adds 1 to each request
    .map_request(|request: usize| request + 1)
    .service(svc);

let response = svc.oneshot(1).await?;
assert_eq!(response, 2);

pub fn map_response<F>(
    self,
    f: F
) -> ServiceBuilder<Stack<MapResponseLayer<F>, L>>
[src]

This is supported on crate feature util only.

Map one response type to another.

This wraps the inner service with an instance of the MapResponse middleware.

See the documentation for the map_response combinator for details.

pub fn map_err<F>(self, f: F) -> ServiceBuilder<Stack<MapErrLayer<F>, L>>[src]

This is supported on crate feature util only.

Map one error type to another.

This wraps the inner service with an instance of the MapErr middleware.

See the documentation for the map_err combinator for details.

pub fn then<F>(self, f: F) -> ServiceBuilder<Stack<ThenLayer<F>, L>>[src]

This is supported on crate feature util only.

Apply a function after the service, regardless of whether the future succeeds or fails.

This wraps the inner service with an instance of the Then middleware.

This is similar to the map_response and map_err functions, except that the same function is invoked when the service's future completes, whether it completes successfully or fails. This function takes the Result returned by the service's future, and returns a Result.

See the documentation for the then combinator for details.

pub fn into_inner(self) -> L[src]

Returns the underlying Layer implementation.

pub fn service<S>(&self, service: S) -> L::Service where
    L: Layer<S>, 
[src]

Wrap the service S with the middleware provided by this ServiceBuilder's Layer's, returning a new Service.

Trait Implementations

impl<L: Clone> Clone for ServiceBuilder<L>[src]

impl<L: Debug> Debug for ServiceBuilder<L>[src]

impl Default for ServiceBuilder<Identity>[src]

Auto Trait Implementations

impl<L> RefUnwindSafe for ServiceBuilder<L> where
    L: RefUnwindSafe
[src]

impl<L> Send for ServiceBuilder<L> where
    L: Send
[src]

impl<L> Sync for ServiceBuilder<L> where
    L: Sync
[src]

impl<L> Unpin for ServiceBuilder<L> where
    L: Unpin
[src]

impl<L> UnwindSafe for ServiceBuilder<L> where
    L: UnwindSafe
[src]

Blanket Implementations

impl<T> Any for T where
    T: 'static + ?Sized
[src]

impl<T> Borrow<T> for T where
    T: ?Sized
[src]

impl<T> BorrowMut<T> for T where
    T: ?Sized
[src]

impl<T> From<T> for T[src]

impl<T> Instrument for T[src]

impl<T, U> Into<U> for T where
    U: From<T>, 
[src]

impl<T> ToOwned for T where
    T: Clone
[src]

type Owned = T

The resulting type after obtaining ownership.

impl<T, U> TryFrom<U> for T where
    U: Into<T>, 
[src]

type Error = Infallible

The type returned in the event of a conversion error.

impl<T, U> TryInto<U> for T where
    U: TryFrom<T>, 
[src]

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.

impl<V, T> VZip<V> for T where
    V: MultiLane<T>,