Tower (Rust Library)

Tower is a set of modular and reusable components for building robust client and server applications in Rust's asynchronous ecosystem. It provides a foundational abstraction for asynchronous services, enabling developers to compose complex network logic from simpler, independent units. While not an HTTP framework itself, Tower forms the backbone for popular web frameworks like Axum and HTTP libraries like Hyper, as well as gRPC frameworks like Tonic.

At its core, Tower defines two primary traits:

1. `Service<Request>`: This is the fundamental trait representing an asynchronous operation that takes a `Request` and eventually produces a `Response`.
* `poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>`: This method is crucial for implementing *backpressure*. It allows a service to signal when it is ready to process a new request or when it's overloaded and needs to pause. A service should only `call` another service if `poll_ready` returns `Poll::Ready(Ok(()))`.
* `call(&mut self, req: Request) -> Self::Future`: This method takes a `Request` and returns a `Future` that resolves to `Result<Self::Response, Self::Error>`. The `call` method itself is not asynchronous; it immediately returns a `Future` that, when awaited, performs the actual asynchronous work.

2. `Layer<S>`: This trait represents a middleware. A `Layer` takes an inner `Service` (`S`) and wraps it, returning a new `Service` (`Self::Service`) that adds behavior around the inner service. This allows for modular composition of functionalities like logging, metrics, timeouts, retries, authentication, and more, without modifying the core business logic.
* `layer(&self, inner: S) -> Self::Service`: This method is responsible for constructing the new, wrapped service.

Why Use Tower?
* Modularity and Reusability: Common concerns (like logging or error handling) can be implemented once as a `Layer` and reused across many different services or applications.
* Composability: Layers can be stacked (`layer_a.layer(layer_b.layer(my_service))`) to build complex behaviors from simple, independent units.
* Backpressure: The `poll_ready` mechanism allows services to gracefully handle high load by signaling when they are unable to accept more requests, preventing resource exhaustion and improving system stability.
* Asynchronous-native: Designed from the ground up for Rust's `async/await` paradigm, integrating seamlessly with `tokio` and other async runtimes.
* Ecosystem Integration: Provides a common interface for different network protocols (HTTP, gRPC, custom TCP protocols), making it easier to build interoperable systems and leverage existing Tower-compatible components.

In summary, Tower provides a powerful, abstract, and composable foundation for building robust and scalable asynchronous services in Rust, encouraging good architectural practices and enabling the creation of highly resilient network applications.

Example Code

```rust
use std::{
    future::Future,
    pin::Pin,
    task::{Context, Poll},
    time::Duration,
};
use tower::{Layer, Service};
use tokio::time::sleep;

// --- 1. Define a custom Service ---
// Our basic service will take a String and return a String.
struct MyService;

impl Service<String> for MyService {
    // The response type
    type Response = String;
    // The error type
    type Error = Box<dyn std::error::Error + Send + Sync>;
    // The future returned by `call`
    type Future = Pin<Box<dyn Future<Output = Result<Self::Response, Self::Error>> + Send>>;

    // `poll_ready` is for backpressure. Here, we're always ready.
    fn poll_ready(&mut self, _cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
        Poll::Ready(Ok(()))
    }

    // `call` processes the request asynchronously.
    fn call(&mut self, req: String) -> Self::Future {
        println!("  (Inner Service) Received request: {}", req);
        let fut = async move {
            // Simulate some async work
            sleep(Duration::from_millis(100)).await;
            let response = format!("Processed: {}", req);
            println!("  (Inner Service) Sending response: {}", response);
            Ok(response)
        };
        Box::pin(fut)
    }
}

// --- 2. Define a custom Layer ---
// This layer will add logging functionality.
struct MyLoggingLayer;

impl<S> Layer<S> for MyLoggingLayer {
    type Service = MyLoggingService<S>;

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

struct MyLoggingService<S> {
    inner: S,
}

impl<S, Request> Service<Request> for MyLoggingService<S>
where
    S: Service<Request>,
    S::Future: Send + 'static, // Ensure the inner future is Send and 'static
    Request: std::fmt::Debug + Send + 'static, // Request needs to be Debug for logging
    S::Error: Into<Box<dyn std::error::Error + Send + Sync>> + Send, // Ensure error can be converted
{
    type Response = S::Response;
    type Error = Box<dyn std::error::Error + Send + Sync>;
    type Future = Pin<Box<dyn Future<Output = Result<Self::Response, Self::Error>> + Send>>;

    fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
        // Delegate readiness check to the inner service
        self.inner.poll_ready(cx).map_err(Into::into)
    }

    fn call(&mut self, req: Request) -> Self::Future {
        println!("[Logging Layer] Request received: {:?}", req);

        let inner_fut = self.inner.call(req);
        let fut = async move {
            let res = inner_fut.await.map_err(Into::into)?;
            println!("[Logging Layer] Response sent.");
            Ok(res)
        };
        Box::pin(fut)
    }
}


#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    println!("--- Tower Example ---");

    // Create the base service
    let my_service = MyService;

    // Create the logging layer
    let logging_layer = MyLoggingLayer;

    // Compose them: apply the layer to the service
    // The layer wraps the service, so `composed_service` is now a `Service`
    // that first logs, then calls `my_service`.
    let mut composed_service = logging_layer.layer(my_service);

    println!("\nCalling composed service with 'Hello Tower!'");
    let response = composed_service.call("Hello Tower!".to_string()).await?;
    println!("Main received response: {}\n", response);

    println!("\nCalling composed service again with 'Rust is great!'");
    let response = composed_service.call("Rust is great!".to_string()).await?;
    println!("Main received response: {}\n", response);

    Ok(())
}
```

Tower (Rust Library)

Example Code

Related Topics