Skip to main content

Crate cookie_rs

Crate cookie_rs 

Source
Expand description

cercis-preview

cookie-rs is a flexible library for working with HTTP cookies. It allows you to create, parse, and manage cookies.

§Features

  • Create cookies with various attributes (e.g., Domain, Path, Secure, HttpOnly).
  • Parse cookies from HTTP headers in lenient or strict mode.
  • Manage cookies using CookieJar, which tracks additions and removals.
  • Support for SameSite attribute.
  • Automatic percent-encoding and decoding of cookie values (enabled by default).
  • Errors are handled gracefully through ParseError.

§Quick Start

To use this library, add it to your dependencies:

[dependencies]
...
+ cookie-rs = "0.5.0"
use cookie_rs::prelude::*;

let cookie = Cookie::builder("session", "abc123")
    .domain("example.com")
    .path("/")
    .secure(true)
    .http_only(true)
    .same_site(SameSite::Lax)
    .build();

println!("{}", cookie.to_string());

Output:

session=abc123; Domain=example.com; HttpOnly; Path=/; SameSite=Lax; Secure
use cookie_rs::Cookie;

let cookie = Cookie::parse("session=abc123; Secure; HttpOnly").unwrap();
assert_eq!(cookie.name(), "session");
assert_eq!(cookie.value(), "abc123");
assert_eq!(cookie.secure(), Some(true));
assert_eq!(cookie.http_only(), Some(true));

§Percent-Encoding

Cookie values are automatically percent-encoded when serialized and decoded when parsed. This behavior is enabled by default and can be disabled via Cargo features.

use cookie_rs::prelude::*;

let cookie = Cookie::new("data", "hello world");
assert_eq!(cookie.to_string(), "data=hello%20world");

let parsed = Cookie::parse("data=hello%20world").unwrap();
assert_eq!(parsed.value(), "hello world");

To disable encoding:

[dependencies]
cookie-rs = { version = "0.5.0", default-features = false }

§Manage Cookies with CookieJar

use cookie_rs::{Cookie, CookieJar};

let mut jar = CookieJar::default();

jar.add(Cookie::new("user", "john"));

if let Some(cookie) = jar.get("user") {
    println!("Found cookie: {}={}.", cookie.name(), cookie.value());
}

jar.remove("user");
assert!(jar.get("user").is_none());

CookieJar::parse accepts the Cookie request header format (name=value pairs separated by ; ).

use cookie_rs::CookieJar;

let jar = CookieJar::parse("name1=value1; name2=value2").unwrap();
assert!(jar.get("name1").is_some());
assert!(jar.get("name2").is_some());
use cookie_rs::{Cookie, CookieJar};

let mut jar = CookieJar::default();
jar.add(Cookie::new("name1", "value1"));
jar.add(Cookie::new("name2", "value2"));

for header in jar.as_header_values() {
    println!("Set-Cookie: {}", header);
}

Output:

Set-Cookie: name1=value1
Set-Cookie: name2=value2

§Owned Cookies

To detach a cookie from the lifetime of the source string use into_owned:

use cookie_rs::prelude::*;

fn parse_session(header: &str) -> Cookie<'static> {
    Cookie::parse(header).unwrap().into_owned()
}

Re-exports§

pub use crate::cookie::Cookie;
pub use crate::cookie::CookieBuilder;
pub use crate::jar::CookieJar;

Modules§

cookie
error
jar
prelude