Struct axum_extra::extract::cookie::Cookie

source · [−]
pub struct Cookie<'c> { /* private fields */ }
Available on crate feature cookie only.
Expand description

Representation of an HTTP cookie.

To construct a cookie with only a name/value, use Cookie::new():

use cookie::Cookie;

let cookie = Cookie::new("name", "value");
assert_eq!(&cookie.to_string(), "name=value");

To construct more elaborate cookies, use Cookie::build() and CookieBuilder methods:

use cookie::Cookie;

let cookie = Cookie::build("name", "value")
    .domain("www.rust-lang.org")
    .path("/")
    .secure(true)
    .http_only(true)
    .finish();

Implementations

Creates a new Cookie with the given name and value.

Example
use cookie::Cookie;

let cookie = Cookie::new("name", "value");
assert_eq!(cookie.name_value(), ("name", "value"));

Creates a new Cookie with the given name and an empty value.

Example
use cookie::Cookie;

let cookie = Cookie::named("name");
assert_eq!(cookie.name(), "name");
assert!(cookie.value().is_empty());

Creates a new CookieBuilder instance from the given key and value strings.

Example
use cookie::Cookie;

let c = Cookie::build("foo", "bar").finish();
assert_eq!(c.name_value(), ("foo", "bar"));

Parses a Cookie from the given HTTP cookie header value string. Does not perform any percent-decoding.

Example
use cookie::Cookie;

let c = Cookie::parse("foo=bar%20baz; HttpOnly").unwrap();
assert_eq!(c.name_value(), ("foo", "bar%20baz"));
assert_eq!(c.http_only(), Some(true));
Available on crate feature percent-encode only.

Parses a Cookie from the given HTTP cookie header value string where the name and value fields are percent-encoded. Percent-decodes the name/value fields.

Example
use cookie::Cookie;

let c = Cookie::parse_encoded("foo=bar%20baz; HttpOnly").unwrap();
assert_eq!(c.name_value(), ("foo", "bar baz"));
assert_eq!(c.http_only(), Some(true));

Converts self into a Cookie with a static lifetime with as few allocations as possible.

Example
use cookie::Cookie;

let c = Cookie::new("a", "b");
let owned_cookie = c.into_owned();
assert_eq!(owned_cookie.name_value(), ("a", "b"));

Returns the name of self.

Example
use cookie::Cookie;

let c = Cookie::new("name", "value");
assert_eq!(c.name(), "name");

Returns the value of self.

Example
use cookie::Cookie;

let c = Cookie::new("name", "value");
assert_eq!(c.value(), "value");

Returns the name and value of self as a tuple of (name, value).

Example
use cookie::Cookie;

let c = Cookie::new("name", "value");
assert_eq!(c.name_value(), ("name", "value"));

Returns whether this cookie was marked HttpOnly or not. Returns Some(true) when the cookie was explicitly set (manually or parsed) as HttpOnly, Some(false) when http_only was manually set to false, and None otherwise.

Example
use cookie::Cookie;

let c = Cookie::parse("name=value; httponly").unwrap();
assert_eq!(c.http_only(), Some(true));

let mut c = Cookie::new("name", "value");
assert_eq!(c.http_only(), None);

let mut c = Cookie::new("name", "value");
assert_eq!(c.http_only(), None);

// An explicitly set "false" value.
c.set_http_only(false);
assert_eq!(c.http_only(), Some(false));

// An explicitly set "true" value.
c.set_http_only(true);
assert_eq!(c.http_only(), Some(true));

Returns whether this cookie was marked Secure or not. Returns Some(true) when the cookie was explicitly set (manually or parsed) as Secure, Some(false) when secure was manually set to false, and None otherwise.

Example
use cookie::Cookie;

let c = Cookie::parse("name=value; Secure").unwrap();
assert_eq!(c.secure(), Some(true));

let mut c = Cookie::parse("name=value").unwrap();
assert_eq!(c.secure(), None);

let mut c = Cookie::new("name", "value");
assert_eq!(c.secure(), None);

// An explicitly set "false" value.
c.set_secure(false);
assert_eq!(c.secure(), Some(false));

// An explicitly set "true" value.
c.set_secure(true);
assert_eq!(c.secure(), Some(true));

