tower-http

https://docs.rs/tower-http/latest/
Admin
tower-http is a library that provides HTTP-specific middleware and utilities built on top of tower,...
Tokens:1,436,819
Snippets:10,414
Trust Score:9.1
Update:1 week ago
Show doc for...
Tokens:
Raw
### Example: TraceLayer with all callbacks

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

Shows how to customize all five trace callbacks on a TraceLayer::new_for_http() service. The example records a span with method and URI, then logs debug events for request start, response end, body chunks, stream end, and failures. Each callback receives a span reference and specific timing data.

```rust
use http::{Request, Response};
use http_body_util::Full;
use bytes::Bytes;
use tower::ServiceBuilder;
use tower_http::classify::ServerErrorsFailureClass;
use tower_http::trace::TraceLayer;
use tracing::{Span, info_span};
use std::time::Duration;

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

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let service = ServiceBuilder::new()
        .layer(
            TraceLayer::new_for_http()
                .make_span_with(|request: &Request<Body>| {
                    info_span!(
                        "request",
                        method = %request.method(),
                        uri = %request.uri(),
                    )
                })
                .on_request(|request: &Request<Body>, _span: &Span| {
                    tracing::debug!("started processing request")
                })
                .on_response(|response: &Response<Body>, latency: Duration, _span: &Span| {
                    tracing::debug!("finished processing request")
                })
                .on_body_chunk(|chunk: &Bytes, latency: Duration, _span: &Span| {
                    tracing::debug!("sending {} bytes", chunk.len())
                })
                .on_eos(|trailers: Option<&HeaderMap>, stream_duration: Duration, _span: &Span| {
                    tracing::debug!("stream closed after {:?}", stream_duration)
                })
                .on_failure(|error: ServerErrorsFailureClass, latency: Duration, _span: &Span| {
                    tracing::debug!("something went wrong")
                })
        )
        .service_fn(handle);
    Ok(())
}
```

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

### CSRF middleware usage example

Source: https://docs.rs/tower-http/latest/src/tower_http/csrf/mod.rs.html

Shows how to create a CsrfLayer, add a trusted origin, and build a service that allows safe methods (GET) and blocks cross-site POSTs. The example asserts that a GET request returns OK and a cross-site POST returns FORBIDDEN.

```rust
use bytes::Bytes;
use http::{Request, Response, StatusCode};
use http_body_util::Full;
use tower::{Service, ServiceExt, ServiceBuilder, service_fn, BoxError};
use tower_http::csrf::CsrfLayer;

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

# #[tokio::main]
# async fn main() -> Result<(), BoxError> {
let layer = CsrfLayer::new()
    .add_trusted_origin("https://example.com")?;

let mut service = ServiceBuilder::new()
    .layer(layer)
    .service_fn(handle);

// Safe methods always pass.
let request = Request::builder()
    .method("GET")
    .uri("/")
    .body(Full::default())
    .unwrap();

let response = service.ready().await?.call(request).await?;

assert_eq!(response.status(), StatusCode::OK);

// Cross-site POSTs are blocked.
let request = Request::builder()
    .method("POST")
    .uri("/")
    .header("host", "example.com")
    .header("sec-fetch-site", "cross-site")
    .body(Full::default())
    .unwrap();

let response = service.ready().await?.call(request).await?;

assert_eq!(response.status(), StatusCode::FORBIDDEN);

# Ok(())
# }

```

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

### Basic TraceLayer example and expected logs

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

Shows the minimal setup for adding tracing with TraceLayer::new_for_http(), expected logs when running with `RUST_LOG=tower_http=trace cargo run`. The output includes the exact request/response log lines with method, path, latency, and status.

```rust
```rust
use http::{Request, Response};
use tower::{ServiceBuilder, ServiceExt, Service};
use tower_http::trace::TraceLayer;
use std::convert::Infallible;
use http_body_util::Full;
use bytes::Bytes;

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

# #[tokio::main]
# async fn main() -> Result<(), Box<dyn std::error::Error>> {
// Setup tracing
tracing_subscriber::fmt::init();

let mut service = ServiceBuilder::new()
    .layer(TraceLayer::new_for_http())
    .service_fn(handle);

let request = Request::new(Full::from("foo"));

let response = service
    .ready()
    .await?
    .call(request)
    .await?;
# Ok(())
# }
```
```

```text
```text
Mar 05 20:50:28.523 DEBUG request{method=GET path="/foo"}: tower_http::trace::on_request: started processing request
Mar 05 20:50:28.524 DEBUG request{method=GET path="/foo"}: tower_http::trace::on_response: finished processing request latency=1 ms status=200
```
```

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

### Example trace log output

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

Example log output when running the basic example with RUST_LOG=tower_http=trace.

```text
Mar 05 20:50:28.523 DEBUG request{method=GET path="/foo"}: tower_http::trace::on_request: started processing request
Mar 05 20:50:28.524 DEBUG request{method=GET path="/foo"}: tower_http::trace::on_response: finished processing request latency=1 ms status=200
```

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

### clone_from example for Box

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

Example showing how to copy contents from one Box to another without creating a new allocation.

