Struct CookieJar

Source

pub struct CookieJar { /* private fields */ }

Expand description

A generic CookieJar for cookie management. Can be used to read update or delete cookies from a user session.

§`axum` feature

Note that to set the cookies, the jar must be returned from the handler. Otherwise the cookies are not updated.

§Example

use cookie_monster::{CookieJar, Cookie};

static COOKIE_NAME: &str = "session";

async fn handler(mut jar: CookieJar) -> CookieJar {

    if let Some(cookie) = jar.get(COOKIE_NAME) {
        println!("Removing cookie {cookie:?}");
        jar.remove(Cookie::named(COOKIE_NAME));
    } else {
        let cookie = Cookie::new(COOKIE_NAME, "hello, world");
        println!("Setting cookie {cookie:?}");
        jar.add(cookie);
    }

    // Important, return the jar to update the cookies!
    jar
}

Implementations§

Source §

impl CookieJar

Source

pub fn new() -> Self

Creates an empty CookieJar.

Source

pub fn from_cookie(header: &str) -> Self

Parses the given cookie header value and return a CookieJar. This function ignores cookies that were not able to be parsed.

§Duplicate names

If the header contains the same cookie name more than once, the last occurrence wins. This matches the cookie crate, axum-extra, Python’s SimpleCookie and ASP.NET Core.

Duplicate-name resolution is not a security boundary. Note that the __Host- / __Secure- prefix is stripped from the name when parsing, so a prefixed cookie and a plain cookie of the same logical name collide here and the last one wins. If you rely on a prefix as a trust signal, reject requests that carry duplicate cookie names.

use cookie_monster::CookieJar;

let jar = CookieJar::from_cookie("name=first; name=second");
assert_eq!(jar.get("name").map(|c| c.value()), Some("second"));

Source

pub fn from_encoded_cookie(header: &str) -> Self

Parses the given cookie header value and return a CookieJar. The cookie name and values are percent-decoded. Cookies that were not able to be parsed are ignored.

Like from_cookie, duplicate cookie names resolve to the last occurrence; see its docs for the cookie-shadowing note.

Source

pub fn add_original(&mut self, cookie: Cookie)

Adds an original cookie to the jar. These are never sent back to the user-agent, but are visible in the cookie jar.

If a cookie with the same name is already present it is replaced (last-wins), matching add.

Source

pub fn from_original<T: IntoIterator<Item = Cookie>>(cookies: T) -> Self

Source

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

Get a cookie by name. Gives back either an original or newly added cookie.

Parsing strips the __Host- / __Secure- prefix from the cookie name, so a cookie received (or built) with a prefix is looked up by its logical (unprefixed) name.

Source

pub fn set_cookie_headers(&self) -> impl Iterator<Item = Result<String, Error>>

Iterate over all changes. This returns all removed and newly created cookies.

Source

pub fn remove(&mut self, cookie: impl Into<Cookie>) -> Option<Cookie>

Removes the cookie from the local cookie store and issues a cookie with an Expires attribute in the past and Max-Age of 0 seconds.

If one of the time, chrono or jiff features are enabled, the Expires tag is set to the current time minus one year. If none of the those features are enabled, the Expires attribute is set to 1 Jan 1970 00:00.

To ensure a cookie is removed from the user-agent, set the Path and Domain attributes with the same values that were used to create the cookie.

Source