Struct 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 read_mode_threshold(self, size: u64) -> Self

Sets the size threshold that determines file read mode (sync/async).

When a file is smaller than the threshold (bytes), the reader will switch from synchronous (blocking) file-reads to async reads to avoid blocking the main-thread when processing large files.

Tweaking this value according to your expected usage may lead to signifiant performance gains (or losses in other handlers, if size is too high).

When the experimental-io-uring crate feature is enabled, file reads are always async.

Default is 0, meaning all files are read asynchronously.

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