Returns the SameSite attribute of this cookie if one was specified.

Example
use cookie::{Cookie, SameSite};

let c = Cookie::parse("name=value; SameSite=Lax").unwrap();
assert_eq!(c.same_site(), Some(SameSite::Lax));

Returns the specified max-age of the cookie if one was specified.

Example
use cookie::Cookie;

let c = Cookie::parse("name=value").unwrap();
assert_eq!(c.max_age(), None);

let c = Cookie::parse("name=value; Max-Age=3600").unwrap();
assert_eq!(c.max_age().map(|age| age.whole_hours()), Some(1));

Returns the Path of the cookie if one was specified.

Example
use cookie::Cookie;

let c = Cookie::parse("name=value").unwrap();
assert_eq!(c.path(), None);

let c = Cookie::parse("name=value; Path=/").unwrap();
assert_eq!(c.path(), Some("/"));

let c = Cookie::parse("name=value; path=/sub").unwrap();
assert_eq!(c.path(), Some("/sub"));

Returns the Domain of the cookie if one was specified.

Example
use cookie::Cookie;

let c = Cookie::parse("name=value").unwrap();
assert_eq!(c.domain(), None);

let c = Cookie::parse("name=value; Domain=crates.io").unwrap();
assert_eq!(c.domain(), Some("crates.io"));

Returns the Expiration of the cookie if one was specified.

Example
use cookie::{Cookie, Expiration};

let c = Cookie::parse("name=value").unwrap();
assert_eq!(c.expires(), None);

// Here, `cookie.expires_datetime()` returns `None`.
let c = Cookie::build("name", "value").expires(None).finish();
assert_eq!(c.expires(), Some(Expiration::Session));

let expire_time = "Wed, 21 Oct 2017 07:28:00 GMT";
let cookie_str = format!("name=value; Expires={}", expire_time);
let c = Cookie::parse(cookie_str).unwrap();
assert_eq!(c.expires().and_then(|e| e.datetime()).map(|t| t.year()), Some(2017));

Returns the expiration date-time of the cookie if one was specified.

Example
use cookie::Cookie;

let c = Cookie::parse("name=value").unwrap();
assert_eq!(c.expires_datetime(), None);

// Here, `cookie.expires()` returns `Some`.
let c = Cookie::build("name", "value").expires(None).finish();
assert_eq!(c.expires_datetime(), None);

let expire_time = "Wed, 21 Oct 2017 07:28:00 GMT";
let cookie_str = format!("name=value; Expires={}", expire_time);
let c = Cookie::parse(cookie_str).unwrap();
assert_eq!(c.expires_datetime().map(|t| t.year()), Some(2017));

Sets the name of self to name.

Example
use cookie::Cookie;

let mut c = Cookie::new("name", "value");
assert_eq!(c.name(), "name");

c.set_name("foo");
assert_eq!(c.name(), "foo");

Sets the value of self to value.

Example
use cookie::Cookie;

let mut c = Cookie::new("name", "value");
assert_eq!(c.value(), "value");

c.set_value("bar");
assert_eq!(c.value(), "bar");

Sets the value of http_only in self to value. If value is None, the field is unset.

Example
use cookie::Cookie;

let mut c = Cookie::new("name", "value");
assert_eq!(c.http_only(), None);

c.set_http_only(true);
assert_eq!(c.http_only(), Some(true));

c.set_http_only(false);
assert_eq!(c.http_only(), Some(false));

c.set_http_only(None);
assert_eq!(c.http_only(), None);

Sets the value of secure in self to value. If value is None, the field is unset.

Example
use cookie::Cookie;

let mut c = Cookie::new("name", "value");
assert_eq!(c.secure(), None);

c.set_secure(true);
assert_eq!(c.secure(), Some(true));

c.set_secure(false);
assert_eq!(c.secure(), Some(false));

c.set_secure(None);
assert_eq!(c.secure(), None);

Sets the value of same_site in self to value. If value is None, the field is unset. If value is SameSite::None, the “Secure” flag will be set when the cookie is written out unless secure is explicitly set to false via Cookie::set_secure() or the equivalent builder method.

Example
use cookie::{Cookie, SameSite};

let mut c = Cookie::new("name", "value");
assert_eq!(c.same_site(), None);

