Struct tower::ServiceBuilder
source · pub struct ServiceBuilder<L> { /* private fields */ }
Expand description
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§
source§impl ServiceBuilder<Identity>
impl ServiceBuilder<Identity>
sourcepub const fn new() -> Self
pub const fn new() -> Self
Create a new ServiceBuilder
.
source§impl<L> ServiceBuilder<L>
impl<L> ServiceBuilder<L>
sourcepub fn layer<T>(self, layer: T) -> ServiceBuilder<Stack<T, L>>
pub fn layer<T>(self, layer: T) -> ServiceBuilder<Stack<T, L>>
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.
sourcepub fn option_layer<T>(
self,
layer: Option<T>,
) -> ServiceBuilder<Stack<Either<T, Identity>, L>>
pub fn option_layer<T>( self, layer: Option<T>, ) -> ServiceBuilder<Stack<Either<T, Identity>, L>>
Optionally add a new layer T
into the ServiceBuilder
.
// Apply a timeout if configured
ServiceBuilder::new()
.option_layer(timeout.map(TimeoutLayer::new))
.service(svc)
sourcepub fn layer_fn<F>(self, f: F) -> ServiceBuilder<Stack<LayerFn<F>, L>>
pub fn layer_fn<F>(self, f: F) -> ServiceBuilder<Stack<LayerFn<F>, L>>
sourcepub fn map_request<F, R1, R2>(
self,
f: F,
) -> ServiceBuilder<Stack<MapRequestLayer<F>, L>>
pub fn map_request<F, R1, R2>( self, f: F, ) -> ServiceBuilder<Stack<MapRequestLayer<F>, L>>
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 middleware 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);
sourcepub fn map_response<F>(
self,
f: F,
) -> ServiceBuilder<Stack<MapResponseLayer<F>, L>>
pub fn map_response<F>( self, f: F, ) -> ServiceBuilder<Stack<MapResponseLayer<F>, L>>
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.
sourcepub fn map_err<F>(self, f: F) -> ServiceBuilder<Stack<MapErrLayer<F>, L>>
pub fn map_err<F>(self, f: F) -> ServiceBuilder<Stack<MapErrLayer<F>, L>>
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.
sourcepub fn map_future<F>(self, f: F) -> ServiceBuilder<Stack<MapFutureLayer<F>, L>>
pub fn map_future<F>(self, f: F) -> ServiceBuilder<Stack<MapFutureLayer<F>, L>>
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.
sourcepub fn then<F>(self, f: F) -> ServiceBuilder<Stack<ThenLayer<F>, L>>
pub fn then<F>(self, f: F) -> ServiceBuilder<Stack<ThenLayer<F>, L>>
Apply an asynchronous 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.
sourcepub fn and_then<F>(self, f: F) -> ServiceBuilder<Stack<AndThenLayer<F>, L>>
pub fn and_then<F>(self, f: F) -> ServiceBuilder<Stack<AndThenLayer<F>, L>>
Executes a new future after this service’s future resolves. This does
not alter the behaviour of the poll_ready
method.
This method can be used to change the Response
type 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.
This wraps the inner service with an instance of the AndThen
middleware.
See the documentation for the and_then
combinator for details.
sourcepub fn map_result<F>(self, f: F) -> ServiceBuilder<Stack<MapResultLayer<F>, L>>
pub fn map_result<F>(self, f: F) -> ServiceBuilder<Stack<MapResultLayer<F>, L>>
Maps this service’s result type (Result<Self::Response, Self::Error>
)
to a different value, regardless of whether the future succeeds or
fails.
This wraps the inner service with an instance of the MapResult
middleware.
See the documentation for the map_result
combinator for details.
sourcepub fn into_inner(self) -> L
pub fn into_inner(self) -> L
Returns the underlying Layer
implementation.
sourcepub fn service<S>(&self, service: S) -> L::Servicewhere
L: Layer<S>,
pub fn service<S>(&self, service: S) -> L::Servicewhere
L: Layer<S>,
Wrap the service S
with the middleware provided by this
ServiceBuilder
’s Layer
’s, returning a new Service
.
sourcepub fn service_fn<F>(self, f: F) -> L::Service
pub fn service_fn<F>(self, f: F) -> L::Service
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");
sourcepub fn check_clone(self) -> Selfwhere
Self: Clone,
pub fn check_clone(self) -> Selfwhere
Self: Clone,
Check that the builder implements Clone
.
This can be useful when debugging type errors in ServiceBuilder
s with lots of layers.
Doesn’t actually change the builder but serves as a type check.
§Example
use tower::ServiceBuilder;
let builder = ServiceBuilder::new()
// Do something before processing the request
.map_request(|request: String| {
println!("got request!");
request
})
// Ensure our `ServiceBuilder` can be cloned
.check_clone()
// Do something after processing the request
.map_response(|response: String| {
println!("got response!");
response
});
sourcepub fn check_service_clone<S>(self) -> Self
pub fn check_service_clone<S>(self) -> Self
Check that the builder when given a service of type S
produces a service that implements
Clone
.
This can be useful when debugging type errors in ServiceBuilder
s with lots of layers.
Doesn’t actually change the builder but serves as a type check.
§Example
use tower::ServiceBuilder;
let builder = ServiceBuilder::new()
// Do something before processing the request
.map_request(|request: String| {
println!("got request!");
request
})
// Ensure that the service produced when given a `MyService` implements
.check_service_clone::<MyService>()
// Do something after processing the request
.map_response(|response: String| {
println!("got response!");
response
});
sourcepub fn check_service<S, T, U, E>(self) -> Self
pub fn check_service<S, T, U, E>(self) -> Self
Check that the builder when given a service of type S
produces a service with the given
request, response, and error types.
This can be useful when debugging type errors in ServiceBuilder
s with lots of layers.
Doesn’t actually change the builder but serves as a type check.
§Example
use tower::ServiceBuilder;
use std::task::{Poll, Context};
use tower::{Service, ServiceExt};
// An example service
struct MyService;
impl Service<Request> for MyService {
type Response = Response;
type Error = Error;
type Future = futures_util::future::Ready<Result<Response, Error>>;
fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
// ...
}
fn call(&mut self, request: Request) -> Self::Future {
// ...
}
}
struct Request;
struct Response;
struct Error;
struct WrappedResponse(Response);
let builder = ServiceBuilder::new()
// At this point in the builder if given a `MyService` it produces a service that
// accepts `Request`s, produces `Response`s, and fails with `Error`s
.check_service::<MyService, Request, Response, Error>()
// Wrap responses in `WrappedResponse`
.map_response(|response: Response| WrappedResponse(response))
// Now the response type will be `WrappedResponse`
.check_service::<MyService, _, WrappedResponse, _>();
sourcepub fn boxed<S, R>(
self,
) -> ServiceBuilder<Stack<LayerFn<fn(_: L::Service) -> BoxService<R, <L::Service as Service<R>>::Response, <L::Service as Service<R>>::Error>>, L>>
pub fn boxed<S, R>( self, ) -> ServiceBuilder<Stack<LayerFn<fn(_: L::Service) -> BoxService<R, <L::Service as Service<R>>::Response, <L::Service as Service<R>>::Error>>, L>>
This wraps the inner service with the Layer
returned by BoxService::layer()
.
See that method for more details.
§Example
use tower::{Service, ServiceBuilder, BoxError, util::BoxService};
use std::time::Duration;
let service: BoxService<Request, Response, BoxError> = ServiceBuilder::new()
.boxed()
.load_shed()
.concurrency_limit(64)
.timeout(Duration::from_secs(10))
.service_fn(|req: Request| async {
Ok::<_, BoxError>(Response::new())
});
sourcepub fn boxed_clone<S, R>(
self,
) -> ServiceBuilder<Stack<LayerFn<fn(_: L::Service) -> BoxCloneService<R, <L::Service as Service<R>>::Response, <L::Service as Service<R>>::Error>>, L>>
pub fn boxed_clone<S, R>( self, ) -> ServiceBuilder<Stack<LayerFn<fn(_: L::Service) -> BoxCloneService<R, <L::Service as Service<R>>::Response, <L::Service as Service<R>>::Error>>, L>>
This wraps the inner service with the Layer
returned by BoxCloneService::layer()
.
This is similar to the boxed
method, but it requires that Self
implement
Clone
, and the returned boxed service implements Clone
.
See BoxCloneService
for more details.
§Example
use tower::{Service, ServiceBuilder, BoxError, util::BoxCloneService};
use std::time::Duration;
let service: BoxCloneService<Request, Response, BoxError> = ServiceBuilder::new()
.boxed_clone()
.load_shed()
.concurrency_limit(64)
.timeout(Duration::from_secs(10))
.service_fn(|req: Request| async {
Ok::<_, BoxError>(Response::new())
});
// The boxed service can still be cloned.
service.clone();
Trait Implementations§
source§impl<L: Clone> Clone for ServiceBuilder<L>
impl<L: Clone> Clone for ServiceBuilder<L>
source§fn clone(&self) -> ServiceBuilder<L>
fn clone(&self) -> ServiceBuilder<L>
1.0.0 · source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read moresource§impl<L: Debug> Debug for ServiceBuilder<L>
impl<L: Debug> Debug for ServiceBuilder<L>
source§impl Default for ServiceBuilder<Identity>
impl Default for ServiceBuilder<Identity>
Auto Trait Implementations§
impl<L> Freeze for ServiceBuilder<L>where
L: Freeze,
impl<L> RefUnwindSafe for ServiceBuilder<L>where
L: RefUnwindSafe,
impl<L> Send for ServiceBuilder<L>where
L: Send,
impl<L> Sync for ServiceBuilder<L>where
L: Sync,
impl<L> Unpin for ServiceBuilder<L>where
L: Unpin,
impl<L> UnwindSafe for ServiceBuilder<L>where
L: UnwindSafe,
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
source§unsafe fn clone_to_uninit(&self, dst: *mut T)
unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)