Struct cookie::CookieBuilder

source ·

pub struct CookieBuilder<'c> {
    cookie: Cookie<'c>,
}

Expand description

Structure that follows the builder pattern for building Cookie structs.

To construct a cookie:

Call Cookie::build() to start building.
Use any of the builder methods to set fields in the cookie.

The resulting CookieBuilder can be passed directly into methods expecting a T: Into<Cookie>:

use cookie::{Cookie, CookieJar};

let mut jar = CookieJar::new();
jar.add(Cookie::build(("key", "value")).secure(true).path("/"));
jar.remove(Cookie::build("key").path("/"));

You can also call CookieBuilder::build() directly to get a Cookie:

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

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

Fields§

§cookie: Cookie<'c>

The cookie being built.

Implementations§

source §

impl<'c> CookieBuilder<'c>

source

pub fn new<N, V>(name: N, value: V) -> Self
where N: Into<Cow<'c, str>>, V: Into<Cow<'c, str>>,

Creates a new CookieBuilder instance from the given name and value.

This method is typically called indirectly via Cookie::build().

§Example

use cookie::Cookie;

// These two snippets are equivalent:

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

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

source

pub fn expires<E: Into<Expiration>>(self, when: E) -> Self

Sets the expires field in the cookie being built.

See Expiration for conversions.

§Example

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

let c = Cookie::build(("foo", "bar")).expires(OffsetDateTime::now_utc());
assert!(c.inner().expires().is_some());

let c = Cookie::build(("foo", "bar")).expires(None);
assert_eq!(c.inner().expires(), Some(Expiration::Session));

source

pub fn max_age(self, value: Duration) -> Self

Sets the max_age field in the cookie being built.

§Example

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

let c = Cookie::build(("foo", "bar")).max_age(Duration::minutes(30));
assert_eq!(c.inner().max_age(), Some(Duration::seconds(30 * 60)));

source

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

Sets the domain field in the cookie being built.

§Example

use cookie::Cookie;

let c = Cookie::build(("foo", "bar")).domain("www.rust-lang.org");
assert_eq!(c.inner().domain(), Some("www.rust-lang.org"));

source

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

Sets the path field in the cookie being built.

§Example

use cookie::Cookie;

let c = Cookie::build(("foo", "bar")).path("/");
assert_eq!(c.inner().path(), Some("/"));

source

pub fn secure(self, value: bool) -> Self

Sets the secure field in the cookie being built.

§Example

use cookie::Cookie;

let c = Cookie::build(("foo", "bar")).secure(true);
assert_eq!(c.inner().secure(), Some(true));

source

pub fn http_only(self, value: bool) -> Self

Sets the http_only field in the cookie being built.

§Example

use cookie::Cookie;

let c = Cookie::build(("foo", "bar")).http_only(true);
assert_eq!(c.inner().http_only(), Some(true));

source

pub fn same_site(self, value: SameSite) -> Self

Sets the same_site field in the cookie being built.

§Example

use cookie::{Cookie, SameSite};

let c = Cookie::build(("foo", "bar")).same_site(SameSite::Strict);
assert_eq!(c.inner().same_site(), Some(SameSite::Strict));

source

pub fn partitioned(self, value: bool) -> Self

Sets the partitioned field in the cookie being built.

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 cookie::Cookie;

let c = Cookie::build(("foo", "bar")).partitioned(true);
assert_eq!(c.inner().partitioned(), Some(true));
assert!(c.to_string().contains("Secure"));

source

pub fn permanent(self) -> Self

Makes the cookie being built ‘permanent’ by extending its expiration and max age 20 years into the future. See also Cookie::make_permanent().

§Example

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

let c = Cookie::build(("foo", "bar")).permanent();
assert_eq!(c.inner().max_age(), Some(Duration::days(365 * 20)));

source

pub fn removal(self) -> Self

Makes the cookie being built ‘removal’ by clearing its value, setting a max-age of 0, and setting an expiration date far in the past. See also Cookie::make_removal().

§Example

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

let mut builder = Cookie::build("foo").removal();
assert_eq!(builder.inner().max_age(), Some(Duration::ZERO));

let mut builder = Cookie::build(("name", "value")).removal();
assert_eq!(builder.inner().value(), "");
assert_eq!(builder.inner().max_age(), Some(Duration::ZERO));

source

pub fn inner(&self) -> &Cookie<'c>

Returns a borrow to the cookie currently being built.

§Example

use cookie::Cookie;

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

assert_eq!(builder.inner().name_value(), ("name", "value"));
assert_eq!(builder.inner().domain(), Some("www.rust-lang.org"));
assert_eq!(builder.inner().path(), Some("/"));
assert_eq!(builder.inner().http_only(), Some(true));
assert_eq!(builder.inner().secure(), None);

source

pub fn inner_mut(&mut self) -> &mut Cookie<'c>

Returns a mutable borrow to the cookie currently being built.

§Example

use cookie::Cookie;

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

assert_eq!(builder.inner().http_only(), Some(true));

builder.inner_mut().set_http_only(false);
assert_eq!(builder.inner().http_only(), Some(false));

source

pub fn build(self) -> Cookie<'c>

Finishes building and returns the built Cookie.

This method usually does not need to be called directly. This is because CookieBuilder implements Into<Cookie>, so a value of CookieBuilder can be passed directly into any method that expects a C: Into<Cookie>.

§Example

use cookie::{Cookie, CookieJar};

// We don't usually need to use `build()`. Inspect with `inner()`, and
// pass the builder directly into methods expecting `T: Into<Cookie>`.
let c = Cookie::build(("foo", "bar"))
    .domain("crates.io")
    .path("/");

// Use `inner()` and inspect the cookie.
assert_eq!(c.inner().name_value(), ("foo", "bar"));
assert_eq!(c.inner().domain(), Some("crates.io"));
assert_eq!(c.inner().path(), Some("/"));

// Add the cookie to a jar. Note the automatic conversion.
CookieJar::new().add(c);

// We could use `build()` to get a `Cookie` when needed.
let c = Cookie::build(("foo", "bar"))
    .domain("crates.io")
    .path("/")
    .build();

// Inspect the built cookie.
assert_eq!(c.name_value(), ("foo", "bar"));
assert_eq!(c.domain(), Some("crates.io"));
assert_eq!(c.path(), Some("/"));

// Add the cookie to a jar.
CookieJar::new().add(c);

source

pub fn finish(self) -> Cookie<'c>

👎Deprecated since 0.18.0: CookieBuilder can be passed in to methods expecting a Cookie; for other cases, use CookieBuilder::build()

Deprecated. Convert self into a Cookie.

Instead of using this method, pass a CookieBuilder directly into methods expecting a T: Into<Cookie>. For other cases, use CookieBuilder::build().