Struct ServeDir

pub struct ServeDir<F = DefaultServeDirFallback> { /* 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
• On unix, any segment of the path referenced as directory is actually an existing file (/file.html/something)
• We don’t have necessary permissions to read the file

Example

use rama_http_backend::server::HttpServer;
use rama_http::service::fs::{ServeDir, ServeFile};
use rama_core::{
    rt::Executor,
    Layer, layer::TraceErrLayer,
};
use rama_tcp::server::TcpListener;

#[tokio::main]
async fn main() {
    let exec = Executor::default();

    let listener = TcpListener::bind("127.0.0.1:8080")
        .await
        .expect("bind TCP Listener");

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

    // Serve the HTTP server over TCP
    listener
        .serve(TraceErrLayer::new().layer(http_fs_server))
        .await;
}

Implementations

impl ServeDir

pub fn new<P>(path: P) -> ServeDir

where P: AsRef<Path>,

Create a new ServeDir.

impl<F> ServeDir<F>

pub fn append_index_html_on_directories(self, append: bool) -> ServeDir<F>

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

This is useful for static sites.

Defaults to true.

pub fn set_append_index_html_on_directories( &mut self, append: bool, ) -> &mut ServeDir<F>

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) -> ServeDir<F>

Set a specific read buffer chunk size.

The default capacity is 64kb.

pub fn set_buf_chunk_size(&mut self, chunk_size: usize) -> &mut ServeDir<F>

Set a specific read buffer chunk size.

The default capacity is 64kb.

pub fn precompressed_gzip(self) -> ServeDir<F>

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 set_precompressed_gzip(&mut self) -> &mut ServeDir<F>

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) -> ServeDir<F>

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 set_precompressed_br(&mut self) -> &mut ServeDir<F>

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) -> ServeDir<F>

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.

pub fn set_precompressed_deflate(&mut self) -> &mut ServeDir<F>

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.

pub fn precompressed_zstd(self) -> ServeDir<F>

Informs the service that it should also look for a precompressed zstd 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 zstd encoding will receive the file dir/foo.txt.zst 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 set_precompressed_zstd(&mut self) -> &mut ServeDir<F>

Informs the service that it should also look for a precompressed zstd 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 zstd encoding will receive the file dir/foo.txt.zst 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 fallback<F2>(self, new_fallback: F2) -> ServeDir<F2>

Set the fallback service.

This service will be called if there is no file at the path of the request.

The status code returned by the fallback will not be altered. Use ServeDir::not_found_service to set a fallback and always respond with 404 Not Found.

Example

This can be used to respond with a different file:

use rama_core::{
    rt::Executor,
    Layer, layer::TraceErrLayer,
};
use rama_tcp::server::TcpListener;
use rama_http_backend::server::HttpServer;
use rama_http::service::fs::{ServeDir, ServeFile};

#[tokio::main]
async fn main() {
    let exec = Executor::default();

    let listener = TcpListener::bind("127.0.0.1:8080")
        .await
        .expect("bind TCP Listener");

    // This will serve files in the "assets" directory and
    // its subdirectories, and use assets/not_found.html as the fallback page
    let fs_server = ServeDir::new("assets").fallback(ServeFile::new("assets/not_found.html"));
    let http_fs_server = HttpServer::auto(exec).service(fs_server);

    // Serve the HTTP server over TCP
    listener
        .serve(TraceErrLayer::new().layer(http_fs_server))
        .await;
}

pub fn not_found_service<F2>(self, new_fallback: F2) -> ServeDir<SetStatus<F2>>

Set the fallback service and override the fallback’s status code to 404 Not Found.

This service will be called if there is no file at the path of the request.

Example

This can be used to respond with a different file:

use rama_core::{
    rt::Executor,
    layer::TraceErrLayer,
    Layer,
};
use rama_tcp::server::TcpListener;
use rama_http_backend::server::HttpServer;
use rama_http::service::fs::{ServeDir, ServeFile};

#[tokio::main]
async fn main() {
    let exec = Executor::default();

    let listener = TcpListener::bind("127.0.0.1:8080")
        .await
        .expect("bind TCP Listener");

    // This will serve files in the "assets" directory and
    // its subdirectories, and use assets/not_found.html as the not_found page
    let fs_server = ServeDir::new("assets").not_found_service(ServeFile::new("assets/not_found.html"));
    let http_fs_server = HttpServer::auto(exec).service(fs_server);

    // Serve the HTTP server over TCP
    listener
        .serve(TraceErrLayer::new().layer(http_fs_server))
        .await;
}

Setups like this are often found in single page applications.

pub fn call_fallback_on_method_not_allowed( self, call_fallback: bool, ) -> ServeDir<F>

Customize whether or not to call the fallback for requests that aren’t GET or HEAD.

Defaults to not calling the fallback and instead returning 405 Method Not Allowed.

pub fn set_call_fallback_on_method_not_allowed( &mut self, call_fallback: bool, ) -> &mut ServeDir<F>

Customize whether or not to call the fallback for requests that aren’t GET or HEAD.

Defaults to not calling the fallback and instead returning 405 Method Not Allowed.

pub async fn try_call<State, ReqBody, FResBody>( &self, ctx: Context<State>, req: Request<ReqBody>, ) -> Result<Response<Body>, Error>

where State: Clone + Send + Sync + 'static, F: Service<State, Request<ReqBody>, Response = Response<FResBody>, Error = Infallible> + Clone, FResBody: Body<Data = Bytes> + Send + Sync + 'static, <FResBody as Body>::Error: Into<Box<dyn Error + Sync + Send>>,

Call the service and get a future that contains any std::io::Error that might have happened.

By default <ServeDir as Service<_>>::call will handle IO errors and convert them into responses. It does that by converting std::io::ErrorKind::NotFound and std::io::ErrorKind::PermissionDenied to 404 Not Found and any other error to 500 Internal Server Error. The error will also be logged with tracing.

If you want to manually control how the error response is generated you can make a new service that wraps a ServeDir and calls try_call instead of call.

Example

use rama_core::{
    rt::Executor,
    service::service_fn,
    layer::TraceErrLayer,
    Context, Layer,
};
use rama_tcp::server::TcpListener;
use rama_http_backend::server::HttpServer;
use rama_http::service::fs::ServeDir;
use rama_http::{Body, Request, Response, StatusCode};
use std::convert::Infallible;

#[tokio::main]
async fn main() {
    let exec = Executor::default();

    let listener = TcpListener::bind("127.0.0.1:8080")
        .await
        .expect("bind TCP Listener");

    // This will serve files in the "assets" directory and
    // its subdirectories, and use assets/not_found.html as the fallback page
    let http_fs_server = HttpServer::auto(exec).service(service_fn(serve_dir));

    // Serve the HTTP server over TCP
    listener
        .serve(TraceErrLayer::new().layer(http_fs_server))
        .await;
}

async fn serve_dir<State>(
    ctx: Context<State>,
    request: Request,
) -> Result<Response<Body>, Infallible>
where
    State: Clone + Send + Sync + 'static,
{
    let service = ServeDir::new("assets");

    match service.try_call(ctx, request).await {
        Ok(response) => Ok(response),
        Err(_) => {
            let body = Body::from("Something went wrong...");
            let response = Response::builder()
                .status(StatusCode::INTERNAL_SERVER_ERROR)
                .body(body)
                .unwrap();
            Ok(response)
        }
    }
}

Trait Implementations

impl<F> Clone for ServeDir<F>

where F: Clone,

fn clone(&self) -> ServeDir<F>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<F> Debug for ServeDir<F>

where F: Debug,

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

Formats the value using the given formatter.

impl<State, ReqBody, F, FResBody> Service<State, Request<ReqBody>> for ServeDir<F>

where State: Clone + Send + Sync + 'static, ReqBody: Send + 'static, F: Service<State, Request<ReqBody>, Response = Response<FResBody>, Error = Infallible> + Clone, FResBody: Body<Data = Bytes> + Send + Sync + 'static, <FResBody as Body>::Error: Into<Box<dyn Error + Sync + Send>>,

type Response = Response<Body>

The type of response returned by the service.

type Error = Infallible

The type of error returned by the service.

async fn serve( &self, ctx: Context<State>, req: Request<ReqBody>, ) -> Result<<ServeDir<F> as Service<State, Request<ReqBody>>>::Response, <ServeDir<F> as Service<State, Request<ReqBody>>>::Error>

Serve a response or error for the given request, using the given context.

fn boxed(self) -> BoxService<S, Request, Self::Response, Self::Error>

Box this service to allow for dynamic dispatch.