Tower

https://docs.rs/tower
Admin
Tower is a library of modular and reusable components for building robust networking clients and...
Tokens:251,584
Snippets:2,755
Trust Score:9.7
Update:2 months ago
Show doc for...
Tokens:
Raw
### Service Function Wrapping Examples

Source: https://docs.rs/tower/latest/src/tower/builder/mod.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Examples demonstrating how to wrap async functions using service_fn.

```rust
ServiceBuilder::new()
    // ...
    .service(service_fn(handler_fn))
```

```rust
use std::time::Duration;
use tower::{ServiceBuilder, ServiceExt, BoxError, service_fn};

# #[tokio::main]
# async fn main() -> Result<(), BoxError> {
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?;
```

--------------------------------

### Constructing a Service Stack

Source: https://docs.rs/tower/latest/tower/builder/struct.ServiceBuilder.html?search=u32+-%3E+bool

Examples of building service stacks with single and multiple layers.

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

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

--------------------------------

### Issue a Request with a Service Client

Source: https://docs.rs/tower-service/latest/src/tower_service/lib.rs.html?search=std%3A%3Avec

Example of using a Service client to issue a request and await the response.

```rust
let client = redis::Client::new()
    .connect("127.0.0.1:6379".parse().unwrap())
    .unwrap();

let resp = client.call(Cmd::set("foo", "this is the value of foo")).await?;

// Wait for the future to resolve
println!("Redis response: {:?}", resp);
```

--------------------------------

### Implement Service call method

Source: https://docs.rs/tower-service/latest/tower_service/trait.Service.html?search=

Example implementation of the call method for a service, demonstrating how to handle request processing asynchronously.

```rust
fn call(&mut self, req: R) -> Self::Future {
    let clone = self.inner.clone();
    // take the service that was ready
    let mut inner = std::mem::replace(&mut self.inner, clone);
    Box::pin(async move {
        inner.call(req).await
    })
}
```

--------------------------------

### Implement a Service for an HTTP Server

Source: https://docs.rs/tower-service/latest/src/tower_service/lib.rs.html?search=std%3A%3Avec

Example of implementing the Service trait for a struct to handle HTTP requests.

```rust
# use std::pin::Pin;
# use std::task::{Poll, Context};
# use std::future::Future;
# use tower_service::Service;
use http::{Request, Response, StatusCode};

struct HelloWorld;

impl Service<Request<Vec<u8>>> for HelloWorld {
    type Response = Response<Vec<u8>>;
    type Error = http::Error;
    type Future = Pin<Box<dyn Future<Output = Result<Self::Response, Self::Error>>>>;

    fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
        Poll::Ready(Ok(()))
    }

    fn call(&mut self, req: Request<Vec<u8>>) -> Self::Future {
        // create the body
        let body: Vec<u8> = "hello, world!\n"
            .as_bytes()
            .to_owned();
        // Create the HTTP response
        let resp = Response::builder()
            .status(StatusCode::OK)
            .body(body)
            .expect("Unable to create `http::Response`");

        // create a response in a future.
        let fut = async {
            Ok(resp)
        };

        // Return the response as an immediate future
        Box::pin(fut)
    }
}
```

--------------------------------

### Using CallAll to process requests in order

Source: https://docs.rs/tower/latest/src/tower/util/call_all/ordered.rs.html?search=std%3A%3Avec

This example demonstrates how to use the CallAll combinator to process a stream of string requests through a service that returns the first letter of each string.

```rust
# use std::task::{Poll, Context};
# use std::cell::Cell;
# use std::error::Error;
# use std::rc::Rc;
#
use std::future::{ready, Ready};
use futures::StreamExt;
use futures::channel::mpsc;
use tower_service::Service;
use tower::util::ServiceExt;

// First, we need to have a Service to process our requests.
#[derive(Debug, Eq, PartialEq)]
struct FirstLetter;
impl Service<&'static str> for FirstLetter {
     type Response = &'static str;
     type Error = Box<dyn Error + Send + Sync>;
     type Future = Ready<Result<Self::Response, Self::Error>>;

     fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
         Poll::Ready(Ok(()))
     }

     fn call(&mut self, req: &'static str) -> Self::Future {
         ready(Ok(&req[..1]))
     }
}

#[tokio::main]
async fn main() {
    // Next, we need a Stream of requests.
    // TODO(eliza): when `tokio-util` has a nice way to convert MPSCs to streams,
    //              tokio::sync::mpsc again?
    let (mut reqs, rx) = mpsc::unbounded();
    // Note that we have to help Rust out here by telling it what error type to use.
    // Specifically, it has to be From<Service::Error> + From<Stream::Error>.
    let mut rsps = FirstLetter.call_all(rx);

    // Now, let's send a few requests and then check that we get the corresponding responses.
    reqs.unbounded_send("one").unwrap();
    reqs.unbounded_send("two").unwrap();
    reqs.unbounded_send("three").unwrap();
    drop(reqs);

    // We then loop over the response `Stream` that we get back from call_all.
    let mut i = 0usize;
    while let Some(rsp) = rsps.next().await {
        // Each response is a Result (we could also have used TryStream::try_next)
        match (i + 1, rsp.unwrap()) {
            (1, "o") |
            (2, "t") |
            (3, "t") => {}
            (n, i) => {
                unreachable!("{}. response was '{}'", n, i);
            }
        }
        i += 1;
    }

    // And at the end, we can get the Service back when there are no more requests.
    assert_eq!(rsps.into_inner(), FirstLetter);
}
```

