pub struct Shield { /* private fields */ }
Expand description
A Fairing
that injects browser security and privacy headers into all
outgoing responses.
Usage
To use Shield
, first construct an instance of it. To use the default
set of headers, construct with Shield::default()
.
For an instance with no preset headers, use Shield::new()
. To
enable an additional header, use enable()
, and to
disable a header, use disable()
:
use rocket::shield::Shield;
use rocket::shield::{XssFilter, ExpectCt};
// A `Shield` with the default headers:
let shield = Shield::default();
// A `Shield` with the default headers minus `XssFilter`:
let shield = Shield::default().disable::<XssFilter>();
// A `Shield` with the default headers plus `ExpectCt`.
let shield = Shield::default().enable(ExpectCt::default());
// A `Shield` with only `XssFilter` and `ExpectCt`.
let shield = Shield::default()
.enable(XssFilter::default())
.enable(ExpectCt::default());
Then, attach the instance of Shield
to your application’s instance of
Rocket
:
rocket::build()
// ...
.attach(shield)
The fairing will inject all enabled headers into all outgoing responses unless the response already contains a header with the same name. If it does contain the header, a warning is emitted, and the header is not overwritten.
TLS and HSTS
If TLS is configured and enabled when the application is launched in a non-debug profile, HSTS is automatically enabled with its default policy and a warning is logged.
To get rid of this warning, explicitly Shield::enable()
an Hsts
policy.
Implementations§
source§impl Shield
impl Shield
sourcepub fn new() -> Self
pub fn new() -> Self
Returns an instance of Shield
with no headers enabled.
Example
use rocket::shield::Shield;
let shield = Shield::new();
sourcepub fn enable<P: Policy>(self, policy: P) -> Self
pub fn enable<P: Policy>(self, policy: P) -> Self
Enables the policy header policy
.
If the policy was previously enabled, the configuration is replaced
with that of policy
.
Example
use rocket::shield::Shield;
use rocket::shield::NoSniff;
let shield = Shield::new().enable(NoSniff::default());
sourcepub fn disable<P: Policy>(self) -> Self
pub fn disable<P: Policy>(self) -> Self
Disables the policy header policy
.
Example
use rocket::shield::Shield;
use rocket::shield::NoSniff;
let shield = Shield::default().disable::<NoSniff>();
sourcepub fn is_enabled<P: Policy>(&self) -> bool
pub fn is_enabled<P: Policy>(&self) -> bool
Returns true
if the policy P
is enabled.
Example
use rocket::shield::Shield;
use rocket::shield::{Permission, NoSniff, Frame};
use rocket::shield::{Prefetch, ExpectCt, Referrer};
let shield = Shield::default();
assert!(shield.is_enabled::<NoSniff>());
assert!(shield.is_enabled::<Frame>());
assert!(shield.is_enabled::<Permission>());
assert!(!shield.is_enabled::<Prefetch>());
assert!(!shield.is_enabled::<ExpectCt>());
assert!(!shield.is_enabled::<Referrer>());
Trait Implementations§
source§impl Fairing for Shield
impl Fairing for Shield
source§fn on_liftoff<'life0, 'life1, 'async_trait>(
&'life0 self,
rocket: &'life1 Rocket<Orbit>
) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
fn on_liftoff<'life0, 'life1, 'async_trait>( &'life0 self, rocket: &'life1 Rocket<Orbit> ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,
source§fn on_response<'r, 'life0, 'life1, 'life2, 'async_trait>(
&'life0 self,
_: &'r Request<'life1>,
response: &'life2 mut Response<'r>
) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>where
Self: 'async_trait,
'r: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
fn on_response<'r, 'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _: &'r Request<'life1>, response: &'life2 mut Response<'r> ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>where Self: 'async_trait, 'r: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,
source§fn on_ignite<'life0, 'async_trait>(
&'life0 self,
rocket: Rocket<Build>
) -> Pin<Box<dyn Future<Output = Result> + Send + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
fn on_ignite<'life0, 'async_trait>( &'life0 self, rocket: Rocket<Build> ) -> Pin<Box<dyn Future<Output = Result> + Send + 'async_trait>>where Self: 'async_trait, 'life0: 'async_trait,
Ok
if ignition should proceed and Err
if ignition and launch should be aborted. Read moresource§fn on_request<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>(
&'life0 self,
_req: &'life1 mut Request<'life2>,
_data: &'life3 mut Data<'life4>
) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
'life3: 'async_trait,
'life4: 'async_trait,
fn on_request<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>( &'life0 self, _req: &'life1 mut Request<'life2>, _data: &'life3 mut Data<'life4> ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, 'life4: 'async_trait,
Auto Trait Implementations§
impl !RefUnwindSafe for Shield
impl Send for Shield
impl Sync for Shield
impl Unpin for Shield
impl !UnwindSafe for Shield
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> Instrument for T
impl<T> Instrument for T
source§fn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
source§fn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
source§impl<T> IntoCollection<T> for T
impl<T> IntoCollection<T> for 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);