Cookie Library

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"

Create a Cookie

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

Parse a Cookie

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());

Parse a Cookie Request Header

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());

Generate Set-Cookie Response Headers

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()
}