Struct tower_http::services::ServeDir

pub struct ServeDir { /* private fields */ }

Service that serves files from a given directory and all its sub directories.

The Content-Type will be guessed from the file extension.

An empty response with status 404 Not Found will be returned if:

• The file doesn’t exist
• Any segment of the path contains ..
• Any segment of the path contains a backslash
• We don’t have necessary permissions to read the file

Example

use tower_http::services::ServeDir;

// This will serve files in the "assets" directory and
// its subdirectories
let service = ServeDir::new("assets");

// Run our service using `hyper`
let addr = std::net::SocketAddr::from(([127, 0, 0, 1], 3000));
hyper::Server::bind(&addr)
    .serve(tower::make::Shared::new(service))
    .await
    .expect("server error");

Handling files not found

By default ServeDir will return an empty 404 Not Found response if there is no file at the requested path. That can be customized by using and_then to change the response:

use tower_http::services::fs::{ServeDir, ServeFileSystemResponseBody};
use tower::ServiceBuilder;
use http::{StatusCode, Response};
use http_body::{Body as _, Full};
use std::io;

let service = ServiceBuilder::new()
    .and_then(|response: Response<ServeFileSystemResponseBody>| async move {
        let response = if response.status() == StatusCode::NOT_FOUND {
            let body = Full::from("Not Found")
                .map_err(|err| match err {})
                .boxed();
            Response::builder()
                .status(StatusCode::NOT_FOUND)
                .body(body)
                .unwrap()
        } else {
            response.map(|body| body.boxed())
        };

        Ok::<_, io::Error>(response)
    })
    .service(ServeDir::new("assets"));

Implementations

impl ServeDir

pub fn new<P: AsRef<Path>>(path: P) -> Self

This is supported on crate feature fs only.

Create a new ServeDir.

pub fn append_index_html_on_directories(self, append: bool) -> Self

This is supported on crate feature fs only.

If the requested path is a directory append index.html.

This is useful for static sites.

Defaults to true.

pub fn with_buf_chunk_size(self, chunk_size: usize) -> Self

This is supported on crate feature fs only.

Set a specific read buffer chunk size.

The default capacity is 64kb.

pub fn precompressed_gzip(self) -> Self

This is supported on crate feature fs only.

Informs the service that it should also look for a precompressed gzip version of any file in the directory.

Assuming the dir directory is being served and dir/foo.txt is requested, a client with an Accept-Encoding header that allows the gzip encoding will receive the file dir/foo.txt.gz instead of dir/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 directory. Different precompressed variants can be combined.

pub fn precompressed_br(self) -> Self

This is supported on crate feature fs only.

Informs the service that it should also look for a precompressed brotli version of any file in the directory.

Assuming the dir directory is being served and dir/foo.txt is requested, a client with an Accept-Encoding header that allows the brotli encoding will receive the file dir/foo.txt.br instead of dir/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 directory. Different precompressed variants can be combined.

pub fn precompressed_deflate(self) -> Self

This is supported on crate feature fs only.

Informs the service that it should also look for a precompressed deflate version of any file in the directory.

Assuming the dir directory is being served and dir/foo.txt is requested, a client with an Accept-Encoding header that allows the deflate encoding will receive the file dir/foo.txt.zz instead of dir/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 directory. Different precompressed variants can be combined.

Trait Implementations

impl Clone for ServeDir

This is supported on crate feature fs only.

fn clone(&self) -> ServeDir

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ServeDir

This is supported on crate feature fs only.

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<ReqBody> Service<Request<ReqBody>> for ServeDir

This is supported on crate feature fs only.

type Response = Response<ResponseBody>

Responses given by the service.

type Error = Error

Errors produced by the service.

type Future = ResponseFuture

The future response value.

fn poll_ready(&mut self, _cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>

Returns Poll::Ready(Ok(())) when the service is able to process requests.

fn call(&mut self, req: Request<ReqBody>) -> Self::Future

Process the request and return the response asynchronously.