```rust
let x = Box::new(5);
let mut y = Box::new(10);
let yp: *const i32 = &*y;

y.clone_from(&x);

// The value is the same
assert_eq!(x, y);

// And no allocation occurred
assert_eq!(yp, &*y);
```

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

### Basic TraceLayer setup with ServiceBuilder

Source: https://docs.rs/tower-http/latest/tower_http/trace/index.html

Adds high-level tracing to a service using `TraceLayer::new_for_http()`. Requires the `trace` crate feature. The example sets up a tracing subscriber and uses `ServiceBuilder` to layer the trace middleware. Run with `RUST_LOG=tower_http=trace cargo run` to see the logs.

```rust
use http::{Request, Response};
use tower::{ServiceBuilder, ServiceExt, Service};
use tower_http::trace::TraceLayer;
use std::convert::Infallible;
use http_body_util::Full;
use bytes::Bytes;

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

// Setup tracing
tracing_subscriber::fmt::init();

let mut service = ServiceBuilder::new()
    .layer(TraceLayer::new_for_http())
    .service_fn(handle);

let request = Request::new(Full::from("foo"));

let response = service
    .ready()
    .await?
    .call(request)
    .await?;
```

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

### CORS Layer Example: Allow GET and POST from Any Origin

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

Shows how to create a `CorsLayer` that allows `GET` and `POST` methods from any origin, apply it to a service, and verify the `Access-Control-Allow-Origin` header is set to `*`. Requires the `http`, `http-body-util`, `bytes`, `tower`, and `tower-http` crates.

```rust
use http::{Request, Response, Method, header};
use http_body_util::Full;
use bytes::Bytes;
use tower::{ServiceBuilder, ServiceExt, Service};
use tower_http::cors::{Any, CorsLayer};
use std::convert::Infallible;

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

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let cors = CorsLayer::new()
        // allow `GET` and `POST` when accessing the resource
        .allow_methods([Method::GET, Method::POST])
        // allow requests from any origin
        .allow_origin(Any);

    let mut service = ServiceBuilder::new()
        .layer(cors)
        .service_fn(handle);

    let request = Request::builder()
        .header(header::ORIGIN, "https://example.com")
        .body(Full::default())
        .unwrap();

    let response = service
        .ready()
        .await?
        .call(request)
        .await?;

    assert_eq!(
        response.headers().get(header::ACCESS_CONTROL_ALLOW_ORIGIN).unwrap(),
        "*",
    );
    Ok(())
}
```

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

### tower_http::limit module documentation with RequestBodyLimitLayer examples

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

Module-level documentation for tower_http::limit, including two Rust examples: one for limiting based on Content-Length and one for limiting without known Content-Length. The examples show how to use RequestBodyLimitLayer with ServiceBuilder and handle LengthLimitError.

