camino_tempfile/builder.rs
1// Copyright (c) The camino-tempfile Contributors
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4use crate::{helpers::utf8_env_temp_dir, NamedUtf8TempFile, Utf8TempDir};
5use camino::{Utf8Path, Utf8PathBuf};
6use std::{convert::TryFrom, io};
7
8/// Create a new temporary file or directory with custom parameters.
9#[derive(Debug, Clone, Default, Eq, PartialEq)]
10pub struct Builder<'a, 'b> {
11 inner: tempfile::Builder<'a, 'b>,
12}
13
14impl<'a, 'b> Builder<'a, 'b> {
15 /// Create a new `Builder`.
16 ///
17 /// # Examples
18 ///
19 /// Create a named temporary file and write some data into it:
20 ///
21 /// ```
22 /// # use std::io;
23 /// # use std::ffi::OsStr;
24 /// # fn main() {
25 /// # if let Err(_) = run() {
26 /// # ::std::process::exit(1);
27 /// # }
28 /// # }
29 /// # fn run() -> Result<(), io::Error> {
30 /// use camino_tempfile::Builder;
31 ///
32 /// let named_tempfile = Builder::new()
33 /// .prefix("my-temporary-note")
34 /// .suffix(".txt")
35 /// .rand_bytes(5)
36 /// .tempfile()?;
37 ///
38 /// let name = named_tempfile.path().file_name();
39 ///
40 /// if let Some(name) = name {
41 /// assert!(name.starts_with("my-temporary-note"));
42 /// assert!(name.ends_with(".txt"));
43 /// assert_eq!(name.len(), "my-temporary-note.txt".len() + 5);
44 /// }
45 /// # Ok(())
46 /// # }
47 /// ```
48 ///
49 /// Create a temporary directory and add a file to it:
50 ///
51 /// ```
52 /// # use std::io::{self, Write};
53 /// # use std::fs::File;
54 /// # use std::ffi::OsStr;
55 /// # fn main() {
56 /// # if let Err(_) = run() {
57 /// # ::std::process::exit(1);
58 /// # }
59 /// # }
60 /// # fn run() -> Result<(), io::Error> {
61 /// use camino_tempfile::Builder;
62 ///
63 /// let dir = Builder::new()
64 /// .prefix("my-temporary-dir")
65 /// .rand_bytes(5)
66 /// .tempdir()?;
67 ///
68 /// let file_path = dir.path().join("my-temporary-note.txt");
69 /// let mut file = File::create(file_path)?;
70 /// writeln!(file, "Brian was here. Briefly.")?;
71 ///
72 /// // By closing the `Utf8TempDir` explicitly, we can check that it has
73 /// // been deleted successfully. If we don't close it explicitly,
74 /// // the directory will still be deleted when `dir` goes out
75 /// // of scope, but we won't know whether deleting the directory
76 /// // succeeded.
77 /// drop(file);
78 /// dir.close()?;
79 /// # Ok(())
80 /// # }
81 /// ```
82 ///
83 /// Create a temporary directory with a chosen prefix under a chosen folder:
84 ///
85 /// ```ignore
86 /// let dir = Builder::new()
87 /// .prefix("my-temporary-dir")
88 /// .tempdir_in("folder-with-tempdirs")?;
89 /// ```
90 #[must_use]
91 pub fn new() -> Self {
92 Self::default()
93 }
94
95 /// Set a custom filename prefix.
96 ///
97 /// Path separators are legal but not advisable.
98 /// Default: `.tmp`.
99 ///
100 /// # Examples
101 ///
102 /// ```
103 /// # use std::io;
104 /// # fn main() {
105 /// # if let Err(_) = run() {
106 /// # ::std::process::exit(1);
107 /// # }
108 /// # }
109 /// # fn run() -> Result<(), io::Error> {
110 /// # use camino_tempfile::Builder;
111 /// let named_tempfile = Builder::new()
112 /// .prefix("my-temporary-note")
113 /// .tempfile()?;
114 /// # Ok(())
115 /// # }
116 /// ```
117 pub fn prefix<S: AsRef<str> + ?Sized>(&mut self, prefix: &'a S) -> &mut Self {
118 self.inner.prefix(prefix.as_ref());
119 self
120 }
121
122 /// Set a custom filename suffix.
123 ///
124 /// Path separators are legal but not advisable.
125 /// Default: empty.
126 ///
127 /// # Examples
128 ///
129 /// ```
130 /// # use std::io;
131 /// # fn main() {
132 /// # if let Err(_) = run() {
133 /// # ::std::process::exit(1);
134 /// # }
135 /// # }
136 /// # fn run() -> Result<(), io::Error> {
137 /// # use camino_tempfile::Builder;
138 /// let named_tempfile = Builder::new()
139 /// .suffix(".txt")
140 /// .tempfile()?;
141 /// # Ok(())
142 /// # }
143 /// ```
144 pub fn suffix<S: AsRef<str> + ?Sized>(&mut self, suffix: &'b S) -> &mut Self {
145 self.inner.suffix(suffix.as_ref());
146 self
147 }
148
149 /// Set the number of random bytes.
150 ///
151 /// Default: `6`.
152 ///
153 /// # Examples
154 ///
155 /// ```
156 /// # use std::io;
157 /// # fn main() {
158 /// # if let Err(_) = run() {
159 /// # ::std::process::exit(1);
160 /// # }
161 /// # }
162 /// # fn run() -> Result<(), io::Error> {
163 /// # use camino_tempfile::Builder;
164 /// let named_tempfile = Builder::new()
165 /// .rand_bytes(5)
166 /// .tempfile()?;
167 /// # Ok(())
168 /// # }
169 /// ```
170 pub fn rand_bytes(&mut self, rand: usize) -> &mut Self {
171 self.inner.rand_bytes(rand);
172 self
173 }
174
175 /// Set the file to be opened in append mode.
176 ///
177 /// Default: `false`.
178 ///
179 /// # Examples
180 ///
181 /// ```
182 /// # use std::io;
183 /// # fn main() {
184 /// # if let Err(_) = run() {
185 /// # ::std::process::exit(1);
186 /// # }
187 /// # }
188 /// # fn run() -> Result<(), io::Error> {
189 /// # use camino_tempfile::Builder;
190 /// let named_tempfile = Builder::new()
191 /// .append(true)
192 /// .tempfile()?;
193 /// # Ok(())
194 /// # }
195 /// ```
196 pub fn append(&mut self, append: bool) -> &mut Self {
197 self.inner.append(append);
198 self
199 }
200
201 /// The permissions to create the tempfile or [tempdir](Self::tempdir) with.
202 ///
203 /// # Security
204 ///
205 /// By default, the permissions of tempfiles on Unix are set for it to be
206 /// readable and writable by the owner only, yielding the greatest amount of
207 /// security. As this method allows to widen the permissions, security would
208 /// be reduced in such cases.
209 ///
210 /// # Platform Notes
211 ///
212 /// ## Unix
213 ///
214 /// The actual permission bits set on the tempfile or tempdir will be
215 /// affected by the `umask` applied by the underlying syscall. The actual
216 /// permission bits are calculated via `permissions & !umask`.
217 ///
218 /// Permissions default to `0o600` for tempfiles and `0o777` for tempdirs.
219 /// Note, this doesn't include effects of the current `umask`. For example,
220 /// combined with the standard umask `0o022`, the defaults yield `0o600` for
221 /// tempfiles and `0o755` for tempdirs.
222 ///
223 /// ## Windows and others
224 ///
225 /// This setting is unsupported and trying to set a file or directory
226 /// read-only will return an error.
227 ///
228 /// # Examples
229 ///
230 /// Create a named temporary file that is world-readable.
231 ///
232 /// ```
233 /// # #[cfg(unix)]
234 /// # {
235 /// use camino_tempfile::Builder;
236 /// use std::os::unix::fs::PermissionsExt;
237 ///
238 /// let all_read_write = std::fs::Permissions::from_mode(0o666);
239 /// let tempfile = Builder::new().permissions(all_read_write).tempfile()?;
240 /// let actual_permissions = tempfile.path().metadata()?.permissions();
241 /// assert_ne!(
242 /// actual_permissions.mode() & !0o170000,
243 /// 0o600,
244 /// "we get broader permissions than the default despite umask"
245 /// );
246 /// # }
247 /// # Ok::<(), std::io::Error>(())
248 /// ```
249 ///
250 /// Create a named temporary directory that is restricted to the owner.
251 ///
252 /// ```
253 /// # #[cfg(unix)]
254 /// # {
255 /// use camino_tempfile::Builder;
256 /// use std::os::unix::fs::PermissionsExt;
257 ///
258 /// let owner_rwx = std::fs::Permissions::from_mode(0o700);
259 /// let tempdir = Builder::new().permissions(owner_rwx).tempdir()?;
260 /// let actual_permissions = tempdir.path().metadata()?.permissions();
261 /// assert_eq!(
262 /// actual_permissions.mode() & !0o170000,
263 /// 0o700,
264 /// "we get the narrow permissions we asked for"
265 /// );
266 /// # }
267 /// # Ok::<(), std::io::Error>(())
268 /// ```
269 pub fn permissions(&mut self, permissions: std::fs::Permissions) -> &mut Self {
270 self.inner.permissions(permissions);
271 self
272 }
273
274 /// Disable cleanup of the file/folder to even when the
275 /// [`NamedUtf8TempFile`]/[`Utf8TempDir`] goes out of scope. Prefer
276 /// [`NamedUtf8TempFile::keep`] and [`Utf8TempDir::keep`] where possible,
277 /// `disable_cleanup` is provided for testing & debugging.
278 ///
279 /// By default, the file/folder is automatically cleaned up in the
280 /// destructor of [`NamedUtf8TempFile`]/[`Utf8TempDir`]. When
281 /// `disable_cleanup` is set to `true`, this behavior is suppressed. If you
282 /// wish to disable cleanup after creating a temporary file/directory, call
283 /// [`NamedUtf8TempFile::disable_cleanup`] or
284 /// [`Utf8TempDir::disable_cleanup`].
285 ///
286 /// # Warnings
287 ///
288 /// On some platforms (for now, only Windows), temporary files are marked
289 /// with a special "temporary file" (`FILE_ATTRIBUTE_TEMPORARY`) attribute.
290 /// Disabling cleanup _will not_ unset this attribute while calling
291 /// [`NamedUtf8TempFile::keep`] will.
292 ///
293 /// # Examples
294 ///
295 /// ```
296 /// use camino_tempfile::Builder;
297 ///
298 /// let named_tempfile = Builder::new()
299 /// .disable_cleanup(true)
300 /// .tempfile()?;
301 /// # Ok::<(), std::io::Error>(())
302 /// ```
303 pub fn disable_cleanup(&mut self, disable_cleanup: bool) -> &mut Self {
304 self.inner.disable_cleanup(disable_cleanup);
305 self
306 }
307
308 /// Create the named temporary file.
309 ///
310 /// # Security
311 ///
312 /// See [the security][security] docs on `NamedUtf8TempFile`.
313 ///
314 /// # Resource leaking
315 ///
316 /// See [the resource leaking][resource-leaking] docs on `NamedUtf8TempFile`.
317 ///
318 /// # Errors
319 ///
320 /// If the file cannot be created, `Err` is returned.
321 ///
322 /// # Examples
323 ///
324 /// ```
325 /// # use std::io;
326 /// # fn main() {
327 /// # if let Err(_) = run() {
328 /// # ::std::process::exit(1);
329 /// # }
330 /// # }
331 /// # fn run() -> Result<(), io::Error> {
332 /// # use camino_tempfile::Builder;
333 /// let tempfile = Builder::new().tempfile()?;
334 /// # Ok(())
335 /// # }
336 /// ```
337 ///
338 /// [security]: struct.NamedUtf8TempFile.html#security
339 /// [resource-leaking]: struct.NamedUtf8TempFile.html#resource-leaking
340 pub fn tempfile(&self) -> io::Result<NamedUtf8TempFile> {
341 self.tempfile_in(utf8_env_temp_dir()?)
342 }
343
344 /// Create the named temporary file in the specified directory.
345 ///
346 /// # Security
347 ///
348 /// See [the security][security] docs on `NamedUtf8TempFile`.
349 ///
350 /// # Resource leaking
351 ///
352 /// See [the resource leaking][resource-leaking] docs on `NamedUtf8TempFile`.
353 ///
354 /// # Errors
355 ///
356 /// If the file cannot be created, `Err` is returned.
357 ///
358 /// # Examples
359 ///
360 /// ```
361 /// # use std::io;
362 /// # fn main() {
363 /// # if let Err(_) = run() {
364 /// # ::std::process::exit(1);
365 /// # }
366 /// # }
367 /// # fn run() -> Result<(), io::Error> {
368 /// # use camino_tempfile::Builder;
369 /// let tempfile = Builder::new().tempfile_in("./")?;
370 /// # Ok(())
371 /// # }
372 /// ```
373 ///
374 /// [security]: struct.NamedUtf8TempFile.html#security
375 /// [resource-leaking]: struct.NamedUtf8TempFile.html#resource-leaking
376 pub fn tempfile_in<P: AsRef<Utf8Path>>(&self, dir: P) -> io::Result<NamedUtf8TempFile> {
377 let temp_file = self.inner.tempfile_in(dir.as_ref())?;
378 NamedUtf8TempFile::from_temp_file(temp_file)
379 }
380
381 /// Attempts to make a temporary directory inside of [`std::env::temp_dir()`] whose name will
382 /// have the prefix, `prefix`. The directory and everything inside it will be automatically
383 /// deleted once the returned `Utf8TempDir` is destroyed.
384 ///
385 /// # Resource leaking
386 ///
387 /// See [the resource leaking][resource-leaking] docs on `TempDir`.
388 ///
389 /// # Errors
390 ///
391 /// If the directory can not be created, or if [`std::env::temp_dir()`] is non-UTF-8, `Err` is
392 /// returned.
393 ///
394 /// # Examples
395 ///
396 /// ```
397 /// use std::fs::File;
398 /// use std::io::Write;
399 /// use camino_tempfile::Builder;
400 ///
401 /// # use std::io;
402 /// # fn run() -> Result<(), io::Error> {
403 /// let tmp_dir = Builder::new().tempdir()?;
404 /// # Ok(())
405 /// # }
406 /// ```
407 ///
408 /// [resource-leaking]: struct.Utf8TempDir.html#resource-leaking
409 pub fn tempdir(&self) -> io::Result<Utf8TempDir> {
410 self.tempdir_in(utf8_env_temp_dir()?)
411 }
412
413 /// Attempts to make a temporary directory inside of `dir`.
414 /// The directory and everything inside it will be automatically
415 /// deleted once the returned `Utf8TempDir` is destroyed.
416 ///
417 /// # Resource leaking
418 ///
419 /// See [the resource leaking][resource-leaking] docs on `Utf8TempDir`.
420 ///
421 /// # Errors
422 ///
423 /// If the directory can not be created, `Err` is returned.
424 ///
425 /// # Examples
426 ///
427 /// ```
428 /// use std::fs::{self, File};
429 /// use std::io::Write;
430 /// use camino_tempfile::Builder;
431 ///
432 /// # use std::io;
433 /// # fn run() -> Result<(), io::Error> {
434 /// let tmp_dir = Builder::new().tempdir_in("./")?;
435 /// # Ok(())
436 /// # }
437 /// ```
438 ///
439 /// [resource-leaking]: struct.Utf8TempDir.html#resource-leaking
440 pub fn tempdir_in<P: AsRef<Utf8Path>>(&self, dir: P) -> io::Result<Utf8TempDir> {
441 let temp_dir = self.inner.tempdir_in(dir.as_ref())?;
442 Utf8TempDir::from_temp_dir(temp_dir)
443 }
444
445 /// Attempts to create a temporary file (or file-like object) using the
446 /// provided closure. The closure is passed a temporary file path and
447 /// returns an [`std::io::Result`]. The path provided to the closure will be
448 /// inside of [`std::env::temp_dir()`]. Use [`Builder::make_in`] to provide
449 /// a custom temporary directory. If the closure returns one of the
450 /// following errors, then another randomized file path is tried:
451 /// - [`std::io::ErrorKind::AlreadyExists`]
452 /// - [`std::io::ErrorKind::AddrInUse`]
453 ///
454 /// This can be helpful for taking full control over the file creation, but
455 /// leaving the temporary file path construction up to the library. This
456 /// also enables creating a temporary UNIX domain socket, since it is not
457 /// possible to bind to a socket that already exists.
458 ///
459 /// Note that [`Builder::append`] is ignored when using [`Builder::make`].
460 ///
461 /// # Security
462 ///
463 /// This has the same [security implications][security] as
464 /// [`NamedUtf8TempFile`], but with additional caveats. Specifically, it is up
465 /// to the closure to ensure that the file does not exist and that such a
466 /// check is *atomic*. Otherwise, a [time-of-check to time-of-use
467 /// bug][TOCTOU] could be introduced.
468 ///
469 /// For example, the following is **not** secure:
470 ///
471 /// ```
472 /// # use std::io;
473 /// # use std::fs::File;
474 /// # fn main() {
475 /// # if let Err(_) = run() {
476 /// # ::std::process::exit(1);
477 /// # }
478 /// # }
479 /// # fn run() -> Result<(), io::Error> {
480 /// # use camino_tempfile::Builder;
481 /// // This is NOT secure!
482 /// let tempfile = Builder::new().make(|path| {
483 /// if path.is_file() {
484 /// return Err(io::ErrorKind::AlreadyExists.into());
485 /// }
486 ///
487 /// // Between the check above and the usage below, an attacker could
488 /// // have replaced `path` with another file, which would get truncated
489 /// // by `File::create`.
490 ///
491 /// File::create(path)
492 /// })?;
493 /// # Ok(())
494 /// # }
495 /// ```
496 /// Note that simply using [`std::fs::File::create`] alone is not correct
497 /// because it does not fail if the file already exists:
498 /// ```
499 /// # use std::io;
500 /// # use std::fs::File;
501 /// # fn main() {
502 /// # if let Err(_) = run() {
503 /// # ::std::process::exit(1);
504 /// # }
505 /// # }
506 /// # fn run() -> Result<(), io::Error> {
507 /// # use camino_tempfile::Builder;
508 /// // This could overwrite an existing file!
509 /// let tempfile = Builder::new().make(|path| File::create(path))?;
510 /// # Ok(())
511 /// # }
512 /// ```
513 /// For creating regular temporary files, use [`Builder::tempfile`] instead
514 /// to avoid these problems. This function is meant to enable more exotic
515 /// use-cases.
516 ///
517 /// # Resource leaking
518 ///
519 /// See [the resource leaking][resource-leaking] docs on `NamedUtf8TempFile`.
520 ///
521 /// # Errors
522 ///
523 /// If the closure returns any error besides
524 /// [`std::io::ErrorKind::AlreadyExists`] or
525 /// [`std::io::ErrorKind::AddrInUse`], then `Err` is returned.
526 ///
527 /// # Examples
528 /// ```
529 /// # use std::io;
530 /// # fn main() {
531 /// # if let Err(_) = run() {
532 /// # ::std::process::exit(1);
533 /// # }
534 /// # }
535 /// # fn run() -> Result<(), io::Error> {
536 /// # use camino_tempfile::Builder;
537 /// # #[cfg(unix)]
538 /// use std::os::unix::net::UnixListener;
539 /// # #[cfg(unix)]
540 /// let tempsock = Builder::new().make(|path| UnixListener::bind(path))?;
541 /// # Ok(())
542 /// # }
543 /// ```
544 ///
545 /// [TOCTOU]: https://en.wikipedia.org/wiki/Time-of-check_to_time-of-use
546 /// [security]: struct.NamedUtf8TempFile.html#security
547 /// [resource-leaking]: struct.NamedUtf8TempFile.html#resource-leaking
548 pub fn make<F, R>(&self, f: F) -> io::Result<NamedUtf8TempFile<R>>
549 where
550 F: FnMut(&Utf8Path) -> io::Result<R>,
551 {
552 self.make_in(utf8_env_temp_dir()?, f)
553 }
554
555 /// This is the same as [`Builder::make`], except `dir` is used as the base
556 /// directory for the temporary file path.
557 ///
558 /// See [`Builder::make`] for more details and security implications.
559 ///
560 /// # Examples
561 /// ```
562 /// # use std::io;
563 /// # fn main() {
564 /// # if let Err(_) = run() {
565 /// # ::std::process::exit(1);
566 /// # }
567 /// # }
568 /// # fn run() -> Result<(), io::Error> {
569 /// # use camino_tempfile::Builder;
570 /// # #[cfg(unix)]
571 /// use std::os::unix::net::UnixListener;
572 /// # #[cfg(unix)]
573 /// let tempsock = Builder::new().make_in("./", |path| UnixListener::bind(path))?;
574 /// # Ok(())
575 /// # }
576 /// ```
577 pub fn make_in<F, R, P>(&self, dir: P, mut f: F) -> io::Result<NamedUtf8TempFile<R>>
578 where
579 F: FnMut(&Utf8Path) -> io::Result<R>,
580 P: AsRef<Utf8Path>,
581 {
582 let temp_file = self.inner.make_in(dir.as_ref(), |path| {
583 // This produces a better error message.
584 let utf8_path =
585 Utf8PathBuf::try_from(path.to_path_buf()).map_err(|error| error.into_io_error())?;
586 f(&utf8_path)
587 })?;
588 NamedUtf8TempFile::from_temp_file(temp_file)
589 }
590}