Tower

https://docs.rs/tower/latest/tower/
Admin
Tower is a library of modular and reusable components for building robust networking clients and...
Tokens:199,041
Snippets:2,084
Trust Score:9.7
Update:11 months ago
Show doc for...
Tokens:
Raw
### Example: Creating a router with Steer

Source: https://docs.rs/tower/latest/tower/steer/index

Demonstrates how to use `Steer` to route incoming HTTP requests to different services based on request method and path. It sets up a service for `GET /` and a fallback for all other requests. Requires `http` and `tower` crates.

```rust
use http::{Request, Response, StatusCode, Method};
use tower::{service_fn, BoxService};
use std::convert::Infallible;

// Service that responds to `GET /`
let root = service_fn(|req: Request<String>| async move {
    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(), "");

```

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

### Example: Create and Use Service from Function (Rust)

Source: https://docs.rs/tower/latest/tower/builder/struct.ServiceBuilder

Demonstrates creating a service using `ServiceBuilder::service_fn` and then invoking it. This example shows middleware like `buffer` and `timeout` being applied.

```rust
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");
```

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

### Buffer Usage Example - Rust

Source: https://docs.rs/tower/latest/tower/buffer/index

Demonstrates how to use the `Buffer` middleware to create a cloneable service handle that enqueues requests into a buffered channel. This example shows spawning multiple tasks that send requests to the buffered service.

```rust
use tower::buffer::Buffer;
use tower::{Service, ServiceExt};
async fn mass_produce<S: Service<usize>>(svc: S)
where
  S: 'static + Send,
  S::Error: Send + Sync + std::error::Error,
  S::Future: Send
{
    let svc = Buffer::new(svc, 10 /* buffer length */);
    for _ in 0..10 {
        let mut svc = svc.clone();
        tokio::spawn(async move {
            for i in 0usize.. {
                svc.ready().await.expect("service crashed").call(i).await;
            }
        });
    }
}
```

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

### Rust Service Load Balancing Example using Tower

Source: https://docs.rs/tower/latest/tower/load/index

Demonstrates how to balance requests between two services based on their current load, using the `Load` trait and `ServiceExt::ready` from the Tower crate. This example assumes services implement `Load` and `Service` traits.

```rust
use tower::util::ServiceExt;
use tower::{load::Load, Service};
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
    }
}
```

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

### BoxCloneServiceLayer Example: Dynamic Layer Creation

Source: https://docs.rs/tower/latest/tower/util/struct.BoxCloneServiceLayer

Demonstrates the usage of BoxCloneServiceLayer to dynamically create a Layer based on an environment variable. It showcases how to conditionally apply a timeout middleware and return a consistent BoxCloneServiceLayer type, allowing for cloning of both the layer and the resulting service. This example requires the 'tower' crate.

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


fn common_layer<S, T>() -> BoxCloneServiceLayer<S, T, S::Response, BoxError>
where
    S: Service<T> + Clone + Send + '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();

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

        BoxCloneServiceLayer::new(layer)
    }
}

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

let cloned_layer = boxed_clone_layer.clone();

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


// And we can still clone the service
let cloned_service = service.clone();

```

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

### BoxCloneService Example: Creating and Cloning a Service

Source: https://docs.rs/tower/latest/tower/util/struct.BoxCloneService

Demonstrates how to create a BoxCloneService from an existing service, which includes request/response mapping, load shedding, concurrency limiting, and timeouts. It then shows how to clone the BoxCloneService.

```Rust
use tower::{Service, ServiceBuilder, BoxError, util::BoxCloneService};
use std::time::Duration;

// This service has a complex type that is hard to name
let service = ServiceBuilder::new()
    .map_request(|req| {
        println!("received request");
        req
    })
    .map_response(|res| {
        println!("response produced");
        res
    })
    .load_shed()
    .concurrency_limit(64)
    .timeout(Duration::from_secs(10))
    .service_fn(|req: Request| async {
        Ok::<_, BoxError>(Response::new())
    });

// `BoxCloneService` will erase the type so it's nameable
let service: BoxCloneService<Request, Response, BoxError> = BoxCloneService::new(service);

// And we can still clone the service
let cloned_service = service.clone();

