Struct Files 

pub struct Files { /* private fields */ }

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

impl Files

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

where T: Into<PathBuf>,

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.

pub fn show_files_listing(self) -> Files

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.

pub fn redirect_to_slash_directory(self) -> Files

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

By default never redirect.

pub fn files_listing_renderer<F>(self, f: F) -> Files

where F: for<'r, 's> Fn(&'r Directory, &'s HttpRequest) -> Result<ServiceResponse, Error> + 'static,

Set custom directory renderer.

pub fn mime_override<F>(self, f: F) -> Files

where F: Fn(&Name<'_>) -> DispositionType + 'static,

Specifies MIME override callback.

pub fn path_filter<F>(self, f: F) -> Files

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

pub fn index_file<T>(self, index: T) -> Files

where T: Into<String>,

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.

pub fn read_mode_threshold(self, size: u64) -> Files

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.

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

Specifies whether to use ETag or not.

Default is true.

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

Specifies whether to use Last-Modified or not.

Default is true.

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

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

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

pub fn guard<G>(self, guard: G) -> Files

where G: Guard + 'static,

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

pub fn method_guard<G>(self, guard: G) -> Files

where G: Guard + 'static,

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.

pub fn disable_content_disposition(self) -> Files

Disable Content-Disposition header.

By default Content-Disposition` header is enabled.

pub fn default_handler<F, U>(self, f: F) -> Files

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

pub fn use_hidden_files(self) -> Files

Enables serving hidden files and directories, allowing a leading dots in url fragments.

Trait Implementations

impl Clone for Files

fn clone(&self) -> Files

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Files

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

Formats the value using the given formatter.

impl HttpServiceFactory for Files

fn register(self, config: &mut AppService)

impl ServiceFactory<ServiceRequest> for Files

type Response = ServiceResponse

Responses given by the created services.

type Error = Error

Errors produced by the created services.

type Config = ()

Service factory configuration.

type Service = FilesService

The kind of Service created by this factory.

type InitError = ()

Errors potentially raised while building a service.

type Future = Pin<Box<dyn Future<Output = Result<<Files as ServiceFactory<ServiceRequest>>::Service, <Files as ServiceFactory<ServiceRequest>>::InitError>>>>

The future of the Service instance.g

fn new_service( &self, _: (), ) -> <Files as ServiceFactory<ServiceRequest>>::Future

Create and return a new service asynchronously.