pub struct CookieJar { /* private fields */ }
Expand description

A collection of cookies that tracks its modifications.

A CookieJar provides storage for any number of cookies. Any changes made to the jar are tracked; the changes can be retrieved via the delta method which returns an iterator over the changes.

Usage

A jar’s life begins via new and calls to add_original:

use cookie::{Cookie, CookieJar};

let mut jar = CookieJar::new();
jar.add_original(Cookie::new("name", "value"));
jar.add_original(Cookie::new("second", "another"));

Cookies can be added via add and removed via remove. Finally, cookies can be looked up via get:

let mut jar = CookieJar::new();
jar.add(Cookie::new("a", "one"));
jar.add(Cookie::new("b", "two"));

assert_eq!(jar.get("a").map(|c| c.value()), Some("one"));
assert_eq!(jar.get("b").map(|c| c.value()), Some("two"));

jar.remove(Cookie::named("b"));
assert!(jar.get("b").is_none());

Deltas

A jar keeps track of any modifications made to it over time. The modifications are recorded as cookies. The modifications can be retrieved via delta. Any new Cookie added to a jar via add results in the same Cookie appearing in the delta; cookies added via add_original do not count towards the delta. Any original cookie that is removed from a jar results in a “removal” cookie appearing in the delta. A “removal” cookie is a cookie that a server sends so that the cookie is removed from the client’s machine.

Deltas are typically used to create Set-Cookie headers corresponding to the changes made to a cookie jar over a period of time.

let mut jar = CookieJar::new();

// original cookies don't affect the delta
jar.add_original(Cookie::new("original", "value"));
assert_eq!(jar.delta().count(), 0);

// new cookies result in an equivalent `Cookie` in the delta
jar.add(Cookie::new("a", "one"));
jar.add(Cookie::new("b", "two"));
assert_eq!(jar.delta().count(), 2);

// removing an original cookie adds a "removal" cookie to the delta
jar.remove(Cookie::named("original"));
assert_eq!(jar.delta().count(), 3);

// removing a new cookie that was added removes that `Cookie` from the delta
jar.remove(Cookie::named("a"));
assert_eq!(jar.delta().count(), 2);

Implementations

Creates an empty cookie jar.

Example
use cookie::CookieJar;

let jar = CookieJar::new();
assert_eq!(jar.iter().count(), 0);

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

Example
use cookie::{CookieJar, Cookie};

let mut jar = CookieJar::new();
assert!(jar.get("name").is_none());

jar.add(Cookie::new("name", "value"));
assert_eq!(jar.get("name").map(|c| c.value()), Some("value"));

Adds an “original” cookie to this jar. If an original cookie with the same name already exists, it is replaced with cookie. Cookies added with add take precedence and are not replaced by this method.

Adding an original cookie does not affect the delta computation. This method is intended to be used to seed the cookie jar with cookies received from a client’s HTTP message.

For accurate delta computations, this method should not be called after calling remove.

Example
use cookie::{CookieJar, Cookie};

let mut jar = CookieJar::new();
jar.add_original(Cookie::new("name", "value"));
jar.add_original(Cookie::new("second", "two"));

assert_eq!(jar.get("name").map(|c| c.value()), Some("value"));
assert_eq!(jar.get("second").map(|c| c.value()), Some("two"));
assert_eq!(jar.iter().count(), 2);
assert_eq!(jar.delta().count(), 0);

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

Example
use cookie::{CookieJar, Cookie};

let mut jar = CookieJar::new();
jar.add(Cookie::new("name", "value"));
jar.add(Cookie::new("second", "two"));

assert_eq!(jar.get("name").map(|c| c.value()), Some("value"));
assert_eq!(jar.get("second").map(|c| c.value()), Some("two"));
assert_eq!(jar.iter().count(), 2);
assert_eq!(jar.delta().count(), 2);

Removes cookie from this jar. If an original cookie with the same name as cookie is present in the jar, a removal cookie will be present in the delta computation. To properly generate the removal cookie, cookie must contain the same path and domain as the cookie that was initially 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. See also Cookie::make_removal().

Example

Removing an original cookie results in a removal cookie:

extern crate time;

use cookie::{CookieJar, Cookie};
use time::Duration;

let mut jar = CookieJar::new();

// Assume this cookie originally had a path of "/" and domain of "a.b".
jar.add_original(Cookie::new("name", "value"));

// If the path and domain were set, they must be provided to `remove`.
jar.remove(Cookie::build("name", "").path("/").domain("a.b").finish());

