Enum rocket::fs::TempFile

source ·
pub enum TempFile<'v> {
    // some variants omitted
}
Expand description

A data and form guard that streams data into a temporary file.

TempFile is a data and form field (both value and data fields) guard that streams incoming data into file in a temporary location. The file is deleted when the TempFile handle is dropped unless it is persisted with TempFile::persist_to() or copied with TempFile::copy_to().

§Hazards

Temporary files are cleaned by system file cleaners periodically. While an attempt is made not to delete temporary files in use, detection of when a temporary file is being used is unreliable. As a result, a time-of-check to time-of-use race condition from the creation of a TempFile to the persistence of the TempFile may occur. Specifically, the following sequence may occur:

  1. A TempFile is created at random path foo.
  2. The system cleaner removes the file at path foo.
  3. Another application creates a file at path foo.
  4. The TempFile, ostensibly at path foo, is persisted unexpectedly with contents different from those in step 1.

To safe-guard against this issue, you should ensure that your temporary file cleaner, if any, does not delete files too eagerly.

§Configuration

TempFile is configured via the following config parameters:

NameDefaultDescription
temp_direnv::temp_dir()Directory for temporary file storage.
limits.file1MiBDefault limit for all file extensions.
limits.file/$extN/ALimit for files with extension $ext.

When used as a form guard, the extension $ext is identified by the form field’s Content-Type (ContentType::extension()). When used as a data guard, the extension is identified by the Content-Type of the request, if any. If there is no Content-Type, the limit file is used.

§Cappable

A data stream can be partially read into a TempFile even if the incoming stream exceeds the data limit via the Capped<TempFile> data and form guard.

§Examples

Data Guard

use rocket::fs::TempFile;

#[post("/upload", data = "<file>")]
async fn upload(mut file: TempFile<'_>) -> std::io::Result<()> {
    file.persist_to("/tmp/complete/file.txt").await?;
    Ok(())
}

Form Field

use rocket::fs::TempFile;
use rocket::form::Form;

#[derive(FromForm)]
struct Upload<'f> {
    upload: TempFile<'f>
}

#[post("/form", data = "<form>")]
async fn upload(mut form: Form<Upload<'_>>) -> std::io::Result<()> {
    form.upload.persist_to("/tmp/complete/file.txt").await?;
    Ok(())
}

See also the Capped documentation for an example of Capped<TempFile> as a data guard.

Implementations§

source§

impl<'v> TempFile<'v>

source

pub async fn persist_to<P>(&mut self, path: P) -> Result<()>
where P: AsRef<Path>,

Persists the temporary file, moving it to path. If a file exists at the target path, self will atomically replace it. self.path() is updated to path.

This method does not create a copy of self, nor a new link to the contents of self: it renames the temporary file to path and marks it as non-temporary. As a result, this method cannot be used to create multiple copies of self. To create multiple links, use std::fs::hard_link() with path as the src after calling this method.

§Cross-Device Persistence

Attempting to persist a temporary file across logical devices (or mount points) will result in an error. This is a limitation of the underlying OS. Your options are thus:

  1. Store temporary file in the same logical device.

    Change the temp_dir configuration parameter to be in the same logical device as the permanent location. This is the preferred solution.

  2. Copy the temporary file using TempFile::copy_to() or TempFile::move_copy_to() instead.

    This is a full copy of the file, creating a duplicate version of the file at the destination. This should be avoided for performance reasons.

§Example
use rocket::fs::TempFile;

#[post("/", data = "<file>")]
async fn handle(mut file: TempFile<'_>) -> std::io::Result<()> {
    file.persist_to(&some_path).await?;
    assert_eq!(file.path(), Some(&*some_path));

    Ok(())
}
source

pub async fn copy_to<P>(&mut self, path: P) -> Result<()>
where P: AsRef<Path>,

Persists the temporary file at its temporary path and creates a full copy at path. The self.path() is not updated, unless no temporary file existed prior, and the temporary file is not removed. Thus, there will be two files with the same contents.

Unlike TempFile::persist_to(), this method does not incur cross-device limitations, at the performance cost of a full copy. Prefer to use persist_to() with a valid temp_dir configuration parameter if no more than one copy of a file is required.

§Example
use rocket::fs::TempFile;

