Struct StaticFiles

pub struct StaticFiles { /* private fields */ }

Available on crate feature file-stream only.

A resource that serves static files from a directory.

Supports range requests, multipart/byteranges, pre-encoded files, and also dynamically encoding files while streaming.

The directory to serve files from should contain two child directories, “encoded” and “unencoded”. StaticFiles serves unencoded files from the “unencoded” directory. But if the file size is within the allowed bounds, it dynamically encodes these files when the supported coding is requested, and there is no pre-encoded version in the “enoced” directory. “encoded” directory should contain pre-encoded files in the directories named after their coding.

use argan::StaticFiles;

// some_dir - encoded - gzip - docs - ...
//         |                 - ...
//         |
//          - unencoded - docs - ...
//                      - ...

let static_files = StaticFiles::new("/static", "some_dir");

In the above example, when the request is made to “/static/docs/README.md” without Accept-Encoding, StaticFiles tries to serve the file from the directory “some_dir/unencoded/docs/”. If the gzip is requested in theAccept-Encoding, StaticFiles first looks for a file “README.md.gz” in “some_dir/encoded/gzip/docs/”. If there is no such file, then it tries to serve the file as previously stated, but dynamically compresses it with gzip if the file size is within the allowed bounds. For deflate and br, it looks for a file with the extensions “.df” and “.br”, respectively, under their corresponding directories. If the identity is forbidden in the Accept-Encoding when some encoding is requested and there is neither a pre-encoded file nor an unencoded file with the suitable size to dynamically encode, then 406 Not Acceptable is returned.

Note that range requests are not supported for dynamically encoded files.

When the StaticFiles is converted into a Resource, it’s possible to add other subresources to it. When a request is made targeting a subresource, that subresource handles the request. The StaticFiles will try to handle the request only when there is no subresource that matches the request’s path.

use argan::{Resource, StaticFiles, handler::HandlerSetter, http::Method};

let mut static_files = StaticFiles::new("/some_pattern", "some_dir").into_resource();
static_files
    .subresource_mut("/resource_1_0")
    .set_handler_for(Method::GET.to(|| async { "resource_1_0" }));

static_files
    .subresource_mut("/resource_1_1/resource_2_0")
    .set_handler_for(Method::GET.to(|| async { "resource_2_0" }));

let service = static_files.into_arc_service();

Implementations

impl StaticFiles

pub fn new(uri_pattern: impl AsRef<str>, files_dir: impl AsRef<Path>) -> Self

Creates a new instance from the uri pattern and files’ directory.

pub fn as_attachments(self) -> Self

Configures the StaticFiles to serve files as attachments, setting Content-Disposition to attachment.

pub fn with_encoding_level(self, level: u32) -> Self

Dynamic compression level.

pub fn with_min_size_to_encode(self, min_size_to_encode: u64) -> Self

Minimum file size to dynamically encode. Default is 1 KiB.

pub fn with_max_size_to_encode(self, max_size_to_encode: u64) -> Self

Maximum file size to dynamically encode. Default is 8 KiB.

pub fn into_resource(self) -> Resource

Converts the StaticFiles into a resource.

use argan::resource::{Resource, StaticFiles};

let static_files = StaticFiles::new("/static", "some_directory").into_resource();

let mut pages = Resource::new("/pages");
pages.add_subresource(static_files);