#![cfg_attr(all(nightly, doc), feature(doc_cfg))]
#![doc(html_root_url = "https://docs.rs/cookie/0.15")]
#![deny(missing_docs)]
#[cfg(feature = "percent-encode")] extern crate percent_encoding;
extern crate time;
mod builder;
mod parse;
mod jar;
mod delta;
mod draft;
mod expiration;
#[cfg(any(feature = "private", feature = "signed"))] #[macro_use] mod secure;
#[cfg(any(feature = "private", feature = "signed"))] pub use secure::*;
use std::borrow::Cow;
use std::fmt;
use std::str::FromStr;
#[allow(unused_imports, deprecated)]
use std::ascii::AsciiExt;
#[cfg(feature = "percent-encode")]
use percent_encoding::{AsciiSet, percent_encode as encode};
use time::{Duration, OffsetDateTime, UtcOffset};
use crate::parse::parse_cookie;
pub use crate::parse::ParseError;
pub use crate::builder::CookieBuilder;
pub use crate::jar::{CookieJar, Delta, Iter};
pub use crate::draft::*;
pub use crate::expiration::*;
#[derive(Debug, Clone)]
enum CookieStr<'c> {
Indexed(usize, usize),
Concrete(Cow<'c, str>),
}
impl<'c> CookieStr<'c> {
fn to_str<'s>(&'s self, string: Option<&'s Cow<str>>) -> &'s str {
match *self {
CookieStr::Indexed(i, j) => {
let s = string.expect("`Some` base string must exist when \
converting indexed str to str! (This is a module invariant.)");
&s[i..j]
},
CookieStr::Concrete(ref cstr) => &*cstr,
}
}
#[allow(clippy::ptr_arg)]
fn to_raw_str<'s, 'b: 's>(&'s self, string: &'s Cow<'b, str>) -> Option<&'b str> {
match *self {
CookieStr::Indexed(i, j) => {
match *string {
Cow::Borrowed(s) => Some(&s[i..j]),
Cow::Owned(_) => None,
}
},
CookieStr::Concrete(_) => None,
}
}
fn into_owned(self) -> CookieStr<'static> {
use crate::CookieStr::*;
match self {
Indexed(a, b) => Indexed(a, b),
Concrete(Cow::Owned(c)) => Concrete(Cow::Owned(c)),
Concrete(Cow::Borrowed(c)) => Concrete(Cow::Owned(c.into())),
}
}
}
#[derive(Debug, Clone)]
pub struct Cookie<'c> {
cookie_string: Option<Cow<'c, str>>,
name: CookieStr<'c>,
value: CookieStr<'c>,
expires: Option<Expiration>,
max_age: Option<Duration>,
domain: Option<CookieStr<'c>>,
path: Option<CookieStr<'c>>,
secure: Option<bool>,
http_only: Option<bool>,
same_site: Option<SameSite>,
}
impl<'c> Cookie<'c> {
pub fn new<N, V>(name: N, value: V) -> Self
where N: Into<Cow<'c, str>>,
V: Into<Cow<'c, str>>
{
Cookie {
cookie_string: None,
name: CookieStr::Concrete(name.into()),
value: CookieStr::Concrete(value.into()),
expires: None,
max_age: None,
domain: None,
path: None,
secure: None,
http_only: None,
same_site: None,
}
}
pub fn named<N>(name: N) -> Cookie<'c>
where N: Into<Cow<'c, str>>
{
Cookie::new(name, "")
}
pub fn build<N, V>(name: N, value: V) -> CookieBuilder<'c>
where N: Into<Cow<'c, str>>,
V: Into<Cow<'c, str>>
{
CookieBuilder::new(name, value)
}
pub fn parse<S>(s: S) -> Result<Cookie<'c>, ParseError>
where S: Into<Cow<'c, str>>
{
parse_cookie(s, false)
}
#[cfg(feature = "percent-encode")]
#[cfg_attr(all(nightly, doc), doc(cfg(feature = "percent-encode")))]
pub fn parse_encoded<S>(s: S) -> Result<Cookie<'c>, ParseError>
where S: Into<Cow<'c, str>>
{
parse_cookie(s, true)
}
pub fn into_owned(self) -> Cookie<'static> {
Cookie {
cookie_string: self.cookie_string.map(|s| s.into_owned().into()),
name: self.name.into_owned(),
value: self.value.into_owned(),
expires: self.expires,
max_age: self.max_age,
domain: self.domain.map(|s| s.into_owned()),
path: self.path.map(|s| s.into_owned()),
secure: self.secure,
http_only: self.http_only,
same_site: self.same_site,
}
}
#[inline]
pub fn name(&self) -> &str {
self.name.to_str(self.cookie_string.as_ref())
}
#[inline]
pub fn value(&self) -> &str {
self.value.to_str(self.cookie_string.as_ref())
}
#[inline]
pub fn name_value(&self) -> (&str, &str) {
(self.name(), self.value())
}
#[inline]
pub fn http_only(&self) -> Option<bool> {
self.http_only
}
#[inline]
pub fn secure(&self) -> Option<bool> {
self.secure
}
#[inline]
pub fn same_site(&self) -> Option<SameSite> {
self.same_site
}
#[inline]
pub fn max_age(&self) -> Option<Duration> {
self.max_age
}
#[inline]
pub fn path(&self) -> Option<&str> {
match self.path {
Some(ref c) => Some(c.to_str(self.cookie_string.as_ref())),
None => None,
}
}
#[inline]
pub fn domain(&self) -> Option<&str> {
match self.domain {
Some(ref c) => Some(c.to_str(self.cookie_string.as_ref())),
None => None,
}
}
#[inline]
pub fn expires(&self) -> Option<Expiration> {
self.expires
}
#[inline]
pub fn expires_datetime(&self) -> Option<OffsetDateTime> {
self.expires.and_then(|e| e.datetime())
}
pub fn set_name<N: Into<Cow<'c, str>>>(&mut self, name: N) {
self.name = CookieStr::Concrete(name.into())
}
pub fn set_value<V: Into<Cow<'c, str>>>(&mut self, value: V) {
self.value = CookieStr::Concrete(value.into())
}
#[inline]
pub fn set_http_only<T: Into<Option<bool>>>(&mut self, value: T) {
self.http_only = value.into();
}
#[inline]
pub fn set_secure<T: Into<Option<bool>>>(&mut self, value: T) {
self.secure = value.into();
}
#[inline]
pub fn set_same_site<T: Into<Option<SameSite>>>(&mut self, value: T) {
self.same_site = value.into();
}
#[inline]
pub fn set_max_age<D: Into<Option<Duration>>>(&mut self, value: D) {
self.max_age = value.into();
}
pub fn set_path<P: Into<Cow<'c, str>>>(&mut self, path: P) {
self.path = Some(CookieStr::Concrete(path.into()));
}
pub fn unset_path(&mut self) {
self.path = None;
}
pub fn set_domain<D: Into<Cow<'c, str>>>(&mut self, domain: D) {
self.domain = Some(CookieStr::Concrete(domain.into()));
}
pub fn unset_domain(&mut self) {
self.domain = None;
}
pub fn set_expires<T: Into<Expiration>>(&mut self, time: T) {
use time::{date, time, offset};
static MAX_DATETIME: OffsetDateTime = date!(9999-12-31)
.with_time(time!(23:59:59.999_999))
.assume_utc()
.to_offset(offset!(UTC));
self.expires = Some(time.into()
.map(|time| std::cmp::min(time, MAX_DATETIME)));
}
pub fn unset_expires(&mut self) {
self.expires = None;
}
pub fn make_permanent(&mut self) {
let twenty_years = Duration::days(365 * 20);
self.set_max_age(twenty_years);
self.set_expires(OffsetDateTime::now_utc() + twenty_years);
}
pub fn make_removal(&mut self) {
self.set_value("");
self.set_max_age(Duration::seconds(0));
self.set_expires(OffsetDateTime::now_utc() - Duration::days(365));
}
fn fmt_parameters(&self, f: &mut fmt::Formatter) -> fmt::Result {
if let Some(true) = self.http_only() {
write!(f, "; HttpOnly")?;
}
if let Some(same_site) = self.same_site() {
write!(f, "; SameSite={}", same_site)?;
if same_site.is_none() && self.secure().is_none() {
write!(f, "; Secure")?;
}
}
if let Some(true) = self.secure() {
write!(f, "; Secure")?;
}
if let Some(path) = self.path() {
write!(f, "; Path={}", path)?;
}
if let Some(domain) = self.domain() {
write!(f, "; Domain={}", domain)?;
}
if let Some(max_age) = self.max_age() {
write!(f, "; Max-Age={}", max_age.whole_seconds())?;
}
if let Some(time) = self.expires_datetime() {
let time = time.to_offset(UtcOffset::UTC);
write!(f, "; Expires={}", time.format("%a, %d %b %Y %H:%M:%S GMT"))?;
}
Ok(())
}
#[inline]
pub fn name_raw(&self) -> Option<&'c str> {
self.cookie_string.as_ref()
.and_then(|s| self.name.to_raw_str(s))
}
#[inline]
pub fn value_raw(&self) -> Option<&'c str> {
self.cookie_string.as_ref()
.and_then(|s| self.value.to_raw_str(s))
}
#[inline]
pub fn path_raw(&self) -> Option<&'c str> {
match (self.path.as_ref(), self.cookie_string.as_ref()) {
(Some(path), Some(string)) => path.to_raw_str(string),
_ => None,
}
}
#[inline]
pub fn domain_raw(&self) -> Option<&'c str> {
match (self.domain.as_ref(), self.cookie_string.as_ref()) {
(Some(domain), Some(string)) => domain.to_raw_str(string),
_ => None,
}
}
#[cfg(feature = "percent-encode")]
#[cfg_attr(all(nightly, doc), doc(cfg(feature = "percent-encode")))]
#[inline(always)]
pub fn encoded<'a>(&'a self) -> Display<'a, 'c> {
Display::new_encoded(self)
}
#[cfg_attr(feature = "percent-encode", doc = r##"
// Note: `encoded()` is only available when `percent-encode` is enabled.
assert_eq!(&c.stripped().encoded().to_string(), "key%3F=value");
#"##)]
#[inline(always)]
pub fn stripped<'a>(&'a self) -> Display<'a, 'c> {
Display::new_stripped(self)
}
}
#[cfg(feature = "percent-encode")]
const FRAGMENT_ENCODE_SET: &AsciiSet = &percent_encoding::CONTROLS.add(b' ').add(b'"').add(b'<').add(b'>').add(b'`');
#[cfg(feature = "percent-encode")]
const PATH_ENCODE_SET: &AsciiSet = &FRAGMENT_ENCODE_SET.add(b'#').add(b'?').add(b'{').add(b'}');
#[cfg(feature = "percent-encode")]
const USERINFO_ENCODE_SET: &AsciiSet = &PATH_ENCODE_SET
.add(b'/')
.add(b':')
.add(b';')
.add(b'=')
.add(b'@')
.add(b'[')
.add(b'\\')
.add(b']')
.add(b'^')
.add(b'|')
.add(b'%');
#[cfg(feature = "percent-encode")]
const COOKIE_ENCODE_SET: &AsciiSet = &USERINFO_ENCODE_SET
.add(b'(')
.add(b')')
.add(b',');
#[cfg_attr(feature = "percent-encode", doc = r##"
// Note: `encoded()` is only available when `percent-encode` is enabled.
assert_eq!(&c.encoded().to_string(), "my%20name=this%3B%20value%25%3F; Secure");
assert_eq!(&c.stripped().encoded().to_string(), "my%20name=this%3B%20value%25%3F");
assert_eq!(&c.encoded().stripped().to_string(), "my%20name=this%3B%20value%25%3F");
"##)]
pub struct Display<'a, 'c: 'a> {
cookie: &'a Cookie<'c>,
#[cfg(feature = "percent-encode")]
encode: bool,
strip: bool,
}
impl<'a, 'c: 'a> fmt::Display for Display<'a, 'c> {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
#[cfg(feature = "percent-encode")] {
if self.encode {
let name = encode(self.cookie.name().as_bytes(), COOKIE_ENCODE_SET);
let value = encode(self.cookie.value().as_bytes(), COOKIE_ENCODE_SET);
write!(f, "{}={}", name, value)?;
} else {
write!(f, "{}={}", self.cookie.name(), self.cookie.value())?;
}
}
#[cfg(not(feature = "percent-encode"))] {
write!(f, "{}={}", self.cookie.name(), self.cookie.value())?;
}
match self.strip {
true => Ok(()),
false => self.cookie.fmt_parameters(f)
}
}
}
impl<'a, 'c> Display<'a, 'c> {
#[cfg(feature = "percent-encode")]
fn new_encoded(cookie: &'a Cookie<'c>) -> Self {
Display { cookie, strip: false, encode: true }
}
fn new_stripped(cookie: &'a Cookie<'c>) -> Self {
Display { cookie, strip: true, #[cfg(feature = "percent-encode")] encode: false }
}
#[inline]
#[cfg(feature = "percent-encode")]
#[cfg_attr(all(nightly, doc), doc(cfg(feature = "percent-encode")))]
pub fn encoded(mut self) -> Self {
self.encode = true;
self
}
#[inline]
pub fn stripped(mut self) -> Self {
self.strip = true;
self
}
}
impl<'c> fmt::Display for Cookie<'c> {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
write!(f, "{}={}", self.name(), self.value())?;
self.fmt_parameters(f)
}
}
impl FromStr for Cookie<'static> {
type Err = ParseError;
fn from_str(s: &str) -> Result<Cookie<'static>, ParseError> {
Cookie::parse(s).map(|c| c.into_owned())
}
}
impl<'a, 'b> PartialEq<Cookie<'b>> for Cookie<'a> {
fn eq(&self, other: &Cookie<'b>) -> bool {
let so_far_so_good = self.name() == other.name()
&& self.value() == other.value()
&& self.http_only() == other.http_only()
&& self.secure() == other.secure()
&& self.max_age() == other.max_age()
&& self.expires() == other.expires();
if !so_far_so_good {
return false;
}
match (self.path(), other.path()) {
(Some(a), Some(b)) if a.eq_ignore_ascii_case(b) => {}
(None, None) => {}
_ => return false,
};
match (self.domain(), other.domain()) {
(Some(a), Some(b)) if a.eq_ignore_ascii_case(b) => {}
(None, None) => {}
_ => return false,
};
true
}
}
#[cfg(test)]
mod tests {
use crate::{Cookie, SameSite};
use crate::parse::parse_gmt_date;
use crate::{time::Duration, OffsetDateTime};
#[test]
fn format() {
let cookie = Cookie::new("foo", "bar");
assert_eq!(&cookie.to_string(), "foo=bar");
let cookie = Cookie::build("foo", "bar")
.http_only(true).finish();
assert_eq!(&cookie.to_string(), "foo=bar; HttpOnly");
let cookie = Cookie::build("foo", "bar")
.max_age(Duration::seconds(10)).finish();
assert_eq!(&cookie.to_string(), "foo=bar; Max-Age=10");
let cookie = Cookie::build("foo", "bar")
.secure(true).finish();
assert_eq!(&cookie.to_string(), "foo=bar; Secure");
let cookie = Cookie::build("foo", "bar")
.path("/").finish();
assert_eq!(&cookie.to_string(), "foo=bar; Path=/");
let cookie = Cookie::build("foo", "bar")
.domain("www.rust-lang.org").finish();
assert_eq!(&cookie.to_string(), "foo=bar; Domain=www.rust-lang.org");
let time_str = "Wed, 21 Oct 2015 07:28:00 GMT";
let expires = parse_gmt_date(time_str, "%a, %d %b %Y %H:%M:%S GMT").unwrap();
let cookie = Cookie::build("foo", "bar")
.expires(expires).finish();
assert_eq!(&cookie.to_string(),
"foo=bar; Expires=Wed, 21 Oct 2015 07:28:00 GMT");
let cookie = Cookie::build("foo", "bar")
.same_site(SameSite::Strict).finish();
assert_eq!(&cookie.to_string(), "foo=bar; SameSite=Strict");
let cookie = Cookie::build("foo", "bar")
.same_site(SameSite::Lax).finish();
assert_eq!(&cookie.to_string(), "foo=bar; SameSite=Lax");
let mut cookie = Cookie::build("foo", "bar")
.same_site(SameSite::None).finish();
assert_eq!(&cookie.to_string(), "foo=bar; SameSite=None; Secure");
cookie.set_same_site(None);
assert_eq!(&cookie.to_string(), "foo=bar");
let mut cookie = Cookie::build("foo", "bar")
.same_site(SameSite::None)
.secure(false)
.finish();
assert_eq!(&cookie.to_string(), "foo=bar; SameSite=None");
cookie.set_secure(true);
assert_eq!(&cookie.to_string(), "foo=bar; SameSite=None; Secure");
}
#[test]
#[ignore]
fn format_date_wraps() {
let expires = OffsetDateTime::unix_epoch() + Duration::max_value();
let cookie = Cookie::build("foo", "bar")
.expires(expires).finish();
assert_eq!(&cookie.to_string(),
"foo=bar; Expires=Fri, 31 Dec 9999 23:59:59 GMT");
}
#[test]
fn cookie_string_long_lifetimes() {
let cookie_string = "bar=baz; Path=/subdir; HttpOnly; Domain=crates.io".to_owned();
let (name, value, path, domain) = {
let c = Cookie::parse(cookie_string.as_str()).unwrap();
(c.name_raw(), c.value_raw(), c.path_raw(), c.domain_raw())
};
assert_eq!(name, Some("bar"));
assert_eq!(value, Some("baz"));
assert_eq!(path, Some("/subdir"));
assert_eq!(domain, Some("crates.io"));
}
#[test]
fn owned_cookie_string() {
let cookie_string = "bar=baz; Path=/subdir; HttpOnly; Domain=crates.io".to_owned();
let (name, value, path, domain) = {
let c = Cookie::parse(cookie_string).unwrap();
(c.name_raw(), c.value_raw(), c.path_raw(), c.domain_raw())
};
assert_eq!(name, None);
assert_eq!(value, None);
assert_eq!(path, None);
assert_eq!(domain, None);
}
#[test]
fn owned_cookie_struct() {
let cookie_string = "bar=baz; Path=/subdir; HttpOnly; Domain=crates.io";
let (name, value, path, domain) = {
let c = Cookie::parse(cookie_string).unwrap().into_owned();
(c.name_raw(), c.value_raw(), c.path_raw(), c.domain_raw())
};
assert_eq!(name, None);
assert_eq!(value, None);
assert_eq!(path, None);
assert_eq!(domain, None);
}
#[test]
#[cfg(feature = "percent-encode")]
fn format_encoded() {
let cookie = Cookie::build("foo !%?=", "bar;;, a").finish();
let cookie_str = cookie.encoded().to_string();
assert_eq!(&cookie_str, "foo%20!%25%3F%3D=bar%3B%3B%2C%20a");
let cookie = Cookie::parse_encoded(cookie_str).unwrap();
assert_eq!(cookie.name_value(), ("foo !%?=", "bar;;, a"));
}
}