c.set_same_site(SameSite::None);
assert_eq!(c.same_site(), Some(SameSite::None));
assert_eq!(c.to_string(), "name=value; SameSite=None; Secure");

c.set_secure(false);
assert_eq!(c.to_string(), "name=value; SameSite=None");

let mut c = Cookie::new("name", "value");
assert_eq!(c.same_site(), None);

c.set_same_site(SameSite::Strict);
assert_eq!(c.same_site(), Some(SameSite::Strict));
assert_eq!(c.to_string(), "name=value; SameSite=Strict");

c.set_same_site(None);
assert_eq!(c.same_site(), None);
assert_eq!(c.to_string(), "name=value");

Sets the value of max_age in self to value. If value is None, the field is unset.

Example
use cookie::Cookie;
use cookie::time::Duration;

let mut c = Cookie::new("name", "value");
assert_eq!(c.max_age(), None);

c.set_max_age(Duration::hours(10));
assert_eq!(c.max_age(), Some(Duration::hours(10)));

c.set_max_age(None);
assert!(c.max_age().is_none());

Sets the path of self to path.

Example
use cookie::Cookie;

let mut c = Cookie::new("name", "value");
assert_eq!(c.path(), None);

c.set_path("/");
assert_eq!(c.path(), Some("/"));

Unsets the path of self.

Example
use cookie::Cookie;

let mut c = Cookie::new("name", "value");
assert_eq!(c.path(), None);

c.set_path("/");
assert_eq!(c.path(), Some("/"));

c.unset_path();
assert_eq!(c.path(), None);

Sets the domain of self to domain.

Example
use cookie::Cookie;

let mut c = Cookie::new("name", "value");
assert_eq!(c.domain(), None);

c.set_domain("rust-lang.org");
assert_eq!(c.domain(), Some("rust-lang.org"));

Unsets the domain of self.

Example
use cookie::Cookie;

let mut c = Cookie::new("name", "value");
assert_eq!(c.domain(), None);

c.set_domain("rust-lang.org");
assert_eq!(c.domain(), Some("rust-lang.org"));

c.unset_domain();
assert_eq!(c.domain(), None);

Sets the expires field of self to time. If time is None, an expiration of Session is set.

Example
use cookie::{Cookie, Expiration};
use cookie::time::{Duration, OffsetDateTime};

let mut c = Cookie::new("name", "value");
assert_eq!(c.expires(), None);

let mut now = OffsetDateTime::now_utc();
now += Duration::weeks(52);

c.set_expires(now);
assert!(c.expires().is_some());

c.set_expires(None);
assert_eq!(c.expires(), Some(Expiration::Session));

Unsets the expires of self.

Example
use cookie::{Cookie, Expiration};

let mut c = Cookie::new("name", "value");
assert_eq!(c.expires(), None);

c.set_expires(None);
assert_eq!(c.expires(), Some(Expiration::Session));

c.unset_expires();
assert_eq!(c.expires(), None);

Makes self a “permanent” cookie by extending its expiration and max age 20 years into the future.

Example
use cookie::Cookie;
use cookie::time::Duration;

let mut c = Cookie::new("foo", "bar");
assert!(c.expires().is_none());
assert!(c.max_age().is_none());

c.make_permanent();
assert!(c.expires().is_some());
assert_eq!(c.max_age(), Some(Duration::days(365 * 20)));

Make self a “removal” cookie by clearing its value, setting a max-age of 0, and setting an expiration date far in the past.

Example
use cookie::Cookie;
use cookie::time::Duration;

let mut c = Cookie::new("foo", "bar");
c.make_permanent();
assert_eq!(c.max_age(), Some(Duration::days(365 * 20)));
assert_eq!(c.value(), "bar");

c.make_removal();
assert_eq!(c.value(), "");
assert_eq!(c.max_age(), Some(Duration::ZERO));

Returns the name of self as a string slice of the raw string self was originally parsed from. If self was not originally parsed from a raw string, returns None.

This method differs from Cookie::name() in that it returns a string with the same lifetime as the originally parsed string. This lifetime may outlive self. If a longer lifetime is not required, or you’re unsure if you need a longer lifetime, use Cookie::name().

Example
use cookie::Cookie;