--------------------------------

### Constructing a Service stack with ServiceBuilder

Source: https://docs.rs/tower/latest/src/tower/builder/mod.rs.html

Demonstrates how the order of layers in ServiceBuilder affects request handling. The first example shows buffer followed by concurrency limit, while the second shows the reverse order.

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

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

--------------------------------

### Box Error Conversion Examples

Source: https://docs.rs/tower/latest/tower/type.BoxError.html?search=

Examples demonstrating how to convert various error types into boxed trait objects.

```rust
let a_cow_str_error = Cow::from("a str error");
let a_boxed_error = Box::<dyn Error + Send + Sync>::from(a_cow_str_error);
assert!(
    size_of::<Box<dyn Error + Send + Sync>>() == size_of_val(&a_boxed_error))
```

```rust
use std::error::Error;
use std::fmt;

#[derive(Debug)]
struct AnError;

impl fmt::Display for AnError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "An error")
    }
}

impl Error for AnError {}

let an_error = AnError;
assert!(0 == size_of_val(&an_error));
let a_boxed_error = Box::<dyn Error>::from(an_error);
assert!(size_of::<Box<dyn Error>>() == size_of_val(&a_boxed_error))
```

```rust
use std::error::Error;
use std::fmt;

#[derive(Debug)]
struct AnError;

impl fmt::Display for AnError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "An error")
    }
}

impl Error for AnError {}

unsafe impl Send for AnError {}

unsafe impl Sync for AnError {}

let an_error = AnError;
assert!(0 == size_of_val(&an_error));
let a_boxed_error = Box::<dyn Error + Send + Sync>::from(an_error);
assert!(
    size_of::<Box<dyn Error + Send + Sync>>() == size_of_val(&a_boxed_error))
```

```rust
use std::error::Error;

let a_string_error = "a string error".to_string();
let a_boxed_error = Box::<dyn Error>::from(a_string_error);
assert!(size_of::<Box<dyn Error>>() == size_of_val(&a_boxed_error))
```

```rust
use std::error::Error;

let a_string_error = "a string error".to_string();
let a_boxed_error = Box::<dyn Error + Send + Sync>::from(a_string_error);
assert!(
    size_of::<Box<dyn Error + Send + Sync>>() == size_of_val(&a_boxed_error))
```

--------------------------------

### Service Function Wrapping

Source: https://docs.rs/tower/latest/src/tower/builder/mod.rs.html?search=u32+-%3E+bool

Examples of wrapping async functions with ServiceBuilder.

```rust
/// # use tower::{ServiceBuilder, service_fn};
/// # async fn handler_fn(_: ()) -> Result<(), ()> { Ok(()) }
/// # let _ = {
/// ServiceBuilder::new()
///     // ...
///     .service(service_fn(handler_fn))
/// # };
```

```rust
use std::time::Duration;
use tower::{ServiceBuilder, ServiceExt, BoxError, service_fn};

# #[tokio::main]
# async fn main() -> Result<(), BoxError> {
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?;
```

--------------------------------

### get_ready

Source: https://docs.rs/tower/latest/tower/ready_cache/cache/struct.ReadyCache.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Obtains a reference to a service in the ready set by key.

```APIDOC
### pub fn get_ready<Q: Hash + Equivalent<K>>( &self, key: &Q, ) -> Option<(usize, &K, &S)>

Obtains a reference to a service in the ready set by key.
```

--------------------------------

### Pinning a Box

Source: https://docs.rs/tower/latest/tower/type.BoxError.html

Demonstrates an example of a poor implementation of From for Pin that can cause ambiguity.

```rust
struct Foo; // A type defined in this crate.
impl From<Box<()>> for Pin<Foo> {
    fn from(_: Box<()>) -> Pin<Foo> {
        Pin::new(Foo)
    }
}

let foo = Box::new(());
let bar = Pin::from(foo);
```

--------------------------------

### Create a router with Steer

Source: https://docs.rs/tower/latest/src/tower/steer/mod.rs.html?search=std%3A%3Avec

Demonstrates how to use Steer to route requests to different services based on the request path and method. Services must be boxed to allow them to be stored in a single collection.

```rust
# use std::task::{Context, Poll, ready};
# use tower_service::Service;
# use tower::steer::Steer;
# use tower::service_fn;
# use tower::util::BoxService;
# use tower::ServiceExt;
# use std::convert::Infallible;
use http::{Request, Response, StatusCode, Method};

# #[tokio::main]
# async fn main() -> Result<(), Box<dyn std::error::Error>> {
// Service that responds to `GET /`
let root = service_fn(|req: Request<String>| async move {
    # assert_eq!(req.uri().path(), "/");
    let res = Response::new("Hello, World!".to_string());
    Ok::<_, Infallible>(res)
});
// We have to box the service so its type gets erased and we can put it in a `Vec` with other
// services
let root = BoxService::new(root);

// Service that responds with `404 Not Found` to all requests
let not_found = service_fn(|req: Request<String>| async move {
    let res = Response::builder()
        .status(StatusCode::NOT_FOUND)
        .body(String::new())
        .expect("response is valid");
    Ok::<_, Infallible>(res)
});
// Box that as well
let not_found = BoxService::new(not_found);

let mut svc = Steer::new(
    // All services we route between
    vec![root, not_found],
    // How we pick which service to send the request to
    |req: &Request<String>, _services: &[_]| {
        if req.method() == Method::GET && req.uri().path() == "/" {
            0 // Index of `root`
        } else {
            1 // Index of `not_found`
        }
    },
);

// This request will get sent to `root`
let req = Request::get("/").body(String::new()).unwrap();
let res = svc.ready().await?.call(req).await?;
assert_eq!(res.into_body(), "Hello, World!");

// This request will get sent to `not_found`
let req = Request::get("/does/not/exist").body(String::new()).unwrap();
let res = svc.ready().await?.call(req).await?;
assert_eq!(res.status(), StatusCode::NOT_FOUND);
assert_eq!(res.into_body(), "");
#
# Ok(())
# }
```

