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