tower-http

Response classification is the process of determining whether an HTTP response (or an error) should be treated as a success or a failure. This is primarily used by middleware like logging, metrics, or retry policies to react to the outcome of a request.

There are three main levels of abstraction:

1. ClassifyResponse: The core trait. It attempts to classify a response immediately (ClassifiedResponse::Ready) or indicates that classification must wait until the response body stream ends (ClassifiedResponse::RequiresEos).
2. ClassifyEos: Used for streaming responses (like gRPC) where the final status might only be available in the response trailers at the End of Stream (EOS).
3. MakeClassifier: A factory trait used when the classification logic depends on information from the incoming Request (e.g., the URI or HTTP method).

If your classifier does not depend on the request, you can use SharedClassifier to wrap a ClassifyResponse implementation into a MakeClassifier.

// Example of a simple classifier that only cares about errors
#[derive(Clone, Copy)]
struct MyClassifier;

impl ClassifyResponse for MyClassifier {
    type FailureClass = String;
    type ClassifyEos = NeverClassifyEos<Self::FailureClass>;

    fn classify_response<B>(self, _res: &Response<B>) -> ClassifiedResponse<Self::FailureClass, Self::ClassifyEos> {
        ClassifiedResponse::Ready(Ok(()))
    }

    fn classify_error<E>(self, error: &E) -> Self::FailureClass
    where E: std::fmt::Display + 'static,
    {
        error.to_string()
    }
}

// Use SharedClassifier to turn it into a MakeClassifier
let make_classifier = SharedClassifier::new(MyClassifier);

The ServiceBuilderExt trait extends tower::ServiceBuilder with specialized methods for adding tower-http middleware. This allows you to chain HTTP-specific layers (like compression, tracing, or header manipulation) directly onto a ServiceBuilder instance.

Note that many of these methods are gated by Cargo features (e.g., compression-gzip, trace, set-header). Ensure the required feature is enabled in your Cargo.toml to access the corresponding method.

use http::{Request, Response, header::HeaderName};
use bytes::Bytes;
use http_body_util::Full;
use std::{time::Duration, convert::Infallible};
use tower::{ServiceBuilder, ServiceExt, Service};
use tower_http::ServiceBuilderExt;

async fn handle(request: Request<Full<Bytes>>) -> Result<Response<Full<Bytes>>, Infallible> {
    Ok(Response::new(Full::default()))
}

#[tokio::main]
async fn main() {
    let service = ServiceBuilder::new()
        // Methods from tower
        .timeout(Duration::from_secs(30))
        // Methods from tower-http
        .trace_for_http()
        .propagate_header(HeaderName::from_static("x-request-id"))
        .service_fn(handle);
    
    let mut service = service;
    service.ready().await.unwrap().call(Request::new(Full::default())).await.unwrap();
}

A TimeoutBody is a wrapper around an http_body::Body that enforces a timeout on the interval between consecutive data frames.

Key Behaviors:

• Inactivity Timeout: The timeout is enforced between consecutive Frame polls. It resets every time a new frame is successfully produced.
• Total Duration: The total time to produce a full body can exceed the timeout duration, provided that no single interval between frames exceeds the specified Duration.
• Error Trigger: If the underlying body does not produce a requested data frame within the timeout period, it returns a TimeoutError.

Difference from Timeout middleware:

• Timeout (from crate::timeout::Timeout) applies to the entire request future and does not reset as bytes are processed.
• TimeoutBody is specifically for asynchronous body streaming, which occurs outside the standard Tower service stack's future lifecycle.

use http_body_util::Full;
use bytes::Bytes;
use std::time::Duration;
use tower::ServiceBuilder;
use tower_http::timeout::RequestBodyTimeoutLayer;

// Example of applying a body timeout layer to a service
let svc = ServiceBuilder::new()
    .layer(RequestBodyTimeoutLayer::new(Duration::from_secs(30)))
    .service_fn(handle);