```

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

### ServiceBuilder Initialization and Layer Composition

Source: https://docs.rs/tower/latest/tower/builder/struct.ServiceBuilder

Demonstrates initializing ServiceBuilder and applying various layers sequentially. The order of layer application affects how requests are processed. This example shows combining buffer, concurrency limit, and a service.

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

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

```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);
```

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

### HTTP Server Implementation using Tower Service in Rust

Source: https://docs.rs/tower/latest/tower/trait.Service

Demonstrates implementing the `Service` trait to act as an HTTP server. This example creates a `HelloWorld` service that responds to requests with a 'hello, world!' message.

```rust
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)
    }
}
```

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

### Instantiate FutureService with a Future producing a Service (Rust)

Source: https://docs.rs/tower/latest/tower/util/struct.FutureService

Demonstrates how to create a FutureService by wrapping a future that resolves to a service. It shows the necessary imports and the usage of `Box::pin` for async blocks that require `Unpin`. The example awaits the service readiness and then calls it.

```rust
use tower::{service_fn, Service, ServiceExt};
use tower::util::FutureService;
use std::convert::Infallible;

// A future which outputs a type implementing `Service`.
let future_of_a_service = async {
    let svc = service_fn(|_req: ()| async { Ok::<_, Infallible>("ok") });
    Ok::<_, Infallible>(svc)
};

// Wrap the future with a `FutureService`, allowing it to be used
// as a service without awaiting the future's completion:
let mut svc = FutureService::new(Box::pin(future_of_a_service));

// Now, when we wait for the service to become ready, it will
// drive the future to completion internally.
let svc = svc.ready().await.unwrap();
let res = svc.call(()).await.unwrap();

```

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

### Example: Checking Service Types (Rust)

Source: https://docs.rs/tower/latest/tower/builder/struct.ServiceBuilder

Shows how `check_service` is used to assert the request, response, and error types of a service at different stages of the `ServiceBuilder` pipeline.

```rust
use tower::ServiceBuilder;
use std::task::{Poll, Context};
use tower::{Service, ServiceExt};

// Dummy types for example
struct Request;
struct Response;
struct Error;
struct WrappedResponse(Response);

// An example service stub
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>> {
      Poll::Ready(Ok(()))
  }

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

let builder = ServiceBuilder::new()
    // Check initial types
    .check_service::<MyService, Request, Response, Error>()
    // Modify response type
    .map_response(|response: Response| WrappedResponse(response))
    // Check updated types
    .check_service::<MyService, _, WrappedResponse, _>();
```

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

### ServiceBuilder New Instance

Source: https://docs.rs/tower/latest/tower/builder/struct.ServiceBuilder

Provides a constant function `new` to create a new instance of `ServiceBuilder`. This is the starting point for building a service stack.

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

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

### Tower LogLayer Example Implementation

Source: https://docs.rs/tower/latest/tower/layer/trait.Layer

An example implementation of the `Layer` trait named `LogLayer`. This layer wraps a service to add request logging functionality before delegating the call to the inner 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)
    }
}
```

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

### MakeService into_service() Example

Source: https://docs.rs/tower/latest/tower/make/trait.MakeService

Demonstrates how to convert a MakeService into a Service using the `into_service` method. This consumes the original MakeService and returns a Service that can be called to produce new services.

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

// 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();

```

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

### MakeService as_service() Example

Source: https://docs.rs/tower/latest/tower/make/trait.MakeService

Illustrates using the `as_service` method to obtain a Service from a MakeService without consuming the original MakeService. This allows the original MakeService to be used further.

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

// A `MakeService`
let mut 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.as_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();

// The original `MakeService` is still accessible
let new_svc = make_service.make_service(()).await.unwrap();

```

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

### Get Ready Service (Oneshot)

Source: https://docs.rs/tower/latest/tower/hedge/struct.Hedge

Yields the service when it is ready to accept a request, consuming the service. Requires the 'util' crate feature. This is a one-time operation to get the service once it's ready.

```Rust
fn ready_oneshot(self) -> ReadyOneshot<Self, Request>
```

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

### Example: Checking Service Cloneability (Rust)

Source: https://docs.rs/tower/latest/tower/builder/struct.ServiceBuilder

Demonstrates using `check_service_clone::<MyService>()` to ensure the resulting service is cloneable when the input service is of type `MyService`.

```rust
use tower::ServiceBuilder;

// Assume MyService is defined elsewhere and implements Clone
struct MyService;

let builder = ServiceBuilder::new()
    .map_request(|request: String| {
        println!("got request!");
        request
    })
    .check_service_clone::<MyService>()
    .map_response(|response: String| {
        println!("got response!");
        response
    });
```

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

### Load Balancing with Tower's p2c Algorithm (Rust)

Source: https://docs.rs/tower/latest/tower/balance/index

Demonstrates how to use the `Balance` middleware with the 'Power of Two Random Choices' algorithm to spread requests evenly across multiple services. This example requires the 'balance' crate feature and assumes services implement the `Load` trait.

