Struct biscotti::ResponseCookie

pub struct ResponseCookie<'c> { /* private fields */ }

A cookie set by a server in an HTTP response using the Set-Cookie header.

Constructing a ResponseCookie

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

use biscotti::ResponseCookie;

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

Building a ResponseCookie

To construct more elaborate cookies, use ResponseCookie’s set_* methods.

use biscotti::ResponseCookie;

let cookie = ResponseCookie::new("name", "value")
    .set_domain("www.rust-lang.org")
    .set_path("/")
    .set_secure(true)
    .set_http_only(true);

Implementations

impl<'c> ResponseCookie<'c>

pub fn new<N, V>(name: N, value: V) -> Self

where N: Into<Cow<'c, str>>, V: Into<Cow<'c, str>>,

Creates a new ResponseCookie with the given name and value.

Example

use biscotti::ResponseCookie;

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

// This is equivalent to `from` with a `(name, value)` tuple:
let cookie = ResponseCookie::from(("name", "value"));
assert_eq!(cookie.name_value(), ("name", "value"));

pub fn into_owned(self) -> ResponseCookie<'static>

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

Example

use biscotti::ResponseCookie;

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

pub fn name(&self) -> &str

Returns the name of self.

Example

use biscotti::ResponseCookie;

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

pub fn value(&self) -> &str

Returns the value of self.

Does not strip surrounding quotes. See ResponseCookie::value_trimmed() for a version that does.

Example

use biscotti::ResponseCookie;

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

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

pub fn value_trimmed(&self) -> &str

Returns the value of self with surrounding double-quotes trimmed.

This is not the value of the cookie (that is ResponseCookie::value()). Instead, this is the value with a surrounding pair of double-quotes, if any, trimmed away. Quotes are only trimmed when they form a pair and never otherwise. The trimmed value is never used for other operations, such as equality checking, on self.

Example

use biscotti::ResponseCookie;
let c0 = ResponseCookie::new("name", "value");
assert_eq!(c0.value_trimmed(), "value");

let c = ResponseCookie::new("name", "\"value\"");
assert_eq!(c.value_trimmed(), "value");
assert!(c != c0);

let c = ResponseCookie::new("name", "\"value");
assert_eq!(c.value(), "\"value");
assert_eq!(c.value_trimmed(), "\"value");
assert!(c != c0);

let c = ResponseCookie::new("name", "\"value\"\"");
assert_eq!(c.value(), "\"value\"\"");
assert_eq!(c.value_trimmed(), "value\"");
assert!(c != c0);

pub fn name_value(&self) -> (&str, &str)

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

Example

use biscotti::ResponseCookie;

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

pub fn name_value_trimmed(&self) -> (&str, &str)

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

Example

use biscotti::ResponseCookie;

let c = ResponseCookie::new("name", "\"value\"");
assert_eq!(c.name_value_trimmed(), ("name", "value"));

pub fn http_only(&self) -> Option<bool>

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 biscotti::ResponseCookie;

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

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

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

pub fn secure(&self) -> Option<bool>

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 biscotti::ResponseCookie;

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

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

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

pub fn same_site(&self) -> Option<SameSite>

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

Example

use biscotti::{ResponseCookie, SameSite};

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

c = c.set_same_site(SameSite::Lax);
assert_eq!(c.same_site(), Some(SameSite::Lax));

c = c.set_same_site(None);
assert_eq!(c.same_site(), None);

pub fn partitioned(&self) -> Option<bool>

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

Note: This cookie attribute is experimental! Its meaning and definition are not standardized and therefore subject to change.

Example

use biscotti::ResponseCookie;

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

// An explicitly set "false" value.
c = c.set_partitioned(false);
assert_eq!(c.partitioned(), Some(false));

// An explicitly set "true" value.
c = c.set_partitioned(true);
assert_eq!(c.partitioned(), Some(true));

pub fn max_age(&self) -> Option<Duration>

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

Example

use biscotti::{ResponseCookie, time::Duration};

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

c = c.set_max_age(Duration::hours(1));
assert_eq!(c.max_age().map(|age| age.whole_hours()), Some(1));

pub fn path(&self) -> Option<&str>

Returns the Path of the cookie if one was specified.

Example

use biscotti::ResponseCookie;

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

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

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

pub fn domain(&self) -> Option<&str>

Returns the Domain of the cookie if one was specified.

This does not consider whether the Domain is valid; validation is left to higher-level libraries, as needed. However, if the Domain starts with a leading ., the leading . is stripped.

Example

use biscotti::ResponseCookie;

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

c = c.set_domain("crates.io");
assert_eq!(c.domain(), Some("crates.io"));

c = c.set_domain(".crates.io");
assert_eq!(c.domain(), Some("crates.io"));

// Note that `..crates.io` is not a valid domain.
c = c.set_domain("..crates.io");
assert_eq!(c.domain(), Some(".crates.io"));

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

pub fn expires(&self) -> Option<Expiration>

Returns the Expiration of the cookie if one was specified.

Example

use biscotti::{ResponseCookie, Expiration};
use time::{OffsetDateTime, macros::{date, time}};

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

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

let expire_time = OffsetDateTime::new_utc(date!(2017-10-21), time!(07:28:00));
c = c.set_expires(Some(expire_time));
assert_eq!(c.expires().and_then(|e| e.datetime()).map(|t| t.year()), Some(2017));

pub fn expires_datetime(&self) -> Option<OffsetDateTime>

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

It returns None if the cookie is a session cookie or if the expiration was not specified.

Example

use biscotti::{Expiration, ResponseCookie};
use time::{OffsetDateTime, macros::{date, time}};

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

// Here, `cookie.expires()` returns `Some(Expiration::Session)`.
c = c.set_expires(Expiration::Session);
assert_eq!(c.expires_datetime(), None);

