[−][src]Enum rocket_http::Cookies
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
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]
ⓘImportant traits for SmallVec<A>fn into_collection<A>(Self) -> SmallVec<A> where
A: Array<Item = T>,
[src]
A: Array<Item = T>,
ⓘImportant traits for SmallVec<A>fn mapped<U, F, A>(Self, F) -> SmallVec<A> where
A: Array<Item = U>,
F: FnMut(T) -> U,
[src]
A: Array<Item = U>,
F: FnMut(T) -> U,
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T> From<T> for T
[src]
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,
type Error = <U as TryFrom<T>>::Error
The type returned in the event of a conversion error.
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
[src]
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T, I> AsResult<T, I> for T where
I: Input,
[src]
I: Input,
impl<T> Typeable for T where
T: Any,
T: Any,