Struct rocket::http::CookieJar

source ·
pub struct CookieJar<'a> { /* private fields */ }
Expand description

Collection of one or more HTTP cookies.

CookieJar allows for retrieval of cookies from an incoming request. It also tracks modifications (additions and removals) and marks them as pending.

Pending

Changes to a CookieJar are not visible via the normal get() and get_private() methods. This is typically the desired effect as a CookieJar always reflects the cookies in an incoming request. In cases where this is not desired, the get_pending() method is available, which always returns the latest changes.

use rocket::http::{CookieJar, Cookie};

#[get("/message")]
fn message(jar: &CookieJar<'_>) {
    jar.add(Cookie::new("message", "hello!"));
    jar.add(Cookie::new("other", "bye!"));

    // `get()` does not reflect changes.
    assert!(jar.get("other").is_none());

    // `get_pending()` does.
    let other_pending = jar.get_pending("other");
    let message_pending = jar.get_pending("message");
    assert_eq!(other_pending.as_ref().map(|c| c.value()), Some("bye!"));
    assert_eq!(message_pending.as_ref().map(|c| c.value()), Some("hello!"));
}

Usage

A type of &CookieJar can be retrieved via its FromRequest implementation as a request guard or via the Request::cookies() method. Individual cookies can be retrieved via the get() and get_private() methods. Pending changes can be observed via the get_pending() method. Cookies can be added or removed via the add(), add_private(), remove(), and remove_private() methods.

Examples

The following example shows &CookieJar being used as a request guard in a handler to retrieve the value of a “message” cookie.

use rocket::http::CookieJar;

#[get("/message")]
fn message<'a>(jar: &'a CookieJar<'_>) -> Option<&'a str> {
    jar.get("message").map(|cookie| cookie.value())
}

The following snippet shows &CookieJar being retrieved from a Request in a custom request guard implementation for User. A private cookie containing a user’s ID is retrieved. If the cookie exists and the ID parses as an integer, a User structure is validated. Otherwise, the guard forwards.

use rocket::http::Status;
use rocket::request::{self, Request, FromRequest};
use rocket::outcome::IntoOutcome;

// In practice, we'd probably fetch the user from the database.
struct User(usize);

#[rocket::async_trait]
impl<'r> FromRequest<'r> for User {
    type Error = std::convert::Infallible;

    async fn from_request(request: &'r Request<'_>) -> request::Outcome<Self, Self::Error> {
        request.cookies()
            .get_private("user_id")
            .and_then(|c| c.value().parse().ok())
            .map(|id| User(id))
            .or_forward(Status::Unauthorized)
    }
}

Private Cookies

Private cookies are just like regular cookies except that they are encrypted using authenticated encryption, a form of encryption which simultaneously provides confidentiality, integrity, and authenticity. This means that private cookies cannot be inspected, tampered with, or manufactured by clients. If you prefer, you can think of private cookies as being signed and encrypted.

Private cookies can be retrieved, added, and removed from a CookieJar collection via the get_private(), add_private(), and remove_private() methods.

Encryption Key

To encrypt private cookies, Rocket uses the 256-bit key specified in the secret_key configuration parameter. If one is not specified, Rocket will automatically generate a fresh key. Note, however, that a private cookie can only be decrypted with the same key with which it was encrypted. As such, it is important to set a secret_key configuration parameter when using private cookies so that cookies decrypt properly after an application restart. Rocket will emit a warning if an application is run in production mode without a configured secret_key.

Generating a string suitable for use as a secret_key configuration value is usually done through tools like openssl. Using openssl, for instance, a 256-bit base64 key can be generated with the command openssl rand -base64 32.

Implementations§

source§

impl<'a> CookieJar<'a>

source

pub fn get(&self, name: &str) -> Option<&Cookie<'static>>

Returns a reference to the original Cookie inside this container with the name name. If no such cookie exists, returns None.

Note: This method does not observe changes made via additions and removals to the cookie jar. To observe those changes, use CookieJar::get_pending().

