warp_sessions/
lib.rs

1//! # warp-sessions
2//!
3//! The `warp-sessions` crate provides a set of filters and an
4//! interface to add session support to your warp handlers.
5//!
6//! It operates as such:
7//! 1. A warp filter is created which has access to some `SessionStore`.
8//!    This filter will, upon receiving a request, extract the session ID
9//!    cookie, fetch the matching session, and return it to be used by the
10//!    route handler. It'll also handle creating a new session in the absence
11//!    of one.
12//! 2. The route handler operates as normal, fetching and setting information
13//!    in the session struct it received.
14//! 3. When the route is ready to reply, it creates its reply struct and places
15//!    it in a tuple with the session struct it received. It then calls the session
16//!    reply handler inside a `.and_then(...)` call, using `.untuple_one()` to unpair
17//!    the output first.
18//!
19//! # Example
20//!
21//! ```
22//! use warp::{Filter, Rejection};
23//! use warp_sessions::{MemoryStore, SessionWithStore, CookieOptions, SameSiteCookieOption};
24//!
25//! #[tokio::main]
26//! async fn main() {
27//!     let session_store = MemoryStore::new();
28//!
29//!     let route = warp::get()
30//!         .and(warp::path!("test"))
31//!         .and(warp_sessions::request::with_session(
32//!             session_store,
33//!             Some(CookieOptions {
34//!                 cookie_name: "sid",
35//!                 cookie_value: None,
36//!                 max_age: Some(60),
37//!                 domain: None,
38//!                 path: None,
39//!                 secure: false,
40//!                 http_only: true,
41//!                 same_site: Some(SameSiteCookieOption::Strict),
42//!             }),
43//!         ))
44//!         .and_then(
45//!             move |session_with_store: SessionWithStore<MemoryStore>| async move {
46//!                 Ok::<_, Rejection>((
47//!                     warp::reply::html("<html></html>".to_string()),
48//!                     session_with_store,
49//!                 ))
50//!             },
51//!         )
52//!         .untuple_one()
53//!         .and_then(warp_sessions::reply::with_session);
54//!
55//!     // Start the server
56//!     let port = 8080;
57//!     println!("starting server listening on ::{}", port);
58//!     // warp::serve(route).run(([0, 0, 0, 0], port)).await;
59//! }
60//! ```
61//!
62//! The `Some(CookieOptions)` provided as the second argument to `warp_sessions::request::with_session`
63//! can optionally be `None`. This will result in a value of CookieOptions::default(). This option
64//! encodes the full set of possible cookie parameters that could be applied to the session ID cookie.
65//! Check the [CookieOptions](crate::cookie::CookieOptions) for information on fields.
66//!
67//! Addresses issue [#609](https://github.com/seanmonstar/warp/issues/609) by appending to
68//! the header map rather than inserting, allowing for multiple session cookies to be set.
69//!
70//! This session middleware is meant to be very light and has no shared state other than
71//! the session store. It could be reused multiple times in the same route, and with
72//! different session stores.
73//!
74//! The backing session logic is provided by the [async-session](https://docs.rs/async-session/2.0.1/async_session/)
75//! crate. Simply implement the `SessionStore` trait and pass it on to the provided
76//! `with_session(...)` filter to use it.
77
78mod cookie;
79mod error;
80mod session;
81
82pub mod reply;
83pub mod request;
84
85pub use async_session::{MemoryStore, Session, SessionStore};
86pub use cookie::{CookieOptions, SameSiteCookieOption};
87pub use error::SessionError;
88pub use session::{ArcSessionStore, SessionWithStore, WithSession};