--------------------------------

### ServiceBuilder Usage

Source: https://docs.rs/tower/latest/tower/builder/struct.ServiceBuilder.html?search=

Example of using ServiceBuilder to compose layers and apply them to a service.

```APIDOC
## ServiceBuilder Usage

### Description
Constructs a service by chaining layers using the ServiceBuilder interface.

### Example
```rust
ServiceBuilder::new()
    .buffer(100)
    .concurrency_limit(10)
    .service(svc);
```
```

--------------------------------

### Using CallAll to process a stream of requests

Source: https://docs.rs/tower/latest/src/tower/util/call_all/ordered.rs.html?search=

Demonstrates how to implement a Service and use the call_all method to process a stream of requests, yielding responses in the original order.

```rust
# use std::task::{Poll, Context};
# use std::cell::Cell;
# use std::error::Error;
# use std::rc::Rc;
#
use std::future::{ready, Ready};
use futures::StreamExt;
use futures::channel::mpsc;
use tower_service::Service;
use tower::util::ServiceExt;

// First, we need to have a Service to process our requests.
#[derive(Debug, Eq, PartialEq)]
struct FirstLetter;
impl Service<&'static str> for FirstLetter {
     type Response = &'static str;
     type Error = Box<dyn Error + Send + Sync>;
     type Future = Ready<Result<Self::Response, Self::Error>>;

     fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
         Poll::Ready(Ok(()))
     }

     fn call(&mut self, req: &'static str) -> Self::Future {
         ready(Ok(&req[..1]))
     }
}

#[tokio::main] // This is a [`Stream`] of responses resulting from calling the wrapped [`Service`] for each
    /// request received on the wrapped [`Stream`].
    ///
    /// ```rust
    /// # use std::task::{Poll, Context};
    /// # use std::cell::Cell;
    /// # use std::error::Error;
    /// # use std::rc::Rc;
    /// #
    /// use std::future::{ready, Ready};
    /// use futures::StreamExt;
    /// use futures::channel::mpsc;
    /// use tower_service::Service;
    /// use tower::util::ServiceExt;
    ///
    /// // First, we need to have a Service to process our requests.
    /// #[derive(Debug, Eq, PartialEq)]
    /// struct FirstLetter;
    /// impl Service<&'static str> for FirstLetter {
    ///      type Response = &'static str;
    ///      type Error = Box<dyn Error + Send + Sync>;
    ///      type Future = Ready<Result<Self::Response, Self::Error>>;
    ///
    ///      fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
    ///          Poll::Ready(Ok(()))
    ///      }
    ///
    ///      fn call(&mut self, req: &'static str) -> Self::Future {
    ///          ready(Ok(&req[..1]))
    ///      }
    /// }
    ///
    /// #[tokio::main]
    /// async fn main() {
    ///     // Next, we need a Stream of requests.
    // TODO(eliza): when `tokio-util` has a nice way to convert MPSCs to streams,
    ///              tokio::sync::mpsc again?
    ///     let (mut reqs, rx) = mpsc::unbounded();
    ///     // Note that we have to help Rust out here by telling it what error type to use.
    ///     // Specifically, it has to be From<Service::Error> + From<Stream::Error>.
    ///     let mut rsps = FirstLetter.call_all(rx);
    ///
    ///     // Now, let's send a few requests and then check that we get the corresponding responses.
    ///     reqs.unbounded_send("one").unwrap();
    ///     reqs.unbounded_send("two").unwrap();
    ///     reqs.unbounded_send("three").unwrap();
    ///     drop(reqs);
    ///
    ///     // We then loop over the response `Stream` that we get back from call_all.
    ///     let mut i = 0usize;
    ///     while let Some(rsp) = rsps.next().await {
    ///         // Each response is a Result (we could also have used TryStream::try_next)
    ///         match (i + 1, rsp.unwrap()) {
    ///             (1, "o") |
    ///             (2, "t") |
    ///             (3, "t") => {}
    ///             (n, i) => {
    ///                 unreachable!("{}. response was '{}'", n, i);
    ///             }
    ///         }
    ///         i += 1;
    ///     }
    ///
    ///     // And at the end, we can get the Service back when there are no more requests.
    ///     assert_eq!(rsps.into_inner(), FirstLetter);
    /// }
```

--------------------------------

### Allocating with a custom allocator

Source: https://docs.rs/tower/latest/tower/type.BoxError.html

Examples of using new_in and try_new_in to allocate memory using a specific allocator.

```rust
#![feature(allocator_api)]

use std::alloc::System;

let five = Box::new_in(5, System);
```

```rust
#![feature(allocator_api)]

use std::alloc::System;
```

--------------------------------

### ReadyOneshot::new

Source: https://docs.rs/tower/latest/tower/util/struct.ReadyOneshot.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates a new ReadyOneshot instance for a given service.

```APIDOC
## pub const fn new(service: T) -> Self

### Description
Creates a new ReadyOneshot future that will resolve when the provided service is ready to accept a request.

