version bump, comments, improve examples, update readme

5 years ago · f8d5445cdc
parent cde08fe788
commit f8d5445cdc
5 changed files with 100 additions and 60 deletions
--- a/Cargo.toml
+++ b/Cargo.toml
@ -1,6 +1,6 @@
 [package]
 name = "rocket_session"
-version = "0.1.1"
+version = "0.2.0"
 authors = ["Ondřej Hruška <ondra@ondrovo.com>"]
 edition = "2018"
 license = "MIT"
--- a/README.md
+++ b/README.md
@ -2,17 +2,38 @@

 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`,
 `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 data associated with it is dropped. All expired sessions may be cleared by calling `.remove_expired()`
-on the `SessionStore`, which is be obtained in routes as `State<SessionStore>`, or from a 
-session instance by calling `.get_store()`.
+The session lifetime, cookie name, and other parameters can be configured by calling chained 
+methods on the fairing. When a session expires, the data associated with it is dropped.
+
+## Usage
+
+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.

-The session cookie is currently hardcoded to "SESSID" and contains 16 random characters.
+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.

-## Basic Example
+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,
 it just needs to implement `Send + Sync + Default`. 
@ -28,7 +49,7 @@ pub type Session<'a> = rocket_session::Session<'a, u64>;

 fn main() {
    rocket::ignite()
-        .attach(Session::fairing(Duration::from_secs(3600)))
+        .attach(Session::fairing())
        .mount("/", routes![index])
        .launch();
 }
@ -53,7 +74,10 @@ fn index(session: Session) -> String {
 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
-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
 use serde_json::Value;
--- a/examples/dog_list/main.rs
+++ b/examples/dog_list/main.rs
@ -2,9 +2,9 @@
 #[macro_use]
 extern crate rocket;

+use rocket::request::Form;
 use rocket::response::content::Html;
 use rocket::response::Redirect;
-use rocket::request::Form;

 type Session<'a> = rocket_session::Session<'a, Vec<String>>;

@ -18,7 +18,8 @@ fn main() {
 #[get("/")]
 fn index(session: Session) -> Html<String> {
    let mut page = String::new();
-    page.push_str(r#"
+    page.push_str(
+        r#"
            <!DOCTYPE html>
            <h1>My Dogs</h1>

@ -27,19 +28,25 @@ fn index(session: Session) -> Html<String> {
            </form>

            <ul>
-        "#);
+        "#,
+    );

    session.tap(|sess| {
        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>
-            "#, dog, n));
+            "#,
+                dog, n
+            ));
        }
    });

-    page.push_str(r#"
+    page.push_str(
+        r#"
            </ul>
-        "#);
+        "#,
+    );

    Html(page)
 }
--- a/examples/visit_counter/main.rs
+++ b/examples/visit_counter/main.rs
@ -6,8 +6,8 @@
 #[macro_use]
 extern crate rocket;

-use std::time::Duration;
 use rocket::response::content::Html;
+use std::time::Duration;

 #[derive(Default, Clone)]
 struct SessionData {
@ -20,13 +20,14 @@ type Session<'a> = rocket_session::Session<'a, SessionData>;

 fn main() {
    rocket::ignite()
-        .attach(Session::fairing()
+        .attach(
+            Session::fairing()
                // 10 seconds of inactivity until session expires
                // (wait 10s and refresh, the numbers will reset)
                .with_lifetime(Duration::from_secs(10))
                // custom cookie name and length
                .with_cookie_name("my_cookie")
-            .with_cookie_len(20)
+                .with_cookie_len(20),
        )
        .mount("/", routes![index, about])
        .launch();
@ -41,14 +42,14 @@ fn index(session: Session) -> Html<String> {
    session.tap(|sess| {
        sess.visits1 += 1;

-        Html(format!(r##"
+        Html(format!(
+            r##"
                <!DOCTYPE html>
                <h1>Home</h1>
                <a href="/">Refresh</a> &bull; <a href="/about/">go to About</a>
                <p>Visits: home {}, about {}</p>
            "##,
-            sess.visits1,
-            sess.visits2
+            sess.visits1, sess.visits2
        ))
    })
 }
@ -61,7 +62,8 @@ fn about(session: Session) -> Html<String> {
        sess.visits2
    });

-    Html(format!(r##"
+    Html(format!(
+        r##"
            <!DOCTYPE html>
            <h1>About</h1>
            <a href="/about">Refresh</a> &bull; <a href="/">go home</a>
--- a/src/lib.rs
+++ b/src/lib.rs
@ -1,4 +1,4 @@
-use parking_lot::{RwLock, RwLockUpgradableReadGuard, Mutex};
+use parking_lot::{Mutex, RwLock, RwLockUpgradableReadGuard};
 use rand::Rng;

 use rocket::{
@ -8,12 +8,12 @@ use rocket::{
    Outcome, Request, Response, Rocket, State,
 };

+use std::borrow::Cow;
 use std::collections::HashMap;
+use std::fmt::{self, Display, Formatter};
 use std::marker::PhantomData;
 use std::ops::Add;
 use std::time::{Duration, Instant};
-use std::borrow::Cow;
-use std::fmt::{Display, Formatter, self};

 /// Session store (shared state)
 #[derive(Debug)]
@ -55,14 +55,16 @@ impl Default for SessionConfig {
 #[derive(Debug)]
 struct StoreInner<D>
 where
-        D: 'static + Sync + Send + Default {
+    D: 'static + Sync + Send + Default,
+{
    sessions: HashMap<String, Mutex<SessionInstance<D>>>,
    last_expiry_sweep: Instant,
 }

 impl<D> Default for StoreInner<D>
 where
-        D: 'static + Sync + Send + Default {
+    D: 'static + Sync + Send + Default,
+{
    fn default() -> Self {
        Self {
            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);

-                if let Some(m) = id.as_ref()
+                if let Some(m) = id
+                    .as_ref()
                    .and_then(|token| store_ug.sessions.get(token.as_str()))
                {
                    // --- 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
                    if store_wg.last_expiry_sweep.elapsed() > store.config.lifespan {
                        let now = Instant::now();
-                        store_wg.sessions
-                            .retain(|_k, v| v.lock().expires > now);
+                        store_wg.sessions.retain(|_k, v| v.lock().expires > now);

                        store_wg.last_expiry_sweep = now;
                    }
@ -231,7 +233,9 @@ impl<'a, D> Session<'a, D>

        // Unlock the session's mutex.
        // 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")
            .lock();

@ -251,7 +255,7 @@ pub struct SessionFairing<D>

 impl<D> SessionFairing<D>
 where
-        D: 'static + Sync + Send + Default
+    D: 'static + Sync + Send + Default,
 {
    fn new() -> Self {
        Self::default()
@ -314,8 +318,11 @@ impl<D> Fairing for SessionFairing<D>
        let session = request.local_cache(|| SessionID("".to_string()));

        if !session.0.is_empty() {
-            response.adjoin_header(Cookie::build(self.config.cookie_name.clone(), session.to_string())
-                .path("/").finish());
+            response.adjoin_header(
+                Cookie::build(self.config.cookie_name.clone(), session.to_string())
+                    .path("/")
+                    .finish(),
+            );
        }
    }
 }