Struct CookieStore 

pub struct CookieStore { /* private fields */ }

A client-side cookie store: RFC 6265 §5.3 storage, §5.4 retrieval, §6.1 capacity limits — the state a cookie-aware HTTP client keeps between a response’s Set-Cookie and the next request’s Cookie:.

The store is a plain value — &mut self writes, &self reads — with no lock of its own; share it the standard way:

use std::sync::RwLock;

use kekse::{CookieStore, Insertion, OffsetDateTime};

let now = OffsetDateTime::from_unix_timestamp(1_752_000_000)?;
let url = url::Url::parse("https://example.test/")?;
let store = RwLock::new(CookieStore::new());

let stored = store.write().unwrap().insert(&url, "SID=deadbeef; Secure", now);
assert_eq!(stored, Insertion::Stored);
let header = store.read().unwrap().cookie_header(&url, now);
assert_eq!(header.unwrap(), "SID=deadbeef");

Implementations

impl CookieStore

pub fn new() -> Self

An empty store with the default StoreConfig (RFC 6265 §6.1: 3000 cookies, 50 per domain).

pub fn with_config(config: StoreConfig) -> Self

An empty store with explicit capacity limits.

pub fn insert( &mut self, origin: &Url, set_cookie: &str, now: OffsetDateTime, ) -> Insertion

Ingest one Set-Cookie header value per RFC 6265 §5.3, with the RFC 6265bis storage gates. The outcome is always reported: stored, replaced (same (name, domain, path) identity, creation order kept), deleted (the already-expired idiom, including a negative Max-Age), or rejected with a RejectionReason.

Storage follows the user-agent rules. A Domain must cover the origin host (the anti-planting rule; under psl a refused public-suffix Domain is rejected for a foreign host and degrades to host-only when the origin is the suffix — §5.3 step 5 exactly), a missing or relative Path takes the origin’s default-path, and Max-Age wins over Expires, with a negative Max-Age honored as “expire now”. The RFC 6265bis gates then apply: a Secure cookie only over a secure origin — a TLS scheme (https/wss) or a loopback destination (loopback IPs, localhost, *.localhost), the trustworthy-origin convention — and the __Host-/__Secure- prefix requirements and CHIPS’ Partitioned/Secure pairing as witnessed by the parse; a case-variant prefix whose requirements are met stores verbatim, as user agents do. Finally the StoreConfig caps evict, expired cookies first, then oldest by creation.

The line is parsed leniently (SetCookie::parse) — the store mirrors a user agent, and a recoverable deviation never costs the cookie. A caller who wants strict grading gates before feeding the store.

use kekse::{CookieStore, Insertion, OffsetDateTime, RejectionReason};

let now = OffsetDateTime::from_unix_timestamp(1_752_000_000)?;
let origin = url::Url::parse("https://shop.example.test/cart")?;
let mut store = CookieStore::new();

let stored = store.insert(&origin, "SID=deadbeef; Path=/; Secure", now);
assert_eq!(stored, Insertion::Stored);

// The anti-planting rule: a foreign Domain is refused.
let planted = store.insert(&origin, "SID=evil; Domain=victim.test", now);
assert_eq!(
    planted,
    Insertion::Rejected(RejectionReason::DomainMismatch)
);

pub fn insert_all<'s>( &mut self, origin: &Url, lines: impl IntoIterator<Item = &'s str>, now: OffsetDateTime, )

Ingest several Set-Cookie header values from one response, in order. Per-line outcomes are discarded — use insert where they matter.

pub fn insert_response( &mut self, origin: &Url, headers: &HeaderMap, now: OffsetDateTime, )

Ingest every Set-Cookie header of a response’s http::HeaderMap, in order. A header value that is not valid UTF-8 is skipped (the parse boundary is &str); per-line outcomes are discarded — use insert where they matter.

pub fn matches<'s>( &'s self, request: &Url, now: OffsetDateTime, ) -> impl Iterator<Item = StoredRef<'s>> + 's

The cookies to attach to a request, per RFC 6265 §5.4: not expired at now, Secure only onto a secure request (a TLS scheme or a loopback destination), host or domain match, path match — ordered per §5.4.2 (longest path first, then earliest creation). A hostless URL matches nothing.

pub fn cookie_header( &self, request: &Url, now: OffsetDateTime, ) -> Option<HeaderValue>

The request Cookie: header for request — the matches rendered through a CookieJar with the canonical Percent encoding — or None when nothing matches (send no header at all, rather than an empty one).

pub fn iter(&self) -> impl Iterator<Item = StoredRef<'_>>

Every stored cookie, in storage order — including cookies already expired but not yet purged (purge_expired).

pub fn get<'s>( &'s self, name: &'s str, ) -> impl Iterator<Item = StoredRef<'s>> + 's

Every stored cookie with this name (any domain and path), in storage order.

pub fn remove(&mut self, name: &str, domain: &str, path: &str) -> bool

Remove the cookie with exactly this (name, domain, path) identity — domain is the effective domain (the setting host for a host-only cookie); a leading dot is stripped and the comparison is case-insensitive, like storage. true iff a cookie was removed.

pub fn clear(&mut self)

Drop every cookie.

pub fn purge_expired(&mut self, now: OffsetDateTime)

Drop every cookie expired at now. Retrieval already filters expiry, so this is housekeeping, not correctness.

pub fn len(&self) -> usize

The number of stored cookies — including expired-but-unpurged ones.

pub fn is_empty(&self) -> bool

Whether the store holds no cookies at all.

impl CookieStore

pub fn export(&self) -> PersistedStore

Export the stored representation for persistence: every cookie — session cookies and the expired-but-unpurged included — in creation order, as plain data.

pub fn import( persisted: PersistedStore, config: StoreConfig, now: OffsetDateTime, ) -> Self

Rebuild a store from its persisted representation, under config: list order becomes creation order, cookies already expired at now are dropped, and the capacity caps apply immediately. Import trusts its input — the persisted form is the caller’s own export — and an unrecognized same_site token degrades to unset.

Trait Implementations

impl Clone for CookieStore

fn clone(&self) -> CookieStore

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CookieStore

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

Formats the value using the given formatter.

impl Default for CookieStore

fn default() -> CookieStore

Returns the “default value” for a type.