```rust
use tower::balance::p2c::Balance;
use tower::load::Load;
use tower::{Service, ServiceExt};
use futures_util::pin_mut;
use std::stream::Stream;

async fn spread<Req, S: Service<Req> + Load>(svc1: S, svc2: S, reqs: impl Stream<Item = Req>)
where
    S::Error: Into<tower::BoxError>,
    S::Metric: std::fmt::Debug,
{
    // Spread load evenly across the two services
    let p2c = Balance::new(tower::discover::ServiceList::new(vec![svc1, svc2]));

    // Issue all the requests that come in.
    // Some will go to svc1, some will go to svc2.
    pin_mut!(reqs);
    let mut responses = p2c.call_all(reqs);
    while let Some(rsp) = responses.next().await {
        // ...
    }
}
```

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

### Redis Client Request using Tower Service in Rust

Source: https://docs.rs/tower/latest/tower/trait.Service

Illustrates how a client can consume a `Service` to issue a Redis command. This example shows connecting to a Redis server and making a `SET` command, awaiting 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);
```

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

### Get Service When Ready (Rust)

Source: https://docs.rs/tower/latest/tower/timeout/struct.Timeout

Yields the service when it is ready to accept a request. This method consumes the service and requires the `util` crate feature.

```rust
fn ready_oneshot(self) -> ReadyOneshot<Self, Request>
where
    Self: Sized,

```

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

### ReadyCache - Get reference to a ready service by key - Rust

Source: https://docs.rs/tower/latest/tower/ready_cache/cache/struct.ReadyCache

Obtains an immutable reference to a service in the ready set using its key. Returns `None` if the key is not present in the ready set. The returned tuple includes the service's index, key, and a reference to the service.

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

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

### Get Ready Service Reference

Source: https://docs.rs/tower/latest/tower/hedge/struct.Hedge

Yields a mutable reference to the service when it is ready to accept a request. Requires the 'util' crate feature. This is useful for ensuring a service is available before sending a request.

```Rust
fn ready(&mut self) -> Ready<'_, Self, Request>
```

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

### RateLimit Constructor and Accessors

Source: https://docs.rs/tower/latest/tower/limit/rate/struct.RateLimit

Provides methods to create a new RateLimit instance, get immutable or mutable references to the inner service, and consume the RateLimit to retrieve the inner service. These methods are part of the RateLimit implementation.

```rust
pub fn new(inner: T, rate: Rate) -> Self

Get a reference to the inner service
pub fn get_ref(&self) -> &T

Get a mutable reference to the inner service
pub fn get_mut(&mut self) -> &mut T

Consume `self`, returning the inner service
pub fn into_inner(self) -> T
```

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

### AsyncPredicate Trait Implementation Example

Source: https://docs.rs/tower/latest/tower/filter/trait.AsyncPredicate

An example implementation of the AsyncPredicate trait for a closure that returns a Future. This implementation defines the Future and Request types based on the closure's output.

```Rust
impl<F, T, U, R, E> AsyncPredicate<T> for F
where F: FnMut(T) -> U, U: Future<Output = Result<R, E>>, E: Into<BoxError> {
    type Future = ErrInto<U, Box<dyn Error + Sync + Send>>;
    type Request = R;
}
```

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

### TryFrom and TryInto Traits

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

Documentation for the `TryFrom` and `TryInto` traits, used for fallible type conversions.

```APIDOC
### `impl<T, U> TryFrom<U> for T`

**Description**: Trait for fallible conversions from type `U` into type `T`.

#### `type Error = Infallible`

**Description**: The type returned in the event of a conversion error. For `TryFrom` implementations where conversion is always infallible, this is typically `Infallible`.

#### `fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>`

**Description**: Performs the conversion from `U` to `T`.

**Method**: `try_from`

**Endpoint**: N/A (Trait method)

**Parameters**:
#### Path Parameters
None
#### Query Parameters
None
#### Request Body
None

### `impl<T, U> TryInto<U> for T`

**Description**: Trait for fallible conversions from type `T` into type `U`.

#### `type Error = <U as TryFrom<T>>::Error`

**Description**: The type returned in the event of a conversion error.

#### `fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>`

**Description**: Performs the conversion from `T` to `U`.

**Method**: `try_into`

**Endpoint**: N/A (Trait method)

