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