### 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| 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| 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, _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>(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( svc1: &mut S1, svc2: &mut S2, request: R ) -> Result where S1: Load + Service, S2: Load + Service { 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() -> BoxCloneServiceLayer where S: Service + Clone + Send + 'static, S::Future: Send + 'static, S::Error: Into + '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 = 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 = 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>> for HelloWorld { type Response = Response>; type Error = http::Error; type Future = Pin>>>; fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll> { Poll::Ready(Ok(())) } fn call(&mut self, req: Request>) -> Self::Future { // create the body let body: Vec = "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(); ``` -------------------------------- ### 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 ``` -------------------------------- ### 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 for MyService { type Response = Response; type Error = Error; type Future = futures_util::future::Ready>; fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll> { 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::() // Modify response type .map_response(|response: Response| WrappedResponse(response)) // Check updated types .check_service::(); ``` -------------------------------- ### 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 Layer for LogLayer { type Service = LogService; fn layer(&self, service: S) -> Self::Service { LogService { target: self.target, service } } } // This service implements the Log behavior pub struct LogService { target: &'static str, service: S, } impl Service for LogService where S: Service, Request: fmt::Debug, { type Response = S::Response; type Error = S::Error; type Future = S::Future; fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll> { 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 ``` -------------------------------- ### Example: Checking Service Cloneability (Rust) Source: https://docs.rs/tower/latest/tower/builder/struct.ServiceBuilder Demonstrates using `check_service_clone::()` 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::() .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 + Load>(svc1: S, svc2: S, reqs: impl Stream) where S::Error: Into, 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 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>( &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 AsyncPredicate for F where F: FnMut(T) -> U, U: Future>, E: Into { type Future = ErrInto>; 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 TryFrom 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>::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 TryInto for T` **Description**: Trait for fallible conversions from type `T` into type `U`. #### `type Error = >::Error` **Description**: The type returned in the event of a conversion error. #### `fn try_into(self) -> Result>::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 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 Policy for Attempts { type Future = future::Ready<()>; fn retry(&mut self, req: &mut Req, result: &mut Result) -> Option { 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 { 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 fn oneshot(self, req: Request) -> Oneshot fn call_all(self, reqs: S) -> CallAll where Self: Sized, S: Stream ``` -------------------------------- ### 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 { /* 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 for MyService { type Response = Response; type Error = Infallible; type Future = Ready>; fn poll_ready(&mut self, _cx: &mut Context<'_>) -> Poll> { 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) where Make: MakeService { // ... } // 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 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() -> BoxLayer where S: Service + Send + 'static, S::Future: Send + 'static, S::Error: Into + '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; ``` -------------------------------- ### 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 ``` -------------------------------- ### 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 TryStream for S` **Description**: Trait for streams that yield `Result` 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::Ok, ::Error>>>` **Description**: Polls the `TryStream` for the next item, returning `Poll>>`. **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( service: S, policy: P, min_data_points: u64, latency_percentile: f32, period: Duration, ) -> Hedge where S: Service + Clone, S::Error: Into, P: Policy + 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 fn oneshot(self, req: Request) -> Oneshot fn call_all(self, reqs: S) -> CallAll where Self: Sized, S: Stream, ``` -------------------------------- ### 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 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 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 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 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 ``` -------------------------------- ### 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 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` 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 TryStreamExt for S where S: TryStream + ?Sized, { fn into_stream(self) -> IntoStream where Self: Sized, { // Implementation details... } fn try_next(&mut self) -> TryNext<'_, Self> where Self: Unpin, { // Implementation details... } fn try_for_each(self, f: F) -> TryForEach where F: FnMut(Self::Ok) -> Fut, Fut: TryFuture, 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 FutureExt for T where T: Future + ?Sized, { fn flatten(self) -> Flatten where Self::Output: Future, Self: Sized, // ... implementation details ... } ``` -------------------------------- ### 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, ) -> >::Future ``` -------------------------------- ### 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 ``` -------------------------------- ### 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 + Load>(svc1: S, svc2: S, reqs: impl Stream) where S::Error: Into, 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 { // ... } } ``` -------------------------------- ### 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 Layer for MakeBalanceLayer where S: tower_discover::MakeDiscover { type Service = MakeBalance; 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 AsyncFilter { pub fn get_ref(&self) -> &T pub fn get_mut(&mut self) -> &mut T pub fn into_inner(self) -> T } ``` -------------------------------- ### 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 where Self: Sized ``` -------------------------------- ### 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, ``` -------------------------------- ### 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) - 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 + ?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 FutureExt for T where T: Future + ?Sized, { fn map(self, f: F) -> Map where F: FnOnce(Self::Output) -> U, Self: Sized, { // ... map implementation ... } fn map_into(self) -> MapInto where Self::Output: Into, Self: Sized, { // ... map_into implementation ... } fn then(self, f: F) -> Then 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 where Self: Sized ```