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//! # Usage
8//! Add cookie-monster in your Cargo.toml:
9//! ```toml
10//![dependencies]
11//!cookie-monster = "0.1"
12//!```
13//!
14//! # Features
15//! * `jiff`
16//!
17//! Adds support for the [jiff](https://docs.rs/jiff/latest/jiff/) crate.
18//! This exposes methods to [`Cookie`] to retrieve the `Expires` and `Max-Age` attributes with jiff
19//! specific types.
20//!
21//! * `chrono`
22//!
23//! Adds support for the [chrono](https://docs.rs/chrono/latest/chrono/) crate.
24//! This exposes methods to [`Cookie`] to retrieve the `Expires` and `Max-Age` attributes with
25//! chrono specific types.
26//!
27//! * `time`
28//!
29//! Adds support for the [time](https://docs.rs/time/latest/time/index.html) crate.
30//! This exposes methods to [`Cookie`] to retrieve the `Expires` and `Max-Age` attributes with time
31//! specific types.
32//!
33//! * `percent-encode`
34//!
35//! Parse/serialize [`Cookie`]s that are percent-encoded.
36//!
37//! * `axum`
38//!
39//! Adds integration with the [axum](https://docs.rs/axum/latest/axum/) crate.
40//! Implements [`IntoResponse`](https://docs.rs/axum/latest/axum/response/trait.IntoResponse.html) and
41//! [`IntoResponseParts`](https://docs.rs/axum/latest/axum/response/trait.IntoResponseParts.html)
42//! for [`Cookie`] and [`CookieJar`].
43//! Implements [`FromRequestParts`](https://docs.rs/axum/latest/axum/extract/trait.FromRequestParts.html) only for [`CookieJar`]
44//!
45//! * `http`
46//!
47//! Adds integration with the [http](https://docs.rs/http/latest/http/) crate.
48//! Create a [`CookieJar`] from a [`HeaderMap`](https://docs.rs/http/latest/http/header/struct.HeaderMap.html).
49//! Write a [`CookieJar`] to a [`HeaderMap`](https://docs.rs/http/latest/http/header/struct.HeaderMap.html).
50//!
51//!
52//! # Axum example
53//!
54//! ```rust
55//! # #[cfg(feature="axum")]
56//! # {
57//! use axum::response::IntoResponse;
58//! use cookie_monster::{Cookie, CookieJar, SameSite};
59//!
60//! static COOKIE_NAME: &str = "session";
61//!
62//! async fn handler(mut jar: CookieJar) -> impl IntoResponse {
63//! if let Some(cookie) = jar.get(COOKIE_NAME) {
64//! // Remove cookie
65//! println!("Removing cookie {cookie:?}");
66//! jar.remove(Cookie::named(COOKIE_NAME));
67//! } else {
68//! // Set cookie.
69//! let cookie = Cookie::build(COOKIE_NAME, "hello, world")
70//! .http_only()
71//! .same_site(SameSite::Strict);
72//!
73//! println!("Setting cookie {cookie:?}");
74//! jar.add(cookie);
75//! }
76//! // Return the jar so the cookies are updated
77//! jar
78//! }
79//! # }
80//! ```
81//!
82//!
83//! ### Honorable mention
84//! This crate takes a lot of inspiration from the [cookie](https://crates.io/crates/cookie) crate.
85
86mod cookie;
87mod error;
88mod jar;
89mod util;
90
91#[cfg(feature = "axum")]
92mod axum;
93
94#[cfg(feature = "http")]
95mod http;
96
97pub use cookie::{Cookie, CookieBuilder, expires::Expires, same_site::SameSite};
98pub use error::Error;
99pub(crate) type Result<T, E = Error> = ::std::result::Result<T, E>;
100pub use jar::CookieJar;