let expire_time = OffsetDateTime::new_utc(date!(2017-10-21), time!(07:28:00));
c = c.set_expires(Some(expire_time));
assert_eq!(c.expires_datetime().map(|t| t.year()), Some(2017));

pub fn set_name<N: Into<Cow<'c, str>>>(self, name: N) -> Self

Sets the name of self to name.

Example

use biscotti::ResponseCookie;

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

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

pub fn set_value<V: Into<Cow<'c, str>>>(self, value: V) -> Self

Sets the value of self to value.

Example

use biscotti::ResponseCookie;

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

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

pub fn set_http_only<T: Into<Option<bool>>>(self, value: T) -> Self

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

Example

use biscotti::ResponseCookie;

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

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

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

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

pub fn set_secure<T: Into<Option<bool>>>(self, value: T) -> Self

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

Example

use biscotti::ResponseCookie;

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

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

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

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

pub fn set_same_site<T: Into<Option<SameSite>>>(self, value: T) -> Self

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

Example

use biscotti::{ResponseCookie, SameSite};

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

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

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

Example: SameSite::None

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 ResponseCookie::set_secure() or the equivalent builder method.

use biscotti::{ResponseCookie, SameSite};

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

c = 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 = c.set_secure(false);
assert_eq!(c.to_string(), "name=value; SameSite=None");

pub fn set_partitioned<T: Into<Option<bool>>>(self, value: T) -> Self

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

Note: Partitioned cookies require the Secure attribute to be set. As such, Partitioned cookies are always rendered with the Secure attribute, irrespective of the Secure attribute’s setting.

Note: This cookie attribute is an HTTP draft! Its meaning and definition are not standardized and therefore subject to change.

Example

use biscotti::ResponseCookie;

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

c = c.set_partitioned(true);
assert_eq!(c.partitioned(), Some(true));
assert!(c.to_string().contains("Secure"));

c = c.set_partitioned(false);
assert_eq!(c.partitioned(), Some(false));
assert!(!c.to_string().contains("Secure"));

c = c.set_partitioned(None);
assert_eq!(c.partitioned(), None);
assert!(!c.to_string().contains("Secure"));

pub fn set_max_age<D: Into<Option<Duration>>>(self, value: D) -> Self

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

Example

use biscotti::ResponseCookie;
use biscotti::time::Duration;

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

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

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

pub fn set_path<P: Into<Cow<'c, str>>>(self, path: P) -> Self

Sets the path of self to path.

Example

use biscotti::ResponseCookie;

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

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

pub fn unset_path(self) -> Self

Unsets the path of self.

Example

use biscotti::ResponseCookie;

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

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

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

pub fn set_domain<D: Into<Cow<'c, str>>>(self, domain: D) -> Self

Sets the domain of self to domain.

Example

use biscotti::ResponseCookie;

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

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

pub fn unset_domain(self) -> Self

Unsets the domain of self.

Example

use biscotti::ResponseCookie;

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

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

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

pub fn set_expires<T: Into<Expiration>>(self, time: T) -> Self

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

Example

use biscotti::{ResponseCookie, Expiration};
use biscotti::time::{Duration, OffsetDateTime};

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

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

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

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

pub fn unset_expires(self) -> Self

Unsets the expires of self.

Example

use biscotti::{ResponseCookie, Expiration};

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

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

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

pub fn make_permanent(self) -> Self

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

Example

use biscotti::ResponseCookie;
use biscotti::time::Duration;

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

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

pub fn into_removal(self) -> RemovalCookie<'c>

Make self a “removal” cookie by clearing its value and setting an expiration date far in the past.

Example

use biscotti::ResponseCookie;
use biscotti::time::{Duration, OffsetDateTime};

let c = ResponseCookie::new("foo", "bar");
let removal = c.into_removal();

// You can convert a `RemovalCookie` back into a "raw" `ResponseCookie`
// to inspect its properties.
let raw: ResponseCookie = removal.into();
assert_eq!(raw.value(), "");
let expiration = raw.expires_datetime().unwrap();
assert!(expiration < OffsetDateTime::now_utc());

pub fn id(&self) -> ResponseCookieId<'c>

Returns a ResponseCookieId that can be used to identify self in a collection of response cookies.

It takes into account the name, domain, and path of self.

Trait Implementations

impl<'a> AsMut<ResponseCookie<'a>> for ResponseCookie<'a>

fn as_mut(&mut self) -> &mut ResponseCookie<'a>

Converts this type into a mutable reference of the (usually inferred) input type.

impl<'a> AsRef<ResponseCookie<'a>> for ResponseCookie<'a>

fn as_ref(&self) -> &ResponseCookie<'a>

Converts this type into a shared reference of the (usually inferred) input type.

impl<'c> Clone for ResponseCookie<'c>

fn clone(&self) -> ResponseCookie<'c>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'c> Debug for ResponseCookie<'c>

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

Formats the value using the given formatter.

impl<'c> Display for ResponseCookie<'c>

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

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

Example

use biscotti::ResponseCookie;

let cookie = ResponseCookie::new("foo", "bar").set_path("/");
assert_eq!(cookie.to_string(), "foo=bar; Path=/");

impl<'a, N, V> From<(N, V)> for ResponseCookie<'a>

where N: Into<Cow<'a, str>>, V: Into<Cow<'a, str>>,

fn from((name, value): (N, V)) -> Self

Converts to this type from the input type.

impl<'c> From<RemovalCookie<'c>> for ResponseCookie<'c>

fn from(value: RemovalCookie<'c>) -> Self

Converts to this type from the input type.

impl<'a, 'b> PartialEq<ResponseCookie<'b>> for ResponseCookie<'a>

fn eq(&self, other: &ResponseCookie<'b>) -> bool

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

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.