Struct multipart::server::save::SaveBuilder

#[must_use = "nothing saved to the filesystem yet"]
pub struct SaveBuilder<S> { /* fields omitted */ }

A builder for saving a file or files to the local filesystem.

OpenOptions

This builder holds an instance of std::fs::OpenOptions which is used when creating the new file(s).

By default, the open options are set with .write(true).create_new(true), so if the file already exists then an error will be thrown. This is to avoid accidentally overwriting files from other requests.

If you want to modify the options used to open the save file, you can use mod_open_opts().

File Size and Count Limits

You can set a size limit for individual files with size_limit(), which takes either u64 or Option<u64>.

You can also set the maximum number of files to process with count_limit(), which takes either u32 or Option<u32>. This only has an effect when using SaveBuilder<[&mut] Multipart>.

Warning: Do not trust user input!

It is a serious security risk to create files or directories with paths based on user input. A malicious user could craft a path which can be used to overwrite important files, such as web templates, static assets, Javascript files, database files, configuration files, etc., if they are writable by the server process.

This can be mitigated somewhat by setting filesystem permissions as conservatively as possible and running the server under its own user with restricted permissions, but you should still not use user input directly as filesystem paths. If it is truly necessary, you should sanitize user input such that it cannot cause a path to be misinterpreted by the OS. Such functionality is outside the scope of this crate.

Methods

impl<S> SaveBuilder<S>

fn size_limit<L: Into<Option<u64>>>(self, limit: L) -> Self

Set the maximum number of bytes to write out per file.

Can be u64 or Option<u64>. If None, clears the limit.

fn mod_open_opts<F: FnOnce(&mut OpenOptions)>(self, opts_fn: F) -> Self

Modify the OpenOptions used to open any files for writing.

The write flag will be reset to true after the closure returns. (It'd be pretty pointless otherwise, right?)

impl<M> SaveBuilder<M> where M: ReadEntry

Save API for whole multipart requests.

fn count_limit<L: Into<Option<u32>>>(self, count_limit: L) -> Self

Set the maximum number of files to write out.

Can be u32 or Option<u32>. If None, clears the limit.

fn temp(self) -> EntriesSaveResult<M>

Save the file fields in the request to a new temporary directory prefixed with multipart-rs in the OS temporary directory.

For more options, create a TempDir yourself and pass it to with_temp_dir() instead.

Note: Temporary

See SaveDir for more info (the type of Entries::save_dir).

fn temp_with_prefix(self, prefix: &str) -> EntriesSaveResult<M>

Save the file fields in the request to a new temporary directory with the given string as a prefix in the OS temporary directory.

For more options, create a TempDir yourself and pass it to with_temp_dir() instead.

Note: Temporary

See SaveDir for more info (the type of Entries::save_dir).

fn with_temp_dir(self, tempdir: TempDir) -> EntriesSaveResult<M>

Save the file fields to the given TempDir.

The TempDir is returned in the result under Entries::save_dir.

fn with_dir<P: Into<PathBuf>>(self, dir: P) -> EntriesSaveResult<M>

Save the file fields in the request to a new permanent directory with the given path.

Any nonexistent directories in the path will be created.

fn with_entries(self, entries: Entries) -> EntriesSaveResult<M>

Commence the save operation using the existing Entries instance.

May be used to resume a saving operation after handling an error.

impl<'m, M: 'm> SaveBuilder<&'m mut MultipartFile<M>> where MultipartFile<M>: BufRead

Save API for individual files.

fn temp(&mut self) -> FileSaveResult

Save to a file with a random alphanumeric name in the OS temporary directory.

Does not use user input to create the path.

See with_path() for more details.

fn with_filename(&mut self, filename: &str) -> FileSaveResult

Save to a file with the given name in the OS temporary directory.

See with_path() for more details.

Warning: Do **not* trust user input!

It is a serious security risk to create files or directories with paths based on user input. A malicious user could craft a path which can be used to overwrite important files, such as web templates, static assets, Javascript files, database files, configuration files, etc., if they are writable by the server process.

This can be mitigated somewhat by setting filesystem permissions as conservatively as possible and running the server under its own user with restricted permissions, but you should still not use user input directly as filesystem paths. If it is truly necessary, you should sanitize filenames such that they cannot be misinterpreted by the OS.

fn with_dir<P: AsRef<Path>>(&mut self, dir: P) -> FileSaveResult

Save to a file with a random alphanumeric name in the given directory.

See with_path() for more details.

Warning: Do **not* trust user input!

It is a serious security risk to create files or directories with paths based on user input. A malicious user could craft a path which can be used to overwrite important files, such as web templates, static assets, Javascript files, database files, configuration files, etc., if they are writable by the server process.

This can be mitigated somewhat by setting filesystem permissions as conservatively as possible and running the server under its own user with restricted permissions, but you should still not use user input directly as filesystem paths. If it is truly necessary, you should sanitize filenames such that they cannot be misinterpreted by the OS.

fn with_path<P: Into<PathBuf>>(&mut self, path: P) -> FileSaveResult

Save to a file with the given path.

Creates any missing directories in the path. Uses the contained OpenOptions to create the file. Truncates the file to the given limit, if set.

fn write_to<W: Write>(&mut self, dest: W) -> SaveResult<u64, u64>

Write out the file field to dest, truncating if a limit was set.

Returns the number of bytes copied, and whether or not the limit was reached (tested by MultipartFile::fill_buf().is_empty() so no bytes are consumed).

Retries on interrupts.