### Parameters
- **service** (T) - The service to wait for, which must implement the Service<Request> trait.
```

--------------------------------

### Initialize Select middleware

Source: https://docs.rs/tower/latest/src/tower/hedge/select.rs.html

Use the new constructor to create a Select instance with a policy and two services.

```rust
impl<P, A, B> Select<P, A, B> {
    pub const fn new<Request>(policy: P, a: A, b: B) -> Self
    where
        P: Policy<Request>,
        A: Service<Request>,
        A::Error: Into<crate::BoxError>,
        B: Service<Request, Response = A::Response>,
        B::Error: Into<crate::BoxError>,
    {
        Select { policy, a, b }
    }
}
```

--------------------------------

### Implementing a Logging Layer

Source: https://docs.rs/tower/latest/tower/layer/trait.Layer.html?search=

An example of implementing the Layer trait to create a reusable logging middleware for any service.

```rust
pub struct LogLayer {
    target: &'static str,
}

impl<S> Layer<S> for LogLayer {
    type Service = LogService<S>;

    fn layer(&self, service: S) -> Self::Service {
        LogService {
            target: self.target,
            service
        }
    }
}

// This service implements the Log behavior
pub struct LogService<S> {
    target: &'static str,
    service: S,
}

impl<S, Request> Service<Request> for LogService<S>
where
    S: Service<Request>,
    Request: fmt::Debug,
{
    type Response = S::Response;
    type Error = S::Error;
    type Future = S::Future;

    fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
        self.service.poll_ready(cx)
    }

    fn call(&mut self, request: Request) -> Self::Future {
        // Insert log statement here or other functionality
        println!("request = {:?}, target = {:?}", request, self.target);
        self.service.call(request)
    }
}
```

--------------------------------

### SpawnReady::new

Source: https://docs.rs/tower/latest/src/tower/spawn_ready/service.rs.html?search=u32+-%3E+bool

Creates a new SpawnReady instance that wraps the provided service.

```APIDOC
### `SpawnReady::new(service: S) -> Self`

Creates a new `SpawnReady` wrapping the given `service`.
```

--------------------------------

### Consume Box into Raw Pointer

Source: https://docs.rs/tower/latest/tower/type.BoxError.html

Examples demonstrating how to consume a Box into a raw pointer using Box::into_raw.

```rust
let x = Box::new(String::from("Hello"));
let ptr = Box::into_raw(x);
let x = unsafe { Box::from_raw(ptr) };
```

```rust
use std::alloc::{dealloc, Layout};
use std::ptr;

let x = Box::new(String::from("Hello"));
let ptr = Box::into_raw(x);
unsafe {
    ptr::drop_in_place(ptr);
    dealloc(ptr as *mut u8, Layout::new::<String>());
}
```

```rust
let x = Box::new(String::from("Hello"));
let ptr = Box::into_raw(x);
unsafe {
    drop(Box::from_raw(ptr));
}
```

--------------------------------

### AndThen::new

Source: https://docs.rs/tower/latest/tower/util/struct.AndThen.html?search=std%3A%3Avec

Creates a new AndThen service instance.

```APIDOC
## pub const fn new(inner: S, f: F) -> Self

### Description
Creates a new `AndThen` service that wraps an inner service `S` and a function `f` to be applied to the service's response.

### Parameters
- **inner** (S) - The inner service to wrap.
- **f** (F) - The function to apply to the response of the inner service.
```

--------------------------------

### Construct Box from NonNull Pointer

Source: https://docs.rs/tower/latest/tower/type.BoxError.html

Examples demonstrating how to create a Box from a NonNull pointer using Box::from_non_null.

```rust
#![feature(box_vec_non_null)]

let x = Box::new(5);
let non_null = Box::into_non_null(x);
let x = unsafe { Box::from_non_null(non_null) };
```

```rust
#![feature(box_vec_non_null)]

use std::alloc::{alloc, Layout};
use std::ptr::NonNull;

unsafe {
    let non_null = NonNull::new(alloc(Layout::new::<i32>()).cast::<i32>())
        .expect("allocation failed");
    // In general .write is required to avoid attempting to destruct
    // the (uninitialized) previous contents of `non_null`.
    non_null.write(5);
    let x = Box::from_non_null(non_null);
}
```

--------------------------------

### Correct Service Handling Pattern

Source: https://docs.rs/tower-service/latest/tower_service/trait.Service.html?search=

A partial implementation showing the correct approach to managing service readiness using std::mem::replace.

```rust
struct Wrapper<S> {
    inner: S,
}

impl<R, S> Service<R> for Wrapper<S>
where
    S: Service<R> + Clone + 'static,
    R: 'static,
{
    type Response = S::Response;
    type Error = S::Error;
    type Future = Pin<Box<dyn Future<Output = Result<Self::Response, Self::Error>>>>;

    fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
        self.inner.poll_ready(cx)
    }
```

--------------------------------

### Construct Box from Raw Pointer

Source: https://docs.rs/tower/latest/tower/type.BoxError.html

Examples demonstrating how to create a Box from a raw pointer using Box::from_raw.

```rust
let x = Box::new(5);
let ptr = Box::into_raw(x);
let x = unsafe { Box::from_raw(ptr) };
```

```rust
use std::alloc::{alloc, Layout};

