pavex::cookie

Struct ResponseCookie

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

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) -> ResponseCookie<'c>
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>(self, name: N) -> ResponseCookie<'c>
where N: Into<Cow<'c, str>>,

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>(self, value: V) -> ResponseCookie<'c>
where V: Into<Cow<'c, str>>,

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>(self, value: T) -> ResponseCookie<'c>
where T: Into<Option<bool>>,

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>(self, value: T) -> ResponseCookie<'c>
where T: Into<Option<bool>>,

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>(self, value: T) -> ResponseCookie<'c>
where T: Into<Option<SameSite>>,

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>(self, value: T) -> ResponseCookie<'c>
where T: Into<Option<bool>>,

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>(self, value: D) -> ResponseCookie<'c>
where D: Into<Option<Duration>>,

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>(self, path: P) -> ResponseCookie<'c>
where P: Into<Cow<'c, str>>,

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) -> ResponseCookie<'c>

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>(self, domain: D) -> ResponseCookie<'c>
where D: Into<Cow<'c, str>>,

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) -> ResponseCookie<'c>

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>(self, time: T) -> ResponseCookie<'c>
where T: Into<Expiration>,

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) -> ResponseCookie<'c>

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) -> ResponseCookie<'c>

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. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
§

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

§

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

Formats the value using the given formatter. Read more
§

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

§

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

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(_: (N, V)) -> ResponseCookie<'a>

Converts to this type from the input type.
§

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

§

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

Converts to this type from the input type.
§

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

§

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

Tests for self and other values to be equal, and is used by ==.
1.0.0 · source§

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

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

Auto Trait Implementations§

§

impl<'c> Freeze for ResponseCookie<'c>

§

impl<'c> RefUnwindSafe for ResponseCookie<'c>

§

impl<'c> Send for ResponseCookie<'c>

§

impl<'c> Sync for ResponseCookie<'c>

§

impl<'c> Unpin for ResponseCookie<'c>

§

impl<'c> UnwindSafe for ResponseCookie<'c>

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> CloneToUninit for T
where T: Clone,

source§

unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

§

impl<T> Instrument for T

§

fn instrument(self, span: Span) -> Instrumented<Self>

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

fn in_current_span(self) -> Instrumented<Self>

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

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

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

source§

impl<T> Same for T

source§

type Output = T

Should always be Self
source§

impl<T> ToOwned for T
where T: Clone,

source§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

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

fn clone_into(&self, target: &mut T)

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

impl<T> ToString for T
where T: Display + ?Sized,

source§

default fn to_string(&self) -> String

Converts the given value to a String. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

source§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

§

fn vzip(self) -> V

§

impl<T> WithSubscriber for T

§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

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

fn with_current_subscriber(self) -> WithDispatch<Self>

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