Example
use rocket::http::{Cookie, CookieJar};

#[get("/")]
fn handler(jar: &CookieJar<'_>) {
    let cookie = jar.get("name");
}
source

pub fn get_private(&self, name: &str) -> Option<Cookie<'static>>

Available on crate feature secrets only.

Retrieves the original Cookie inside this collection with the name name and authenticates and decrypts the cookie’s value. If the cookie cannot be found, or the cookie fails to authenticate or decrypt, None is returned.

Note: This method does not observe changes made via additions and removals to the cookie jar. To observe those changes, use CookieJar::get_pending().

Example
use rocket::http::{Cookie, CookieJar};

#[get("/")]
fn handler(jar: &CookieJar<'_>) {
    let cookie = jar.get_private("name");
}
source

pub fn get_pending(&self, name: &str) -> Option<Cookie<'static>>

Returns a reference to the original or pending Cookie inside this container with the name name, irrespective of whether the cookie was private or not. If no such cookie exists, returns None.

In general, due to performance overhead, calling this method should be avoided if it is known that a cookie called name is not pending. Instead, prefer to use CookieJar::get() or CookieJar::get_private().

Example
use rocket::http::{Cookie, CookieJar};

#[get("/")]
fn handler(jar: &CookieJar<'_>) {
    let pending_cookie = jar.get_pending("name");
}
source

