[][src]Enum rocket_http::Cookies

pub enum Cookies<'a> {
    // some variants omitted
}

Collection of one or more HTTP cookies.

The Cookies type allows for retrieval of cookies from an incoming request as well as modifications to cookies to be reflected by Rocket on outgoing responses. Cookies is a smart-pointer; it internally borrows and refers to the collection of cookies active during a request's life-cycle.

Usage

A type of Cookies 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. Cookies can be added or removed via the add(), add_private(), remove(), and remove_private() methods.

Examples

The following short snippet shows Cookies being used as a request guard in a handler to retrieve the value of a "message" cookie.

use rocket::http::Cookies;

#[get("/message")]
fn message(cookies: Cookies) -> Option<String> {
    cookies.get("message").map(|c| format!("Message: {}", c.value()))
}

The following snippet shows Cookies 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::outcome::IntoOutcome;
use rocket::request::{self, Request, FromRequest};

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

impl<'a, 'r> FromRequest<'a, 'r> for User {
    type Error = !;

    fn from_request(request: &'a Request<'r>) -> request::Outcome<User, !> {
        request.cookies()
            .get_private("user_id")
            .and_then(|cookie| cookie.value().parse().ok())
            .map(|id| User(id))
            .or_forward(())
    }
}

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 Cookies 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.

Methods

impl<'a> Cookies<'a>[src]

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

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

Example

use rocket::http::Cookies;

fn handler(cookies: Cookies) {
    let cookie = cookies.get("name");
}

pub fn add(&mut self, cookie: Cookie<'static>)[src]

Adds cookie to this collection.

Example

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

fn handler(mut cookies: Cookies) {
    cookies.add(Cookie::new("name", "value"));

    let cookie = Cookie::build("name", "value")
        .path("/")
        .secure(true)
        .finish();

    cookies.add(cookie);
}

pub fn remove(&mut self, cookie: Cookie<'static>)[src]

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.

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, Cookies};

fn handler(mut cookies: Cookies) {
    cookies.remove(Cookie::named("name"));
}

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

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

Example

use rocket::http::Cookies;

fn handler(cookies: Cookies) {
    for c in cookies.iter() {
        println!("Name: '{}', Value: '{}'", c.name(), c.value());
    }
}

Trait Implementations

impl<'a> Debug for Cookies<'a>[src]

Auto Trait Implementations

impl<'a> !Sync for Cookies<'a>

impl<'a> !Send for Cookies<'a>

impl<'a> Unpin for Cookies<'a>

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

impl<'a> !UnwindSafe for Cookies<'a>

Blanket Implementations

impl<T> IntoCollection<T> for T[src]

impl<T, U> Into<U> for T where
    U: From<T>, 
[src]

impl<T> From<T> for T[src]

impl<T, U> TryFrom<U> for T where
    U: Into<T>, 
[src]

type Error = Infallible

The type returned in the event of a conversion error.

impl<T, U> TryInto<U> for T where
    U: TryFrom<T>, 
[src]

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

The type returned in the event of a conversion error.

impl<T> BorrowMut<T> for T where
    T: ?Sized
[src]

impl<T> Borrow<T> for T where
    T: ?Sized
[src]

impl<T> Any for T where
    T: 'static + ?Sized
[src]

impl<T, I> AsResult<T, I> for T where
    I: Input
[src]

impl<T> Typeable for T where
    T: Any

fn get_type(&self) -> TypeId

Get the TypeId of this object.