**Parameters**:
#### Path Parameters
None
#### Query Parameters
None
#### Request Body
None
```

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

### Ready and ReadyOneshot for Service

Source: https://docs.rs/tower/latest/tower/make/struct.IntoService

Utilities to check service readiness. `ready` yields a mutable reference when the service is ready, while `ready_oneshot` yields the service itself when ready. Both require the 'util' crate feature.

```rust
fn ready(&mut self) -> Ready<'_, Self, Request>
where Self: Sized,
Available on **crate feature`util`** only.
Yields a mutable reference to the service when it is ready to accept a request.
```

```rust
fn ready_oneshot(self) -> ReadyOneshot<Self, Request>
where Self: Sized,
Available on **crate feature`util`** only.
Yields the service when it is ready to accept a request.
```

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

### ReadyCache - Get the total number of services - Rust

Source: https://docs.rs/tower/latest/tower/ready_cache/cache/struct.ReadyCache

Returns the total number of services currently managed by the ReadyCache, including both pending and ready services. This provides an overall count of all services being tracked.

```rust
pub fn len(&self) -> usize
```

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

### Tower Retry Policy Example Implementation

Source: https://docs.rs/tower/latest/tower/retry/trait.Policy

An example implementation of the `Policy` trait in Rust, demonstrating how to limit the number of retries based on a counter. It shows how to conditionally return a future for retrying or `None` to stop.

```rust
use tower::retry::Policy;
use futures_util::future;

type Req = String;
type Res = String;

struct Attempts(usize);

impl<E> Policy<Req, Res, E> for Attempts {
    type Future = future::Ready<()>;

    fn retry(&mut self, req: &mut Req, result: &mut Result<Res, E>) -> Option<Self::Future> {
        match result {
            Ok(_) => {
                // Treat all `Response`s as success,
                // so don't retry...
                None
            },
            Err(_) => {
                // Treat all errors as failures...
                // But we limit the number of attempts...
                if self.0 > 0 {
                    // Try again!
                    self.0 -= 1;
                    Some(future::ready(()))
                } else {
                    // Used all our attempts, no retry...
                    None
                }
            }
        }
    }

    fn clone_request(&mut self, req: &Req) -> Option<Req> {
        Some(req.clone())
    }
}
```

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

### Service Readiness and Request Handling Utilities (Rust)

Source: https://docs.rs/tower/latest/tower/util/struct.Optional

Provides functions to manage service readiness and process requests. Includes methods like `ready`, `ready_oneshot`, `oneshot`, and `call_all`. These functions are available when the `util` crate feature is enabled.

```rust
fn ready(&mut self) -> Ready<'_, Self, Request>

fn ready_oneshot(self) -> ReadyOneshot<Self, Request>

fn oneshot(self, req: Request) -> Oneshot<Self, Request>

fn call_all<S>(self, reqs: S) -> CallAll<Self, S>
where Self: Sized, S: Stream<Item = Request>
```

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

### Shared Struct Definition and Usage Example

Source: https://docs.rs/tower/latest/tower/make/struct.Shared

Defines the Shared struct which wraps a service to enable cloning. The example demonstrates how to use Shared to make a non-cloneable service cloneable and then use it with MakeService. It requires the 'make' feature flag.

```rust
pub struct Shared<S> { /* private fields */ }

// 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>
{
    // ...
}

// 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;
```

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

### Create and Apply Layer with layer_fn - Rust

Source: https://docs.rs/tower/latest/tower/layer/fn.layer_fn

Complete example demonstrating layer_fn usage to create a logging layer, wrap an uppercase string service, and compose them together. Shows how layer_fn eliminates boilerplate by accepting a closure instead of a full Layer struct.

```rust
// A `Layer` that wraps services in `LogService`
let log_layer = layer_fn(|service| {
    LogService {
        service,
        target: "tower-docs",
    }
});

// An example service. This one uppercases strings
let uppercase_service = tower::service_fn(|request: String| async move {
    Ok::<_, Infallible>(request.to_uppercase())
});

// Wrap our service in a `LogService` so requests are logged.
let wrapped_service = log_layer.layer(uppercase_service);
```

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

### IntoService and AsService for MakeService

Source: https://docs.rs/tower/latest/tower/make/struct.IntoService

Methods to convert a MakeService into a Service. `into_service` consumes the MakeService, while `as_service` provides a reference without consuming it. Both require the 'make' crate feature.

```rust
fn into_service(self) -> IntoService<Self, Request>
where Self: Sized,
Available on **crate feature`make`** only.
Consume this `MakeService` and convert it into a `Service`.
```

```rust
fn as_service(&mut self) -> AsService<'_, Self, Request>
where Self: Sized,
Available on **crate feature`make`** only.
Convert this `MakeService` into a `Service` without consuming the original `MakeService`.
```

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

### Create a BoxLayer with conditional middleware in Rust

Source: https://docs.rs/tower/latest/tower/util/struct.BoxLayer

Demonstrates how to use BoxLayer to create a consistent Service type, even when middleware like Timeout is conditionally applied based on environment variables. This example utilizes ServiceBuilder and BoxLayer to manage dynamic layer creation.

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

fn common_layer<S, T>() -> BoxLayer<S, T, S::Response, BoxError>
where
    S: Service<T> + Send + '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();

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

        BoxLayer::new(layer)
    }
}
```

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

