Struct ServiceBuilder

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

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>

pub const fn new() -> Self

Create a new ServiceBuilder.

impl<L> ServiceBuilder<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.

pub fn layer_fn<F>(self, f: F) -> ServiceBuilder<Stack<LayerFn<F>, L>>

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 into_inner(self) -> L

Returns the underlying Layer implementation.

pub fn service<S>(&self, service: S) -> L::Service

where L: Layer<S>,

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

pub fn check_clone(self) -> Self

where Self: Clone,

Check that the builder implements Clone.

This can be useful when debugging type errors in ServiceBuilders 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
    });

pub fn check_service_clone<S>(self) -> Self

where L: Layer<S>, L::Service: Clone,

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 ServiceBuilders 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
    });

pub fn check_service<S, T, U, E>(self) -> Self

where L: Layer<S>, L::Service: Service<T, Response = U, Error = E>,

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 ServiceBuilders 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, _>();

Trait Implementations

impl<L: Clone> Clone for ServiceBuilder<L>

fn clone(&self) -> ServiceBuilder<L>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<L: Debug> Debug for ServiceBuilder<L>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ServiceBuilder<Identity>

fn default() -> Self

Returns the “default value” for a type.

impl<S, L> Layer<S> for ServiceBuilder<L>

where L: Layer<S>,

type Service = <L as Layer<S>>::Service

The wrapped service

fn layer(&self, inner: S) -> Self::Service

Wrap the given service with the middleware, returning a new service that has been decorated with the middleware.