cookie_store

cookie_store is a focused Rust crate that solves one problem precisely: storing, matching, and retrieving HTTP cookies according to the domain and path rules laid out in RFC6265. Rather than bundling a full HTTP client, it exposes a CookieStore type that any client implementation can hand raw Set-Cookie headers and request URLs to, receiving back the correctly-scoped set of cookies for outgoing requests.

The crate is best known as the cookie engine behind reqwest_cookie_store, a small adapter crate that implements reqwest::cookie::CookieStore on top of it, but it has no hard dependency on reqwest itself and can be wired into any HTTP stack. Optional feature flags add public-suffix-list awareness for correctly rejecting cookies set on public registrable domains, insertion-order preservation via indexmap, and JSON/RON serialization so a cookie jar can be persisted to disk and reloaded between process runs.

What You Get

• A CookieStore type with insert, insert_raw, parse, remove, matches, and get/get_any methods covering the full cookie lifecycle for a single domain/path/name combination.
• RFC6265-correct domain and path matching (cookie_domain.rs, cookie_path.rs) so cookies are only returned for requests they actually apply to.
• Optional public_suffix feature that wires in the publicsuffix crate to reject cookies incorrectly set on an entire public suffix (e.g. .co.uk).
• save/load methods generic over any Write/BufRead and a caller-supplied cookie-to-string function, plus ready-made save_json/load_json helpers behind the serde_json feature.
• An optional preserve_order feature that swaps the internal storage to indexmap::IndexMap so iteration follows insertion order instead of hash order.

Common Use Cases

• Backing a custom HTTP client (built directly on reqwest, hyper, or similar) with a spec-correct cookie jar, without reimplementing RFC6265 domain/path matching by hand.
• Persisting an authenticated session’s cookies to disk between runs of a CLI tool, using save_json/load_json to serialize the jar as JSON.
• Maintaining cookie state across a multi-request scraping or automation session, respecting expiration, secure, and host-only flags automatically.
• Compiling a Rust HTTP tool to WebAssembly and still needing standards-compliant cookie handling via the wasm-bindgen feature flag.

Under The Hood

Architecture cookie_store is organized as a small set of single-responsibility modules around one core type. cookie_store.rs defines CookieStore, which nests three nominally-typed maps (domain to path to name to Cookie, aliased as DomainMap/PathMap/NameMap and generic over HashMap or, with the preserve_order feature, indexmap::IndexMap) so lookups by domain, path, and name are direct rather than scanned. Matching logic is factored out into cookie_domain.rs and cookie_path.rs, each exposing a standalone is_match function that CookieStore::matches calls per request, keeping the RFC6265 domain/path algorithms testable and independent of the storage structure itself. cookie.rs wraps the lower-level cookie::Cookie (from the separate cookie crate) with CookieDomain, CookiePath, and CookieExpiration value types that encode parsed, validated cookie attributes rather than raw strings. This is a layered design with a clear boundary: storage/lookup, RFC matching rules, and cookie value parsing each live in their own file, and nothing outside cookie_store.rs needs to know how cookies are actually stored in memory.

Tech Stack The crate targets Rust 2021 edition with an MSRV of 1.88.0 and depends on url for URL parsing, time for expiration handling, idna for internationalized domain name normalization, log for diagnostics, and the cookie crate (with its percent-encode feature) for low-level Set-Cookie header parsing. Everything else is opt-in via Cargo features: public_suffix pulls in the publicsuffix crate, preserve_order pulls in indexmap, and the serialization family (serde, serde_json, serde_ron) pulls in serde/serde_derive plus either serde_json or ron. There is no runtime beyond the standard library and these dependencies — no async runtime, no network stack — the crate is deliberately storage-and-matching only, leaving transport to whatever HTTP client embeds it (commonly reqwest, via the companion reqwest_cookie_store crate).

Code Quality The crate has substantial test coverage for its size: roughly 60 #[test] functions across 8 #[cfg(test)] modules exercise insertion, expiration, domain/path matching edge cases, and (de)serialization round-trips. Error handling is explicit and typed — CookieError and a boxed Error/Result alias are used rather than panics for recoverable failures, and public methods return Result types (InsertResult, StoreResult<T>) instead of silently dropping invalid cookies. CI (.github/workflows/ci.yml) runs cargo clippy --all-targets --all-features with warnings denied, cargo fmt -- --check, an MSRV check, and the test suite on every push and PR, so style and lint regressions are caught automatically. Naming is consistent and documentation comments are present on nearly every public item, including feature-flag documentation surfaced via the document-features crate.

What Makes It Unique cookie_store’s niche is doing exactly one thing — RFC6265-compliant cookie storage and matching — as a transport-agnostic library rather than bundling it into a full HTTP client. Most HTTP client crates either omit cookie jar support entirely or implement a minimal, non-spec-compliant version internally; cookie_store instead externalizes that logic so any client (or non-client use case, like session persistence for a CLI tool) can depend on a single well-tested implementation. Its feature-flag design is also notable: public suffix list support, insertion-order preservation, and two independent serialization formats are all optional, letting consumers pull in only the pieces they need rather than paying for a monolithic dependency tree.