Struct pavex::cookie::ResponseCookies

source ·
pub struct ResponseCookies(/* private fields */);
Expand description

A collection of ResponseCookies to be attached to an HTTP response using the Set-Cookie header.

A set’s life begins via ResponseCookies::new() and calls to ResponseCookies::insert():

use pavex::cookie::{ResponseCookie, ResponseCookies};

let mut set = ResponseCookies::new();
set.insert(("name", "value"));
set.insert(("second", "another"));
set.insert(ResponseCookie::new("third", "again").set_path("/"));

If you want to tell the client to remove a cookie, you need to insert a RemovalCookie into the set. Note that any T: Into<ResponseCookie> can be passed into these methods.

use pavex::cookie::{ResponseCookie, ResponseCookies, RemovalCookie, ResponseCookieId};

let mut set = ResponseCookies::new();
let removal = RemovalCookie::new("name").set_path("/");
// This will tell the client to remove the cookie with name "name"
// and path "/".
set.insert(removal);

// If you insert a cookie with the same name and path, it will replace
// the removal cookie.
let cookie = ResponseCookie::new("name", "value").set_path("/");
set.insert(cookie);

let retrieved = set.get(ResponseCookieId::new("name").set_path("/")).unwrap();
assert_eq!(retrieved.value(), "value");

If you want to remove a cookie from the set without telling the client to remove it, you can use ResponseCookies::discard().

Cookies can be retrieved with ResponseCookies::get(). Check the method’s documentation for more information.

Implementations§

source§

impl ResponseCookies

source

pub fn new() -> ResponseCookies

Creates an empty cookie set.

§Example
use pavex::cookie::ResponseCookies;

let set = ResponseCookies::new();
assert_eq!(set.iter().count(), 0);
source

pub fn get<'map, 'key, Key>( &'map self, id: Key, ) -> Option<&'map ResponseCookie<'static>>
where Key: Into<ResponseCookieId<'key>>,

Returns a reference to the ResponseCookie inside this set with the specified id.

§Via id
use pavex::cookie::{ResponseCookies, ResponseCookie, ResponseCookieId};

let mut set = ResponseCookies::new();
assert!(set.get("name").is_none());

let cookie = ResponseCookie::new("name", "value").set_path("/");
set.insert(cookie);

// By specifying just the name, the domain and path are assumed to be None.
let id = ResponseCookieId::new("name");
// `name` has a path of `/`, so it doesn't match the empty path.
assert!(set.get(id).is_none());

let id = ResponseCookieId::new("name").set_path("/");
// You need to specify a matching path to get the cookie we inserted above.
assert_eq!(set.get(id).map(|c| c.value()), Some("value"));
§Via name
use pavex::cookie::{ResponseCookies, ResponseCookie, ResponseCookieId};

let mut set = ResponseCookies::new();
assert!(set.get("name").is_none());

let cookie = ResponseCookie::new("name", "value");
set.insert(cookie);

// By specifying just the name, the domain and path are assumed to be None.
assert_eq!(set.get("name").map(|c| c.value()), Some("value"));
source

pub fn insert<C>(&mut self, cookie: C) -> Option<ResponseCookie<'static>>
where C: Into<ResponseCookie<'static>>,

Inserts cookie into this set. If a cookie with the same ResponseCookieId already exists, it is replaced with cookie and the old cookie is returned.

§Example
use pavex::cookie::{ResponseCookies, ResponseCookie, ResponseCookieId};

let mut set = ResponseCookies::new();
set.insert(("name", "value"));
set.insert(("second", "two"));
// Replaces the "second" cookie with a new one.
assert!(set.insert(("second", "three")).is_some());

assert_eq!(set.get("name").map(|c| c.value()), Some("value"));
assert_eq!(set.get("second").map(|c| c.value()), Some("three"));
assert_eq!(set.iter().count(), 2);

// If we insert another cookie with name "second", but different domain and path,
// it won't replace the existing one.
let cookie = ResponseCookie::new("second", "four").set_domain("rust-lang.org");
set.insert(cookie);

assert_eq!(set.get("second").map(|c| c.value()), Some("three"));
let id = ResponseCookieId::new("second").set_domain("rust-lang.org");
assert_eq!(set.get(id).map(|c| c.value()), Some("four"));
assert_eq!(set.iter().count(), 3);
source

pub fn discard<'map, 'key, Key>(&'map mut self, id: Key)
where Key: Into<ResponseCookieId<'key>>,

Discard cookie from this set.

discard does not instruct the client to remove the cookie. You need to insert a RemovalCookie into ResponseCookies to do that.

§Example
use pavex::cookie::{ResponseCookies, ResponseCookie};

let mut set = ResponseCookies::new();
set.insert(("second", "two"));
set.discard("second");

assert!(set.get("second").is_none());
assert_eq!(set.iter().count(), 0);
§Example with path and domain

A cookie is identified by its name, domain, and path. If you want to discard a cookie with a non-empty domain and/or path, you need to specify them.

use pavex::cookie::{ResponseCookies, ResponseCookie, ResponseCookieId};

let mut set = ResponseCookies::new();
let cookie = ResponseCookie::new("name", "value").set_domain("rust-lang.org").set_path("/");
let id = cookie.id();
set.insert((cookie));

// This won't discard the cookie because the path and the domain don't match.
set.discard("second");
assert_eq!(set.iter().count(), 1);
assert!(set.get(id).is_some());

// This will discard the cookie because the name, the path and the domain match.
let id = ResponseCookieId::new("name").set_domain("rust-lang.org").set_path("/");
set.discard(id);
assert_eq!(set.iter().count(), 0);
source

pub fn iter(&self) -> ResponseCookiesIter<'_>

Returns an iterator over all the cookies present in this set.

§Example
use pavex::cookie::{ResponseCookies, ResponseCookie};

let mut set = ResponseCookies::new();

set.insert(("name", "value"));
set.insert(("second", "two"));
set.insert(("new", "third"));
set.insert(("another", "fourth"));
set.insert(("yac", "fifth"));

set.discard("name");
set.discard("another");

// There are three cookies in the set: "second", "new", and "yac".
for cookie in set.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 set")
    }
}
source

pub fn header_values<'a>( self, processor: &'a Processor, ) -> impl Iterator<Item = String> + 'a

Returns the values that should be sent to the client as Set-Cookie headers.

Trait Implementations§

source§

impl Clone for ResponseCookies

source§

fn clone(&self) -> ResponseCookies

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
source§

impl Debug for ResponseCookies

source§

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

Formats the value using the given formatter. Read more
source§

impl Default for ResponseCookies

source§

fn default() -> ResponseCookies

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

Auto Trait Implementations§

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, 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