Struct tower::builder::ServiceBuilder [−][src]
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 option_layer<T>(
self,
layer: Option<T>
) -> ServiceBuilder<Stack<Either<T, Identity>, L>>
[src]
self,
layer: Option<T>
) -> ServiceBuilder<Stack<Either<T, Identity>, L>>
util
only.Optionally add a new layer T
into the ServiceBuilder
.
// Apply a timeout if configured ServiceBuilder::new() .option_layer(timeout.map(TimeoutLayer::new)) .service(svc)
pub fn layer_fn<F>(self, f: F) -> ServiceBuilder<Stack<LayerFn<F>, L>>
[src]
Add a Layer
built from a function that accepts a service and returns another service.
See the documentation for layer_fn
for more details.
pub fn buffer<Request>(
self,
bound: usize
) -> ServiceBuilder<Stack<BufferLayer<Request>, L>>
[src]
self,
bound: usize
) -> ServiceBuilder<Stack<BufferLayer<Request>, L>>
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]
self,
max: usize
) -> ServiceBuilder<Stack<ConcurrencyLimitLayer, L>>
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]
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]
self,
num: u64,
per: Duration
) -> ServiceBuilder<Stack<RateLimitLayer, L>>
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]
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]
self,
timeout: Duration
) -> ServiceBuilder<Stack<TimeoutLayer, L>>
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]
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]
self,
predicate: P
) -> ServiceBuilder<Stack<AsyncFilterLayer<P>, L>>
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]
self,
f: F
) -> ServiceBuilder<Stack<MapRequestLayer<F>, L>> where
F: FnMut(R1) -> R2 + Clone,
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]
self,
f: F
) -> ServiceBuilder<Stack<MapResponseLayer<F>, L>>
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]
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 map_future<F>(self, f: F) -> ServiceBuilder<Stack<MapFutureLayer<F>, L>>
[src]
util
only.Composes a function that transforms futures produced by the service.
This wraps the inner service with an instance of the MapFutureLayer
middleware.
See the documentation for the map_future
combinator for details.
pub fn then<F>(self, f: F) -> ServiceBuilder<Stack<ThenLayer<F>, L>>
[src]
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]
L: Layer<S>,
Wrap the service S
with the middleware provided by this
ServiceBuilder
’s Layer
’s, returning a new Service
.
pub fn service_fn<F>(self, f: F) -> L::Service where
L: Layer<ServiceFn<F>>,
[src]
L: Layer<ServiceFn<F>>,
util
only.Wrap the async function F
with the middleware provided by this ServiceBuilder
’s
Layer
s, returning a new Service
.
This is a convenience method which is equivalent to calling
ServiceBuilder::service
with a service_fn
, like this:
ServiceBuilder::new() // ... .service(service_fn(handler_fn))
Example
use std::time::Duration; use tower::{ServiceBuilder, ServiceExt, BoxError, service_fn}; async fn handle(request: &'static str) -> Result<&'static str, BoxError> { Ok(request) } let svc = ServiceBuilder::new() .buffer(1024) .timeout(Duration::from_secs(10)) .service_fn(handle); let response = svc.oneshot("foo").await?; assert_eq!(response, "foo");
Trait Implementations
impl<L: Clone> Clone for ServiceBuilder<L>
[src]
fn clone(&self) -> ServiceBuilder<L>
[src]
pub fn clone_from(&mut self, source: &Self)
1.0.0[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,
L: RefUnwindSafe,
impl<L> Send for ServiceBuilder<L> where
L: Send,
L: Send,
impl<L> Sync for ServiceBuilder<L> where
L: Sync,
L: Sync,
impl<L> Unpin for ServiceBuilder<L> where
L: Unpin,
L: Unpin,
impl<L> UnwindSafe for ServiceBuilder<L> where
L: UnwindSafe,
L: UnwindSafe,
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
pub fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> From<T> for T
[src]
impl<T> Instrument for T
[src]
pub fn instrument(self, span: Span) -> Instrumented<Self>
[src]
pub fn in_current_span(self) -> Instrumented<Self>
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T> ToOwned for T where
T: Clone,
[src]
T: Clone,
type Owned = T
The resulting type after obtaining ownership.
pub fn to_owned(&self) -> T
[src]
pub fn clone_into(&self, target: &mut T)
[src]
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,
type Error = <U as TryFrom<T>>::Error
The type returned in the event of a conversion error.
pub fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
[src]
impl<V, T> VZip<V> for T where
V: MultiLane<T>,
V: MultiLane<T>,