#[post("/", data = "<file>")]
async fn handle(mut file: TempFile<'_>) -> std::io::Result<()> {
    file.copy_to(&some_path).await?;
    file.copy_to(&some_other_path).await?;
    assert_eq!(file.path(), Some(&*some_path));

    Ok(())
}
source

pub async fn move_copy_to<P>(&mut self, path: P) -> Result<()>
where P: AsRef<Path>,

Persists the temporary file at its temporary path, creates a full copy at path, and then deletes the temporary file. self.path() is updated to path.

Like TempFile::copy_to() and unlike TempFile::persist_to(), this method does not incur cross-device limitations, at the performance cost of a full copy and file deletion. Prefer to use persist_to() with a valid temp_dir configuration parameter if no more than one copy of a file is required.

§Example
use rocket::fs::TempFile;

#[post("/", data = "<file>")]
async fn handle(mut file: TempFile<'_>) -> std::io::Result<()> {
    file.move_copy_to(&some_path).await?;

    Ok(())
}
source

pub async fn open(&self) -> Result<impl AsyncBufRead + '_>

Open the file for reading, returning an async stream of the file.

This method should be used sparingly. TempFile is intended to be used when the incoming data is destined to be stored on disk. If the incoming data is intended to be streamed elsewhere, prefer to implement a custom form guard via FromFormField that directly streams the incoming data to the ultimate destination.

§Example
use rocket::fs::TempFile;
use rocket::tokio::io;

#[post("/", data = "<file>")]
async fn handle(file: TempFile<'_>) -> std::io::Result<()> {
    let mut stream = file.open().await?;
    io::copy(&mut stream, &mut io::stdout()).await?;
    Ok(())
}
source

pub fn len(&self) -> u64

Returns the size, in bytes, of the file.

This method does not perform any system calls.

use rocket::fs::TempFile;

#[post("/", data = "<file>")]
fn handler(file: TempFile<'_>) {
    let file_len = file.len();
}
source

pub fn path(&self) -> Option<&Path>

Returns the path to the file if it is known.

Once a file is persisted with TempFile::persist_to(), this method is guaranteed to return Some. Prior to this point, however, this method may return Some or None, depending on whether the file is on disk or partially buffered in memory.

use rocket::fs::TempFile;

#[post("/", data = "<file>")]
async fn handle(mut file: TempFile<'_>) -> std::io::Result<()> {
    file.persist_to(&some_path).await?;
    assert_eq!(file.path(), Some(&*some_path));

    Ok(())
}
source

pub fn name(&self) -> Option<&str>

Returns the sanitized file name as specified in the form field.

A multipart data form field can optionally specify the name of a file. A browser will typically send the actual name of a user’s selected file in this field, but clients are also able to specify any name, including invalid or dangerous file names. This method returns a sanitized version of that value, if it was specified, suitable and safe for use as a permanent file name.

Note that you will likely want to prepend or append random or user-specific components to the name to avoid collisions; UUIDs make for a good “random” data.

See FileName::as_str() for specifics on sanitization.

use rocket::fs::TempFile;

#[post("/", data = "<file>")]
async fn handle(mut file: TempFile<'_>) -> std::io::Result<()> {
    if let Some(name) = file.name() {
        // Because of Rocket's sanitization, this is safe.
        file.persist_to(&some_dir.join(name)).await?;
    }

    Ok(())
}
source

pub fn raw_name(&self) -> Option<&FileName>

Returns the raw name of the file as specified in the form field.

use rocket::fs::TempFile;

#[post("/", data = "<file>")]
async fn handle(mut file: TempFile<'_>) {
    let raw_name = file.raw_name();
}
source

pub fn content_type(&self) -> Option<&ContentType>

Returns the Content-Type of the file as specified in the form field.

A multipart data form field can optionally specify the content-type of a file. A browser will typically sniff the file’s extension to set the content-type. This method returns that value, if it was specified.

use rocket::fs::TempFile;

#[post("/", data = "<file>")]
fn handle(file: TempFile<'_>) {
    let content_type = file.content_type();
}

Trait Implementations§

source§

impl<'v> Debug for TempFile<'v>

source§

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

Formats the value using the given formatter. Read more
source§

impl<'r> FromData<'r> for TempFile<'_>

§