pub fn add(&self, cookie: Cookie<'static>)

Adds cookie to this collection.

Unless a value is set for the given property, the following defaults are set on cookie before being added to self:

  • path: "/"
  • SameSite: Strict

Furthermore, if TLS is enabled, the Secure cookie flag is set.

Example
use rocket::http::{Cookie, SameSite, CookieJar};

#[get("/")]
fn handler(jar: &CookieJar<'_>) {
    jar.add(Cookie::new("first", "value"));

    let cookie = Cookie::build("other", "value_two")
        .path("/")
        .secure(true)
        .same_site(SameSite::Lax);

    jar.add(cookie.finish());
}
source

pub fn add_private(&self, cookie: Cookie<'static>)

Available on crate feature secrets only.

Adds cookie to the collection. The cookie’s value is encrypted with authenticated encryption assuring confidentiality, integrity, and authenticity. The cookie can later be retrieved using get_private and removed using remove_private.

Unless a value is set for the given property, the following defaults are set on cookie before being added to self:

  • path: "/"
  • SameSite: Strict
  • HttpOnly: true
  • Expires: 1 week from now

Furthermore, if TLS is enabled, the Secure cookie flag is set. These defaults ensure maximum usability and security. For additional security, you may wish to set the secure flag.

Example
use rocket::http::{Cookie, CookieJar};

#[get("/")]
fn handler(jar: &CookieJar<'_>) {
    jar.add_private(Cookie::new("name", "value"));
}
source

pub fn remove(&self, cookie: Cookie<'static>)

Removes cookie from this collection and generates a “removal” cookies to send to the client on response. For correctness, cookie must contain the same path and domain as the cookie that was initially set. Failure to provide the initial path and domain will result in cookies that are not properly removed. For convenience, if a path is not set on cookie, the "/" path will automatically be set.

A “removal” cookie is a cookie that has the same name as the original cookie but has an empty value, a max-age of 0, and an expiration date far in the past.

Example
use rocket::http::{Cookie, CookieJar};

#[get("/")]
fn handler(jar: &CookieJar<'_>) {
    jar.remove(Cookie::named("name"));
}
source

pub fn remove_private(&self, cookie: Cookie<'static>)

Available on crate feature secrets only.

Removes the private cookie from the collection.

For correct removal, the passed in cookie must contain the same path and domain as the cookie that was initially set. If a path is not set on cookie, the "/" path will automatically be set.

Example
use rocket::http::{Cookie, CookieJar};

#[get("/")]
fn handler(jar: &CookieJar<'_>) {
    jar.remove_private(Cookie::named("name"));
}
source

pub fn iter(&self) -> impl Iterator<Item = &Cookie<'static>>

Returns an iterator over all of the original cookies present in this collection.

Note: This method does not observe changes made via additions and removals to the cookie jar.

Example
use rocket::http::{Cookie, CookieJar};

#[get("/")]
fn handler(jar: &CookieJar<'_>) {
    for c in jar.iter() {
        println!("Name: {:?}, Value: {:?}", c.name(), c.value());
    }
}

Trait Implementations§

source§

impl<'a> Clone for CookieJar<'a>

source§

fn clone(&self) -> Self

Returns a copy of the value. Read more
1.0.0 · source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
source§

impl Debug for CookieJar<'_>

source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
source§

impl<'r> FromRequest<'r> for &'r CookieJar<'r>

§

type Error = Infallible

The associated error to be returned if derivation fails.
source§

fn from_request<'life0, 'async_trait>( request: &'r Request<'life0> ) -> Pin<Box<dyn Future<Output = Outcome<Self, Self::Error>> + Send + 'async_trait>>where Self: 'async_trait, 'r: 'async_trait, 'life0: 'async_trait,

Derives an instance of Self from the incoming request metadata. Read more

Auto Trait Implementations§

§

impl<'a> !RefUnwindSafe for CookieJar<'a>

§

impl<'a> Send for CookieJar<'a>

§

impl<'a> Sync for CookieJar<'a>

§

impl<'a> Unpin for CookieJar<'a>

§

impl<'a> UnwindSafe for CookieJar<'a>

Blanket Implementations§

source§

impl<T> Any for Twhere T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for Twhere T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for Twhere T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for Twhere U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> IntoCollection<T> for T

source§

fn into_collection<A>(self) -> SmallVec<A>where A: Array<Item = T>,

Converts self into a collection.
source§

fn mapped<U, F, A>(self, f: F) -> SmallVec<A>where F: FnMut(T) -> U, A: Array<Item = U>,

source§

impl<T> Paint for Twhere T: ?Sized,

source§

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 primary(&self) -> Painted<&T>

Returns self with the fg() set to Color::Primary.

Example
println!("{}", value.primary());
source§

fn fixed(&self, color: u8) -> Painted<&T>

Returns self with the fg() set to Color::Fixed.

Example
println!("{}", value.fixed(color));
source§

fn rgb(&self, r: u8, g: u8, b: u8) -> Painted<&T>

Returns self with the fg() set to Color::Rgb.

Example
println!("{}", value.rgb(r, g, b));
source§

fn black(&self) -> Painted<&T>

Returns self with the fg() set to Color::Black.

Example
println!("{}", value.black());
source§

fn red(&self) -> Painted<&T>

Returns self with the fg() set to Color::Red.

Example
println!("{}", value.red());
source§

fn green(&self) -> Painted<&T>

Returns self with the fg() set to Color::Green.

Example
println!("{}", value.green());
source§

fn yellow(&self) -> Painted<&T>

Returns self with the fg() set to Color::Yellow.

Example
println!("{}", value.yellow());
source§

fn blue(&self) -> Painted<&T>

Returns self with the fg() set to Color::Blue.

Example
println!("{}", value.blue());
source§

fn magenta(&self) -> Painted<&T>

Returns self with the fg() set to Color::Magenta.

Example
println!("{}", value.magenta());
source§

fn cyan(&self) -> Painted<&T>

Returns self with the fg() set to Color::Cyan.

Example
println!("{}", value.cyan());
source§

fn white(&self) -> Painted<&T>

Returns self with the fg() set to Color::White.

Example
println!("{}", value.white());
source§

fn bright_black(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightBlack.

Example
println!("{}", value.bright_black());
source§

fn bright_red(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightRed.

Example
println!("{}", value.bright_red());
source§

fn bright_green(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightGreen.

Example
println!("{}", value.bright_green());
source§

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>

Returns self with the fg() set to Color::BrightBlue.

Example
println!("{}", value.bright_blue());
source§

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>

Returns self with the fg() set to Color::BrightCyan.

Example
println!("{}", value.bright_cyan());
source§

fn bright_white(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightWhite.

Example
println!("{}", value.bright_white());
source§

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>

Returns self with the bg() set to Color::Primary.

Example
println!("{}", value.on_primary());
source§

fn on_fixed(&self, color: u8) -> Painted<&T>

Returns self with the bg() set to Color::Fixed.

Example
println!("{}", value.on_fixed(color));
source§

fn on_rgb(&self, r: u8, g: u8, b: u8) -> Painted<&T>

Returns self with the bg() set to Color::Rgb.

Example
println!("{}", value.on_rgb(r, g, b));
source§

fn on_black(&self) -> Painted<&T>

Returns self with the bg() set to Color::Black.

Example
println!("{}", value.on_black());
source§

fn on_red(&self) -> Painted<&T>

Returns self with the bg() set to Color::Red.

Example
println!("{}", value.on_red());
source§

fn on_green(&self) -> Painted<&T>

Returns self with the bg() set to Color::Green.

Example
println!("{}", value.on_green());
source§

fn on_yellow(&self) -> Painted<&T>

Returns self with the bg() set to Color::Yellow.

Example
println!("{}", value.on_yellow());
source§

fn on_blue(&self) -> Painted<&T>

Returns self with the bg() set to Color::Blue.

Example
println!("{}", value.on_blue());
source§

fn on_magenta(&self) -> Painted<&T>

Returns self with the bg() set to Color::Magenta.

Example
println!("{}", value.on_magenta());
source§

fn on_cyan(&self) -> Painted<&T>

Returns self with the bg() set to Color::Cyan.

Example
println!("{}", value.on_cyan());
source§

fn on_white(&self) -> Painted<&T>

Returns self with the bg() set to Color::White.

Example
println!("{}", value.on_white());
source§

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>

Returns self with the bg() set to Color::BrightRed.

Example
println!("{}", value.on_bright_red());
source§

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>

Returns self with the bg() set to Color::BrightYellow.

Example
println!("{}", value.on_bright_yellow());
source§

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>

Returns self with the bg() set to Color::BrightMagenta.

Example
println!("{}", value.on_bright_magenta());
source§

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>

Returns self with the bg() set to Color::BrightWhite.

Example
println!("{}", value.on_bright_white());
source§

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 bold(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Bold.

Example
println!("{}", value.bold());
source§

fn dim(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Dim.

Example
println!("{}", value.dim());
source§

fn italic(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Italic.

Example
println!("{}", value.italic());
source§

fn underline(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Underline.

Example
println!("{}", value.underline());

Returns self with the attr() set to Attribute::Blink.

Example
println!("{}", value.blink());

Returns self with the attr() set to Attribute::RapidBlink.

Example
println!("{}", value.rapid_blink());
source§

fn invert(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Invert.

Example
println!("{}", value.invert());
source§

fn conceal(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Conceal.

Example
println!("{}", value.conceal());
source§

fn strike(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Strike.

Example
println!("{}", value.strike());
source§

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 mask(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Mask.

Example
println!("{}", value.mask());
source§

fn wrap(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Wrap.

Example
println!("{}", value.wrap());
source§

fn linger(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Linger.

Example
println!("{}", value.linger());
source§

fn clear(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Clear.

Example
println!("{}", value.clear());
source§

fn bright(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Bright.

Example
println!("{}", value.bright());
source§

fn on_bright(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::OnBright.

Example
println!("{}", value.on_bright());
source§

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);
source§

fn new(self) -> Painted<Self>where Self: Sized,

Create a new Painted with a default Style. Read more
source§

fn paint<S>(&self, style: S) -> Painted<&Self>where S: Into<Style>,

Apply a style wholesale to self. Any previous style is replaced. Read more
source§

impl<T> Same<T> for T

§

type Output = T

Should always be Self
source§

impl<T> ToOwned for Twhere T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<V, T> VZip<V> for Twhere V: MultiLane<T>,

source§

fn vzip(self) -> V

source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more