Skip to main content

synapse_pingora/session/
mod.rs

1//! Session State Management Module
2//!
3//! Provides session tracking with 50K LRU capacity and hijacking detection via JA4 fingerprint binding
4//! for the synapse-pingora WAF proxy.
5//!
6//! # Architecture
7//!
8//! The `SessionManager` coordinates three main data structures:
9//! - **sessions**: Primary DashMap storing SessionState by token_hash
10//! - **session_by_id**: O(1) lookup from session_id to token_hash
11//! - **actor_sessions**: O(1) lookup from actor_id to session_ids
12//!
13//! # Hijack Detection Strategy
14//!
15//! When validating a session, the manager checks for potential hijacking:
16//! 1. JA4 fingerprint mismatch detection (client fingerprint changed)
17//! 2. IP address change detection (optional, for strict mode)
18//! 3. Impossible travel detection (future enhancement)
19//!
20//! # Usage
21//!
22//! ```rust,ignore
23//! use synapse_pingora::session::{SessionManager, SessionConfig, SessionDecision};
24//! use std::sync::Arc;
25//!
26//! // Create manager with custom configuration
27//! let config = SessionConfig {
28//!     max_sessions: 50_000,
29//!     session_ttl_secs: 3600,
30//!     ..Default::default()
31//! };
32//! let manager = Arc::new(SessionManager::new(config));
33//!
34//! // Validate incoming request
35//! let ip = "192.168.1.100".parse().unwrap();
36//! let decision = manager.validate_request("token_hash_abc", ip, Some("t13d1516h2_abc123"));
37//!
38//! match decision {
39//!     SessionDecision::Valid => { /* continue processing */ }
40//!     SessionDecision::New => { /* new session created */ }
41//!     SessionDecision::Suspicious(alert) => { /* potential hijack */ }
42//!     SessionDecision::Expired => { /* session expired */ }
43//!     SessionDecision::Invalid(reason) => { /* invalid session */ }
44//! }
45//!
46//! // Start background cleanup tasks
47//! Arc::clone(&manager).start_background_tasks();
48//! ```
49
50mod manager;
51
52pub use manager::{
53    HijackAlert, HijackType, SessionConfig, SessionDecision, SessionManager, SessionState,
54    SessionStats, SessionStatsSnapshot,
55};