### Get Owned Service Type

Source: https://docs.rs/tower/latest/tower/util/struct.MapErr

Defines the associated type `Owned` which represents the owned version of the service type. This is part of the `ToOwned` trait implementation.

```rust
type Owned = T
```

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

### Create TpsBudget Instance (Rust)

Source: https://docs.rs/tower/latest/tower/retry/budget/tps_budget/struct.TpsBudget

Provides a constructor for TpsBudget. This function initializes a new TpsBudget with specified parameters for time-to-live (ttl), minimum retries per second (min_per_sec), and retry percentage (retry_percent). Input validation constraints are mentioned for each parameter.

```Rust
pub fn new(ttl: Duration, min_per_sec: u32, retry_percent: f32) -> Self
```

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

### Retry Constructor and Inner Service Access (Rust)

Source: https://docs.rs/tower/latest/tower/retry/struct.Retry

Provides the constructor for the Retry struct and methods to get a reference or ownership of the inner service. The `new` function initializes the retry mechanism with a policy and a service. `get_ref`, `get_mut`, and `into_inner` allow interaction with the wrapped service.

```rust
pub const fn new(policy: P, service: S) -> Self

pub fn get_ref(&self) -> &S

pub fn get_mut(&mut self) -> &mut S

pub fn into_inner(self) -> S
```

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

### ServiceExt: Ready and Oneshot Methods (Rust)

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

Utility methods for ServiceExt that provide ways to interact with services when they are ready. `ready` yields a mutable reference, and `ready_oneshot` yields the service itself.

```rust
fn ready(&mut self) -> Ready<'_, Self, Request>;
fn ready_oneshot(self) -> ReadyOneshot<Self, Request>;
```

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

### Get Owned Service Type (Rust)

Source: https://docs.rs/tower/latest/tower/timeout/struct.Timeout

Defines the associated `Owned` type for a service, representing the type after obtaining ownership. This is part of the `ToOwned` implementation.

```rust
type Owned = T;

```

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

### Get Service Reference from MakeService (Rust)

Source: https://docs.rs/tower/latest/tower/timeout/struct.Timeout

Converts a `MakeService` into a `Service` without consuming the original `MakeService`. This method requires the `make` crate feature.

```rust
fn as_service(&mut self) -> AsService<'_, Self, Request>
where
    Self: Sized,

```

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

### Check Service Readiness

Source: https://docs.rs/tower/latest/tower/make/struct.AsService

Provides methods to check if a service is ready to accept requests. `ready` yields a mutable reference, while `ready_oneshot` yields the service itself. Both are available via the 'util' crate feature.

```rust
fn ready(&mut self) -> Ready<'_, Self, Request>

fn ready_oneshot(self) -> ReadyOneshot<Self, Request>
```

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

### TryStream Trait

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

Documentation for the `TryStream` trait, representing streams that yield `Result` items.

