Struct poem::web::cookie::CookieJar

pub struct CookieJar { /* private fields */ }

Available on crate feature cookie only.

A collection of cookies that tracks its modifications.

Example

use poem::{
    get, handler,
    http::{header, StatusCode},
    middleware::CookieJarManager,
    test::TestClient,
    web::cookie::{Cookie, CookieJar},
    Endpoint, EndpointExt, Request, Route,
};

#[handler]
fn index(cookie_jar: &CookieJar) -> String {
    let count = match cookie_jar.get("count") {
        Some(cookie) => cookie.value::<i32>().unwrap() + 1,
        None => 1,
    };
    cookie_jar.add(Cookie::new("count", count));
    format!("count: {}", count)
}

let app = Route::new()
    .at("/", get(index))
    .with(CookieJarManager::new());
let cli = TestClient::new(app);

let resp = cli.get("/").send().await;
resp.assert_status_is_ok();
let cookie = resp.0.headers().get(header::SET_COOKIE).cloned().unwrap();
resp.assert_text("count: 1").await;

let resp = cli.get("/").header(header::COOKIE, cookie).send().await;
resp.assert_status_is_ok();
resp.assert_text("count: 2").await;

Implementations

impl CookieJar

pub fn add(&self, cookie: Cookie)

Adds cookie to this jar. If a cookie with the same name already exists, it is replaced with cookie.

pub fn remove(&self, name: impl AsRef<str>)

Removes cookie from this jar.

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

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

pub fn reset_delta(&self)

Removes all delta cookies.

pub fn with_cookies<F, R>(&self, f: F) -> Rwhere
    F: FnOnce(Iter<'_>) -> R,

Wraps an iterator over all of the cookies present in this jar with a closure.

pub fn private_with_key<'a>(&'a self, key: &'a CookieKey) -> PrivateCookieJar<'a>

Returns a PrivateJar with self as its parent jar using the key to encrypt and decrypt cookies added/retrieved from the child jar.

Example

use poem::web::cookie::{Cookie, CookieJar, CookieKey};

let key = CookieKey::generate();
let cookie_jar = CookieJar::default();

cookie_jar
    .private_with_key(&key)
    .add(Cookie::new_with_str("foo", "bar"));

assert_ne!(cookie_jar.get("foo").unwrap().value_str(), "bar");
assert_eq!(
    cookie_jar
        .private_with_key(&key)
        .get("foo")
        .unwrap()
        .value_str(),
    "bar"
);

let key2 = CookieKey::generate();
assert!(cookie_jar.private_with_key(&key2).get("foo").is_none());

pub fn private(&self) -> PrivateCookieJar<'_>

Similar to the private_with_key function, but using the key specified by the CookieJarManager::with_key.

pub fn signed_with_key<'a>(&'a self, key: &'a CookieKey) -> SignedCookieJar<'a>

Returns a SignedJar with self as its parent jar using the key key to verify cookies retrieved from the child jar. Any retrievals from the child jar will be made from the parent jar.

Example

use poem::web::cookie::{Cookie, CookieJar, CookieKey};

let key = CookieKey::generate();
let cookie_jar = CookieJar::default();

cookie_jar
    .signed_with_key(&key)
    .add(Cookie::new_with_str("foo", "bar"));

assert!(cookie_jar.get("foo").unwrap().value_str().contains("bar"));
assert_eq!(
    cookie_jar
        .signed_with_key(&key)
        .get("foo")
        .unwrap()
        .value_str(),
    "bar"
);

let key2 = CookieKey::generate();
assert!(cookie_jar.signed_with_key(&key2).get("foo").is_none());

pub fn signed(&self) -> SignedCookieJar<'_>

Similar to the signed_with_key function, but using the key specified by the CookieJarManager::with_key.

Trait Implementations

impl Clone for CookieJar

fn clone(&self) -> CookieJar

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Default for CookieJar

fn default() -> CookieJar

Returns the “default value” for a type.

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

fn from_request<'life0, 'async_trait>(
    req: &'a Request,
    _body: &'life0 mut RequestBody
) -> Pin<Box<dyn Future<Output = Result<Self>> + Send + 'async_trait>>where
    'a: 'async_trait,
    'life0: 'async_trait,
    Self: 'async_trait,

Extract from request head and body.

fn from_request_without_body<'async_trait>(
    req: &'a Request
) -> Pin<Box<dyn Future<Output = Result<Self>> + Send + 'async_trait>>where
    'a: 'async_trait,
    Self: Send + 'async_trait,

Extract from request head.

impl FromStr for CookieJar

type Err = Infallible

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.