unsafe {
    let ptr = alloc(Layout::new::<i32>()) as *mut i32;
    // In general .write is required to avoid attempting to destruct
    // the (uninitialized) previous contents of `ptr`, though for this
    // simple example `*ptr = 5` would have worked as well.
    ptr.write(5);
    let x = Box::from_raw(ptr);
}
```

--------------------------------

### ServiceList::new

Source: https://docs.rs/tower/latest/tower/discover/struct.ServiceList.html?search=

Creates a new ServiceList instance with an initial list of services.

```APIDOC
## pub fn new<Request>(services: T) -> ServiceList<T>

### Description
Creates a new `ServiceList` initialized with a collection of services. The discovery process will yield this list once.

### Parameters
- **services** (T) - Required - An iterator of services that implement the `Service<Request>` trait.
```

--------------------------------

### PeakEwma Initialization

Source: https://docs.rs/tower/latest/src/tower/load/peak_ewma.rs.html

Constructor for wrapping a service with PeakEwma load tracking.

```rust
impl<S, C> PeakEwma<S, C> {
    /// Wraps an `S`-typed service so that its load is tracked by the EWMA of its peak latency.
    pub fn new(service: S, default_rtt: Duration, decay_ns: f64, completion: C) -> Self {
        debug_assert!(decay_ns > 0.0, "decay_ns must be positive");
        Self {
            service,
            decay_ns,
            rtt_estimate: Arc::new(Mutex::new(RttEstimate::new(nanos(default_rtt)))),
            completion,
        }
    }

    fn handle(&self) -> Handle {
        Handle {
            decay_ns: self.decay_ns,
            sent_at: Instant::now(),
            rtt_estimate: self.rtt_estimate.clone(),
        }
    }
}
```

--------------------------------

### Define a Timeout Middleware Service

Source: https://docs.rs/tower-service/latest/src/tower_service/lib.rs.html?search=std%3A%3Avec

Example of creating a middleware service that wraps another service to add a timeout.

```rust
use tower_service::Service;
use tower_layer::Layer;
use futures::FutureExt;
use std::future::Future;
use std::task::{Context, Poll};
use std::time::Duration;
use std::pin::Pin;
use std::fmt;
use std::error::Error;

// Our timeout service, which wraps another service and
// adds a timeout to its response future.
pub struct Timeout<T> {
    inner: T,
    timeout: Duration,
}

