tower/builder/mod.rs
1//! Builder types to compose layers and services
2
3use tower_layer::{Identity, Layer, Stack};
4use tower_service::Service;
5
6use std::fmt;
7
8/// Declaratively construct [`Service`] values.
9///
10/// [`ServiceBuilder`] provides a [builder-like interface][builder] for composing
11/// layers to be applied to a [`Service`].
12///
13/// # Service
14///
15/// A [`Service`] is a trait representing an asynchronous function of a request
16/// to a response. It is similar to `async fn(Request) -> Result<Response, Error>`.
17///
18/// A [`Service`] is typically bound to a single transport, such as a TCP
19/// connection. It defines how _all_ inbound or outbound requests are handled
20/// by that connection.
21///
22/// [builder]: https://doc.rust-lang.org/1.0.0/style/ownership/builders.html
23///
24/// # Order
25///
26/// The order in which layers are added impacts how requests are handled. Layers
27/// that are added first will be called with the request first. The argument to
28/// `service` will be last to see the request.
29///
30/// ```
31/// # // this (and other) doctest is ignored because we don't have a way
32/// # // to say that it should only be run with cfg(feature = "...")
33/// # use tower::Service;
34/// # use tower::builder::ServiceBuilder;
35/// # #[cfg(all(feature = "buffer", feature = "limit"))]
36/// # async fn wrap<S>(svc: S) where S: Service<(), Error = &'static str> + 'static + Send, S::Future: Send {
37/// ServiceBuilder::new()
38/// .buffer(100)
39/// .concurrency_limit(10)
40/// .service(svc)
41/// # ;
42/// # }
43/// ```
44///
45/// In the above example, the buffer layer receives the request first followed
46/// by `concurrency_limit`. `buffer` enables up to 100 request to be in-flight
47/// **on top of** the requests that have already been forwarded to the next
48/// layer. Combined with `concurrency_limit`, this allows up to 110 requests to be
49/// in-flight.
50///
51/// ```
52/// # use tower::Service;
53/// # use tower::builder::ServiceBuilder;
54/// # #[cfg(all(feature = "buffer", feature = "limit"))]
55/// # async fn wrap<S>(svc: S) where S: Service<(), Error = &'static str> + 'static + Send, S::Future: Send {
56/// ServiceBuilder::new()
57/// .concurrency_limit(10)
58/// .buffer(100)
59/// .service(svc)
60/// # ;
61/// # }
62/// ```
63///
64/// The above example is similar, but the order of layers is reversed. Now,
65/// `concurrency_limit` applies first and only allows 10 requests to be in-flight
66/// total.
67///
68/// # Examples
69///
70/// A [`Service`] stack with a single layer:
71///
72/// ```
73/// # use tower::Service;
74/// # use tower::builder::ServiceBuilder;
75/// # #[cfg(feature = "limit")]
76/// # use tower::limit::concurrency::ConcurrencyLimitLayer;
77/// # #[cfg(feature = "limit")]
78/// # async fn wrap<S>(svc: S) where S: Service<(), Error = &'static str> + 'static + Send, S::Future: Send {
79/// ServiceBuilder::new()
80/// .concurrency_limit(5)
81/// .service(svc);
82/// # ;
83/// # }
84/// ```
85///
86/// A [`Service`] stack with _multiple_ layers that contain rate limiting,
87/// in-flight request limits, and a channel-backed, clonable [`Service`]:
88///
89/// ```
90/// # use tower::Service;
91/// # use tower::builder::ServiceBuilder;
92/// # use std::time::Duration;
93/// # #[cfg(all(feature = "buffer", feature = "limit"))]
94/// # async fn wrap<S>(svc: S) where S: Service<(), Error = &'static str> + 'static + Send, S::Future: Send {
95/// ServiceBuilder::new()
96/// .buffer(5)
97/// .concurrency_limit(5)
98/// .rate_limit(5, Duration::from_secs(1))
99/// .service(svc);
100/// # ;
101/// # }
102/// ```
103///
104/// [`Service`]: crate::Service
105#[derive(Clone)]
106pub struct ServiceBuilder<L> {
107 layer: L,
108}
109
110impl Default for ServiceBuilder<Identity> {
111 fn default() -> Self {
112 Self::new()
113 }
114}
115
116impl ServiceBuilder<Identity> {
117 /// Create a new [`ServiceBuilder`].
118 pub fn new() -> Self {
119 ServiceBuilder {
120 layer: Identity::new(),
121 }
122 }
123}
124
125impl<L> ServiceBuilder<L> {
126 /// Add a new layer `T` into the [`ServiceBuilder`].
127 ///
128 /// This wraps the inner service with the service provided by a user-defined
129 /// [`Layer`]. The provided layer must implement the [`Layer`] trait.
130 ///
131 /// [`Layer`]: crate::Layer
132 pub fn layer<T>(self, layer: T) -> ServiceBuilder<Stack<T, L>> {
133 ServiceBuilder {
134 layer: Stack::new(layer, self.layer),
135 }
136 }
137
138 /// Optionally add a new layer `T` into the [`ServiceBuilder`].
139 ///
140 /// ```
141 /// # use std::time::Duration;
142 /// # use tower::Service;
143 /// # use tower::builder::ServiceBuilder;
144 /// # use tower::timeout::TimeoutLayer;
145 /// # async fn wrap<S>(svc: S) where S: Service<(), Error = &'static str> + 'static + Send, S::Future: Send {
146 /// # let timeout = Some(Duration::new(10, 0));
147 /// // Apply a timeout if configured
148 /// ServiceBuilder::new()
149 /// .option_layer(timeout.map(TimeoutLayer::new))
150 /// .service(svc)
151 /// # ;
152 /// # }
153 /// ```
154 #[cfg(feature = "util")]
155 #[cfg_attr(docsrs, doc(cfg(feature = "util")))]
156 pub fn option_layer<T>(
157 self,
158 layer: Option<T>,
159 ) -> ServiceBuilder<Stack<crate::util::Either<T, Identity>, L>> {
160 self.layer(crate::util::option_layer(layer))
161 }
162
163 /// Add a [`Layer`] built from a function that accepts a service and returns another service.
164 ///
165 /// See the documentation for [`layer_fn`] for more details.
166 ///
167 /// [`layer_fn`]: crate::layer::layer_fn
168 pub fn layer_fn<F>(self, f: F) -> ServiceBuilder<Stack<crate::layer::LayerFn<F>, L>> {
169 self.layer(crate::layer::layer_fn(f))
170 }
171
172 /// Buffer requests when the next layer is not ready.
173 ///
174 /// This wraps the inner service with an instance of the [`Buffer`]
175 /// middleware.
176 ///
177 /// [`Buffer`]: crate::buffer
178 #[cfg(feature = "buffer")]
179 #[cfg_attr(docsrs, doc(cfg(feature = "buffer")))]
180 pub fn buffer<Request>(
181 self,
182 bound: usize,
183 ) -> ServiceBuilder<Stack<crate::buffer::BufferLayer<Request>, L>> {
184 self.layer(crate::buffer::BufferLayer::new(bound))
185 }
186
187 /// Limit the max number of in-flight requests.
188 ///
189 /// A request is in-flight from the time the request is received until the
190 /// response future completes. This includes the time spent in the next
191 /// layers.
192 ///
193 /// This wraps the inner service with an instance of the
194 /// [`ConcurrencyLimit`] middleware.
195 ///
196 /// [`ConcurrencyLimit`]: crate::limit::concurrency
197 #[cfg(feature = "limit")]
198 #[cfg_attr(docsrs, doc(cfg(feature = "limit")))]
199 pub fn concurrency_limit(
200 self,
201 max: usize,
202 ) -> ServiceBuilder<Stack<crate::limit::ConcurrencyLimitLayer, L>> {
203 self.layer(crate::limit::ConcurrencyLimitLayer::new(max))
204 }
205
206 /// Drop requests when the next layer is unable to respond to requests.
207 ///
208 /// Usually, when a service or middleware does not have capacity to process a
209 /// request (i.e., [`poll_ready`] returns [`Pending`]), the caller waits until
210 /// capacity becomes available.
211 ///
212 /// [`LoadShed`] immediately responds with an error when the next layer is
213 /// out of capacity.
214 ///
215 /// This wraps the inner service with an instance of the [`LoadShed`]
216 /// middleware.
217 ///
218 /// [`LoadShed`]: crate::load_shed
219 /// [`poll_ready`]: crate::Service::poll_ready
220 /// [`Pending`]: std::task::Poll::Pending
221 #[cfg(feature = "load-shed")]
222 #[cfg_attr(docsrs, doc(cfg(feature = "load-shed")))]
223 pub fn load_shed(self) -> ServiceBuilder<Stack<crate::load_shed::LoadShedLayer, L>> {
224 self.layer(crate::load_shed::LoadShedLayer::new())
225 }
226
227 /// Limit requests to at most `num` per the given duration.
228 ///
229 /// This wraps the inner service with an instance of the [`RateLimit`]
230 /// middleware.
231 ///
232 /// [`RateLimit`]: crate::limit::rate
233 #[cfg(feature = "limit")]
234 #[cfg_attr(docsrs, doc(cfg(feature = "limit")))]
235 pub fn rate_limit(
236 self,
237 num: u64,
238 per: std::time::Duration,
239 ) -> ServiceBuilder<Stack<crate::limit::RateLimitLayer, L>> {
240 self.layer(crate::limit::RateLimitLayer::new(num, per))
241 }
242
243 /// Retry failed requests according to the given [retry policy][policy].
244 ///
245 /// `policy` determines which failed requests will be retried. It must
246 /// implement the [`retry::Policy`][policy] trait.
247 ///
248 /// This wraps the inner service with an instance of the [`Retry`]
249 /// middleware.
250 ///
251 /// [`Retry`]: crate::retry
252 /// [policy]: crate::retry::Policy
253 #[cfg(feature = "retry")]
254 #[cfg_attr(docsrs, doc(cfg(feature = "retry")))]
255 pub fn retry<P>(self, policy: P) -> ServiceBuilder<Stack<crate::retry::RetryLayer<P>, L>> {
256 self.layer(crate::retry::RetryLayer::new(policy))
257 }
258
259 /// Fail requests that take longer than `timeout`.
260 ///
261 /// If the next layer takes more than `timeout` to respond to a request,
262 /// processing is terminated and an error is returned.
263 ///
264 /// This wraps the inner service with an instance of the [`timeout`]
265 /// middleware.
266 ///
267 /// [`timeout`]: crate::timeout
268 #[cfg(feature = "timeout")]
269 #[cfg_attr(docsrs, doc(cfg(feature = "timeout")))]
270 pub fn timeout(
271 self,
272 timeout: std::time::Duration,
273 ) -> ServiceBuilder<Stack<crate::timeout::TimeoutLayer, L>> {
274 self.layer(crate::timeout::TimeoutLayer::new(timeout))
275 }
276
277 /// Conditionally reject requests based on `predicate`.
278 ///
279 /// `predicate` must implement the [`Predicate`] trait.
280 ///
281 /// This wraps the inner service with an instance of the [`Filter`]
282 /// middleware.
283 ///
284 /// [`Filter`]: crate::filter
285 /// [`Predicate`]: crate::filter::Predicate
286 #[cfg(feature = "filter")]
287 #[cfg_attr(docsrs, doc(cfg(feature = "filter")))]
288 pub fn filter<P>(
289 self,
290 predicate: P,
291 ) -> ServiceBuilder<Stack<crate::filter::FilterLayer<P>, L>> {
292 self.layer(crate::filter::FilterLayer::new(predicate))
293 }
294
295 /// Conditionally reject requests based on an asynchronous `predicate`.
296 ///
297 /// `predicate` must implement the [`AsyncPredicate`] trait.
298 ///
299 /// This wraps the inner service with an instance of the [`AsyncFilter`]
300 /// middleware.
301 ///
302 /// [`AsyncFilter`]: crate::filter::AsyncFilter
303 /// [`AsyncPredicate`]: crate::filter::AsyncPredicate
304 #[cfg(feature = "filter")]
305 #[cfg_attr(docsrs, doc(cfg(feature = "filter")))]
306 pub fn filter_async<P>(
307 self,
308 predicate: P,
309 ) -> ServiceBuilder<Stack<crate::filter::AsyncFilterLayer<P>, L>> {
310 self.layer(crate::filter::AsyncFilterLayer::new(predicate))
311 }
312
313 /// Map one request type to another.
314 ///
315 /// This wraps the inner service with an instance of the [`MapRequest`]
316 /// middleware.
317 ///
318 /// # Examples
319 ///
320 /// Changing the type of a request:
321 ///
322 /// ```rust
323 /// use tower::ServiceBuilder;
324 /// use tower::ServiceExt;
325 ///
326 /// # #[tokio::main]
327 /// # async fn main() -> Result<(), ()> {
328 /// // Suppose we have some `Service` whose request type is `String`:
329 /// let string_svc = tower::service_fn(|request: String| async move {
330 /// println!("request: {}", request);
331 /// Ok(())
332 /// });
333 ///
334 /// // ...but we want to call that service with a `usize`. What do we do?
335 ///
336 /// let usize_svc = ServiceBuilder::new()
337 /// // Add a middlware that converts the request type to a `String`:
338 /// .map_request(|request: usize| format!("{}", request))
339 /// // ...and wrap the string service with that middleware:
340 /// .service(string_svc);
341 ///
342 /// // Now, we can call that service with a `usize`:
343 /// usize_svc.oneshot(42).await?;
344 /// # Ok(())
345 /// # }
346 /// ```
347 ///
348 /// Modifying the request value:
349 ///
350 /// ```rust
351 /// use tower::ServiceBuilder;
352 /// use tower::ServiceExt;
353 ///
354 /// # #[tokio::main]
355 /// # async fn main() -> Result<(), ()> {
356 /// // A service that takes a number and returns it:
357 /// let svc = tower::service_fn(|request: usize| async move {
358 /// Ok(request)
359 /// });
360 ///
361 /// let svc = ServiceBuilder::new()
362 /// // Add a middleware that adds 1 to each request
363 /// .map_request(|request: usize| request + 1)
364 /// .service(svc);
365 ///
366 /// let response = svc.oneshot(1).await?;
367 /// assert_eq!(response, 2);
368 /// # Ok(())
369 /// # }
370 /// ```
371 ///
372 /// [`MapRequest`]: crate::util::MapRequest
373 #[cfg(feature = "util")]
374 #[cfg_attr(docsrs, doc(cfg(feature = "util")))]
375 pub fn map_request<F, R1, R2>(
376 self,
377 f: F,
378 ) -> ServiceBuilder<Stack<crate::util::MapRequestLayer<F>, L>>
379 where
380 F: FnMut(R1) -> R2 + Clone,
381 {
382 self.layer(crate::util::MapRequestLayer::new(f))
383 }
384
385 /// Map one response type to another.
386 ///
387 /// This wraps the inner service with an instance of the [`MapResponse`]
388 /// middleware.
389 ///
390 /// See the documentation for the [`map_response` combinator] for details.
391 ///
392 /// [`MapResponse`]: crate::util::MapResponse
393 /// [`map_response` combinator]: crate::util::ServiceExt::map_response
394 #[cfg(feature = "util")]
395 #[cfg_attr(docsrs, doc(cfg(feature = "util")))]
396 pub fn map_response<F>(
397 self,
398 f: F,
399 ) -> ServiceBuilder<Stack<crate::util::MapResponseLayer<F>, L>> {
400 self.layer(crate::util::MapResponseLayer::new(f))
401 }
402
403 /// Map one error type to another.
404 ///
405 /// This wraps the inner service with an instance of the [`MapErr`]
406 /// middleware.
407 ///
408 /// See the documentation for the [`map_err` combinator] for details.
409 ///
410 /// [`MapErr`]: crate::util::MapErr
411 /// [`map_err` combinator]: crate::util::ServiceExt::map_err
412 #[cfg(feature = "util")]
413 #[cfg_attr(docsrs, doc(cfg(feature = "util")))]
414 pub fn map_err<F>(self, f: F) -> ServiceBuilder<Stack<crate::util::MapErrLayer<F>, L>> {
415 self.layer(crate::util::MapErrLayer::new(f))
416 }
417
418 /// Composes a function that transforms futures produced by the service.
419 ///
420 /// This wraps the inner service with an instance of the [`MapFutureLayer`] middleware.
421 ///
422 /// See the documentation for the [`map_future`] combinator for details.
423 ///
424 /// [`MapFutureLayer`]: crate::util::MapFutureLayer
425 /// [`map_future`]: crate::util::ServiceExt::map_future
426 #[cfg(feature = "util")]
427 #[cfg_attr(docsrs, doc(cfg(feature = "util")))]
428 pub fn map_future<F>(self, f: F) -> ServiceBuilder<Stack<crate::util::MapFutureLayer<F>, L>> {
429 self.layer(crate::util::MapFutureLayer::new(f))
430 }
431
432 /// Apply an asynchronous function after the service, regardless of whether the future
433 /// succeeds or fails.
434 ///
435 /// This wraps the inner service with an instance of the [`Then`]
436 /// middleware.
437 ///
438 /// This is similar to the [`map_response`] and [`map_err`] functions,
439 /// except that the *same* function is invoked when the service's future
440 /// completes, whether it completes successfully or fails. This function
441 /// takes the [`Result`] returned by the service's future, and returns a
442 /// [`Result`].
443 ///
444 /// See the documentation for the [`then` combinator] for details.
445 ///
446 /// [`Then`]: crate::util::Then
447 /// [`then` combinator]: crate::util::ServiceExt::then
448 /// [`map_response`]: ServiceBuilder::map_response
449 /// [`map_err`]: ServiceBuilder::map_err
450 #[cfg(feature = "util")]
451 #[cfg_attr(docsrs, doc(cfg(feature = "util")))]
452 pub fn then<F>(self, f: F) -> ServiceBuilder<Stack<crate::util::ThenLayer<F>, L>> {
453 self.layer(crate::util::ThenLayer::new(f))
454 }
455
456 /// Executes a new future after this service's future resolves. This does
457 /// not alter the behaviour of the [`poll_ready`] method.
458 ///
459 /// This method can be used to change the [`Response`] type of the service
460 /// into a different type. You can use this method to chain along a computation once the
461 /// service's response has been resolved.
462 ///
463 /// This wraps the inner service with an instance of the [`AndThen`]
464 /// middleware.
465 ///
466 /// See the documentation for the [`and_then` combinator] for details.
467 ///
468 /// [`Response`]: crate::Service::Response
469 /// [`poll_ready`]: crate::Service::poll_ready
470 /// [`and_then` combinator]: crate::util::ServiceExt::and_then
471 /// [`AndThen`]: crate::util::AndThen
472 #[cfg(feature = "util")]
473 #[cfg_attr(docsrs, doc(cfg(feature = "util")))]
474 pub fn and_then<F>(self, f: F) -> ServiceBuilder<Stack<crate::util::AndThenLayer<F>, L>> {
475 self.layer(crate::util::AndThenLayer::new(f))
476 }
477
478 /// Maps this service's result type (`Result<Self::Response, Self::Error>`)
479 /// to a different value, regardless of whether the future succeeds or
480 /// fails.
481 ///
482 /// This wraps the inner service with an instance of the [`MapResult`]
483 /// middleware.
484 ///
485 /// See the documentation for the [`map_result` combinator] for details.
486 ///
487 /// [`map_result` combinator]: crate::util::ServiceExt::map_result
488 /// [`MapResult`]: crate::util::MapResult
489 #[cfg(feature = "util")]
490 #[cfg_attr(docsrs, doc(cfg(feature = "util")))]
491 pub fn map_result<F>(self, f: F) -> ServiceBuilder<Stack<crate::util::MapResultLayer<F>, L>> {
492 self.layer(crate::util::MapResultLayer::new(f))
493 }
494
495 /// Returns the underlying `Layer` implementation.
496 pub fn into_inner(self) -> L {
497 self.layer
498 }
499
500 /// Wrap the service `S` with the middleware provided by this
501 /// [`ServiceBuilder`]'s [`Layer`]'s, returning a new [`Service`].
502 ///
503 /// [`Layer`]: crate::Layer
504 /// [`Service`]: crate::Service
505 pub fn service<S>(&self, service: S) -> L::Service
506 where
507 L: Layer<S>,
508 {
509 self.layer.layer(service)
510 }
511
512 /// Wrap the async function `F` with the middleware provided by this [`ServiceBuilder`]'s
513 /// [`Layer`]s, returning a new [`Service`].
514 ///
515 /// This is a convenience method which is equivalent to calling
516 /// [`ServiceBuilder::service`] with a [`service_fn`], like this:
517 ///
518 /// ```rust
519 /// # use tower::{ServiceBuilder, service_fn};
520 /// # async fn handler_fn(_: ()) -> Result<(), ()> { Ok(()) }
521 /// # let _ = {
522 /// ServiceBuilder::new()
523 /// // ...
524 /// .service(service_fn(handler_fn))
525 /// # };
526 /// ```
527 ///
528 /// # Example
529 ///
530 /// ```rust
531 /// use std::time::Duration;
532 /// use tower::{ServiceBuilder, ServiceExt, BoxError, service_fn};
533 ///
534 /// # #[tokio::main]
535 /// # async fn main() -> Result<(), BoxError> {
536 /// async fn handle(request: &'static str) -> Result<&'static str, BoxError> {
537 /// Ok(request)
538 /// }
539 ///
540 /// let svc = ServiceBuilder::new()
541 /// .buffer(1024)
542 /// .timeout(Duration::from_secs(10))
543 /// .service_fn(handle);
544 ///
545 /// let response = svc.oneshot("foo").await?;
546 ///
547 /// assert_eq!(response, "foo");
548 /// # Ok(())
549 /// # }
550 /// ```
551 ///
552 /// [`Layer`]: crate::Layer
553 /// [`Service`]: crate::Service
554 /// [`service_fn`]: crate::service_fn
555 #[cfg(feature = "util")]
556 #[cfg_attr(docsrs, doc(cfg(feature = "util")))]
557 pub fn service_fn<F>(self, f: F) -> L::Service
558 where
559 L: Layer<crate::util::ServiceFn<F>>,
560 {
561 self.service(crate::util::service_fn(f))
562 }
563
564 /// Check that the builder implements `Clone`.
565 ///
566 /// This can be useful when debugging type errors in `ServiceBuilder`s with lots of layers.
567 ///
568 /// Doesn't actually change the builder but serves as a type check.
569 ///
570 /// # Example
571 ///
572 /// ```rust
573 /// use tower::ServiceBuilder;
574 ///
575 /// let builder = ServiceBuilder::new()
576 /// // Do something before processing the request
577 /// .map_request(|request: String| {
578 /// println!("got request!");
579 /// request
580 /// })
581 /// // Ensure our `ServiceBuilder` can be cloned
582 /// .check_clone()
583 /// // Do something after processing the request
584 /// .map_response(|response: String| {
585 /// println!("got response!");
586 /// response
587 /// });
588 /// ```
589 #[inline]
590 pub fn check_clone(self) -> Self
591 where
592 Self: Clone,
593 {
594 self
595 }
596
597 /// Check that the builder when given a service of type `S` produces a service that implements
598 /// `Clone`.
599 ///
600 /// This can be useful when debugging type errors in `ServiceBuilder`s with lots of layers.
601 ///
602 /// Doesn't actually change the builder but serves as a type check.
603 ///
604 /// # Example
605 ///
606 /// ```rust
607 /// use tower::ServiceBuilder;
608 ///
609 /// # #[derive(Clone)]
610 /// # struct MyService;
611 /// #
612 /// let builder = ServiceBuilder::new()
613 /// // Do something before processing the request
614 /// .map_request(|request: String| {
615 /// println!("got request!");
616 /// request
617 /// })
618 /// // Ensure that the service produced when given a `MyService` implements
619 /// .check_service_clone::<MyService>()
620 /// // Do something after processing the request
621 /// .map_response(|response: String| {
622 /// println!("got response!");
623 /// response
624 /// });
625 /// ```
626 #[inline]
627 pub fn check_service_clone<S>(self) -> Self
628 where
629 L: Layer<S>,
630 L::Service: Clone,
631 {
632 self
633 }
634
635 /// Check that the builder when given a service of type `S` produces a service with the given
636 /// request, response, and error types.
637 ///
638 /// This can be useful when debugging type errors in `ServiceBuilder`s with lots of layers.
639 ///
640 /// Doesn't actually change the builder but serves as a type check.
641 ///
642 /// # Example
643 ///
644 /// ```rust
645 /// use tower::ServiceBuilder;
646 /// use std::task::{Poll, Context};
647 /// use tower::{Service, ServiceExt};
648 ///
649 /// // An example service
650 /// struct MyService;
651 ///
652 /// impl Service<Request> for MyService {
653 /// type Response = Response;
654 /// type Error = Error;
655 /// type Future = futures_util::future::Ready<Result<Response, Error>>;
656 ///
657 /// fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
658 /// // ...
659 /// # todo!()
660 /// }
661 ///
662 /// fn call(&mut self, request: Request) -> Self::Future {
663 /// // ...
664 /// # todo!()
665 /// }
666 /// }
667 ///
668 /// struct Request;
669 /// struct Response;
670 /// struct Error;
671 ///
672 /// struct WrappedResponse(Response);
673 ///
674 /// let builder = ServiceBuilder::new()
675 /// // At this point in the builder if given a `MyService` it produces a service that
676 /// // accepts `Request`s, produces `Response`s, and fails with `Error`s
677 /// .check_service::<MyService, Request, Response, Error>()
678 /// // Wrap responses in `WrappedResponse`
679 /// .map_response(|response: Response| WrappedResponse(response))
680 /// // Now the response type will be `WrappedResponse`
681 /// .check_service::<MyService, _, WrappedResponse, _>();
682 /// ```
683 #[inline]
684 pub fn check_service<S, T, U, E>(self) -> Self
685 where
686 L: Layer<S>,
687 L::Service: Service<T, Response = U, Error = E>,
688 {
689 self
690 }
691
692 /// This wraps the inner service with the [`Layer`] returned by [`BoxService::layer()`].
693 ///
694 /// See that method for more details.
695 ///
696 /// # Example
697 ///
698 /// ```
699 /// use tower::{Service, ServiceBuilder, BoxError, util::BoxService};
700 /// use std::time::Duration;
701 /// #
702 /// # struct Request;
703 /// # struct Response;
704 /// # impl Response {
705 /// # fn new() -> Self { Self }
706 /// # }
707 ///
708 /// let service: BoxService<Request, Response, BoxError> = ServiceBuilder::new()
709 /// .boxed()
710 /// .load_shed()
711 /// .concurrency_limit(64)
712 /// .timeout(Duration::from_secs(10))
713 /// .service_fn(|req: Request| async {
714 /// Ok::<_, BoxError>(Response::new())
715 /// });
716 /// # let service = assert_service(service);
717 /// # fn assert_service<S, R>(svc: S) -> S
718 /// # where S: Service<R> { svc }
719 /// ```
720 ///
721 /// [`BoxService::layer()`]: crate::util::BoxService::layer()
722 #[cfg(feature = "util")]
723 #[cfg_attr(docsrs, doc(cfg(feature = "util")))]
724 pub fn boxed<S, R>(
725 self,
726 ) -> ServiceBuilder<
727 Stack<
728 tower_layer::LayerFn<
729 fn(
730 L::Service,
731 ) -> crate::util::BoxService<
732 R,
733 <L::Service as Service<R>>::Response,
734 <L::Service as Service<R>>::Error,
735 >,
736 >,
737 L,
738 >,
739 >
740 where
741 L: Layer<S>,
742 L::Service: Service<R> + Send + 'static,
743 <L::Service as Service<R>>::Future: Send + 'static,
744 {
745 self.layer(crate::util::BoxService::layer())
746 }
747
748 /// This wraps the inner service with the [`Layer`] returned by [`BoxCloneService::layer()`].
749 ///
750 /// This is similar to the [`boxed`] method, but it requires that `Self` implement
751 /// [`Clone`], and the returned boxed service implements [`Clone`].
752 ///
753 /// See [`BoxCloneService`] for more details.
754 ///
755 /// # Example
756 ///
757 /// ```
758 /// use tower::{Service, ServiceBuilder, BoxError, util::BoxCloneService};
759 /// use std::time::Duration;
760 /// #
761 /// # struct Request;
762 /// # struct Response;
763 /// # impl Response {
764 /// # fn new() -> Self { Self }
765 /// # }
766 ///
767 /// let service: BoxCloneService<Request, Response, BoxError> = ServiceBuilder::new()
768 /// .boxed_clone()
769 /// .load_shed()
770 /// .concurrency_limit(64)
771 /// .timeout(Duration::from_secs(10))
772 /// .service_fn(|req: Request| async {
773 /// Ok::<_, BoxError>(Response::new())
774 /// });
775 /// # let service = assert_service(service);
776 ///
777 /// // The boxed service can still be cloned.
778 /// service.clone();
779 /// # fn assert_service<S, R>(svc: S) -> S
780 /// # where S: Service<R> { svc }
781 /// ```
782 ///
783 /// [`BoxCloneService::layer()`]: crate::util::BoxCloneService::layer()
784 /// [`BoxCloneService`]: crate::util::BoxCloneService
785 /// [`boxed`]: Self::boxed
786 #[cfg(feature = "util")]
787 #[cfg_attr(docsrs, doc(cfg(feature = "util")))]
788 pub fn boxed_clone<S, R>(
789 self,
790 ) -> ServiceBuilder<
791 Stack<
792 tower_layer::LayerFn<
793 fn(
794 L::Service,
795 ) -> crate::util::BoxCloneService<
796 R,
797 <L::Service as Service<R>>::Response,
798 <L::Service as Service<R>>::Error,
799 >,
800 >,
801 L,
802 >,
803 >
804 where
805 L: Layer<S>,
806 L::Service: Service<R> + Clone + Send + 'static,
807 <L::Service as Service<R>>::Future: Send + 'static,
808 {
809 self.layer(crate::util::BoxCloneService::layer())
810 }
811}
812
813impl<L: fmt::Debug> fmt::Debug for ServiceBuilder<L> {
814 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
815 f.debug_tuple("ServiceBuilder").field(&self.layer).finish()
816 }
817}
818
819impl<S, L> Layer<S> for ServiceBuilder<L>
820where
821 L: Layer<S>,
822{
823 type Service = L::Service;
824
825 fn layer(&self, inner: S) -> Self::Service {
826 self.layer.layer(inner)
827 }
828}