cookie_monster/lib.rs
1//! An HTTP Cookie crate.
2//!
3//! # Overview
4//! Exposes types like [`Cookie`] and [`CookieJar`] for working with HTTP cookies. This crate
5//! focuses on server side applications. The main goals are simplicity and ease of use.
6//!
7//! # Prefix cookies
8//! [`Cookie::host`] and [`Cookie::secure`] build cookies that use the `__Host-` and `__Secure-`
9//! name prefixes ([RFC 6265bis ยง4.1.3](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis#section-4.1.3)).
10//! They set the attributes the prefix requires as defaults (which you may override) and apply
11//! the prefix to the name on serialization. Parsing strips a recognized prefix from the name, so
12//! a prefixed cookie is looked up in a [`CookieJar`] by its logical (unprefixed) name.
13//!
14//! ```rust
15//! use cookie_monster::Cookie;
16//!
17//! let cookie = Cookie::host("id", "abc").build();
18//! assert_eq!(cookie.serialize().as_deref(), Ok("__Host-id=abc; Path=/; Secure"));
19//! ```
20//!
21//! # Usage
22//! Add cookie-monster in your Cargo.toml:
23//! ```toml
24//![dependencies]
25//!cookie-monster = "0.1"
26//!```
27//!
28//! # Features
29//! * `jiff`
30//!
31//! Adds support for the [jiff](https://docs.rs/jiff/latest/jiff/) crate.
32//! This exposes methods to [`Cookie`] to retrieve the `Expires` and `Max-Age` attributes with jiff
33//! specific types.
34//!
35//! * `chrono`
36//!
37//! Adds support for the [chrono](https://docs.rs/chrono/latest/chrono/) crate.
38//! This exposes methods to [`Cookie`] to retrieve the `Expires` and `Max-Age` attributes with
39//! chrono specific types.
40//!
41//! * `time`
42//!
43//! Adds support for the [time](https://docs.rs/time/latest/time/index.html) crate.
44//! This exposes methods to [`Cookie`] to retrieve the `Expires` and `Max-Age` attributes with time
45//! specific types.
46//!
47//! * `percent-encode`
48//!
49//! Parse/serialize [`Cookie`]s that are percent-encoded.
50//!
51//! * `axum`
52//!
53//! Adds integration with the [axum](https://docs.rs/axum/latest/axum/) crate.
54//! Implements [`IntoResponse`](https://docs.rs/axum/latest/axum/response/trait.IntoResponse.html) and
55//! [`IntoResponseParts`](https://docs.rs/axum/latest/axum/response/trait.IntoResponseParts.html)
56//! for [`Cookie`] and [`CookieJar`].
57//! Implements [`FromRequestParts`](https://docs.rs/axum/latest/axum/extract/trait.FromRequestParts.html) only for [`CookieJar`]
58//!
59//! * `http`
60//!
61//! Adds integration with the [http](https://docs.rs/http/latest/http/) crate.
62//! Create a [`CookieJar`] from a [`HeaderMap`](https://docs.rs/http/latest/http/header/struct.HeaderMap.html).
63//! Write a [`CookieJar`] to a [`HeaderMap`](https://docs.rs/http/latest/http/header/struct.HeaderMap.html).
64//!
65//!
66//! # Axum example
67//!
68//! ```rust
69//! # #[cfg(feature="axum")]
70//! # {
71//! use axum::response::IntoResponse;
72//! use cookie_monster::{Cookie, CookieJar, SameSite};
73//!
74//! static COOKIE_NAME: &str = "session";
75//!
76//! async fn handler(mut jar: CookieJar) -> impl IntoResponse {
77//! if let Some(cookie) = jar.get(COOKIE_NAME) {
78//! // Remove cookie
79//! println!("Removing cookie {cookie:?}");
80//! jar.remove(Cookie::named(COOKIE_NAME));
81//! } else {
82//! // Set cookie.
83//! let cookie = Cookie::build(COOKIE_NAME, "hello, world")
84//! .http_only()
85//! .same_site(SameSite::Strict);
86//!
87//! println!("Setting cookie {cookie:?}");
88//! jar.add(cookie);
89//! }
90//! // Return the jar so the cookies are updated
91//! jar
92//! }
93//! # }
94//! ```
95//!
96//!
97//! ### Honorable mention
98//! This crate takes a lot of inspiration from the [cookie](https://crates.io/crates/cookie) crate.
99
100mod cookie;
101mod error;
102mod jar;
103mod util;
104
105#[cfg(feature = "axum")]
106mod axum;
107
108#[cfg(feature = "http")]
109mod http;
110
111pub use cookie::{Cookie, CookieBuilder, expires::Expires, same_site::SameSite};
112pub use error::Error;
113pub(crate) type Result<T, E = Error> = ::std::result::Result<T, E>;
114pub use jar::CookieJar;