modo_session/lib.rs
1//! Database-backed HTTP sessions for the modo framework.
2//!
3//! Provides cookie-based session management with:
4//! - ULID session IDs stored in a `modo_sessions` database table
5//! - Cryptographically random tokens (32 bytes); only the SHA-256 hash is persisted
6//! - Server-side fingerprint validation to detect session hijacking
7//! - Automatic LRU eviction when `max_sessions_per_user` is exceeded
8//! - Sliding expiry via periodic `touch` updates
9//!
10//! # Quick start
11//!
12//! Create a [`SessionStore`], register it as a managed service, and install the
13//! middleware layer. Both steps are required: the service makes the store
14//! available to background jobs; the layer handles cookie reading/writing per
15//! request.
16//!
17//! ```rust,no_run
18//! // In your #[modo::main] entry point:
19//! let session_store = modo_session::SessionStore::new(
20//! &db,
21//! modo_session::SessionConfig::default(),
22//! config.core.cookies.clone(),
23//! );
24//!
25//! app.config(config.core)
26//! .managed_service(db)
27//! .service(session_store.clone())
28//! .layer(modo_session::layer(session_store))
29//! .run()
30//! .await?;
31//! ```
32//!
33//! Then inject [`SessionManager`] as an extractor in any handler:
34//!
35//! ```rust,no_run
36//! async fn login(session: modo_session::SessionManager) -> modo::HandlerResult<()> {
37//! session.authenticate("user-123").await?;
38//! Ok(())
39//! }
40//! ```
41//!
42//! # Features
43//!
44//! - `cleanup-job` — registers a cron job (via `modo-jobs`) that deletes expired
45//! sessions every 15 minutes. Requires the `modo-jobs` crate.
46
47pub mod config;
48pub mod device;
49pub mod entity;
50pub mod fingerprint;
51pub mod manager;
52pub mod meta;
53pub mod middleware;
54pub mod store;
55pub mod types;
56
57#[cfg(feature = "cleanup-job")]
58pub mod cleanup;
59
60// Public API
61pub use config::SessionConfig;
62pub use manager::SessionManager;
63pub use meta::SessionMeta;
64pub use middleware::{layer, user_id_from_extensions};
65pub use store::SessionStore;
66pub use types::{SessionData, SessionId, SessionToken};
67
68// Re-exports for macro-generated code
69pub use chrono;
70pub use modo;
71pub use modo_db;
72pub use serde;
73pub use serde_json;