```rust
//! Middleware for limiting request bodies.
//!
//! This layer will also intercept requests with a `Content-Length` header
//! larger than the allowable limit and return an immediate error response
//! before reading any of the body.
//!
//! Note that payload length errors can be used by adversaries in an attempt
//! to smuggle requests. When an incoming stream is dropped due to an
//! over-sized payload, servers should close the connection or resynchronize
//! by optimistically consuming some data in an attempt to reach the end of
//! the current HTTP frame. If the incoming stream cannot be resynchronized,
//! then the connection should be closed. If you're using [hyper] this is
//! automatically handled for you.
//!
//! # Examples
//!
//! ## Limiting based on `Content-Length`
//!
//! If a `Content-Length` header is present and indicates a payload that is
//! larger than the acceptable limit, then the underlying service will not
//! be called and a `413 Payload Too Large` response will be generated.
//!
//! ```rust
//! use bytes::Bytes;
//! use std::convert::Infallible;
//! use http::{Request, Response, StatusCode, HeaderValue, header::CONTENT_LENGTH};
//! use http_body_util::{LengthLimitError};
//! use tower::{Service, ServiceExt, ServiceBuilder};
//! use tower_http::{body::Limited, limit::RequestBodyLimitLayer};
//! use http_body_util::Full;
//!
//! # #[tokio::main]
//! # async fn main() -> Result<(), Box<dyn std::error::Error>> {
//! async fn handle(req: Request<Limited<Full<Bytes>>>) -> Result<Response<Full<Bytes>>, Infallible> {
//!     panic!("This should not be hit")
//! }
//!
//! let mut svc = ServiceBuilder::new()
//!     // Limit incoming requests to 4096 bytes.
//!     .layer(RequestBodyLimitLayer::new(4096))
//!     .service_fn(handle);
//!
//! // Call the service with a header that indicates the body is too large.
//! let mut request = Request::builder()
//!     .header(CONTENT_LENGTH, HeaderValue::from_static("5000"))
//!     .body(Full::<Bytes>::default())
//!     .unwrap();
//!
//! // let response = svc.ready().await?.call(request).await?;
//! let response = svc.call(request).await?;
//!
//! assert_eq!(response.status(), StatusCode::PAYLOAD_TOO_LARGE);
//! #
//! # Ok(())
//! # }
//! ```
//!
//! ## Limiting without known `Content-Length`
//!
//! If a `Content-Length` header is not present, then the body will be read
//! until the configured limit has been reached. If the payload is larger than
//! the limit, the [`http_body_util::Limited`] body will return an error. This
//! error can be inspected to determine if it is a [`http_body_util::LengthLimitError`]
//! and return an appropriate response in such case.
//!
//! Note that no error will be generated if the body is never read. Similarly,
//! if the body _would be_ too large, but is never consumed beyond the length
//! limit, then no error is generated, and handling of the remaining incoming
//! data stream is left to the server implementation as described above.
//!
//! ```rust
//! # use bytes::Bytes;
//! # use std::convert::Infallible;
//! # use http::{Request, Response, StatusCode};
//! # use http_body_util::LengthLimitError;
//! # use tower::{Service, ServiceExt, ServiceBuilder, BoxError};
//! # use tower_http::{body::Limited, limit::RequestBodyLimitLayer};
//! # use http_body_util::Full;
//! # use http_body_util::BodyExt;
//! #
//! # #[tokio::main]
//! # async fn main() -> Result<(), BoxError> {
//! async fn handle(req: Request<Limited<Full<Bytes>>>) -> Result<Response<Full<Bytes>>, BoxError> {
//!     let data = match req.into_body().collect().await {
//!         Ok(collected) => collected.to_bytes(),
//!         Err(err) => {
//!             if let Some(_) = err.downcast_ref::<LengthLimitError>() {
//!                 let mut resp = Response::new(Full::default());
//!                 *resp.status_mut() = StatusCode::PAYLOAD_TOO_LARGE;
//!                 return Ok(resp);
//!             } else {
//!                 return Err(err);
//!             }
//!         }
//!     };
//!
//!     Ok(Response::new(Full::default()))
//! }
//!
//! let mut svc = ServiceBuilder::new()
//!     // Limit incoming requests to 4096 bytes.
//!     .layer(RequestBodyLimitLayer::new(4096))
//!     .service_fn(handle);
//!
//! // Call the service.
//! let request = Request::new(Full::<Bytes>::default());
//!
//! let response = svc.ready().await?.call(request).await?;
//!
//! assert_eq!(response.status(), StatusCode::OK);
//!
//! // Call the service with a body that is too large.
//! let request = Request::new(Full::<Bytes>::from(Bytes::from(vec![0u8; 4097])));
//! #
//! # let response = svc.ready().await?.call(request).await?;
//! #
//! # assert_eq!(response.status(), StatusCode::PAYLOAD_TOO_LARGE);
//! #
//! # Ok(())
//! # }
//! ```
```

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

### Example: Using RequestBodyDeadlineLayer with ServiceBuilder

Source: https://docs.rs/tower-http/latest/src/tower_http/timeout/deadline_body.rs.html?search=

Shows how to wrap a service with `RequestBodyDeadlineLayer` to timeout bodies after 30 seconds. The example uses `ServiceBuilder` and `service_fn`.

```rust
use http::{Request, Response};
use bytes::Bytes;
use http_body_util::Full;
use std::time::Duration;
use tower::ServiceBuilder;
use tower_http::timeout::RequestBodyDeadlineLayer;

async fn handle(_: Request<Full<Bytes>>) -> Result<Response<Full<Bytes>>, std::convert::Infallible> {
    // ...
    # todo!()
}

# #[tokio::main]
# async fn main() -> Result<(), Box<dyn std::error::Error>> {
let svc = ServiceBuilder::new()
    // Timeout bodies after 30 seconds total
    .layer(RequestBodyDeadlineLayer::new(Duration::from_secs(30)))
    .service_fn(handle);
# Ok(())
# }

```

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

### Example: Compress response body with CompressionLayer

Source: https://docs.rs/tower-http/latest/src/tower_http/compression/mod.rs.html

Shows how to create a service that compresses responses based on the Accept-Encoding header. It opens a file, converts it to a body, wraps the service with CompressionLayer, and verifies the response is gzip-compressed and smaller than the original.

```rust
use bytes::{Bytes, BytesMut};
use http::{Request, Response, header::ACCEPT_ENCODING};
use http_body_util::{Full, BodyExt, StreamBody, combinators::UnsyncBoxBody};
use http_body::Frame;
use std::convert::Infallible;
use tokio::fs::{self, File};
use tokio_util::io::ReaderStream;
use tower::{Service, ServiceExt, ServiceBuilder, service_fn};
use tower_http::{compression::CompressionLayer, BoxError};
use futures_util::TryStreamExt;

type BoxBody = UnsyncBoxBody<Bytes, std::io::Error>;

