Skip to main content

ntex_session/
lib.rs

1//! User sessions.
2//!
3//! Actix provides a general solution for session management. Session
4//! middlewares could provide different implementations which could
5//! be accessed via general session api.
6//!
7//! By default, only cookie session backend is implemented. Other
8//! backend implementations can be added.
9//!
10//! In general, you insert a *session* middleware and initialize it
11//! , such as a `CookieSessionBackend`. To access session data,
12//! [*Session*](struct.Session.html) extractor must be used. Session
13//! extractor allows us to get or set session data.
14//!
15//! ```rust,no_run
16//! use ntex::web::{self, App, HttpResponse, WebError};
17//! use ntex_session::{Session, CookieSession};
18//! use serde_json::error::Error as JsonError;
19//!
20//! fn index(session: Session) -> Result<&'static str, JsonError> {
21//!     // access session data
22//!     if let Some(count) = session.get::<i32>("counter")? {
23//!         println!("SESSION value: {}", count);
24//!         session.set("counter", count+1)?;
25//!     } else {
26//!         session.set("counter", 1)?;
27//!     }
28//!
29//!     Ok("Welcome!")
30//! }
31//!
32//! #[ntex::main]
33//! async fn main() -> std::io::Result<()> {
34//!     web::server(
35//!         async |_| App::new().middleware(
36//!               CookieSession::signed(&[0; 32]) // <- create cookie based session middleware
37//!                     .secure(false)
38//!              )
39//!             .service(web::resource("/").to(|| async { HttpResponse::Ok() })))
40//!         .bind("127.0.0.1:59880", ntex::SharedCfg::default())?
41//!         .run()
42//!         .await
43//! }
44//! ```
45use std::{cell::RefCell, convert::Infallible, rc::Rc};
46
47use ntex::http::{Payload, RequestHead};
48use ntex::util::{Extensions, HashMap};
49use ntex::web::{FromRequest, HttpRequest, WebRequest, WebResponse};
50use serde::Serialize;
51use serde::de::DeserializeOwned;
52use serde_json::error::Error as JsonError;
53
54#[cfg(feature = "cookie-session")]
55mod cookie;
56#[cfg(feature = "cookie-session")]
57pub use crate::cookie::CookieSession;
58
59/// The high-level interface you use to modify session data.
60///
61/// Session object could be obtained with
62/// [`RequestSession::session`](trait.RequestSession.html#tymethod.session)
63/// method. `RequestSession` trait is implemented for `HttpRequest`.
64///
65/// ```rust
66/// use ntex_session::Session;
67/// use ntex::web::*;
68/// use serde_json::error::Error as JsonError;
69///
70/// fn index(session: Session) -> Result<&'static str, JsonError> {
71///     // access session data
72///     if let Some(count) = session.get::<i32>("counter")? {
73///         session.set("counter", count + 1)?;
74///     } else {
75///         session.set("counter", 1)?;
76///     }
77///
78///     Ok("Welcome!")
79/// }
80/// # fn main() {}
81/// ```
82pub struct Session(Rc<RefCell<SessionInner>>);
83
84/// Helper trait that allows to get session
85pub trait UserSession {
86    fn get_session(&self) -> Session;
87}
88
89impl UserSession for HttpRequest {
90    fn get_session(&self) -> Session {
91        Session::get_session(&mut self.extensions_mut())
92    }
93}
94
95impl<St> UserSession for WebRequest<St> {
96    fn get_session(&self) -> Session {
97        Session::get_session(&mut self.extensions_mut())
98    }
99}
100
101impl UserSession for RequestHead {
102    fn get_session(&self) -> Session {
103        Session::get_session(&mut self.extensions_mut())
104    }
105}
106
107#[derive(PartialEq, Clone, Debug)]
108pub enum SessionStatus {
109    Changed,
110    Purged,
111    Renewed,
112    Unchanged,
113}
114
115/// #[default] macro can be used but will depend on specific rust version
116impl Default for SessionStatus {
117    fn default() -> SessionStatus {
118        SessionStatus::Unchanged
119    }
120}
121
122#[derive(Default)]
123struct SessionInner {
124    state: HashMap<String, String>,
125    pub status: SessionStatus,
126}
127
128impl Session {
129    /// Get a `value` from the session.
130    pub fn get<T: DeserializeOwned>(&self, key: &str) -> Result<Option<T>, JsonError> {
131        if let Some(s) = self.0.borrow().state.get(key) {
132            Ok(Some(serde_json::from_str(s)?))
133        } else {
134            Ok(None)
135        }
136    }
137
138    /// Set a `value` from the session.
139    pub fn set<T: Serialize>(&self, key: &str, value: T) -> Result<(), JsonError> {
140        let mut inner = self.0.borrow_mut();
141        if inner.status != SessionStatus::Purged {
142            inner.status = SessionStatus::Changed;
143            inner
144                .state
145                .insert(key.to_owned(), serde_json::to_string(&value)?);
146        }
147        Ok(())
148    }
149
150    /// Remove value from the session.
151    pub fn remove(&self, key: &str) {
152        let mut inner = self.0.borrow_mut();
153        if inner.status != SessionStatus::Purged {
154            inner.status = SessionStatus::Changed;
155            inner.state.remove(key);
156        }
157    }
158
159    /// Clear the session.
160    pub fn clear(&self) {
161        let mut inner = self.0.borrow_mut();
162        if inner.status != SessionStatus::Purged {
163            inner.status = SessionStatus::Changed;
164            inner.state.clear()
165        }
166    }
167
168    /// Removes session, both client and server side.
169    pub fn purge(&self) {
170        let mut inner = self.0.borrow_mut();
171        inner.status = SessionStatus::Purged;
172        inner.state.clear();
173    }
174
175    /// Renews the session key, assigning existing session state to new key.
176    pub fn renew(&self) {
177        let mut inner = self.0.borrow_mut();
178        if inner.status != SessionStatus::Purged {
179            inner.status = SessionStatus::Renewed;
180        }
181    }
182
183    pub fn set_session<St>(data: impl Iterator<Item = (String, String)>, req: &WebRequest<St>) {
184        let session = Session::get_session(&mut req.extensions_mut());
185        let mut inner = session.0.borrow_mut();
186        inner.state.extend(data);
187    }
188
189    pub fn get_changes(
190        res: &mut WebResponse,
191    ) -> (
192        SessionStatus,
193        Option<impl Iterator<Item = (String, String)> + use<>>,
194    ) {
195        if let Some(s_impl) = res
196            .request()
197            .extensions()
198            .get::<Rc<RefCell<SessionInner>>>()
199        {
200            let state = std::mem::take(&mut s_impl.borrow_mut().state);
201            (s_impl.borrow().status.clone(), Some(state.into_iter()))
202        } else {
203            (SessionStatus::Unchanged, None)
204        }
205    }
206
207    fn get_session(extensions: &mut Extensions) -> Session {
208        if let Some(s_impl) = extensions.get::<Rc<RefCell<SessionInner>>>() {
209            return Session(Rc::clone(s_impl));
210        }
211        let inner = Rc::new(RefCell::new(SessionInner::default()));
212        extensions.insert(inner.clone());
213        Session(inner)
214    }
215}
216
217/// Extractor implementation for Session type.
218///
219/// ```rust
220/// use ntex_session::Session;
221/// use serde_json::error::Error as JsonError;
222///
223/// fn index(session: Session) -> Result<&'static str, JsonError> {
224///     // access session data
225///     if let Some(count) = session.get::<i32>("counter")? {
226///         session.set("counter", count + 1)?;
227///     } else {
228///         session.set("counter", 1)?;
229///     }
230///
231///     Ok("Welcome!")
232/// }
233/// # fn main() {}
234/// ```
235impl<St> FromRequest<St> for Session {
236    type Error = Infallible;
237
238    #[inline]
239    async fn from_request(
240        _: &St,
241        req: &HttpRequest,
242        _: &mut Payload,
243    ) -> Result<Session, Infallible> {
244        Ok(Session::get_session(&mut req.extensions_mut()))
245    }
246}
247
248#[cfg(test)]
249mod tests {
250    use ntex::web::{HttpResponse, test};
251
252    use super::*;
253
254    #[test]
255    fn session() {
256        let req = test::TestRequest::default().to_srv_request();
257
258        Session::set_session(
259            vec![("key".to_string(), "\"value\"".to_string())].into_iter(),
260            &req,
261        );
262        let session = Session::get_session(&mut req.extensions_mut());
263        let res = session.get::<String>("key").unwrap();
264        assert_eq!(res, Some("value".to_string()));
265
266        session.set("key2", "value2".to_string()).unwrap();
267        session.remove("key");
268
269        let mut res = req.into_response(HttpResponse::Ok().build());
270        let (_status, state) = Session::get_changes(&mut res);
271        let changes: Vec<_> = state.unwrap().collect();
272        assert_eq!(changes, [("key2".to_string(), "\"value2\"".to_string())]);
273    }
274
275    #[test]
276    fn get_session() {
277        let req = test::TestRequest::default().to_srv_request();
278
279        Session::set_session(
280            vec![("key".to_string(), "\"value\"".to_string())].into_iter(),
281            &req,
282        );
283
284        let session = req.get_session();
285        let res = session.get::<String>("key").unwrap();
286        assert_eq!(res, Some("value".to_string()));
287    }
288
289    #[test]
290    fn get_session_from_request_head() {
291        let mut req = test::TestRequest::default().to_srv_request();
292
293        Session::set_session(
294            vec![("key".to_string(), "\"value\"".to_string())].into_iter(),
295            &req,
296        );
297
298        let session = req.head_mut().get_session();
299        let res = session.get::<String>("key").unwrap();
300        assert_eq!(res, Some("value".to_string()));
301    }
302
303    #[test]
304    fn purge_session() {
305        let req = test::TestRequest::default().to_srv_request();
306        let session = Session::get_session(&mut req.extensions_mut());
307        assert_eq!(session.0.borrow().status, SessionStatus::Unchanged);
308        session.purge();
309        assert_eq!(session.0.borrow().status, SessionStatus::Purged);
310    }
311
312    #[test]
313    fn renew_session() {
314        let req = test::TestRequest::default().to_srv_request();
315        let session = Session::get_session(&mut req.extensions_mut());
316        assert_eq!(session.0.borrow().status, SessionStatus::Unchanged);
317        session.renew();
318        assert_eq!(session.0.borrow().status, SessionStatus::Renewed);
319    }
320}