impl<T> Timeout<T> {
    pub const fn new(inner: T, timeout: Duration) -> Timeout<T> {
        Timeout {
            inner,
            timeout,
        }
```

--------------------------------

### Leaking a Box

Source: https://docs.rs/tower/latest/tower/type.BoxError.html

Examples of consuming a Box to return a static mutable reference, applicable to both simple types and unsized slices.

```rust
let x = Box::new(41);
let static_ref: &'static mut usize = Box::leak(x);
*static_ref += 1;
assert_eq!(*static_ref, 42);
```

```rust
let x = vec![1, 2, 3].into_boxed_slice();
let static_ref = Box::leak(x);
static_ref[0] = 4;
assert_eq!(*static_ref, [4, 2, 3]);
```

--------------------------------

### Service Readiness and Execution

Source: https://docs.rs/tower/latest/src/tower/ready_cache/cache.rs.html?search=std%3A%3Avec

Methods for calling ready services by key or index, ensuring proper state management within the cache.

```rust
/// If the specified key does not exist in the ready
    pub fn call_ready<Q: Hash + Equivalent<K>>(&mut self, key: &Q, req: Req) -> S::Future {
        let (index, _, _) = self
            .ready
            .get_full_mut(key)
            .expect("check_ready was not called");
        self.call_ready_index(index, req)
    }

    /// Calls a ready service by index.
    ///
    /// # Panics
    ///
    /// If the specified index is out of range.
    pub fn call_ready_index(&mut self, index: usize, req: Req) -> S::Future {
        let (key, (mut svc, cancel)) = self
            .ready
            .swap_remove_index(index)
            .expect("check_ready_index was not called");

        let fut = svc.call(req);

        // If a new version of this service has been added to the
        // unready set, don't overwrite it.
        if !self.pending_contains(&key) {
            self.push_pending(key, svc, cancel);
        }

        fut
    }
```

--------------------------------

### Constructing a Balance instance

Source: https://docs.rs/tower/latest/src/tower/balance/p2c/service.rs.html?search=

Methods to initialize the load balancer using either default system entropy or a custom random number generator.

```rust
impl<D, Req>
where
    D: Discover,
    D::Key: Hash,
    D::Service: Service<Req>,
    <D::Service as Service<Req>>::Error: Into<crate::BoxError>,
{
    /// Constructs a load balancer that uses operating system entropy.
    pub fn new(discover: D) -> Self {
        Self::from_rng(discover, HasherRng::default())
    }

    /// Constructs a load balancer seeded with the provided random number generator.
    pub fn from_rng<R: Rng + Send + Sync + 'static>(discover: D, rng: R) -> Self {
        let rng = Box::new(rng);
        Self {
            rng,
            discover,
            services: ReadyCache::default(),
            ready_index: None,

            _req: PhantomData,
        }
    }

    /// Returns the number of endpoints currently tracked by the balancer.
    pub fn len(&self) -> usize {
        self.services.len()
    }

    /// Returns whether or not the balancer is empty.
    pub fn is_empty(&self) -> bool {
        self.services.is_empty()
    }
}
```

--------------------------------

### PeakEwma::new

Source: https://docs.rs/tower/latest/tower/load/peak_ewma/struct.PeakEwma.html

Creates a new PeakEwma instance to wrap a service and track its load.

```APIDOC
## PeakEwma::new

### Description
Wraps an S-typed service so that its load is tracked by the EWMA of its peak latency.

### Signature
`pub fn new(service: S, default_rtt: Duration, decay_ns: f64, completion: C) -> Self`

### Parameters
- **service** (S) - The underlying service to wrap.
- **default_rtt** (Duration) - The default round-trip time used when no latency information is available.
- **decay_ns** (f64) - The decay factor for the moving average in nanoseconds.
- **completion** (C) - The completion tracker for the service.
```

--------------------------------

### Manage Box memory with into_non_null

Source: https://docs.rs/tower/latest/tower/type.BoxError.html?search=std%3A%3Avec

Examples demonstrating how to convert a Box to a NonNull pointer and perform cleanup using different approaches.

```rust
#![feature(box_vec_non_null)]

let x = Box::new(String::from("Hello"));
let non_null = Box::into_non_null(x);
let x = unsafe { Box::from_non_null(non_null) };
```

```rust
#![feature(box_vec_non_null)]

use std::alloc::{dealloc, Layout};

let x = Box::new(String::from("Hello"));
let non_null = Box::into_non_null(x);
unsafe {
    non_null.drop_in_place();
    dealloc(non_null.as_ptr().cast::<u8>(), Layout::new::<String>());
}
```

```rust
#![feature(box_vec_non_null)]

let x = Box::new(String::from("Hello"));
let non_null = Box::into_non_null(x);
unsafe {
    drop(Box::from_non_null(non_null));
}
```

--------------------------------

### Convert Box to NonNull pointer with allocator

Source: https://docs.rs/tower/latest/tower/type.BoxError.html

Demonstrates consuming a Box into a NonNull pointer and allocator, with examples for automatic and manual cleanup.

```rust
#![feature(allocator_api)]

use std::alloc::System;

let x = Box::new_in(String::from("Hello"), System);
let (non_null, alloc) = Box::into_non_null_with_allocator(x);
let x = unsafe { Box::from_non_null_in(non_null, alloc) };
```

```rust
#![feature(allocator_api)]

use std::alloc::{Allocator, Layout, System};

let x = Box::new_in(String::from("Hello"), System);
let (non_null, alloc) = Box::into_non_null_with_allocator(x);
unsafe {
    non_null.drop_in_place();
    alloc.deallocate(non_null.cast::<u8>(), Layout::new::<String>());
}
```

--------------------------------

### Hedge::new

Source: https://docs.rs/tower/latest/tower/hedge/struct.Hedge.html?search=u32+-%3E+bool

Creates a new hedge middleware instance.

```APIDOC
## pub fn new<Request>(service: S, policy: P, min_data_points: u64, latency_percentile: f32, period: Duration) -> Hedge<S, P>

### Description
Creates a new hedge middleware. This middleware pre-emptively retries requests that have been outstanding for longer than a given latency percentile.

### Parameters
- **service** (S) - The underlying service to wrap.
- **policy** (P) - The policy to determine when to hedge.
- **min_data_points** (u64) - Minimum number of data points required before hedging begins.
- **latency_percentile** (f32) - The latency percentile threshold.
- **period** (Duration) - The duration period for the latency histogram.
```

--------------------------------

### Using Shared to create a MakeService

Source: https://docs.rs/tower/latest/src/tower/make/make_service/shared.rs.html?search=

Demonstrates wrapping a non-cloneable service with Buffer to make it cloneable, then converting it into a MakeService using Shared.

```rust
# use std::task::{Context, Poll};
# use std::pin::Pin;
# use std::convert::Infallible;
use std::future::{Ready, ready};
use tower::make::{MakeService, Shared};
use tower::buffer::Buffer;
use tower::Service;

// An example connection type
struct Connection {}

// An example request type
struct Request {}

// An example response type
struct Response {}

// Some service that doesn't implement `Clone`
struct MyService;

impl Service<Request> for MyService {
    type Response = Response;
    type Error = Infallible;
    type Future = Ready<Result<Response, Infallible>>;

    fn poll_ready(&mut self, _cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
        Poll::Ready(Ok(()))
    }

    fn call(&mut self, req: Request) -> Self::Future {
        ready(Ok(Response {}))
    }
}

// Example function that runs a service by accepting new connections and using
// `Make` to create new services that might be bound to the connection.
//
// This is similar to what you might find in hyper.
async fn serve_make_service<Make>(make: Make)
where
    Make: MakeService<Connection, Request>
{
    // ...
}

# async {
// Our service
let svc = MyService;

// Make it `Clone` by putting a channel in front
let buffered = Buffer::new(svc, 1024);

// Convert it into a `MakeService`
let make = Shared::new(buffered);

// Run the service and just ignore the `Connection`s as `MyService` doesn't need them
serve_make_service(make).await;
# };
```

--------------------------------

### Convert Box to raw pointer with allocator

Source: https://docs.rs/tower/latest/tower/type.BoxError.html

Demonstrates consuming a Box into a raw pointer and allocator, with examples for automatic and manual cleanup.

```rust
#![feature(allocator_api)]

use std::alloc::System;

let x = Box::new_in(String::from("Hello"), System);
let (ptr, alloc) = Box::into_raw_with_allocator(x);
let x = unsafe { Box::from_raw_in(ptr, alloc) };
```

```rust
#![feature(allocator_api)]

use std::alloc::{Allocator, Layout, System};
use std::ptr::{self, NonNull};

let x = Box::new_in(String::from("Hello"), System);
let (ptr, alloc) = Box::into_raw_with_allocator(x);
unsafe {
    ptr::drop_in_place(ptr);
    let non_null = NonNull::new_unchecked(ptr);
    alloc.deallocate(non_null.cast(), Layout::new::<String>());
}
```

--------------------------------

### Incorrect Service Wrapper Implementation

Source: https://docs.rs/tower-service/latest/src/tower_service/lib.rs.html?search=std%3A%3Avec

An example of an incorrect implementation where cloning the inner service inside call() may lead to unexpected behavior.

```rust
    fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
        self.inner.poll_ready(cx)
    }

    fn call(&mut self, req: R) -> Self::Future {
        let mut inner = self.inner.clone();
        Box::pin(async move {
            // `inner` might not be ready since its a clone
            inner.call(req).await
        })
    }
}
```

--------------------------------

### MapErr::new

Source: https://docs.rs/tower/latest/tower/util/struct.MapErr.html?search=std%3A%3Avec

Creates a new MapErr service instance.

```APIDOC
## pub const fn new(inner: S, f: F) -> Self

