Struct actix_files::Files

source ·

pub struct Files { /* private fields */ }

Expand description

Static files handling service.

Files service must be registered with App::service() method.

§Examples

use actix_web::App;
use actix_files::Files;

let app = App::new()
    .service(Files::new("/static", "."));

Implementations§

source §

impl Files

source

pub fn new<T: Into<PathBuf>>(mount_path: &str, serve_from: T) -> Files

Create new Files instance for a specified base directory.

§Argument Order

The first argument (mount_path) is the root URL at which the static files are served. For example, /assets will serve files at example.com/assets/....

The second argument (serve_from) is the location on disk at which files are loaded. This can be a relative path. For example, ./ would serve files from the current working directory.

§Implementation Notes

If the mount path is set as the root path /, services registered after this one will be inaccessible. Register more specific handlers and services first.

Files utilizes the existing Tokio thread-pool for blocking filesystem operations. The number of running threads is adjusted over time as needed, up to a maximum of 512 times the number of server workers, by default.

source

pub fn show_files_listing(self) -> Self

Show files listing for directories.

By default show files listing is disabled.

When used with Files::index_file(), files listing is shown as a fallback when the index file is not found.

source

pub fn redirect_to_slash_directory(self) -> Self

Redirects to a slash-ended path when browsing a directory.

By default never redirect.

source

pub fn files_listing_renderer<F>(self, f: F) -> Self
where for<'r, 's> F: Fn(&'r Directory, &'s HttpRequest) -> Result<ServiceResponse, Error> + 'static,

Set custom directory renderer.

source

pub fn mime_override<F>(self, f: F) -> Self
where F: Fn(&Name<'_>) -> DispositionType + 'static,

Specifies MIME override callback.

source

pub fn path_filter<F>(self, f: F) -> Self
where F: Fn(&Path, &RequestHead) -> bool + 'static,

Sets path filtering closure.

The path provided to the closure is relative to serve_from path. You can safely join this path with the serve_from path to get the real path. However, the real path may not exist since the filter is called before checking path existence.

When a path doesn’t pass the filter, Files::default_handler is called if set, otherwise, 404 Not Found is returned.

§Examples

use std::path::Path;
use actix_files::Files;

// prevent searching subdirectories and following symlinks
let files_service = Files::new("/", "./static").path_filter(|path, _| {
    path.components().count() == 1
        && Path::new("./static")
            .join(path)
            .symlink_metadata()
            .map(|m| !m.file_type().is_symlink())
            .unwrap_or(false)
});

source

pub fn index_file<T: Into<String>>(self, index: T) -> Self

Set index file

Shows specific index file for directories instead of showing files listing.

If the index file is not found, files listing is shown as a fallback if Files::show_files_listing() is set.

source

pub fn use_etag(self, value: bool) -> Self

Specifies whether to use ETag or not.

Default is true.

source

pub fn use_last_modified(self, value: bool) -> Self

Specifies whether to use Last-Modified or not.

Default is true.

source

pub fn prefer_utf8(self, value: bool) -> Self

Specifies whether text responses should signal a UTF-8 encoding.

Default is false (but will default to true in a future version).

source

pub fn guard<G: Guard + 'static>(self, guard: G) -> Self

Adds a routing guard.

Use this to allow multiple chained file services that respond to strictly different properties of a request. Due to the way routing works, if a guard check returns true and the request starts being handled by the file service, it will not be able to back-out and try the next service, you will simply get a 404 (or 405) error response.

To allow POST requests to retrieve files, see Files::method_guard().

§Examples

use actix_web::{guard::Header, App};
use actix_files::Files;

App::new().service(
    Files::new("/","/my/site/files")
        .guard(Header("Host", "example.com"))
);

source

pub fn method_guard<G: Guard + 'static>(self, guard: G) -> Self

Specifies guard to check before fetching directory listings or files.

Note that this guard has no effect on routing; it’s main use is to guard on the request’s method just before serving the file, only allowing GET and HEAD requests by default. See Files::guard for routing guards.

source

pub fn disable_content_disposition(self) -> Self

Disable Content-Disposition header.

By default Content-Disposition` header is enabled.

source

pub fn default_handler<F, U>(self, f: F) -> Self
where F: IntoServiceFactory<U, ServiceRequest>, U: ServiceFactory<ServiceRequest, Config = (), Response = ServiceResponse, Error = Error> + 'static,

Sets default handler which is used when no matched file could be found.

§Examples

Setting a fallback static file handler:

use actix_files::{Files, NamedFile};
use actix_web::dev::{ServiceRequest, ServiceResponse, fn_service};

let files = Files::new("/", "./static")
    .index_file("index.html")
    .default_handler(fn_service(|req: ServiceRequest| async {
        let (req, _) = req.into_parts();
        let file = NamedFile::open_async("./static/404.html").await?;
        let res = file.into_response(&req);
        Ok(ServiceResponse::new(req, res))
    }));