// The delta will contain the removal cookie.
let delta: Vec<_> = jar.delta().collect();
assert_eq!(delta.len(), 1);
assert_eq!(delta[0].name(), "name");
assert_eq!(delta[0].max_age(), Some(Duration::seconds(0)));

Removing a new cookie does not result in a removal cookie unless there’s an original cookie with the same name:

use cookie::{CookieJar, Cookie};

let mut jar = CookieJar::new();
jar.add(Cookie::new("name", "value"));
assert_eq!(jar.delta().count(), 1);

jar.remove(Cookie::named("name"));
assert_eq!(jar.delta().count(), 0);

jar.add_original(Cookie::new("name", "value"));
jar.add(Cookie::new("name", "value"));
assert_eq!(jar.delta().count(), 1);

jar.remove(Cookie::named("name"));
assert_eq!(jar.delta().count(), 1);

Removes cookie from this jar completely. This method differs from remove in that no delta cookie is created under any condition. Neither the delta nor iter methods will return a cookie that is removed using this method.

Example

Removing an original cookie; no removal cookie is generated:

extern crate time;

use cookie::{CookieJar, Cookie};
use time::Duration;

let mut jar = CookieJar::new();

// Add an original cookie and a new cookie.
jar.add_original(Cookie::new("name", "value"));
jar.add(Cookie::new("key", "value"));
assert_eq!(jar.delta().count(), 1);
assert_eq!(jar.iter().count(), 2);

// Now force remove the original cookie.
jar.force_remove(&Cookie::named("name"));
assert_eq!(jar.delta().count(), 1);
assert_eq!(jar.iter().count(), 1);

// Now force remove the new cookie.
jar.force_remove(&Cookie::named("key"));
assert_eq!(jar.delta().count(), 0);
assert_eq!(jar.iter().count(), 0);

Removes all delta cookies, i.e. all cookies not added via CookieJar::add_original(), from this CookieJar. This undoes any changes from CookieJar::add() and CookieJar::remove() operations.

Example
use cookie::{CookieJar, Cookie};

let mut jar = CookieJar::new();

// Only original cookies will remain after calling `reset_delta`.
jar.add_original(Cookie::new("name", "value"));
jar.add_original(Cookie::new("language", "Rust"));

// These operations, represented by delta cookies, will be reset.
jar.add(Cookie::new("language", "C++"));
jar.remove(Cookie::named("name"));

// All is normal.
assert_eq!(jar.get("name"), None);
assert_eq!(jar.get("language").map(Cookie::value), Some("C++"));
assert_eq!(jar.iter().count(), 1);
assert_eq!(jar.delta().count(), 2);

// Resetting undoes delta operations.
jar.reset_delta();
assert_eq!(jar.get("name").map(Cookie::value), Some("value"));
assert_eq!(jar.get("language").map(Cookie::value), Some("Rust"));
assert_eq!(jar.iter().count(), 2);
assert_eq!(jar.delta().count(), 0);

Returns an iterator over cookies that represent the changes to this jar over time. These cookies can be rendered directly as Set-Cookie header values to affect the changes made to this jar on the client.

Example
use cookie::{CookieJar, Cookie};

let mut jar = CookieJar::new();
jar.add_original(Cookie::new("name", "value"));
jar.add_original(Cookie::new("second", "two"));

// Add new cookies.
jar.add(Cookie::new("new", "third"));
jar.add(Cookie::new("another", "fourth"));
jar.add(Cookie::new("yac", "fifth"));

// Remove some cookies.
jar.remove(Cookie::named("name"));
jar.remove(Cookie::named("another"));

// Delta contains two new cookies ("new", "yac") and a removal ("name").
assert_eq!(jar.delta().count(), 3);

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

Example
use cookie::{CookieJar, Cookie};

let mut jar = CookieJar::new();

jar.add_original(Cookie::new("name", "value"));
jar.add_original(Cookie::new("second", "two"));

jar.add(Cookie::new("new", "third"));
jar.add(Cookie::new("another", "fourth"));
jar.add(Cookie::new("yac", "fifth"));

jar.remove(Cookie::named("name"));
jar.remove(Cookie::named("another"));

// There are three cookies in the jar: "second", "new", and "yac".
for cookie in jar.iter() {
    match cookie.name() {
        "second" => assert_eq!(cookie.value(), "two"),
        "new" => assert_eq!(cookie.value(), "third"),
        "yac" => assert_eq!(cookie.value(), "fifth"),
        _ => unreachable!("there are only three cookies in the jar")
    }
}

Trait Implementations

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

Returns the “default value” for a type. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

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

The resulting type after obtaining ownership.

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

🔬 This is a nightly-only experimental API. (toowned_clone_into)

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

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.