#[repr(transparent)]pub struct FileName(/* private fields */);
Expand description
A file name in a TempFile
or multipart DataField
.
A Content-Disposition
header, either in a response or a multipart field,
can optionally specify a filename
directive as identifying information for
the attached file. This type represents the value of that directive.
Safety
There are no restrictions on the value of the directive. In particular, the
value can be wholly unsafe to use as a file name in common contexts. As
such, Rocket sanitizes the value into a version that is safe to use as a
file name in common contexts; this sanitized version can be retrieved via
FileName::as_str()
and is returned by TempFile::name()
.
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. You may also prefer to avoid the value in the directive entirely by using a safe, application-generated name instead.
Implementations§
source§impl FileName
impl FileName
sourcepub fn new<S: AsRef<str> + ?Sized>(string: &S) -> &FileName
pub fn new<S: AsRef<str> + ?Sized>(string: &S) -> &FileName
Wraps a string as a FileName
. This is cost-free.
Example
use rocket::fs::FileName;
let name = FileName::new("some-file.txt");
assert_eq!(name.as_str(), Some("some-file"));
let name = FileName::new("some-file.txt");
assert_eq!(name.dangerous_unsafe_unsanitized_raw(), "some-file.txt");
sourcepub fn as_str(&self) -> Option<&str>
pub fn as_str(&self) -> Option<&str>
The sanitized file name, stripped of any file extension and special characters, safe for use as a file name.
Sanitization
A “sanitized” file name is a non-empty string, stripped of its file extension, which is not a platform-specific reserved name and does not contain any platform-specific special characters.
On Unix, these are the characters '.', '/', '\\', '<', '>', '|', ':', '(', ')', '&', ';', '#', '?', '*'
.
On Windows (and non-Unix OSs), these are the characters '.', '<', '>', ':', '"', '/', '', '|', '?', '*', ',', ';', '=', '(', ')', '&', '#'
,
and the reserved names "CON", "PRN", "AUX", "NUL", "COM1", "COM2", "COM3", "COM4", "COM5", "COM6", "COM7", "COM8", "COM9", "LPT1", "LPT2", "LPT3", "LPT4", "LPT5", "LPT6", "LPT7", "LPT8", "LPT9"
.
Additionally, all control characters are considered “special”.
An attempt is made to transform the raw file name into a sanitized
version by identifying a valid substring of the raw file name that meets
this criteria. If none is found, None
is returned.
Example
use rocket::fs::FileName;
let name = FileName::new("some-file.txt");
assert_eq!(name.as_str(), Some("some-file"));
let name = FileName::new("some-file.txt.zip");
assert_eq!(name.as_str(), Some("some-file"));
let name = FileName::new("../../../../etc/shadow");
assert_eq!(name.as_str(), Some("shadow"));
let name = FileName::new("/etc/.shadow");
assert_eq!(name.as_str(), Some("shadow"));
let name = FileName::new("/a/b/some/file.txt.zip");
assert_eq!(name.as_str(), Some("file"));
let name = FileName::new("/a/b/some/.file.txt.zip");
assert_eq!(name.as_str(), Some("file"));
let name = FileName::new("/a/b/some/.*file.txt.zip");
assert_eq!(name.as_str(), Some("file"));
let name = FileName::new("a/\\b/some/.*file<.txt.zip");
assert_eq!(name.as_str(), Some("file"));
let name = FileName::new(">>>.foo.txt");
assert_eq!(name.as_str(), Some("foo"));
let name = FileName::new("b:c");
#[cfg(unix)] assert_eq!(name.as_str(), Some("b"));
#[cfg(not(unix))] assert_eq!(name.as_str(), Some("c"));
let name = FileName::new("//./.<>");
assert_eq!(name.as_str(), None);
sourcepub fn is_safe(&self) -> bool
pub fn is_safe(&self) -> bool
Returns true
if the complete raw file name is safe.
Note that .as_str()
returns a safe subset of the raw file name, if
there is one. If this method returns true
, then that subset is the
complete raw file name.
This method should be use sparingly. In particular, there is no
advantage to calling is_safe()
prior to calling as_str()
; simply
call as_str()
.
Example
use rocket::fs::FileName;
let name = FileName::new("some-file.txt");
assert_eq!(name.as_str(), Some("some-file"));
assert!(!name.is_safe());
let name = FileName::new("some-file");
assert_eq!(name.as_str(), Some("some-file"));
assert!(name.is_safe());
sourcepub fn dangerous_unsafe_unsanitized_raw(&self) -> &RawStr
pub fn dangerous_unsafe_unsanitized_raw(&self) -> &RawStr
The raw, unsanitized, potentially unsafe file name. Prefer to use
FileName::as_str()
, always.
⚠️ DANGER ⚠️
This method returns the file name exactly as it was specified by the
client. You should not use this name unless you require the
originally specified filename
and it is known not to contain
special, potentially dangerous characters, and:
-
All clients are known to be trusted, perhaps because the server only runs locally, serving known, local requests, or…
-
You will not use the file name to store a file on disk or any context that expects a file name and you will not use the extension to determine how to handle/parse the data, or…
-
You will expertly process the raw name into a sanitized version for use in specific contexts.
If not all of these cases apply, use FileName::as_str()
.
Example
use rocket::fs::FileName;
let name = FileName::new("some-file.txt");
assert_eq!(name.dangerous_unsafe_unsanitized_raw(), "some-file.txt");
let name = FileName::new("../../../../etc/shadow");
assert_eq!(name.dangerous_unsafe_unsanitized_raw(), "../../../../etc/shadow");
let name = FileName::new("../../.ssh/id_rsa");
assert_eq!(name.dangerous_unsafe_unsanitized_raw(), "../../.ssh/id_rsa");
let name = FileName::new("/Rocket.toml");
assert_eq!(name.dangerous_unsafe_unsanitized_raw(), "/Rocket.toml");
Trait Implementations§
Auto Trait Implementations§
impl RefUnwindSafe for FileName
impl Send for FileName
impl !Sized for FileName
impl Sync for FileName
impl Unpin for FileName
impl UnwindSafe for FileName
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> Paint for Twhere
T: ?Sized,
impl<T> Paint for Twhere T: ?Sized,
source§fn fg(&self, value: Color) -> Painted<&T>
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 bright_black(&self) -> Painted<&T>
fn bright_black(&self) -> Painted<&T>
source§fn bright_red(&self) -> Painted<&T>
fn bright_red(&self) -> Painted<&T>
source§fn bright_green(&self) -> Painted<&T>
fn bright_green(&self) -> Painted<&T>
source§fn bright_yellow(&self) -> Painted<&T>
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>
fn bright_blue(&self) -> Painted<&T>
source§fn bright_magenta(&self) -> Painted<&T>
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>
fn bright_cyan(&self) -> Painted<&T>
source§fn bright_white(&self) -> Painted<&T>
fn bright_white(&self) -> Painted<&T>
source§fn bg(&self, value: Color) -> Painted<&T>
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>
fn on_primary(&self) -> Painted<&T>
source§fn on_magenta(&self) -> Painted<&T>
fn on_magenta(&self) -> Painted<&T>
source§fn on_bright_black(&self) -> Painted<&T>
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>
fn on_bright_red(&self) -> Painted<&T>
source§fn on_bright_green(&self) -> Painted<&T>
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>
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>
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>
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>
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>
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>
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 underline(&self) -> Painted<&T>
fn underline(&self) -> Painted<&T>
Returns self
with the
attr()
set to
Attribute::Underline
.
Example
println!("{}", value.underline());
source§fn rapid_blink(&self) -> Painted<&T>
fn rapid_blink(&self) -> Painted<&T>
Returns self
with the
attr()
set to
Attribute::RapidBlink
.
Example
println!("{}", value.rapid_blink());
source§fn quirk(&self, value: Quirk) -> Painted<&T>
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 whenever(&self, value: Condition) -> Painted<&T>
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);