Struct FileServer

pub struct FileServer { /* private fields */ }

Custom handler for serving static files.

This handler makes is simple to serve static files from a directory on the local file system. To use it, construct a FileServer using FileServer::new(), then mount the handler.

use rocket::fs::FileServer;

#[launch]
fn rocket() -> _ {
    rocket::build()
        .mount("/", FileServer::new("/www/static"))
}

When mounted, the handler serves files from the specified path. If a requested file does not exist, the handler forwards the request with a 404 status.

By default, the route has a rank of 10 which can be changed with FileServer::rank().

Customization

FileServer works through a pipeline of rewrites in which a requested path is transformed into a PathBuf via Segments::to_path_buf() and piped through a series of Rewriters to obtain a final Rewrite which is then used to generate a final response. See Rewriter for complete details on implementing your own Rewriters.

Example

Serve files from the /static directory on the local file system at the /public path:

use rocket::fs::FileServer;

#[launch]
fn rocket() -> _ {
    rocket::build().mount("/public", FileServer::new("/static"))
}

Requests for files at /public/<path..> will be handled by returning the contents of /static/<path..>. Requests for directories will return the contents of index.html.

Relative Paths

In the example above, /static is an absolute path. If your static files are stored relative to your crate and your project is managed by Cargo, use the relative! macro to obtain a path that is relative to your crate’s root. For example, to serve files in the static subdirectory of your crate at /, you might write:

use rocket::fs::{FileServer, relative};

#[launch]
fn rocket() -> _ {
    rocket::build().mount("/", FileServer::new(relative!("static")))
}

Implementations

impl FileServer

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

Constructs a new FileServer that serves files from the file system path with the following rewrites:

• |f, _| f.is_visible(): Serve only visible files (hide dotfiles).
• Prefix::checked(path): Prefix requests with path.
• TrailingDirs: Ensure directory have a trailing slash.
• DirIndex::unconditional("index.html"): Serve $dir/index.html for requests to directory $dir.

If you don’t want to serve index files or want a different index file, use Self::without_index. To customize the entire request to file path rewrite pipeline, use Self::identity.

Example

use rocket::fs::FileServer;

#[launch]
fn rocket() -> _ {
    rocket::build()
        .mount("/", FileServer::new("/www/static"))
}

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

Exactly like FileServer::new() except it does not serve directory index files via DirIndex. It rewrites with the following:

• |f, _| f.is_visible(): Serve only visible files (hide dotfiles).
• Prefix::checked(path): Prefix requests with path.
• TrailingDirs: Ensure directory have a trailing slash.

Example

Constructs a default file server to serve files from ./static using index.txt as the index file if index.html doesn’t exist.

use rocket::fs::{FileServer, rewrite::DirIndex};

#[launch]
fn rocket() -> _ {
    let server = FileServer::new("static")
        .rewrite(DirIndex::if_exists("index.html"))
        .rewrite(DirIndex::unconditional("index.txt"));

    rocket::build()
        .mount("/", server)
}

pub fn identity() -> Self

Constructs a new FileServer with no rewrites.

Without any rewrites, a FileServer will try to serve the requested file from the current working directory. In other words, it represents the identity rewrite. For example, a request GET /foo/bar will be passed through unmodified and thus ./foo/bar will be served. This is very unlikely to be what you want.

Prefer to use FileServer::new() or FileServer::without_index() whenever possible and otherwise use one or more of the rewrites in rocket::fs::rewrite or your own custom rewrites.

Example

use rocket::fs::{FileServer, rewrite};

#[launch]
fn rocket() -> _ {
    // A file server that serves exactly one file: /www/foo.html. The
    // file is served irrespective of what's requested.
    let server = FileServer::identity()
        .rewrite(rewrite::File::checked("/www/foo.html"));

    rocket::build()
        .mount("/", server)
}

pub fn rank(self, rank: isize) -> Self

Sets the rank of the route emitted by the FileServer to rank.

Example

FileServer::identity()
   .rank(5)

pub fn rewrite<R: Rewriter>(self, rewriter: R) -> Self

Add rewriter to the rewrite pipeline.

Example

Redirect filtered requests (None) to /.

use rocket::fs::{FileServer, rewrite::Rewrite};
use rocket::{request::Request, response::Redirect};

fn redir_missing<'r>(p: Option<Rewrite<'r>>, _req: &Request<'_>) -> Option<Rewrite<'r>> {
    Some(p.unwrap_or_else(|| Redirect::temporary(uri!("/")).into()))
}

#[launch]
fn rocket() -> _ {
    rocket::build()
        .mount("/", FileServer::new("static").rewrite(redir_missing))
}

Note that redir_missing is not a closure in this example. Making it a closure causes compilation to fail with a lifetime error. It really shouldn’t but it does.

pub fn filter<F>(self, f: F) -> Self

where F: Fn(&File<'_>, &Request<'_>) -> bool + Send + Sync + 'static,

Adds a rewriter to the pipeline that returns Some only when the function f returns true, filtering out all other files.

Example

Allow all files that don’t have a file name or have a file name other than “hidden”.

use rocket::fs::FileServer;

#[launch]
fn rocket() -> _ {
    let server = FileServer::new("static")
        .filter(|f, _| f.path.file_name() != Some("hidden".as_ref()));

    rocket::build()
        .mount("/", server)
}

pub fn map<F>(self, f: F) -> Self

where F: for<'r> Fn(File<'r>, &Request<'_>) -> Rewrite<'r> + Send + Sync + 'static,

Adds a rewriter to the pipeline that maps the current File to another Rewrite using f. If the current Rewrite is a Redirect, it is passed through without calling f.

Example

Append index.txt to every path.

use rocket::fs::FileServer;

#[launch]
fn rocket() -> _ {
    let server = FileServer::new("static")
        .map(|f, _| f.map_path(|p| p.join("index.txt")).into());

    rocket::build()
        .mount("/", server)
}

Trait Implementations

impl Clone for FileServer

fn clone(&self) -> FileServer

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for FileServer

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

Formats the value using the given formatter.

impl From<FileServer> for Vec<Route>

fn from(server: FileServer) -> Self

Converts to this type from the input type.

impl Handler for FileServer

fn handle<'r, 'life0, 'life1, 'async_trait>( &'life0 self, req: &'r Request<'life1>, data: Data<'r>, ) -> Pin<Box<dyn Future<Output = Outcome<'r>> + Send + 'async_trait>>

where Self: 'async_trait, 'r: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Called by Rocket when a Request with its associated Data should be handled by this handler.