#[tokio::main]
async fn main() -> Result<(), BoxError> {
async fn handle(req: Request<Full<Bytes>>) -> Result<Response<BoxBody>, Infallible> {
    // Open the file.
    let file = File::open("Cargo.toml").await.expect("file missing");
    // Convert the file into a `Stream` of `Bytes`.
    let stream = ReaderStream::new(file);
    // Convert the stream into a stream of data `Frame`s.
    let stream = stream.map_ok(Frame::data);
    // Convert the `Stream` into a `Body`.
    let body = StreamBody::new(stream);
    // Erase the type because it's very hard to name in the function signature.
    let body = body.boxed_unsync();
    // Create response.
    Ok(Response::new(body))
}

let mut service = ServiceBuilder::new()
    // Compress responses based on the `Accept-Encoding` header.
    .layer(CompressionLayer::new())
    .service_fn(handle);

// Call the service.
let request = Request::builder()
    .header(ACCEPT_ENCODING, "gzip")
    .body(Full::<Bytes>::default())?;

let response = service
    .ready()
    .await?
    .call(request)
    .await?;

assert_eq!(response.headers()["content-encoding"], "gzip");

// Read the body
let bytes = response
    .into_body()
    .collect()
    .await?
    .to_bytes();

// The compressed body should be smaller 🤞
let uncompressed_len = fs::read_to_string("Cargo.toml").await?.len();
assert!(bytes.len() < uncompressed_len);

Ok(())
}
```

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

### SetRequestHeaderLayer usage example

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

Example showing how to use SetRequestHeaderLayer to set a request header. The example is part of a tower-http middleware setup and uses the tower Service trait. The code is from the module documentation and is intended to be used in a Rust async context.

```rust
//! let _response = svc.ready().await?.call(request).await?;
//! # Ok(())
//! # }
//! ```
```

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

### OnEarlyDropLayer::new

Source: https://docs.rs/tower-http/latest/tower_http/on_early_drop/struct.OnEarlyDropLayer.html

Installs the same hook in both slots. Typical choice is `EarlyDropsAsFailures`; see the module docs for the example.

```APIDOC
## OnEarlyDropLayer::new

### Description
Installs the same hook in both slots. Typical choice is `EarlyDropsAsFailures`; see the module docs for the example.

### Method
`pub fn new(hook: H) -> Self`

### Parameters
- `hook` (H) - Required - The hook to install in both slots.

### Returns
- `Self` - A new `OnEarlyDropLayer` with the given hook in both slots.

```

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

### on_early_drop module documentation with examples

Source: https://docs.rs/tower-http/latest/src/tower_http/on_early_drop/mod.rs.html?search=

Module-level documentation for tower_http::on_early_drop. It explains the middleware's purpose, distinguishes future drop from body drop, and includes three usage examples: bridging to trace::OnFailure, using the builder with direct callbacks, and using the standalone OnEarlyDropGuard. It also warns that callbacks must not panic because they fire from Drop.

```rust
//! Middleware that detects when a response future or response body is
//! dropped before completion.
//!
//! HTTP services typically learn nothing when a client disconnects
//! mid-request. This middleware installs drop guards so that premature
//! termination is observable: logs, metrics, cleanup.
//!
//! Two events are distinguished:
//!
//! * **Future drop**: the response future was dropped before the inner
//!   service produced any response.
//! * **Body drop**: the response body was dropped before reaching
//!   [`is_end_stream`](http_body::Body::is_end_stream).
//!
//! # Example: bridge to [`trace::OnFailure`](crate::trace::OnFailure)
//!
//! With the `trace` feature, [`EarlyDropsAsFailures`] wraps any
//! [`OnFailure<DroppedFailure>`](crate::trace::OnFailure) and routes both
//! events through it. Place this layer inside [`TraceLayer`](crate::trace::TraceLayer)
//! so that the emitted events inherit the request span.
//!
//! ```
//! # #[cfg(feature = "trace")] {
//! use tower_http::on_early_drop::{OnEarlyDropLayer, EarlyDropsAsFailures};
//! use tower_http::trace::DefaultOnFailure;
//!
//! let layer = OnEarlyDropLayer::new(
//!     EarlyDropsAsFailures::new(DefaultOnFailure::default()),
//! );
//! # }
//! ```
//!
//! Use [`OnEarlyDropLayer::builder`] to place [`EarlyDropsAsFailures`] in a
//! single slot (track only body or only future drops) or to install plain
//! closures.
//!
//! # Example: builder with direct callbacks
//!
//! Use [`OnEarlyDropLayer::builder`] to install closures in either or both
//! slots. The future-drop closure is a factory: outer closure runs at
//! request time, inner closure fires on drop. The body-drop closure uses a
//! three-level chain via [`OnBodyDropFn`]: outer at request time, middle at
//! response-ready time, inner on drop.
//!
//! ```
//! use http::Request;
//! use tower_http::on_early_drop::{OnBodyDropFn, OnEarlyDropLayer};
//!
//! let layer = OnEarlyDropLayer::builder()
//!     .on_future_drop(|req: &Request<()>| {
//!         let uri = req.uri().clone();
//!         move || eprintln!("future dropped for {}", uri)
//!     })
//!     .on_body_drop(OnBodyDropFn::new(|req: &Request<()>| {
//!         let uri = req.uri().clone();
//!         move |parts: &http::response::Parts| {
//!             let status = parts.status;
//!             move || eprintln!("body dropped for {} status {}", uri, status)
//!         }
//!     }));
//! ```
//!
//! Chain just one of the two methods to hook only that event; the other
//! slot stays no-op.
//!
//! # Panics in callbacks
//!
//! Callbacks fire from [`Drop`]. Panicking during a drop that occurs while
//! another panic is unwinding aborts the process. Closures and custom
//! [`OnDropCallback`] implementations must not panic.
//!
//! # Standalone guard
//!
//! [`OnEarlyDropGuard`] is usable on its own to detect early drop of
//! arbitrary scopes.
//!
//! ```
//! use tower_http::on_early_drop::OnEarlyDropGuard;
//!
//! let mut guard = OnEarlyDropGuard::new(|| {
//!     eprintln!("scope exited early");
//! });
//! // ... work that might return early ...
//! guard.completed();
//! ```
```

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

### InFlightRequestsCounter struct and methods

Source: https://docs.rs/tower-http/latest/src/tower_http/metrics/in_flight_requests.rs.html?search=u32+-%3E+bool

Definition of `InFlightRequestsCounter` with `new()`, `get()`, and the start of the private `increment()` method that returns an `IncrementGuard`.

```rust
/// An atomic counter that keeps track of the number of in-flight requests.
///
/// This will normally combined with [`InFlightRequestsLayer`] or [`InFlightRequests`] which will
/// update the counter as requests arrive.
#[derive(Debug, Clone, Default)]
pub struct InFlightRequestsCounter {
    count: Arc<AtomicUsize>,
}