let cookie_string = format!("{}={}", "foo", "bar");

// `c` will be dropped at the end of the scope, but `name` will live on
let name = {
    let c = Cookie::parse(cookie_string.as_str()).unwrap();
    c.name_raw()
};

assert_eq!(name, Some("foo"));

Returns the value of self as a string slice of the raw string self was originally parsed from. If self was not originally parsed from a raw string, returns None.

This method differs from Cookie::value() in that it returns a string with the same lifetime as the originally parsed string. This lifetime may outlive self. If a longer lifetime is not required, or you’re unsure if you need a longer lifetime, use Cookie::value().

Example
use cookie::Cookie;

let cookie_string = format!("{}={}", "foo", "bar");

// `c` will be dropped at the end of the scope, but `value` will live on
let value = {
    let c = Cookie::parse(cookie_string.as_str()).unwrap();
    c.value_raw()
};

assert_eq!(value, Some("bar"));

Returns the Path of self as a string slice of the raw string self was originally parsed from. If self was not originally parsed from a raw string, or if self doesn’t contain a Path, or if the Path has changed since parsing, returns None.

This method differs from Cookie::path() in that it returns a string with the same lifetime as the originally parsed string. This lifetime may outlive self. If a longer lifetime is not required, or you’re unsure if you need a longer lifetime, use Cookie::path().

Example
use cookie::Cookie;

let cookie_string = format!("{}={}; Path=/", "foo", "bar");

// `c` will be dropped at the end of the scope, but `path` will live on
let path = {
    let c = Cookie::parse(cookie_string.as_str()).unwrap();
    c.path_raw()
};

assert_eq!(path, Some("/"));

Returns the Domain of self as a string slice of the raw string self was originally parsed from. If self was not originally parsed from a raw string, or if self doesn’t contain a Domain, or if the Domain has changed since parsing, returns None.

This method differs from Cookie::domain() in that it returns a string with the same lifetime as the originally parsed string. This lifetime may outlive self struct. If a longer lifetime is not required, or you’re unsure if you need a longer lifetime, use Cookie::domain().

Example
use cookie::Cookie;

let cookie_string = format!("{}={}; Domain=crates.io", "foo", "bar");

//`c` will be dropped at the end of the scope, but `domain` will live on
let domain = {
    let c = Cookie::parse(cookie_string.as_str()).unwrap();
    c.domain_raw()
};

assert_eq!(domain, Some("crates.io"));
Available on crate feature percent-encode only.

Wraps self in an encoded Display: a cost-free wrapper around Cookie whose fmt::Display implementation percent-encodes the name and value of the wrapped Cookie.

The returned structure can be chained with Display::stripped() to display only the name and value.

Example
use cookie::Cookie;

let mut c = Cookie::build("my name", "this; value?").secure(true).finish();
assert_eq!(&c.encoded().to_string(), "my%20name=this%3B%20value%3F; Secure");
assert_eq!(&c.encoded().stripped().to_string(), "my%20name=this%3B%20value%3F");

Wraps self in a stripped Display]: a cost-free wrapper around Cookie whose fmt::Display implementation prints only the name and value of the wrapped Cookie.

The returned structure can be chained with Display::encoded() to encode the name and value.

Example
use cookie::Cookie;

let mut c = Cookie::build("key?", "value").secure(true).path("/").finish();
assert_eq!(&c.stripped().to_string(), "key?=value");
// Note: `encoded()` is only available when `percent-encode` is enabled.
assert_eq!(&c.stripped().encoded().to_string(), "key%3F=value");

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

Formats the cookie self as a Set-Cookie header value.

Does not percent-encode any values. To percent-encode, use Cookie::encoded().

Example
use cookie::Cookie;

let mut cookie = Cookie::build("foo", "bar")
    .path("/")
    .finish();

assert_eq!(&cookie.to_string(), "foo=bar; Path=/");

The associated error which can be returned from parsing.

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

This method tests for self and other values to be equal, and is used by ==. Read more

This method tests for !=.

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.

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more

Instruments this type with the current Span, returning an Instrumented wrapper. Read more

Calls U::from(self).

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

Should always be Self

The resulting type after obtaining ownership.

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

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

Converts the given value to a String. 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.

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more