YinMo19/rocket_session
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

version bump, comments, improve examples, update readme

Browse Source
This commit is contained in:
Ondřej Hruška 2019-12-31 20:48:56 +01:00
parent cde08fe788
commit f8d5445cdc
No known key found for this signature in database
GPG Key ID: 2C5FD5035250423D
5 changed files with 100 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Cargo.toml
View File

@ -1,6 +1,6 @@
[package] [package]
name = "rocket_session" name = "rocket_session"
version = "0.1.1" version = "0.2.0"
authors = ["Ondřej Hruška <ondra@ondrovo.com>"] authors = ["Ondřej Hruška <ondra@ondrovo.com>"]
edition = "2018" edition = "2018"
license = "MIT" license = "MIT"

40
README.md
View File

@ -2,17 +2,38 @@
Adding cookie-based sessions to a rocket application is extremely simple with this crate. Adding cookie-based sessions to a rocket application is extremely simple with this crate.
Sessions are used to share data between related requests, such as user authentication, shopping basket,
form values that failed validation for re-filling, etc.
## Configuration
The implementation is generic to support any type as session data: a custom struct, `String`, The implementation is generic to support any type as session data: a custom struct, `String`,
`HashMap`, or perhaps `serde_json::Value`. You're free to choose. `HashMap`, or perhaps `serde_json::Value`. You're free to choose.
The session expiry time is configurable through the Fairing. When a session expires, The session lifetime, cookie name, and other parameters can be configured by calling chained
the data associated with it is dropped. All expired sessions may be cleared by calling `.remove_expired()` methods on the fairing. When a session expires, the data associated with it is dropped.
on the `SessionStore`, which is be obtained in routes as `State<SessionStore>`, or from a
session instance by calling `.get_store()`.
The session cookie is currently hardcoded to "SESSID" and contains 16 random characters. ## Usage
## Basic Example To use session in a route, first make sure you have the fairing attached by calling
`rocket.attach(Session::fairing())` at start-up, and then add something like `session : Session`
to the parameter list of your route(s). Everything else--session init, expiration, cookie
management--is done for you behind the scenes.
Session data is accessed in a closure run in the session context, using the `session.tap()`
method. This closure runs inside a per-session mutex, avoiding simultaneous mutation
from different requests. Try to *avoid lengthy operations inside the closure*,
as it effectively blocks any other request to session-enabled routes by the client.
Every request to a session-enabled route extends the session's lifetime to the full
configured time (defaults to 1 hour). Automatic clean-up removes expired sessions to make sure
the session list does not waste memory.
## Examples
(More examples are in the examples folder)
### Basic Example
This simple example uses u64 as the session variable; note that it can be a struct, map, or anything else, This simple example uses u64 as the session variable; note that it can be a struct, map, or anything else,
it just needs to implement `Send + Sync + Default`. it just needs to implement `Send + Sync + Default`.
@ -28,7 +49,7 @@ pub type Session<'a> = rocket_session::Session<'a, u64>;
fn main() { fn main() {
rocket::ignite() rocket::ignite()
.attach(Session::fairing(Duration::from_secs(3600))) .attach(Session::fairing())
.mount("/", routes![index]) .mount("/", routes![index])
.launch(); .launch();
} }
@ -53,7 +74,10 @@ fn index(session: Session) -> String {
The `.tap()` method is powerful, but sometimes you may wish for something more convenient. The `.tap()` method is powerful, but sometimes you may wish for something more convenient.
Here is an example of using a custom trait and the `json_dotpath` crate to implement Here is an example of using a custom trait and the `json_dotpath` crate to implement
a polymorphic store based on serde serialization: a polymorphic store based on serde serialization.
Note that this approach is prone to data races, since every method contains its own `.tap()`.
It may be safer to simply call the `.dot_*()` methods manually in one shared closure.
```rust ```rust
use serde_json::Value; use serde_json::Value;

21
examples/dog_list/main.rs
View File

@ -2,9 +2,9 @@
#[macro_use] #[macro_use]
extern crate rocket; extern crate rocket;
use rocket::request::Form;
use rocket::response::content::Html; use rocket::response::content::Html;
use rocket::response::Redirect; use rocket::response::Redirect;
use rocket::request::Form;
type Session<'a> = rocket_session::Session<'a, Vec<String>>; type Session<'a> = rocket_session::Session<'a, Vec<String>>;
@ -18,7 +18,8 @@ fn main() {
#[get("/")] #[get("/")]
fn index(session: Session) -> Html<String> { fn index(session: Session) -> Html<String> {
let mut page = String::new(); let mut page = String::new();
page.push_str(r#" page.push_str(
r#"
<!DOCTYPE html> <!DOCTYPE html>
<h1>My Dogs</h1> <h1>My Dogs</h1>
@ -27,19 +28,25 @@ fn index(session: Session) -> Html<String> {
</form> </form>
<ul> <ul>
"#); "#,
);
session.tap(|sess| { session.tap(|sess| {
for (n, dog) in sess.iter().enumerate() { for (n, dog) in sess.iter().enumerate() {
page.push_str(&format!(r#" page.push_str(&format!(
r#"
<li>&#x1F436; {} <a href="/remove/{}">Remove</a></li> <li>&#x1F436; {} <a href="/remove/{}">Remove</a></li>
"#, dog, n)); "#,
dog, n
));
} }
}); });
page.push_str(r#" page.push_str(
r#"
</ul> </ul>
"#); "#,
);
Html(page) Html(page)
} }

16
examples/visit_counter/main.rs
View File

@ -6,8 +6,8 @@
#[macro_use] #[macro_use]
extern crate rocket; extern crate rocket;
use std::time::Duration;
use rocket::response::content::Html; use rocket::response::content::Html;
use std::time::Duration;
#[derive(Default, Clone)] #[derive(Default, Clone)]
struct SessionData { struct SessionData {
@ -20,13 +20,14 @@ type Session<'a> = rocket_session::Session<'a, SessionData>;
fn main() { fn main() {
rocket::ignite() rocket::ignite()
.attach(Session::fairing() .attach(
Session::fairing()
// 10 seconds of inactivity until session expires // 10 seconds of inactivity until session expires
// (wait 10s and refresh, the numbers will reset) // (wait 10s and refresh, the numbers will reset)
.with_lifetime(Duration::from_secs(10)) .with_lifetime(Duration::from_secs(10))
// custom cookie name and length // custom cookie name and length
.with_cookie_name("my_cookie") .with_cookie_name("my_cookie")
.with_cookie_len(20) .with_cookie_len(20),
) )
.mount("/", routes![index, about]) .mount("/", routes![index, about])
.launch(); .launch();
@ -41,14 +42,14 @@ fn index(session: Session) -> Html<String> {
session.tap(|sess| { session.tap(|sess| {
sess.visits1 += 1; sess.visits1 += 1;
Html(format!(r##" Html(format!(
r##"
<!DOCTYPE html> <!DOCTYPE html>
<h1>Home</h1> <h1>Home</h1>
<a href="/">Refresh</a> &bull; <a href="/about/">go to About</a> <a href="/">Refresh</a> &bull; <a href="/about/">go to About</a>
<p>Visits: home {}, about {}</p> <p>Visits: home {}, about {}</p>
"##, "##,
sess.visits1, sess.visits1, sess.visits2
sess.visits2
)) ))
}) })
} }
@ -61,7 +62,8 @@ fn about(session: Session) -> Html<String> {
sess.visits2 sess.visits2
}); });
Html(format!(r##" Html(format!(
r##"
<!DOCTYPE html> <!DOCTYPE html>
<h1>About</h1> <h1>About</h1>
<a href="/about">Refresh</a> &bull; <a href="/">go home</a> <a href="/about">Refresh</a> &bull; <a href="/">go home</a>

31
src/lib.rs
View File

@ -1,4 +1,4 @@
use parking_lot::{RwLock, RwLockUpgradableReadGuard, Mutex}; use parking_lot::{Mutex, RwLock, RwLockUpgradableReadGuard};
use rand::Rng; use rand::Rng;
use rocket::{ use rocket::{
@ -8,12 +8,12 @@ use rocket::{
Outcome, Request, Response, Rocket, State, Outcome, Request, Response, Rocket, State,
}; };
use std::borrow::Cow;
use std::collections::HashMap; use std::collections::HashMap;
use std::fmt::{self, Display, Formatter};
use std::marker::PhantomData; use std::marker::PhantomData;
use std::ops::Add; use std::ops::Add;
use std::time::{Duration, Instant}; use std::time::{Duration, Instant};
use std::borrow::Cow;
use std::fmt::{Display, Formatter, self};
/// Session store (shared state) /// Session store (shared state)
#[derive(Debug)] #[derive(Debug)]
@ -55,14 +55,16 @@ impl Default for SessionConfig {
#[derive(Debug)] #[derive(Debug)]
struct StoreInner<D> struct StoreInner<D>
where where
D: 'static + Sync + Send + Default { D: 'static + Sync + Send + Default,
{
sessions: HashMap<String, Mutex<SessionInstance<D>>>, sessions: HashMap<String, Mutex<SessionInstance<D>>>,
last_expiry_sweep: Instant, last_expiry_sweep: Instant,
} }
impl<D> Default for StoreInner<D> impl<D> Default for StoreInner<D>
where where
D: 'static + Sync + Send + Default { D: 'static + Sync + Send + Default,
{
fn default() -> Self { fn default() -> Self {
Self { Self {
sessions: Default::default(), sessions: Default::default(),
@ -138,7 +140,8 @@ impl<'a, 'r, D> FromRequest<'a, 'r> for Session<'a, D>
let expires = Instant::now().add(store.config.lifespan); let expires = Instant::now().add(store.config.lifespan);
if let Some(m) = id.as_ref() if let Some(m) = id
.as_ref()
.and_then(|token| store_ug.sessions.get(token.as_str())) .and_then(|token| store_ug.sessions.get(token.as_str()))
{ {
// --- ID obtained from a cookie && session found in the store --- // --- ID obtained from a cookie && session found in the store ---
@ -166,8 +169,7 @@ impl<'a, 'r, D> FromRequest<'a, 'r> for Session<'a, D>
// Throttle by lifespan - e.g. sweep every hour // Throttle by lifespan - e.g. sweep every hour
if store_wg.last_expiry_sweep.elapsed() > store.config.lifespan { if store_wg.last_expiry_sweep.elapsed() > store.config.lifespan {
let now = Instant::now(); let now = Instant::now();
store_wg.sessions store_wg.sessions.retain(|_k, v| v.lock().expires > now);
.retain(|_k, v| v.lock().expires > now);
store_wg.last_expiry_sweep = now; store_wg.last_expiry_sweep = now;
} }
@ -231,7 +233,9 @@ impl<'a, D> Session<'a, D>
// Unlock the session's mutex. // Unlock the session's mutex.
// Expiry was checked and prolonged at the beginning of the request // Expiry was checked and prolonged at the beginning of the request
let mut instance = store_rg.sessions.get(self.id.as_str()) let mut instance = store_rg
.sessions
.get(self.id.as_str())
.expect("Session data unexpectedly missing") .expect("Session data unexpectedly missing")
.lock(); .lock();
@ -251,7 +255,7 @@ pub struct SessionFairing<D>
impl<D> SessionFairing<D> impl<D> SessionFairing<D>
where where
D: 'static + Sync + Send + Default D: 'static + Sync + Send + Default,
{ {
fn new() -> Self { fn new() -> Self {
Self::default() Self::default()
@ -314,8 +318,11 @@ impl<D> Fairing for SessionFairing<D>
let session = request.local_cache(|| SessionID("".to_string())); let session = request.local_cache(|| SessionID("".to_string()));
if !session.0.is_empty() { if !session.0.is_empty() {
response.adjoin_header(Cookie::build(self.config.cookie_name.clone(), session.to_string()) response.adjoin_header(
.path("/").finish()); Cookie::build(self.config.cookie_name.clone(), session.to_string())
.path("/")
.finish(),
);
} }
} }
} }