impl InFlightRequestsCounter {
    /// Create a new `InFlightRequestsCounter`.
    pub fn new() -> Self {
        Self::default()
    }

    /// Get the current number of in-flight requests.
    pub fn get(&self) -> usize {
        self.count.load(Ordering::Relaxed)
    }

    fn increment(&self) -> IncrementGuard {
```

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

### ServeFile service implementation with precompressed variants

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

Complete implementation of the `ServeFile` service, a thin wrapper around `ServeDir` that serves a single file. It provides constructors `new` (guessing MIME from the file extension) and `new_with_mime` (panics if the MIME is not a valid header value), plus builder methods for precompressed variants (`precompressed_gzip`, `precompressed_br`, `precompressed_deflate`, `precompressed_zstd`), `with_buf_chunk_size` (default 64kb), and `ignore_multi_range_requests`. The precompressed methods serve `foo.txt.gz`, `foo.txt.br`, `foo.txt.zz`, or `foo.txt.zst` when the client's `Accept-Encoding` allows it and the file exists; otherwise the uncompressed version is served.

```rust
1//! Service that serves a file.
2
3use super::ServeDir;
4use http::{HeaderValue, Request};
5use mime::Mime;
6use std::{
7    path::Path,
8    task::{Context, Poll},
9};
10use tower_service::Service;
11
12/// Service that serves a file.
13#[derive(Clone, Debug)]
pub struct ServeFile(ServeDir);
14
15// Note that this is just a special case of ServeDir
16impl ServeFile {
17    /// Create a new [`ServeFile`].
18    ///
19    /// The `Content-Type` will be guessed from the file extension.
20    pub fn new<P: AsRef<Path>>(path: P) -> Self {
21        let guess = mime_guess::from_path(path.as_ref());
22        let mime = guess
23            .first_raw()
24            .map(HeaderValue::from_static)
25            .unwrap_or_else(|| {
26                HeaderValue::from_str(mime::APPLICATION_OCTET_STREAM.as_ref()).unwrap()
27            });
28
29        Self(ServeDir::new_single_file(path, mime))
30    }
31
32    /// Create a new [`ServeFile`] with a specific mime type.
33    ///
34    /// # Panics
35    ///
    /// Will panic if the mime type isn't a valid [header value].
    ///
    /// [header value]: https://docs.rs/http/latest/http/header/struct.HeaderValue.html
36    pub fn new_with_mime<P: AsRef<Path>>(path: P, mime: &Mime) -> Self {
37        let mime = HeaderValue::from_str(mime.as_ref()).expect("mime isn't a valid header value");
38        Self(ServeDir::new_single_file(path, mime))
39    }
40
41    /// Informs the service that it should also look for a precompressed gzip
42    /// version of the file.
43    ///
    /// If the client has an `Accept-Encoding` header that allows the gzip encoding,
    /// the file `foo.txt.gz` will be served instead of `foo.txt`.
    /// If the precompressed file is not available, or the client doesn't support it,
    /// the uncompressed version will be served instead.
    /// Both the precompressed version and the uncompressed version are expected
    /// to be present in the same directory. Different precompressed
    /// variants can be combined.
44    pub fn precompressed_gzip(self) -> Self {
45        Self(self.0.precompressed_gzip())
46    }
47
    /// Informs the service that it should also look for a precompressed brotli
    /// version of the file.
    ///
    /// If the client has an `Accept-Encoding` header that allows the brotli encoding,
    /// the file `foo.txt.br` will be served instead of `foo.txt`.
    /// If the precompressed file is not available, or the client doesn't support it,
    /// the uncompressed version will be served instead.
    /// Both the precompressed version and the uncompressed version are expected
    /// to be present in the same directory. Different precompressed
    /// variants can be combined.
48    pub fn precompressed_br(self) -> Self {
49        Self(self.0.precompressed_br())
50    }
51
    /// Informs the service that it should also look for a precompressed deflate
    /// version of the file.
    ///
    /// If the client has an `Accept-Encoding` header that allows the deflate encoding,
    /// the file `foo.txt.zz` will be served instead of `foo.txt`.
    /// If the precompressed file is not available, or the client doesn't support it,
    /// the uncompressed version will be served instead.
    /// Both the precompressed version and the uncompressed version are expected
    /// to be present in the same directory. Different precompressed
    /// variants can be combined.
52    pub fn precompressed_deflate(self) -> Self {
53        Self(self.0.precompressed_deflate())
54    }
55
    /// Informs the service that it should also look for a precompressed zstd
    /// version of the file.
    ///
    /// If the client has an `Accept-Encoding` header that allows the zstd encoding,
    /// the file `foo.txt.zst` will be served instead of `foo.txt`.
    /// If the precompressed file is not available, or the client doesn't support it,
    /// the uncompressed version will be served instead.
    /// Both the precompressed version and the uncompressed version are expected
    /// to be present in the same directory. Different precompressed
    /// variants can be combined.
56    pub fn precompressed_zstd(self) -> Self {
57        Self(self.0.precompressed_zstd())
58    }
59
    /// Set a specific read buffer chunk size.
    ///
    /// The default capacity is 64kb.
60    pub fn with_buf_chunk_size(self, chunk_size: usize) -> Self {
61        Self(self.0.with_buf_chunk_size(chunk_size))
62    }
63
    /// Configure whether syntactically valid multi-range requests should be ignored.
    ///
    /// See [`ServeDir::ignore_multi_range_requests`] for details.
64    pub fn ignore_multi_range_requests(self, ignore: bool) -> Self {
65        Self(self.0.ignore_multi_range_requests(ignore))
66    }
}
```

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

### Set Access-Control-Allow-Methods header with allow_methods

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

Configures the Access-Control-Allow-Methods header. The first example allows specific HTTP methods (GET, POST). The second example allows all methods using Any. Note that multiple calls override previous calls.

```rust
use tower_http::cors::CorsLayer;
use http::Method;

let layer = CorsLayer::new().allow_methods([Method::GET, Method::POST]);
```

```rust
use tower_http::cors::{Any, CorsLayer};

let layer = CorsLayer::new().allow_methods(Any);
```

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

### Test ServeFile basic serving

Source: https://docs.rs/tower-http/latest/src/tower_http/services/fs/serve_file.rs.html?search=std%3A%3Avec

Tests that `ServeFile::new` serves a file with the correct MIME type and content. Uses `README_PATH` as the fixture.

```rust
    #[tokio::test]
    async fn basic() {
        let svc = ServeFile::new(README_PATH);

        let res = svc.oneshot(Request::new(Body::empty())).await.unwrap();

        assert_eq!(res.headers()["content-type"], "text/markdown");

        let body = res.into_body().collect().await.unwrap().to_bytes();
        let body = String::from_utf8(body.to_vec()).unwrap();

        assert!(body.starts_with("# Tower HTTP"));
    }
```

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

### Example: Requiring Bearer Token with ValidateRequestHeaderLayer

Source: https://docs.rs/tower-http/latest/src/tower_http/auth/require_authorization.rs.html

Shows how to build a service that requires the `Authorization` header to be `Bearer passwordlol`. Requests with the correct token get a `200 OK` response; requests without a token get a `401 Unauthorized` response.

```rust
use tower_http::validate_request::{ValidateRequest, ValidateRequestHeader, ValidateRequestHeaderLayer};
use http::{Request, Response, StatusCode, header::AUTHORIZATION};
use tower::{Service, ServiceExt, ServiceBuilder, service_fn, BoxError};
use bytes::Bytes;
use http_body_util::Full;

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

#[tokio::main]
async fn main() -> Result<(), BoxError> {
    let mut service = ServiceBuilder::new()
        // Require the `Authorization` header to be `Bearer passwordlol`
        .layer(ValidateRequestHeaderLayer::bearer("passwordlol"))
        .service_fn(handle);

    // Requests with the correct token are allowed through
    let request = Request::builder()
        .header(AUTHORIZATION, "Bearer passwordlol")
        .body(Full::default())
        .unwrap();

    let response = service
        .ready()
        .await?
        .call(request)
        .await?;

    assert_eq!(StatusCode::OK, response.status());

    // Requests with an invalid token get a `401 Unauthorized` response
    let request = Request::builder()
        .body(Full::default())
        .unwrap();

    let response = service
        .ready()
        .await?
        .call(request)
        .await?;

    assert_eq!(StatusCode::UNAUTHORIZED, response.status());
    Ok(())
}
```

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

### Using RequestBodyLimitLayer to enforce body size limit

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

Shows how to wrap a service with RequestBodyLimitLayer to limit request body size. The example checks the response status for PAYLOAD_TOO_LARGE. The code is part of a larger example that includes setup and error handling.

```rust
let response = svc.ready().await?.call(request).await?;

assert_eq!(response.status(), StatusCode::PAYLOAD_TOO_LARGE);
```

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

### Set Access-Control-Allow-Methods with a list of methods

Source: https://docs.rs/tower-http/latest/src/tower_http/cors/mod.rs.html

Sets the Access-Control-Allow-Methods header to a specific list of HTTP methods. The example uses GET and POST.

```rust
use tower_http::cors::CorsLayer;
use http::Method;

let layer = CorsLayer::new().allow_methods([Method::GET, Method::POST]);
```

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

### Redirect HTTP to HTTPS using Redirect::permanent

Source: https://docs.rs/tower-http/latest/src/tower_http/services/redirect.rs.html

Shows how to create a `Redirect` service that permanently redirects all requests to a given URI. The example builds a request to `http://example.com` and asserts the response status is `308 Permanent Redirect` and the `location` header is `https://example.com/`. Requires the `tokio` runtime and the `tower`, `http`, `http-body-util`, and `bytes` crates.

```rust
use http::{Request, Uri, StatusCode};
use http_body_util::Full;
use bytes::Bytes;
use tower::{Service, ServiceExt};
use tower_http::services::Redirect;

# #[tokio::main]
# async fn main() -> Result<(), Box<dyn std::error::Error>> {
let uri: Uri = "https://example.com/".parse().unwrap();
let mut service: Redirect<Full<Bytes>> = Redirect::permanent(uri);

let request = Request::builder()
    .uri("http://example.com")
    .body(Full::<Bytes>::default())
    .unwrap();

let response = service.oneshot(request).await?;

assert_eq!(response.status(), StatusCode::PERMANENT_REDIRECT);
assert_eq!(response.headers()["location"], "https://example.com/");
#
# Ok(())
# }

```

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

### Test: returns_404_if_file_doesnt_exist_when_precompression_is_used

Source: https://docs.rs/tower-http/latest/src/tower_http/services/fs/serve_file.rs.html

Verifies that ServeFile returns 404 when the file does not exist even when precompression is enabled.

```rust
#[tokio::test]
async fn returns_404_if_file_doesnt_exist_when_precompression_is_used() {
    let svc = ServeFile::new("../this-doesnt-exist.md").precompressed_deflate();

    let request = Request::builder()
        .header("Accept-Encoding", "deflate")
        .body(Body::empty())
        .unwrap();
    let res = svc.oneshot(request).await.unwrap();

    assert_eq!(res.status(), StatusCode::NOT_FOUND);
    assert!(res.headers().get(header::CONTENT_TYPE).is_none());
}
```

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

### Usage example: StatusInRangeAsFailures with TraceLayer

Source: https://docs.rs/tower-http/latest/src/tower_http/classify/status_in_range_is_error.rs.html

Shows how to create a `StatusInRangeAsFailures` classifier for status codes 400..=599 and use it with `TraceLayer` to classify client and server errors as failures. The example builds a hyper client and sends a GET request to https://example.com.

```rust
use tower_http::{trace::TraceLayer, classify::StatusInRangeAsFailures};
use tower::{ServiceBuilder, Service, ServiceExt};
use http::{Request, Method};
use http_body_util::Full;
use bytes::Bytes;
use hyper_util::{rt::TokioExecutor, client::legacy::Client};

# async fn foo() -> Result<(), tower::BoxError> {
let classifier = StatusInRangeAsFailures::new(400..=599);

let client = Client::builder(TokioExecutor::new()).build_http();
let mut client = ServiceBuilder::new()
    .layer(TraceLayer::new(classifier.into_make_classifier()))
    .service(client);

let request = Request::builder()
    .method(Method::GET)
    .uri("https://example.com")
    .body(Full::<Bytes>::default())
    .unwrap();

let response = client.ready().await?.call(request).await?;
# Ok(())
# }
```

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

### Example: Using ServiceBuilderExt methods (timeout, trace_for_http, propagate_header)

Source: https://docs.rs/tower-http/latest/tower_http/trait.ServiceBuilderExt.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Shows how to build a service with tower::ServiceBuilder and tower-http's ServiceBuilderExt methods. Requires the 'trace' and 'propagate-header' features for trace_for_http and propagate_header respectively. The example defines an async handler and chains .timeout(), .trace_for_http(), and .propagate_header() before calling .service_fn().

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

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

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

### CORS middleware example using CorsLayer

Source: https://docs.rs/tower-http/latest/src/tower_http/cors/mod.rs.html

Shows how to create a CorsLayer that allows GET and POST methods from any origin, and apply it to a service using ServiceBuilder. The example sends a request with an Origin header and asserts the response contains the Access-Control-Allow-Origin header set to '*'. Requires the tokio runtime and the http, http-body-util, bytes, and tower crates.

```rust
use http::{Request, Response, Method, header};
use http_body_util::Full;
use bytes::Bytes;
use tower::{ServiceBuilder, ServiceExt, Service};
use tower_http::cors::{Any, CorsLayer};
use std::convert::Infallible;

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

# #[tokio::main]
# async fn main() -> Result<(), Box<dyn std::error::Error>> {
let cors = CorsLayer::new()
    // allow `GET` and `POST` when accessing the resource
    .allow_methods([Method::GET, Method::POST])
    // allow requests from any origin
    .allow_origin(Any);

let mut service = ServiceBuilder::new()
    .layer(cors)
    .service_fn(handle);

let request = Request::builder()
    .header(header::ORIGIN, "https://example.com")
    .body(Full::default())
    .unwrap();

let response = service
    .ready()
    .await?
    .call(request)
    .await?;

assert_eq!(
    response.headers().get(header::ACCESS_CONTROL_ALLOW_ORIGIN).unwrap(),
    "*",
);
# Ok(())
# }

```

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

### Basic usage of FollowRedirectLayer

Source: https://docs.rs/tower-http/latest/src/tower_http/follow_redirect/mod.rs.html?search=

Shows how to wrap a service with FollowRedirectLayer to follow redirects. The example uses a mock HTTP client that returns a 301 redirect to https://www.rust-lang.org/. After calling the service, the final request URI is retrieved from the response extensions via RequestUri.

```rust
use http::{Request, Response};
use bytes::Bytes;
use http_body_util::Full;
use tower::{Service, ServiceBuilder, ServiceExt};
use tower_http::follow_redirect::{FollowRedirectLayer, RequestUri};

# #[tokio::main]
# async fn main() -> Result<(), std::convert::Infallible> {
# let http_client = tower::service_fn(|req: Request<_>| async move {
#     let dest = "https://www.rust-lang.org/";
#     let mut res = http::Response::builder();
#     if req.uri() != dest {
#         res = res
#             .status(http::StatusCode::MOVED_PERMANENTLY)
#             .header(http::header::LOCATION, dest);
#     }
#     Ok::<_, std::convert::Infallible>(res.body(Full::<Bytes>::default()).unwrap())
# });
let mut client = ServiceBuilder::new()
    .layer(FollowRedirectLayer::new())
    .service(http_client);

let request = Request::builder()
    .uri("https://rust-lang.org/")
    .body(Full::<Bytes>::default())
    .unwrap();

let response = client.ready().await?.call(request).await?;
// Get the final request URI.
assert_eq!(response.extensions().get::<RequestUri>().unwrap().0, "https://www.rust-lang.org/");
# Ok(())
# }

```

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

### Add tracing to a service with TraceLayer::new_for_http()

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

Basic setup for adding tracing to a service. Run with RUST_LOG=tower_http=trace cargo run to see debug logs for request start and response finish.

```rust
use http::{Request, Response};
use tower::{ServiceBuilder, ServiceExt, Service};
use tower_http::trace::TraceLayer;
use std::convert::Infallible;
use http_body_util::Full;
use bytes::Bytes;

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

# #[tokio::main]
# async fn main() -> Result<(), Box<dyn std::error::Error>> {
// Setup tracing
tracing_subscriber::fmt::init();

let mut service = ServiceBuilder::new()
    .layer(TraceLayer::new_for_http())
    .service_fn(handle);

let request = Request::new(Full::from("foo"));

let response = service
    .ready()
    .await?
    .call(request)
    .await?;
# Ok(())
# }

```

```text
Mar 05 20:50:28.523 DEBUG request{method=GET path="/foo"}: tower_http::trace::on_request: started processing request
Mar 05 20:50:28.524 DEBUG request{method=GET path="/foo"}: tower_http::trace::on_response: finished processing request latency=1 ms status=200

```

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

### Use ServiceBuilderExt convenience methods set_x_request_id and propagate_x_request_id

Source: https://docs.rs/tower-http/latest/src/tower_http/request_id.rs.html?search=

Shows the same request ID setup using the `ServiceBuilderExt` convenience methods `set_x_request_id` and `propagate_x_request_id` instead of the explicit layers. The example asserts the response header equals "0".

```rust
use tower_http::ServiceBuilderExt;
# use http::{Request, Response, header::HeaderName};
# use tower::{Service, ServiceExt, ServiceBuilder};
# use tower_http::request_id::{
#     SetRequestIdLayer, PropagateRequestIdLayer, MakeRequestId, RequestId,
# };
# use bytes::Bytes;
# use http_body_util::Full;
# use std::sync::{Arc, atomic::{AtomicUsize, Ordering}};
# #[tokio::main]
# async fn main() -> Result<(), Box<dyn std::error::Error>> {
# let handler = tower::service_fn(|request: Request<Full<Bytes>>| async move {
#     Ok::<_, std::convert::Infallible>(Response::new(request.into_body()))
# });
# #[derive(Clone, Default)]
# struct MyMakeRequestId {
#     counter: Arc<AtomicUsize>,
# }
# impl MakeRequestId for MyMakeRequestId {
#     fn make_request_id<B>(&mut self, request: &Request<B>) -> Option<RequestId> {
#         let request_id = self.counter
#             .fetch_add(1, Ordering::SeqCst)
#             .to_string()
#             .parse()
#             .unwrap();
#         Some(RequestId::new(request_id))
#     }
# }

let mut svc = ServiceBuilder::new()
    .set_x_request_id(MyMakeRequestId::default())
    .propagate_x_request_id()
    .service(handler);

let request = Request::new(Full::default());
let response = svc.ready().await?.call(request).await?;

assert_eq!(response.headers()["x-request-id"], "0");
#
# Ok(())
# }

```

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

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

Source: https://docs.rs/tower-http/latest/tower_http/auth/add_authorization/struct.AddAuthorization.html

Yields the service when it is ready to accept a request.

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

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

### Method
ready_oneshot

### Signature
fn ready_oneshot(self) -> ReadyOneshot<Self, Request>
where Self: Sized

### Parameters
- **self** (Self) - Required - The service to check readiness on.

### Returns
- **ReadyOneshot<Self, Request>** - A future that resolves to the service when it is ready.
```
Tokens:
Raw