### Description
Creates a new `MapErr` service that wraps an inner service `S` and applies a function `f` to transform its error type.

### Parameters
- **inner** (S) - The inner service to wrap.
- **f** (F) - The function used to map the error type.
```

--------------------------------

### call_ready

Source: https://docs.rs/tower/latest/tower/ready_cache/cache/struct.ReadyCache.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Calls a ready service by key.

```APIDOC
### pub fn call_ready<Q: Hash + Equivalent<K>>( &mut self, key: &Q, req: Req, ) -> S::Future

Calls a ready service by key. Panics if the specified key does not exist in the ready set.
```

--------------------------------

### Incorrect Service Cloning Pattern

Source: https://docs.rs/tower-service/latest/tower_service/trait.Service.html?search=

An example of an unsafe implementation where cloning a service inside the call method may lead to panics if the clone is not ready.

```rust
struct Wrapper<S> {
    inner: S,
}

impl<R, S> Service<R> for Wrapper<S>
where
    S: Service<R> + Clone + 'static,
    R: 'static,
{
    type Response = S::Response;
    type Error = S::Error;
    type Future = Pin<Box<dyn Future<Output = Result<Self::Response, Self::Error>>>>;

    fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
        self.inner.poll_ready(cx)
    }

    fn call(&mut self, req: R) -> Self::Future {
        let mut inner = self.inner.clone();
        Box::pin(async move {
            // `inner` might not be ready since its a clone
            inner.call(req).await
        })
    }
}
```

--------------------------------

### Correct Service Wrapper Implementation

Source: https://docs.rs/tower-service/latest/src/tower_service/lib.rs.html?search=std%3A%3Avec

Use std::mem::replace to correctly take the service that was already verified as ready.

```rust
# use std::pin::Pin;
# use std::task::{Poll, Context};
# use std::future::Future;
# use tower_service::Service;
#
struct Wrapper<S> {
    inner: S,
}

impl<R, S> Service<R> for Wrapper<S>
where
    S: Service<R> + Clone + 'static,
    R: 'static,
{
    type Response = S::Response;
    type Error = S::Error;
    type Future = Pin<Box<dyn Future<Output = Result<Self::Response, Self::Error>>>>;

    fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
        self.inner.poll_ready(cx)
    }

    fn call(&mut self, req: R) -> Self::Future {
        let clone = self.inner.clone();
        // take the service that was ready
        let mut inner = std::mem::replace(&mut self.inner, clone);
        Box::pin(async move {
            inner.call(req).await
        })
    }
}
```

--------------------------------

### SpawnReadyLayer::new

Source: https://docs.rs/tower/latest/src/tower/spawn_ready/layer.rs.html?search=

Creates a new instance of the SpawnReadyLayer.

```APIDOC
## SpawnReadyLayer::new

### Description
Creates a new instance of the `SpawnReadyLayer` struct.

### Signature
`pub fn new() -> Self`
```

--------------------------------

### Using BoxCloneSyncServiceLayer for dynamic configuration

Source: https://docs.rs/tower/latest/src/tower/util/boxed/layer_clone_sync.rs.html?search=u32+-%3E+bool

This example demonstrates how to use BoxCloneSyncServiceLayer to return a consistent type from a layer function, regardless of whether a timeout layer is conditionally applied.

```rust
use std::time::Duration;
use tower::{Service, ServiceBuilder, BoxError};
use tower::util::{BoxCloneSyncServiceLayer, BoxCloneSyncService};

#
# struct Request;
# struct Response;
# impl Response {
#     fn new() -> Self { Self }
# }

fn common_layer<S, T>() -> BoxCloneSyncServiceLayer<S, T, S::Response, BoxError>
where
    S: Service<T> + Clone + Send + Sync + 'static,
    S::Future: Send + 'static,
    S::Error: Into<BoxError> + 'static,
{
    let builder = ServiceBuilder::new()
        .concurrency_limit(100);

    if std::env::var("SET_TIMEOUT").is_ok() {
        let layer = builder
            .timeout(Duration::from_secs(30))
            .into_inner();

        BoxCloneSyncServiceLayer::new(layer)
    } else {
        let layer = builder
            .map_err(Into::into)
            .into_inner();

        BoxCloneSyncServiceLayer::new(layer)
    }
}

// We can clone the layer (this is true of BoxLayer as well)
let boxed_clone_sync_layer = common_layer();

let cloned_sync_layer = boxed_clone_sync_layer.clone();

// Using the `BoxCloneSyncServiceLayer` we can create a `BoxCloneSyncService`
let service: BoxCloneSyncService<Request, Response, BoxError> = ServiceBuilder::new().layer(cloned_sync_layer)
     .service_fn(|req: Request| async {
        Ok::<_, BoxError>(Response::new())
    });