```APIDOC
### `impl<S, T, E> TryStream for S`

**Description**: Trait for streams that yield `Result<T, E>` items.

#### `type Ok = T`

**Description**: The type of successful values yielded by the stream.

#### `type Error = E`

**Description**: The type of failures yielded by the stream.

#### `fn try_poll_next(self: Pin<&mut S>, cx: &mut Context<'_>) -> Poll<Option<Result<<S as TryStream>::Ok, <S as TryStream>::Error>>>`

**Description**: Polls the `TryStream` for the next item, returning `Poll<Option<Result<Ok, Error>>>`.

**Method**: `try_poll_next`

**Endpoint**: N/A (Trait method)

**Parameters**:
#### Path Parameters
None
#### Query Parameters
None
#### Request Body
None
```

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

### Create Hedge Middleware Instance - Rust

Source: https://docs.rs/tower/latest/tower/hedge/struct.Hedge

Initializes a new Hedge middleware with specified service, policy, and latency configuration parameters. Requires the service to implement Clone and Service traits, and the policy to implement Policy and Clone traits.

```rust
pub fn new<Request>(
  service: S,
  policy: P,
  min_data_points: u64,
  latency_percentile: f32,
  period: Duration,
) -> Hedge<S, P>
where
  S: Service<Request> + Clone,
  S::Error: Into<BoxError>,
  P: Policy<Request> + Clone
```

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

### Example: Checking Builder Cloneability (Rust)

Source: https://docs.rs/tower/latest/tower/builder/struct.ServiceBuilder

Illustrates using `check_clone()` on a `ServiceBuilder` after applying request and response mapping middleware. This confirms the builder remains clonable.

```rust
use tower::ServiceBuilder;

let builder = ServiceBuilder::new()
    .map_request(|request: String| {
        println!("got request!");
        request
    })
    .check_clone()
    .map_response(|response: String| {
        println!("got response!");
        response
    });
```

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

### Handle Service Readiness and Request Execution in Rust

Source: https://docs.rs/tower/latest/tower/util/struct.UnsyncBoxService

Provides methods to check service readiness, execute requests, and process multiple requests efficiently. These functions are part of the `util` crate feature.

```rust
fn ready(&mut self) -> Ready<'_, Self, Request>

fn ready_oneshot(self) -> ReadyOneshot<Self, Request>

fn oneshot(self, req: Request) -> Oneshot<Self, Request>

fn call_all<S>(self, reqs: S) -> CallAll<Self, S>
where
    Self: Sized,
    S: Stream<Item = Request>,
```

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

### Future Execution and Polling (Rust)

Source: https://docs.rs/tower/latest/tower/util/struct.Oneshot

Offers utilities for polling futures, including a convenience method for `Unpin` types and a method to get the result immediately if the future is ready.

```rust
/// A convenience for calling `Future::poll` on `Unpin` future types.
fn poll_unpin(&mut self, cx: &mut Context<'_>) -> Poll<Self::Output>
where Self: Unpin,
{
    // Implementation details...
}

/// Evaluates and consumes the future, returning the resulting output if the future is ready after the first call to `Future::poll`.
fn now_or_never(self) -> Option<Self::Output>
where Self: Sized,
{
    // Implementation details...
}
```

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

### Obtain service once ready

Source: https://docs.rs/tower/latest/tower/load/pending_requests/struct.PendingRequests

The `ready_oneshot` method consumes the service and yields it once it is ready to accept a request. Requires the `util` crate feature and is available for Sized types.

```rust
fn ready_oneshot(self) -> ReadyOneshot<Self, Request>
where
    Self: Sized
```

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

### Get Future Output if Ready

Source: https://docs.rs/tower/latest/tower/util/future/struct.MapResponseFuture

Evaluates and consumes the future, returning the resulting output if the future is ready immediately after the first call to `Future::poll`. Otherwise, it returns `None`.

```rust
fn now_or_never(self) -> Option<Self::Output> where Self: Sized
```

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

### Timeout Inner Service Access

Source: https://docs.rs/tower/latest/tower/timeout/struct.Timeout

Provides methods to get a reference or mutable reference to the inner service wrapped by Timeout, and a method to consume the Timeout and retrieve the inner service.

```rust
pub fn get_ref(&self) -> &T

pub fn get_mut(&mut self) -> &mut T

pub fn into_inner(self) -> T
```

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

### AndThen Constructor and Layer

Source: https://docs.rs/tower/latest/tower/util/struct.AndThen

Provides functions to create a new AndThen service and a corresponding Layer. The `new` function directly instantiates the service, while `layer` returns a Layer that can be used to construct AndThen services.

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

pub fn layer(f: F) -> AndThenLayer<F>
```

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

### Display Trait Implementation for Discover

Source: https://docs.rs/tower/latest/tower/balance/error/struct.Discover

Implements the Display trait for the Discover error, allowing it to be formatted into a string. This is the recommended way to get a string representation of the error.

```rust
impl Display for Discover {
    fn fmt(&self, f: &mut Formatter<'_>) -> Result;
}
```

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

### ServiceExt: and_then Example

Source: https://docs.rs/tower/latest/tower/trait.ServiceExt

Demonstrates using the `and_then` method to chain an asynchronous operation after a service successfully resolves. This allows for modifying the service's response into a new type.

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

// Map the response into a new response
let mut new_service = service.and_then(|record: Record| async move {
    let name = record.name;
    avatar_lookup(name).await
});

// Call the new service
let id = 13;
let avatar = new_service.call(id).await.unwrap();
```

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

### Create a new ReadyOneshot Instance in Rust

Source: https://docs.rs/tower/latest/tower/util/struct.ReadyOneshot

This Rust function `new` is a constructor for the `ReadyOneshot` struct. It takes a generic service `T` that implements `tower::Service<Request>` and returns a `ReadyOneshot` instance, initializing it with the provided service.

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

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

### Converting and Iterating Streams with TryStreamExt

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

Provides methods for stream conversion and iteration. `into_stream` converts a `TryStream` into a standard `Stream`. `try_next` creates a future to resolve the next item, returning an error if encountered. `try_for_each` executes an asynchronous closure for each element until completion or error.

```rust
impl<S> TryStreamExt for S
where
    S: TryStream + ?Sized,
{
    fn into_stream(self) -> IntoStream<Self>
    where
        Self: Sized,
    {
        // Implementation details...
    }

    fn try_next(&mut self) -> TryNext<'_, Self>
    where
        Self: Unpin,
    {
        // Implementation details...
    }

    fn try_for_each<Fut, F>(self, f: F) -> TryForEach<Self, Fut, F>
    where
        F: FnMut(Self::Ok) -> Fut,
        Fut: TryFuture<Ok = (), Error = Self::Error>,
        Self: Sized,
    {
        // Implementation details...
    }
}
```

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

### PeakEwma Constructor

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

The `new` function for PeakEwma. It takes a service, a default round-trip time (RTT), a decay factor for the EWMA, and a completion tracker. This function initializes a new PeakEwma instance that wraps an existing service.

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

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

### Future Ext Trait Methods Example: flatten

Source: https://docs.rs/tower/latest/tower/hedge/struct.Future

Demonstrates the `flatten` method from `FutureExt`. This is useful when the output of a future is itself another future, allowing for nested futures to be executed sequentially.

```rust
impl<T> FutureExt for T
where
    T: Future + ?Sized,
{
    fn flatten(self) -> Flatten<Self>
    where
        Self::Output: Future,
        Self: Sized,
    // ... implementation details ...
}
```

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

### Load Balancing with Tower Balance p2c

Source: https://docs.rs/tower/latest/tower/balance

Demonstrates how to use the `Balance` middleware with the 'Power of Two Random Choices' algorithm to spread load across multiple services. It takes a stream of requests and distributes them to available services, handling responses.

```rust
use tower::balance::p2c::Balance;
use tower::load::Load;
use tower::{Service, ServiceExt};
use futures_util::pin_mut;

async fn spread<Req, S: Service<Req> + Load>(svc1: S, svc2: S, reqs: impl Stream<Item = Req>)
where
    S::Error: Into<tower::BoxError>,
    S::Metric: std::fmt::Debug,
{
    // Spread load evenly across the two services
    let p2c = Balance::new(tower::discover::ServiceList::new(vec![svc1, svc2]));

    // Issue all the requests that come in.
    // Some will go to svc1, some will go to svc2.
    pin_mut!(reqs);
    let mut responses = p2c.call_all(reqs);
    while let Some(rsp) = responses.next().await {
        // ...
    }
}
```

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

### ReadyCache - Get number of pending services - Rust

Source: https://docs.rs/tower/latest/tower/ready_cache/cache/struct.ReadyCache

Returns the count of services that are currently in the 'pending' (unready) state within the ReadyCache. These are services that have been added but have not yet polled ready.

```rust
pub fn pending_len(&self) -> usize
```

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

### Tower Balance Utility Methods

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

Offers utility methods for the 'Balance' struct, including 'len' to get the current number of tracked endpoints and 'is_empty' to check if the balancer has any active services.

```rust
pub fn len(&self) -> usize

pub fn is_empty(&self) -> bool

```

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

### Create Service Instance

Source: https://docs.rs/tower/latest/tower/util/struct.MapResponse

Asynchronously creates and returns a new service instance. This function is available only when the `make` feature is enabled.

```rust
fn make_service( &mut self, target: Target,
) -> <M as MakeService<Target, Request>>::Future
```

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

### MakeBalanceLayer Layer Implementation

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

Demonstrates how `MakeBalanceLayer` implements the `Layer` trait from the tower crate. The `layer` method takes a `make_discover` service and returns a `MakeBalance` service, wrapping the original service with the middleware.

```rust
impl<S, Req> Layer<S> for MakeBalanceLayer<S, Req>
where
    S: tower_discover::MakeDiscover
{
    type Service = MakeBalance<S, Req>;

    fn layer(&self, make_discover: S) -> Self::Service {
        MakeBalance::new(make_discover)
    }
}
```

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

### AsyncFilter Inner Service Access

Source: https://docs.rs/tower/latest/tower/filter/struct.AsyncFilter

Provides methods to get a reference or mutable reference to the inner service wrapped by `AsyncFilter`, as well as a method to consume the `AsyncFilter` and retrieve the inner service.

```rust
impl<T, U> AsyncFilter<T, U> {
    pub fn get_ref(&self) -> &T
    pub fn get_mut(&mut self) -> &mut T
    pub fn into_inner(self) -> T
}
```

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

### Get Next Item with try_next in Rust

Source: https://docs.rs/tower/latest/tower/util/struct.CallAllUnordered

Creates a future that resolves to the next item in the stream, returning an Option wrapping a Result. Errors are returned immediately without consuming further items.

```rust
fn try_next(&mut self) -> TryNext<'_, Self>
where
    Self: Unpin,
```

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

### Ready Chunks Stream - Rust Stream Adapter

Source: https://docs.rs/tower/latest/tower/discover/struct.ServiceList

Groups ready items of the stream into vectors of up to capacity size. Returns a ReadyChunks adapter that collects only immediately available items without waiting. Useful for non-blocking batch collection.

```rust
fn ready_chunks(self, capacity: usize) -> ReadyChunks<Self>
where Self: Sized
```

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

### Consuming a Stream to Get the Next Item

Source: https://docs.rs/tower/latest/tower/load/struct.Constant

Creates a future that resolves to the next item in the stream. This operation requires the stream to be `Unpin`. It's a fundamental way to interact with streams sequentially.

```rust
fn next(&mut self) -> Next<'_, Self>
where
    Self: Unpin,
```

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

### ServiceExt::ready

Source: https://docs.rs/tower/latest/tower/make/struct.Shared

Yields a mutable reference to the service when it is ready to accept a request. This method ensures the service is prepared before use.

```APIDOC
## ready

### Description
Yields a mutable reference to the service when it is ready to accept a request.

### Method
Fn

### Signature
```rust
fn ready(&mut self) -> Ready<'_, Self, Request>
where
  Self: Sized
```

### Parameters
#### Method Parameters
- **self** (Service<Request>) - Mutable reference to the service

### Returns
- **Type**: `Ready<'_, Self, Request>` (Future)
- **Description**: A future that resolves when the service is ready

### Features Required
- `util`

### Trait Bound
- Implemented for `T: Service<Request> + ?Sized`
```

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

### Rust Display Trait Implementation for Closed

Source: https://docs.rs/tower/latest/tower/buffer/error/struct.Closed

Shows the implementation of the Display trait for the Closed struct, allowing it to be formatted as a string. This is the recommended way to get a user-friendly error message.

```rust
impl Display for Closed {
    fn fmt(&self, fmt: &mut Formatter<'_>) -> Result {
        /* ... */
    }
}
```

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

### Enable Specific Tower Middleware

Source: https://docs.rs/tower/latest/tower/index

You can selectively enable specific middleware by listing them in the 'features' section of your Cargo.toml. This example shows how to enable only the 'retry' and 'timeout' middleware, reducing compile times and binary size.

```toml
tower = { version = "0.4", features = ["retry", "timeout"] }
```

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

### FutureExt Trait Methods for Futures

Source: https://docs.rs/tower/latest/tower/spawn_ready/future/struct.ResponseFuture

Demonstrates various extension methods provided by the FutureExt trait, applicable to any type implementing the Future trait. These methods offer convenient ways to transform, combine, and manage futures.

```rust
impl<T> FutureExt for T
where T: Future + ?Sized,
{
    fn map<U, F>(self, f: F) -> Map<Self, F>
    where F: FnOnce(Self::Output) -> U, Self: Sized,
    {
        // ... map implementation ...
    }

    fn map_into<U>(self) -> MapInto<Self, U>
    where Self::Output: Into<U>, Self: Sized,
    {
        // ... map_into implementation ...
    }

    fn then<Fut, F>(self, f: F) -> Then<Self, Fut, F>
    where F: FnOnce(Self::Output) -> Fut, Fut: Future, Self: Sized,
    {
        // ... then implementation ...
    }
    // ... other methods like left_future, right_future, into_stream, flatten, etc.
}
```

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

### Take Stream Items - Rust Stream Adapter

Source: https://docs.rs/tower/latest/tower/discover/struct.ServiceList

Creates a new stream containing at most n items from the underlying stream. This adapter limits the number of elements produced by the stream. Consumes self and returns a sized Take wrapper that implements the Stream trait.

```rust
fn take(self, n: usize) -> Take<Self>
where Self: Sized
```
Tokens:
Raw