type Error = <Capped<TempFile<'_>> as FromData<'r>>::Error

The associated error to be returned when the guard fails.
source§

fn from_data<'life0, 'async_trait>( r: &'r Request<'life0>, d: Data<'r> ) -> Pin<Box<dyn Future<Output = Outcome<'r, Self>> + Send + 'async_trait>>
where Self: 'async_trait, 'r: 'async_trait, 'life0: 'async_trait,

Asynchronously validates, parses, and converts an instance of Self from the incoming request body data. Read more
source§

impl<'v> FromFormField<'v> for TempFile<'v>

source§

fn default() -> Option<Self>

Returns a default value, if any exists, to be used during lenient parsing when the form field is missing. Read more
source§

fn from_value(f: ValueField<'v>) -> Result<'v, Self>

Parse a value of T from a form value field. Read more
source§

fn from_data<'life0, 'async_trait>( field: DataField<'v, 'life0> ) -> Pin<Box<dyn Future<Output = Result<'v, Self>> + Send + 'async_trait>>
where Self: 'async_trait, 'v: 'async_trait, 'life0: 'async_trait,

Parse a value of T from a form data field. Read more
source§

impl Len<ByteUnit> for TempFile<'_>

source§

fn len(&self) -> ByteUnit

The length of the value.
source§

fn len_into_u64(len: ByteUnit) -> u64

Convert len into u64.
source§

fn zero_len() -> ByteUnit

The zero value for L.
source§

impl Len<u64> for TempFile<'_>

source§

fn len(&self) -> u64

The length of the value.
source§

fn len_into_u64(len: u64) -> u64

Convert len into u64.
source§

fn zero_len() -> u64

The zero value for L.

Auto Trait Implementations§

§

impl<'v> RefUnwindSafe for TempFile<'v>

§

impl<'v> Send for TempFile<'v>

§

impl<'v> Sync for TempFile<'v>

§

impl<'v> Unpin for TempFile<'v>

§

impl<'v> UnwindSafe for TempFile<'v>

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
§

impl<'a, T> AsTaggedExplicit<'a> for T
where T: 'a,

§

fn explicit(self, class: Class, tag: u32) -> TaggedParser<'a, Explicit, Self>

§

impl<'a, T> AsTaggedImplicit<'a> for T
where T: 'a,

§

fn implicit( self, class: Class, constructed: bool, tag: u32 ) -> TaggedParser<'a, Implicit, Self>

source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<'v, T> FromForm<'v> for T
where T: FromFormField<'v>,

§

type Context = FromFieldContext<'v, T>

The form guard’s parsing context.
source§

fn init(opts: Options) -> <T as FromForm<'v>>::Context

Initializes and returns the parsing context for Self.
source§

fn push_value(ctxt: &mut <T as FromForm<'v>>::Context, field: ValueField<'v>)

Processes the value field field.
source§

fn push_data<'life0, 'life1, 'async_trait>( ctxt: &'life0 mut FromFieldContext<'v, T>, field: DataField<'v, 'life1> ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
where 'v: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, T: 'async_trait,

Processes the data field field.
source§

fn finalize(ctxt: <T as FromForm<'v>>::Context) -> Result<T, Errors<'v>>

Finalizes parsing. Returns the parsed value when successful or collection of Errors otherwise.
source§

fn push_error(_ctxt: &mut Self::Context, _error: Error<'r>)

Processes the external form or field error _error. Read more
source§

fn default(opts: Options) -> Option<Self>

Returns a default value, if any, to use when a value is desired and parsing fails. Read more
§

impl<T> Instrument for T

§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided [Span], returning an Instrumented wrapper. Read more
§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

§

impl<T> IntoCollection<T> for T

§

fn into_collection<A>(self) -> SmallVec<A>
where A: Array<Item = T>,

Converts self into a collection.
§

fn mapped<U, F, A>(self, f: F) -> SmallVec<A>
where F: FnMut(T) -> U, A: Array<Item = U>,

source§

impl<T> Paint for T
where T: ?Sized,

source§

fn fg(&self, value: Color) -> Painted<&T>

Returns a styled value derived from self with the foreground set to value.

This method should be used rarely. Instead, prefer to use color-specific builder methods like red() and green(), which have the same functionality but are pithier.

§Example

Set foreground color to white using fg():

use yansi::{Paint, Color};

painted.fg(Color::White);

Set foreground color to white using white().

use yansi::Paint;

painted.white();
source§

fn primary(&self) -> Painted<&T>

Returns self with the fg() set to Color::Primary.

§Example
println!("{}", value.primary());
source§

fn fixed(&self, color: u8) -> Painted<&T>

Returns self with the fg() set to Color::Fixed.

§Example
println!("{}", value.fixed(color));
source§

fn rgb(&self, r: u8, g: u8, b: u8) -> Painted<&T>

Returns self with the fg() set to Color::Rgb.

§Example
println!("{}", value.rgb(r, g, b));
source§

fn black(&self) -> Painted<&T>

Returns self with the fg() set to Color::Black.

§Example
println!("{}", value.black());
source§

fn red(&self) -> Painted<&T>

Returns self with the fg() set to Color::Red.

§Example
println!("{}", value.red());
source§

fn green(&self) -> Painted<&T>

Returns self with the fg() set to Color::Green.

§Example
println!("{}", value.green());
source§

fn yellow(&self) -> Painted<&T>

Returns self with the fg() set to Color::Yellow.

§Example
println!("{}", value.yellow());
source§

fn blue(&self) -> Painted<&T>

Returns self with the fg() set to Color::Blue.

§Example
println!("{}", value.blue());
source§

fn magenta(&self) -> Painted<&T>

Returns self with the fg() set to Color::Magenta.

§Example
println!("{}", value.magenta());
source§

fn cyan(&self) -> Painted<&T>

Returns self with the fg() set to Color::Cyan.

§Example
println!("{}", value.cyan());
source§

fn white(&self) -> Painted<&T>

Returns self with the fg() set to Color::White.

§Example
println!("{}", value.white());
source§

fn bright_black(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightBlack.

§Example
println!("{}", value.bright_black());
source§

fn bright_red(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightRed.

§Example
println!("{}", value.bright_red());
source§

fn bright_green(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightGreen.

§Example
println!("{}", value.bright_green());
source§

fn bright_yellow(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightYellow.

§Example
println!("{}", value.bright_yellow());
source§

fn bright_blue(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightBlue.

§Example
println!("{}", value.bright_blue());
source§

fn bright_magenta(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightMagenta.

§Example
println!("{}", value.bright_magenta());
source§

fn bright_cyan(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightCyan.

§Example
println!("{}", value.bright_cyan());
source§

fn bright_white(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightWhite.

§Example
println!("{}", value.bright_white());
source§

fn bg(&self, value: Color) -> Painted<&T>

Returns a styled value derived from self with the background set to value.

This method should be used rarely. Instead, prefer to use color-specific builder methods like on_red() and on_green(), which have the same functionality but are pithier.

§Example

Set background color to red using fg():

use yansi::{Paint, Color};

painted.bg(Color::Red);

Set background color to red using on_red().

use yansi::Paint;

painted.on_red();
source§

fn on_primary(&self) -> Painted<&T>

Returns self with the bg() set to Color::Primary.

§Example
println!("{}", value.on_primary());
source§

fn on_fixed(&self, color: u8) -> Painted<&T>

Returns self with the bg() set to Color::Fixed.

§Example
println!("{}", value.on_fixed(color));
source§

fn on_rgb(&self, r: u8, g: u8, b: u8) -> Painted<&T>

Returns self with the bg() set to Color::Rgb.

§Example
println!("{}", value.on_rgb(r, g, b));
source§

fn on_black(&self) -> Painted<&T>

Returns self with the bg() set to Color::Black.

§Example
println!("{}", value.on_black());
source§

fn on_red(&self) -> Painted<&T>

Returns self with the bg() set to Color::Red.

§Example
println!("{}", value.on_red());
source§

fn on_green(&self) -> Painted<&T>

Returns self with the bg() set to Color::Green.

§Example
println!("{}", value.on_green());
source§

fn on_yellow(&self) -> Painted<&T>

Returns self with the bg() set to Color::Yellow.

§Example
println!("{}", value.on_yellow());
source§

fn on_blue(&self) -> Painted<&T>

Returns self with the bg() set to Color::Blue.

§Example
println!("{}", value.on_blue());
source§

fn on_magenta(&self) -> Painted<&T>

Returns self with the bg() set to Color::Magenta.

§Example
println!("{}", value.on_magenta());
source§

fn on_cyan(&self) -> Painted<&T>

Returns self with the bg() set to Color::Cyan.

§Example
println!("{}", value.on_cyan());
source§

fn on_white(&self) -> Painted<&T>

Returns self with the bg() set to Color::White.

§Example
println!("{}", value.on_white());
source§

fn on_bright_black(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightBlack.

§Example
println!("{}", value.on_bright_black());
source§

fn on_bright_red(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightRed.

§Example
println!("{}", value.on_bright_red());
source§

fn on_bright_green(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightGreen.

§Example
println!("{}", value.on_bright_green());
source§

fn on_bright_yellow(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightYellow.

§Example
println!("{}", value.on_bright_yellow());
source§

fn on_bright_blue(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightBlue.

§Example
println!("{}", value.on_bright_blue());
source§

fn on_bright_magenta(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightMagenta.

§Example
println!("{}", value.on_bright_magenta());
source§

fn on_bright_cyan(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightCyan.

§Example
println!("{}", value.on_bright_cyan());
source§

fn on_bright_white(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightWhite.

§Example
println!("{}", value.on_bright_white());
source§

fn attr(&self, value: Attribute) -> Painted<&T>

Enables the styling Attribute value.

This method should be used rarely. Instead, prefer to use attribute-specific builder methods like bold() and underline(), which have the same functionality but are pithier.

§Example

Make text bold using attr():

use yansi::{Paint, Attribute};

painted.attr(Attribute::Bold);

Make text bold using using bold().

use yansi::Paint;

painted.bold();
source§

fn bold(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Bold.

§Example
println!("{}", value.bold());
source§

fn dim(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Dim.

§Example
println!("{}", value.dim());
source§

fn italic(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Italic.

§Example
println!("{}", value.italic());
source§

fn underline(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Underline.

§Example
println!("{}", value.underline());

Returns self with the attr() set to Attribute::Blink.

§Example
println!("{}", value.blink());

Returns self with the attr() set to Attribute::RapidBlink.

§Example
println!("{}", value.rapid_blink());
source§

fn invert(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Invert.

§Example
println!("{}", value.invert());
source§

fn conceal(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Conceal.

§Example
println!("{}", value.conceal());
source§

fn strike(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Strike.

§Example
println!("{}", value.strike());
source§

fn quirk(&self, value: Quirk) -> Painted<&T>

Enables the yansi Quirk value.

This method should be used rarely. Instead, prefer to use quirk-specific builder methods like mask() and wrap(), which have the same functionality but are pithier.

§Example

Enable wrapping using .quirk():

use yansi::{Paint, Quirk};

painted.quirk(Quirk::Wrap);

Enable wrapping using wrap().

use yansi::Paint;

painted.wrap();
source§

fn mask(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Mask.

§Example
println!("{}", value.mask());
source§

fn wrap(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Wrap.

§Example
println!("{}", value.wrap());
source§

fn linger(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Linger.

§Example
println!("{}", value.linger());
source§

fn clear(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Clear.

§Example
println!("{}", value.clear());
source§

fn bright(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Bright.

§Example
println!("{}", value.bright());
source§

fn on_bright(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::OnBright.

§Example
println!("{}", value.on_bright());
source§

fn whenever(&self, value: Condition) -> Painted<&T>

Conditionally enable styling based on whether the Condition value applies. Replaces any previous condition.

See the crate level docs for more details.

§Example

Enable styling painted only when both stdout and stderr are TTYs:

use yansi::{Paint, Condition};

painted.red().on_yellow().whenever(Condition::STDOUTERR_ARE_TTY);
source§

fn new(self) -> Painted<Self>
where Self: Sized,

Create a new Painted with a default Style. Read more
source§

fn paint<S>(&self, style: S) -> Painted<&Self>
where S: Into<Style>,

Apply a style wholesale to self. Any previous style is replaced. Read more
source§

impl<T> Same for T

§

type Output = T

Should always be Self
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

§

fn vzip(self) -> V

§

impl<T> WithSubscriber for T

§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a [WithDispatch] wrapper. Read more
§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a [WithDispatch] wrapper. Read more