Struct Jar 

pub struct Jar(/* private fields */);

Available on crate feature cookies only.

A good default CookieStore implementation.

This is the implementation used when simply calling cookie_store(true). This type is exposed to allow creating one and filling it with some existing cookies more easily, before creating a crate::Client.

Implementations

impl Jar

pub fn get<U: IntoUri>(&self, name: &str, uri: U) -> Option<Cookie<'static>>

Returns an unexpired cookie by name for an exact URI scope.

The URI host is canonicalized and its path is used as the exact stored cookie path. Use matches to select every cookie that would apply to a request URI through RFC domain and path matching. When both storage scopes contain the name, the older cookie is returned.

Example

use wreq::cookie::Jar;
let jar = Jar::default();
jar.add("foo=bar; Path=/foo; Domain=example.com", "http://example.com/foo");
let cookie = jar.get("foo", "http://example.com/foo").unwrap();
assert_eq!(cookie.value(), "bar");

pub fn contains<U: IntoUri>(&self, name: &str, uri: U) -> bool

Returns whether an unexpired cookie exists for an exact URI scope.

This performs the same scope lookup as get without cloning the cookie.

pub fn get_all(&self) -> impl Iterator<Item = Cookie<'static>>

Returns all unexpired cookies in the jar.

The returned cookies are owned snapshots with their effective stored Path. Host-only cookies keep their Domain attribute absent, so importing a snapshot into another jar does not broaden its domain scope. Snapshots are returned in creation order.

Example

use wreq::cookie::Jar;
let jar = Jar::default();
jar.add("foo=bar; Domain=example.com", "http://example.com");
for cookie in jar.get_all() {
    println!("{}={}", cookie.name(), cookie.value());
}

pub fn len(&self) -> usize

Returns the number of unexpired cookies in the jar.

Expired cookies are excluded even if their internal entries have not yet been overwritten or cleared.

pub fn is_empty(&self) -> bool

Returns true when the jar has no unexpired cookies.

pub fn matches<U: IntoUri>( &self, uri: U, ) -> impl Iterator<Item = Cookie<'static>>

Returns the unexpired cookies that apply to an HTTP or HTTPS request URI.

Selection applies domain matching, path matching, host-only scope, the Secure attribute, and expiration rules from the RFC 6265 retrieval model. Returned cookies are owned snapshots that preserve host-only scope. Unsupported URI schemes do not match any cookies.

Example

use wreq::cookie::Jar;

let jar = Jar::default();
jar.add("root=1; Domain=example.com; Path=/", "https://example.com/");
jar.add("api=2; Domain=example.com; Path=/api", "https://example.com/api");

let cookies = jar
    .matches("https://www.example.com/api/users")
    .collect::<Vec<_>>();
assert_eq!(cookies.len(), 2);
assert!(cookies.iter().any(|cookie| cookie.name() == "root"));
assert!(cookies.iter().any(|cookie| cookie.name() == "api"));

pub fn add<C, U>(&self, cookie: C, uri: U)

where C: IntoCookie, U: IntoUri,

Stores a cookie received from a URI.

The URI supplies the host-only domain and default path when those attributes are absent. Cookies with an invalid URI or an invalid or mismatched Domain are ignored. A non-positive Max-Age removes an existing cookie in the same scope, as required by the RFC 6265 storage model. A positive Max-Age is stored as an absolute deadline. Insecure origins cannot set Secure cookies or overlay an existing Secure cookie, following the RFC 6265bis storage model.

Example

use wreq::cookie::Jar;
use cookie::CookieBuilder;
let jar = Jar::default();
let cookie = CookieBuilder::new("foo", "bar")
    .domain("example.com")
    .path("/")
    .build();
jar.add(cookie, "http://example.com");

pub fn remove<C, U>(&self, cookie: C, uri: U)

where C: Into<RawCookie<'static>>, U: IntoUri,

Removes a cookie from an exact URI scope.

The URI host and path identify the stored scope. Both host-only and Domain cookies with the same name in that scope are removed; other domains and paths are left unchanged.

Example

use wreq::cookie::Jar;
let jar = Jar::default();
jar.add("foo=bar; Path=/foo; Domain=example.com", "http://example.com/foo");
assert!(jar.get("foo", "http://example.com/foo").is_some());
jar.remove("foo", "http://example.com/foo");
assert!(jar.get("foo", "http://example.com/foo").is_none());

pub fn clear(&self)

Removes every cookie from the jar, leaving it empty.

Example

use wreq::cookie::Jar;
let jar = Jar::default();
jar.add("foo=bar; Domain=example.com", "http://example.com");
assert_eq!(jar.get_all().count(), 1);
jar.clear();
assert_eq!(jar.get_all().count(), 0);

Trait Implementations

impl CookieStore for Jar

fn set_cookies( &self, cookie_headers: &mut dyn Iterator<Item = &HeaderValue>, uri: &Uri, )

Stores Set-Cookie field values received from uri.

fn cookies(&self, uri: &Uri, version: Version) -> Cookies

Serializes the cookies that apply to uri for the requested HTTP version.

impl Debug for Jar

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Jar

fn default() -> Jar

Returns the “default value” for a type.