Skip to main content

rocket/fs/
temp_file.rs

1use std::{io, mem};
2use std::path::{PathBuf, Path};
3
4use crate::Request;
5use crate::http::{ContentType, Status};
6use crate::data::{self, FromData, Data, Capped, N, Limits};
7use crate::form::{FromFormField, ValueField, DataField, error::Errors};
8use crate::outcome::IntoOutcome;
9use crate::fs::FileName;
10
11use tokio::task;
12use tokio::fs::{self, File};
13use tokio::io::{AsyncBufRead, BufReader};
14use tempfile::{NamedTempFile, TempPath};
15use either::Either;
16
17/// A data and form guard that streams data into a temporary file.
18///
19/// `TempFile` is a data and form field (both value and data fields) guard that
20/// streams incoming data into file in a temporary location. The file is deleted
21/// when the `TempFile` handle is dropped unless it is persisted with
22/// [`TempFile::persist_to()`] or copied with [`TempFile::copy_to()`].
23///
24/// # Hazards
25///
26/// Temporary files are cleaned by system file cleaners periodically. While an
27/// attempt is made not to delete temporary files in use, _detection_ of when a
28/// temporary file is being used is unreliable. As a result, a time-of-check to
29/// time-of-use race condition from the creation of a `TempFile` to the
30/// persistence of the `TempFile` may occur. Specifically, the following
31/// sequence may occur:
32///
33/// 1. A `TempFile` is created at random path `foo`.
34/// 2. The system cleaner removes the file at path `foo`.
35/// 3. Another application creates a file at path `foo`.
36/// 4. The `TempFile`, ostensibly at path `foo`, is persisted unexpectedly
37///    with contents different from those in step 1.
38///
39/// To safe-guard against this issue, you should ensure that your temporary file
40/// cleaner, if any, does not delete files too eagerly.
41///
42/// # Configuration
43///
44/// `TempFile` is configured via the following [`config`](crate::config)
45/// parameters:
46///
47/// | Name               | Default             | Description                             |
48/// |--------------------|---------------------|-----------------------------------------|
49/// | `temp_dir`         | [`env::temp_dir()`] | Directory for temporary file storage.   |
50/// | `limits.file`      | 1MiB                | Default limit for all file extensions.  |
51/// | `limits.file/$ext` | _N/A_               | Limit for files with extension `$ext`.  |
52///
53/// [`env::temp_dir()`]: std::env::temp_dir()
54///
55/// When used as a form guard, the extension `$ext` is identified by the form
56/// field's `Content-Type` ([`ContentType::extension()`]). When used as a data
57/// guard, the extension is identified by the Content-Type of the request, if
58/// any. If there is no Content-Type, the limit `file` is used.
59///
60/// Multipart data fields without a Content-Type use [`ContentType::Binary`],
61/// so `file/bin` applies when configured, and `file` otherwise. A field's file
62/// name does not select its limit.
63///
64/// Value fields are buffered in memory. Data fields, including multipart fields
65/// with a file name, are stored in `temp_dir`, which must exist and be writable.
66///
67/// # Cappable
68///
69/// A data stream can be partially read into a `TempFile` even if the incoming
70/// stream exceeds the data limit via the [`Capped<TempFile>`] data and form
71/// guard.
72///
73/// # Examples
74///
75/// **Data Guard**
76///
77/// ```rust
78/// # use rocket::post;
79/// use rocket::fs::TempFile;
80///
81/// #[post("/upload", data = "<file>")]
82/// async fn upload(mut file: TempFile<'_>) -> std::io::Result<()> {
83///     file.persist_to("/tmp/complete/file.txt").await?;
84///     Ok(())
85/// }
86/// ```
87///
88/// **Form Field**
89///
90/// ```rust
91/// # #[macro_use] extern crate rocket;
92/// use rocket::fs::TempFile;
93/// use rocket::form::Form;
94///
95/// #[derive(FromForm)]
96/// struct Upload<'f> {
97///     upload: TempFile<'f>
98/// }
99///
100/// #[post("/form", data = "<form>")]
101/// async fn upload(mut form: Form<Upload<'_>>) -> std::io::Result<()> {
102///     form.upload.persist_to("/tmp/complete/file.txt").await?;
103///     Ok(())
104/// }
105/// ```
106///
107/// See also the [`Capped`] documentation for an example of `Capped<TempFile>`
108/// as a data guard.
109#[derive(Debug)]
110pub enum TempFile<'v> {
111    #[doc(hidden)]
112    File {
113        file_name: Option<&'v FileName>,
114        content_type: Option<ContentType>,
115        path: Either<TempPath, PathBuf>,
116        len: u64,
117    },
118    #[doc(hidden)]
119    Buffered {
120        content: &'v [u8],
121    }
122}
123
124impl<'v> TempFile<'v> {
125    /// Persists the temporary file, moving it to `path`. If a file exists at
126    /// the target path, `self` will atomically replace it. `self.path()` is
127    /// updated to `path`.
128    ///
129    /// This method _does not_ create a copy of `self`, nor a new link to the
130    /// contents of `self`: it renames the temporary file to `path` and marks it
131    /// as non-temporary. As a result, this method _cannot_ be used to create
132    /// multiple copies of `self`. To create multiple links, use
133    /// [`std::fs::hard_link()`] with `path` as the `src` _after_ calling this
134    /// method.
135    ///
136    /// # Cross-Device Persistence
137    ///
138    /// Attempting to persist a temporary file across logical devices (or mount
139    /// points) will result in an error. This is a limitation of the underlying
140    /// OS. Your options are thus:
141    ///
142    ///   1. Store temporary file in the same logical device.
143    ///
144    ///      Change the `temp_dir` configuration parameter to be in the same
145    ///      logical device as the permanent location. This is the preferred
146    ///      solution.
147    ///
148    ///   2. Copy the temporary file using [`TempFile::copy_to()`] or
149    ///      [`TempFile::move_copy_to()`] instead.
150    ///
151    ///      This is a _full copy_ of the file, creating a duplicate version of
152    ///      the file at the destination. This should be avoided for performance
153    ///      reasons.
154    ///
155    /// # Example
156    ///
157    /// ```rust
158    /// # #[macro_use] extern crate rocket;
159    /// use rocket::fs::TempFile;
160    ///
161    /// #[post("/", data = "<file>")]
162    /// async fn handle(mut file: TempFile<'_>) -> std::io::Result<()> {
163    ///     # assert!(file.path().is_none());
164    ///     # let some_path = std::env::temp_dir().join("some-persist.txt");
165    ///     file.persist_to(&some_path).await?;
166    ///     assert_eq!(file.path(), Some(&*some_path));
167    ///
168    ///     Ok(())
169    /// }
170    /// # let file = TempFile::Buffered { content: "hi".as_bytes() };
171    /// # rocket::async_test(handle(file)).unwrap();
172    /// ```
173    pub async fn persist_to<P>(&mut self, path: P) -> io::Result<()>
174        where P: AsRef<Path>
175    {
176        let new_path = path.as_ref().to_path_buf();
177        match self {
178            TempFile::File { path: either, .. } => {
179                let path = mem::replace(either, Either::Right(new_path.clone()));
180                match path {
181                    Either::Left(temp) => {
182                        let result = task::spawn_blocking(move || temp.persist(new_path)).await
183                            .map_err(|_| io::Error::new(io::ErrorKind::BrokenPipe, "spawn_block"))?;
184
185                        if let Err(e) = result {
186                            *either = Either::Left(e.path);
187                            return Err(e.error);
188                        }
189                    },
190                    Either::Right(prev) => {
191                        if let Err(e) = fs::rename(&prev, new_path).await {
192                            *either = Either::Right(prev);
193                            return Err(e);
194                        }
195                    }
196                }
197            }
198            TempFile::Buffered { content } => {
199                fs::write(&new_path, &content).await?;
200                *self = TempFile::File {
201                    file_name: None,
202                    content_type: None,
203                    path: Either::Right(new_path),
204                    len: content.len() as u64
205                };
206            }
207        }
208
209        Ok(())
210    }
211
212    /// Persists the temporary file at its temporary path and creates a full
213    /// copy at `path`. The `self.path()` is _not_ updated, unless no temporary
214    /// file existed prior, and the temporary file is _not_ removed. Thus, there
215    /// will be _two_ files with the same contents.
216    ///
217    /// Unlike [`TempFile::persist_to()`], this method does not incur
218    /// cross-device limitations, at the performance cost of a full copy. Prefer
219    /// to use `persist_to()` with a valid `temp_dir` configuration parameter if
220    /// no more than one copy of a file is required.
221    ///
222    /// # Example
223    ///
224    /// ```rust
225    /// # #[macro_use] extern crate rocket;
226    /// use rocket::fs::TempFile;
227    ///
228    /// #[post("/", data = "<file>")]
229    /// async fn handle(mut file: TempFile<'_>) -> std::io::Result<()> {
230    ///     # assert!(file.path().is_none());
231    ///     # let some_path = std::env::temp_dir().join("some-file.txt");
232    ///     file.copy_to(&some_path).await?;
233    ///     # assert_eq!(file.path(), Some(&*some_path));
234    ///     # let some_other_path = std::env::temp_dir().join("some-other.txt");
235    ///     file.copy_to(&some_other_path).await?;
236    ///     assert_eq!(file.path(), Some(&*some_path));
237    ///     # assert_eq!(std::fs::read(some_path).unwrap(), b"hi");
238    ///     # assert_eq!(std::fs::read(some_other_path).unwrap(), b"hi");
239    ///
240    ///     Ok(())
241    /// }
242    /// # let file = TempFile::Buffered { content: b"hi" };
243    /// # rocket::async_test(handle(file)).unwrap();
244    /// ```
245    pub async fn copy_to<P>(&mut self, path: P) -> io::Result<()>
246        where P: AsRef<Path>
247    {
248        match self {
249            TempFile::File { path: either, .. } => {
250                let old_path = mem::replace(either, Either::Right(either.to_path_buf()));
251                match old_path {
252                    Either::Left(temp) => {
253                        let result = task::spawn_blocking(move || temp.keep()).await
254                            .map_err(|_| io::Error::new(io::ErrorKind::BrokenPipe, "spawn_block"))?;
255
256                        if let Err(e) = result {
257                            *either = Either::Left(e.path);
258                            return Err(e.error);
259                        }
260                    },
261                    Either::Right(_) => { /* do nada */ }
262                };
263
264                tokio::fs::copy(&either, path).await?;
265            }
266            TempFile::Buffered { content } => {
267                let path = path.as_ref();
268                fs::write(&path, &content).await?;
269                *self = TempFile::File {
270                    file_name: None,
271                    content_type: None,
272                    path: Either::Right(path.to_path_buf()),
273                    len: content.len() as u64
274                };
275            }
276        }
277
278        Ok(())
279    }
280
281    /// Persists the temporary file at its temporary path, creates a full copy
282    /// at `path`, and then deletes the temporary file. `self.path()` is updated
283    /// to `path`.
284    ///
285    /// Like [`TempFile::copy_to()`] and unlike [`TempFile::persist_to()`], this
286    /// method does not incur cross-device limitations, at the performance cost
287    /// of a full copy and file deletion. Prefer to use `persist_to()` with a
288    /// valid `temp_dir` configuration parameter if no more than one copy of a
289    /// file is required.
290    ///
291    /// # Example
292    ///
293    /// ```rust
294    /// # #[macro_use] extern crate rocket;
295    /// use rocket::fs::TempFile;
296    ///
297    /// #[post("/", data = "<file>")]
298    /// async fn handle(mut file: TempFile<'_>) -> std::io::Result<()> {
299    ///     # assert!(file.path().is_none());
300    ///     # let some_path = std::env::temp_dir().join("some-copy.txt");
301    ///     file.move_copy_to(&some_path).await?;
302    ///     # assert_eq!(file.path(), Some(&*some_path));
303    ///
304    ///     Ok(())
305    /// }
306    /// # let file = TempFile::Buffered { content: "hi".as_bytes() };
307    /// # rocket::async_test(handle(file)).unwrap();
308    /// ```
309    pub async fn move_copy_to<P>(&mut self, path: P) -> io::Result<()>
310        where P: AsRef<Path>
311    {
312        let dest = path.as_ref();
313        self.copy_to(dest).await?;
314
315        if let TempFile::File { path, .. } = self {
316            fs::remove_file(&path).await?;
317            *path = Either::Right(dest.to_path_buf());
318        }
319
320        Ok(())
321    }
322
323    /// Open the file for reading, returning an `async` stream of the file.
324    ///
325    /// This method should be used sparingly. `TempFile` is intended to be used
326    /// when the incoming data is destined to be stored on disk. If the incoming
327    /// data is intended to be streamed elsewhere, prefer to implement a custom
328    /// form guard via [`FromFormField`] that directly streams the incoming data
329    /// to the ultimate destination.
330    ///
331    /// # Example
332    ///
333    /// ```rust
334    /// # #[macro_use] extern crate rocket;
335    /// use rocket::fs::TempFile;
336    /// use rocket::tokio::io;
337    ///
338    /// #[post("/", data = "<file>")]
339    /// async fn handle(file: TempFile<'_>) -> std::io::Result<()> {
340    ///     let mut stream = file.open().await?;
341    ///     io::copy(&mut stream, &mut io::stdout()).await?;
342    ///     Ok(())
343    /// }
344    /// # let file = TempFile::Buffered { content: "hi".as_bytes() };
345    /// # rocket::async_test(handle(file)).unwrap();
346    /// ```
347    pub async fn open(&self) -> io::Result<impl AsyncBufRead + '_> {
348        use tokio_util::either::Either;
349
350        match self {
351            TempFile::File { path, .. } => {
352                let path = match path {
353                    either::Either::Left(p) => p.as_ref(),
354                    either::Either::Right(p) => p.as_path(),
355                };
356
357                let reader = BufReader::new(File::open(path).await?);
358                Ok(Either::Left(reader))
359            },
360            TempFile::Buffered { content } => {
361                Ok(Either::Right(*content))
362            },
363        }
364    }
365
366    /// Returns whether the file is empty.
367    ///
368    /// This is equivalent to `file.len() == 0`.
369    ///
370    /// This method does not perform any system calls.
371    ///
372    /// ```rust
373    /// # #[macro_use] extern crate rocket;
374    /// use rocket::fs::TempFile;
375    ///
376    /// #[post("/", data = "<file>")]
377    /// fn handler(file: TempFile<'_>) {
378    ///     if file.is_empty() {
379    ///         assert_eq!(file.len(), 0);
380    ///     }
381    /// }
382    /// ```
383    pub fn is_empty(&self) -> bool {
384        self.len() == 0
385    }
386
387    /// Returns the size, in bytes, of the file.
388    ///
389    /// This method does not perform any system calls.
390    ///
391    /// ```rust
392    /// # #[macro_use] extern crate rocket;
393    /// use rocket::fs::TempFile;
394    ///
395    /// #[post("/", data = "<file>")]
396    /// fn handler(file: TempFile<'_>) {
397    ///     let file_len = file.len();
398    /// }
399    /// ```
400    pub fn len(&self) -> u64 {
401        match self {
402            TempFile::File { len, .. } => *len,
403            TempFile::Buffered { content } => content.len() as u64,
404        }
405    }
406
407    /// Returns the path to the file if it is known.
408    ///
409    /// Once a file is persisted with [`TempFile::persist_to()`], this method is
410    /// guaranteed to return `Some`. Prior to this point, however, this method
411    /// may return `Some` or `None`, depending on whether the file is on disk or
412    /// partially buffered in memory.
413    ///
414    /// ```rust
415    /// # #[macro_use] extern crate rocket;
416    /// use rocket::fs::TempFile;
417    ///
418    /// #[post("/", data = "<file>")]
419    /// async fn handle(mut file: TempFile<'_>) -> std::io::Result<()> {
420    ///     # assert!(file.path().is_none());
421    ///     # let some_path = std::env::temp_dir().join("some-path.txt");
422    ///     file.persist_to(&some_path).await?;
423    ///     assert_eq!(file.path(), Some(&*some_path));
424    ///     # assert_eq!(std::fs::read(some_path).unwrap(), b"hi");
425    ///
426    ///     Ok(())
427    /// }
428    /// # let file = TempFile::Buffered { content: b"hi" };
429    /// # rocket::async_test(handle(file)).unwrap();
430    /// ```
431    pub fn path(&self) -> Option<&Path> {
432        match self {
433            TempFile::File { path: Either::Left(p), .. } => Some(p.as_ref()),
434            TempFile::File { path: Either::Right(p), .. } => Some(p.as_path()),
435            TempFile::Buffered { .. } => None,
436        }
437    }
438
439    /// Returns the sanitized file name as specified in the form field.
440    ///
441    /// A multipart data form field can optionally specify the name of a file. A
442    /// browser will typically send the actual name of a user's selected file in
443    /// this field, but clients are also able to specify _any_ name, including
444    /// invalid or dangerous file names. This method returns a sanitized version
445    /// of that value, if it was specified, suitable and safe for use as a
446    /// permanent file name.
447    ///
448    /// Note that you will likely want to prepend or append random or
449    /// user-specific components to the name to avoid collisions; UUIDs make for
450    /// a good "random" data.
451    ///
452    /// See [`FileName::as_str()`] for specifics on sanitization.
453    ///
454    /// ```rust
455    /// # #[macro_use] extern crate rocket;
456    /// use rocket::fs::TempFile;
457    ///
458    /// #[post("/", data = "<file>")]
459    /// async fn handle(mut file: TempFile<'_>) -> std::io::Result<()> {
460    ///     # let some_dir = std::env::temp_dir();
461    ///     if let Some(name) = file.name() {
462    ///         // Because of Rocket's sanitization, this is safe.
463    ///         file.persist_to(&some_dir.join(name)).await?;
464    ///     }
465    ///
466    ///     Ok(())
467    /// }
468    /// ```
469    pub fn name(&self) -> Option<&str> {
470        self.raw_name().and_then(|f| f.as_str())
471    }
472
473    /// Returns the raw name of the file as specified in the form field.
474    ///
475    /// ```rust
476    /// # #[macro_use] extern crate rocket;
477    /// use rocket::fs::TempFile;
478    ///
479    /// #[post("/", data = "<file>")]
480    /// async fn handle(mut file: TempFile<'_>) {
481    ///     let raw_name = file.raw_name();
482    /// }
483    /// ```
484    pub fn raw_name(&self) -> Option<&FileName> {
485        match *self {
486            TempFile::File { file_name, .. } => file_name,
487            TempFile::Buffered { .. } => None
488        }
489    }
490
491    /// Returns the Content-Type of the file, if known.
492    ///
493    /// A multipart data form field can optionally specify the content-type of a
494    /// file. A browser will typically sniff the file's extension to set the
495    /// content-type. This method returns that value, if it was specified.
496    /// For multipart data fields without a Content-Type, this is
497    /// [`ContentType::Binary`]. For value fields, this is `None`.
498    ///
499    /// ```rust
500    /// # #[macro_use] extern crate rocket;
501    /// use rocket::fs::TempFile;
502    ///
503    /// #[post("/", data = "<file>")]
504    /// fn handle(file: TempFile<'_>) {
505    ///     let content_type = file.content_type();
506    /// }
507    /// ```
508    pub fn content_type(&self) -> Option<&ContentType> {
509        match self {
510            TempFile::File { content_type, .. } => content_type.as_ref(),
511            TempFile::Buffered { .. } => None
512        }
513    }
514
515    async fn from<'a>(
516        req: &Request<'_>,
517        data: Data<'_>,
518        file_name: Option<&'a FileName>,
519        content_type: Option<ContentType>,
520    ) -> io::Result<Capped<TempFile<'a>>> {
521        let limit = content_type.as_ref()
522            .and_then(|ct| ct.extension())
523            .and_then(|ext| req.limits().find(["file", ext.as_str()]))
524            .or_else(|| req.limits().get("file"))
525            .unwrap_or(Limits::FILE);
526
527        let temp_dir = req.rocket().config().temp_dir.relative();
528        let file = task::spawn_blocking(move || NamedTempFile::new_in(temp_dir));
529        let file = file.await;
530        let file = file.map_err(|_| io::Error::new(io::ErrorKind::Other, "spawn_block panic"))??;
531        let (file, temp_path) = file.into_parts();
532
533        let mut file = File::from_std(file);
534        let fut = data.open(limit).stream_to(tokio::io::BufWriter::new(&mut file));
535        let n = fut.await;
536        let n = n?;
537        let temp_file = TempFile::File {
538            content_type, file_name,
539            path: Either::Left(temp_path),
540            len: n.written,
541        };
542
543        Ok(Capped::new(temp_file, n))
544    }
545}
546
547#[crate::async_trait]
548impl<'v> FromFormField<'v> for Capped<TempFile<'v>> {
549    fn from_value(field: ValueField<'v>) -> Result<Self, Errors<'v>> {
550        let n = N { written: field.value.len() as u64, complete: true  };
551        Ok(Capped::new(TempFile::Buffered { content: field.value.as_bytes() }, n))
552    }
553
554    async fn from_data(
555        f: DataField<'v, '_>
556    ) -> Result<Self, Errors<'v>> {
557        Ok(TempFile::from(f.request, f.data, f.file_name, Some(f.content_type)).await?)
558    }
559}
560
561#[crate::async_trait]
562impl<'r> FromData<'r> for Capped<TempFile<'_>> {
563    type Error = io::Error;
564
565    async fn from_data(req: &'r Request<'_>, data: Data<'r>) -> data::Outcome<'r, Self> {
566        let has_form = |ty: &ContentType| ty.is_form_data() || ty.is_form();
567        if req.content_type().map_or(false, has_form) {
568            warn!(request.content_type = req.content_type().map(display),
569                "Request contains a form that is not being processed.\n\
570                Bare `TempFile` data guard writes raw, unprocessed streams to disk\n\
571                Perhaps you meant to use `Form<TempFile<'_>>` instead?");
572        }
573
574        TempFile::from(req, data, None, req.content_type().cloned())
575            .await
576            .or_error(Status::BadRequest)
577    }
578}
579
580impl_strict_from_form_field_from_capped!(TempFile<'v>);
581impl_strict_from_data_from_capped!(TempFile<'_>);