# let service = assert_service(service);

// And we can still clone the service
let cloned_service = service.clone();
#
# fn assert_service<S, R>(svc: S) -> S
# where S: Service<R> { svc }

```

--------------------------------

### Mapping Service Results

Source: https://docs.rs/tower/latest/src/tower/util/mod.rs.html?search=std%3A%3Avec

Use map_result to transform the output of a service, allowing for error handling or logging. This example demonstrates boxing errors to unify different error types.

```rust
use tower::BoxError;

// A service returning Result<Record, DbError>
let service = DatabaseService::new("127.0.0.1:8080");

// If the user is zero years old, return an error.
let mut new_service = service.map_result(|result| {
   let record = result?;

   if record.age == 0 {
        // Users must have been born to use our app!
        let app_error = AppError::from("users cannot be 0 years old!");

        // Box the error to erase its type (as it can be an `AppError`
        // *or* the inner service's `DbError`).
        return Err(BoxError::from(app_error));
    }

    // Otherwise, return the record.
    Ok(record)
});

// Call the new service
let id = 13;
let record = new_service
    .ready()
    .await?
    .call(id)
    .await?;
```

--------------------------------

### Check Service Readiness by Key

Source: https://docs.rs/tower/latest/src/tower/ready_cache/cache.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Checks if a specific endpoint is ready using its key. Returns true if ready, false if not, or an error if the service failed.

```rust
pub fn check_ready<Q: Hash + Equivalent<K>>(
        &mut self,
        cx: &mut Context<'_>,
        key: &Q,
    ) -> Result<bool, error::Failed<K>> {
        match self.ready.get_full_mut(key) {
            Some((index, _, _)) => self.check_ready_index(cx, index),
            None => Ok(false),
        }
    }
```

--------------------------------

### Convert MakeService into a Service

Source: https://docs.rs/tower/latest/src/tower/make/make_service.rs.html

Demonstrates consuming a MakeService to create a Service that produces new services.

```rust
use std::convert::Infallible;
use tower::Service;
use tower::make::MakeService;
use tower::service_fn;

# fn main() {
# async {
// A `MakeService`
let make_service = service_fn(|make_req: ()| async {
    Ok::<_, Infallible>(service_fn(|req: String| async {
        Ok::<_, Infallible>(req)
    }))
});

// Convert the `MakeService` into a `Service`
let mut svc = make_service.into_service();

// Make a new service
let mut new_svc = svc.call(()).await.unwrap();

// Call the service
let res = new_svc.call("foo".to_string()).await.unwrap();
# };
# }
```

--------------------------------

### iter_ready

Source: https://docs.rs/tower/latest/tower/ready_cache/cache/struct.ReadyCache.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Returns an iterator over the ready keys and services.

```APIDOC
### pub fn iter_ready(&self) -> impl Iterator<Item = (&K, &S)>

Returns an iterator over the ready keys and services.
```

--------------------------------

### Initialize MakeBalanceLayer

Source: https://docs.rs/tower/latest/tower/balance/p2c/struct.MakeBalanceLayer.html

Create a new instance of MakeBalanceLayer using operating system entropy.

```rust
pub const fn new() -> Self
```

--------------------------------

### Implement basic load-based service selection

Source: https://docs.rs/tower/latest/src/tower/load/mod.rs.html

Demonstrates how to compare the load of two services implementing the Load trait and dispatch a request to the one with the lower load.

```rust
# #[cfg(feature = "util")]
use tower::util::ServiceExt;
# #[cfg(feature = "util")]
use tower::{load::Load, Service};
# #[cfg(feature = "util")]
async fn simple_balance<S1, S2, R>(
    svc1: &mut S1,
    svc2: &mut S2,
    request: R
) -> Result<S1::Response, S1::Error>
where
    S1: Load + Service<R>,
    S2: Load<Metric = S1::Metric> + Service<R, Response = S1::Response, Error = S1::Error>
{
    if svc1.load() < svc2.load() {
        svc1.ready().await?.call(request).await
    } else {
        svc2.ready().await?.call(request).await
    }
}
```

--------------------------------

### ready_len

Source: https://docs.rs/tower/latest/tower/ready_cache/cache/struct.ReadyCache.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Returns the number of services in the ready set.

```APIDOC
### pub fn ready_len(&self) -> usize

Returns the number of services in the ready set.
```

--------------------------------

### Initialize PeakEwmaDiscover

Source: https://docs.rs/tower/latest/src/tower/load/peak_ewma.rs.html

Creates a new wrapper for service discovery that tracks Peak EWMA load metrics.

```rust
#[cfg(feature = "discover")]
impl<D, C> PeakEwmaDiscover<D, C> {
    /// Wraps a `D`-typed [`Discover`] so that services have a [`PeakEwma`] load metric.
    ///
    /// The provided `default_rtt` is used as the default RTT estimate for newly
    /// added services.
    ///
    /// They `decay` value determines over what time period a RTT estimate should
    /// decay.
    pub fn new<Request>(discover: D, default_rtt: Duration, decay: Duration, completion: C) -> Self
    where
        D: Discover,
        D::Service: Service<Request>,
        C: TrackCompletion<Handle, <D::Service as Service<Request>>::Response>,
    {
        PeakEwmaDiscover {
            discover,
            decay_ns: nanos(decay),
            default_rtt,
            completion,
        }
    }
}
```
Tokens:
Raw