systemprompt_traits/
analytics.rs

1use async_trait::async_trait;
2use chrono::{DateTime, Utc};
3use http::{HeaderMap, Uri};
4use std::sync::Arc;
5use systemprompt_identifiers::{SessionId, SessionSource, UserId};
6
7pub type AnalyticsResult<T> = Result<T, AnalyticsProviderError>;
8
9#[derive(Debug, thiserror::Error)]
10#[non_exhaustive]
11pub enum AnalyticsProviderError {
12    #[error("Session not found")]
13    SessionNotFound,
14
15    #[error("Fingerprint not found")]
16    FingerprintNotFound,
17
18    #[error("Internal error: {0}")]
19    Internal(String),
20}
21
22impl From<anyhow::Error> for AnalyticsProviderError {
23    fn from(err: anyhow::Error) -> Self {
24        Self::Internal(err.to_string())
25    }
26}
27
28#[derive(Debug, Clone, Default)]
29pub struct SessionAnalytics {
30    pub ip_address: Option<String>,
31    pub user_agent: Option<String>,
32    pub device_type: Option<String>,
33    pub browser: Option<String>,
34    pub os: Option<String>,
35    pub fingerprint_hash: Option<String>,
36    pub referer: Option<String>,
37    pub referrer_url: Option<String>,
38    pub referrer_source: Option<String>,
39    pub accept_language: Option<String>,
40    pub preferred_locale: Option<String>,
41    pub screen_width: Option<i32>,
42    pub screen_height: Option<i32>,
43    pub timezone: Option<String>,
44    pub page_url: Option<String>,
45    pub landing_page: Option<String>,
46    pub entry_url: Option<String>,
47    pub country: Option<String>,
48    pub region: Option<String>,
49    pub city: Option<String>,
50    pub utm_source: Option<String>,
51    pub utm_medium: Option<String>,
52    pub utm_campaign: Option<String>,
53}
54
55impl SessionAnalytics {
56    pub fn is_bot(&self) -> bool {
57        self.user_agent.as_ref().is_some_and(|ua| {
58            let ua_lower = ua.to_lowercase();
59            ua_lower.contains("bot")
60                || ua_lower.contains("crawler")
61                || ua_lower.contains("spider")
62                || ua_lower.contains("headless")
63        })
64    }
65
66    pub fn compute_fingerprint(&self) -> String {
67        use xxhash_rust::xxh64::xxh64;
68
69        if let Some(hash) = &self.fingerprint_hash {
70            return hash.clone();
71        }
72
73        let data = format!(
74            "{}|{}",
75            self.user_agent.as_deref().unwrap_or(""),
76            self.accept_language
77                .as_deref()
78                .or(self.preferred_locale.as_deref())
79                .unwrap_or("")
80        );
81
82        format!("fp_{:016x}", xxh64(data.as_bytes(), 0))
83    }
84}
85
86#[derive(Debug, Clone)]
87pub struct AnalyticsSession {
88    pub session_id: String,
89    pub user_id: Option<String>,
90    pub fingerprint: Option<String>,
91    pub created_at: DateTime<Utc>,
92}
93
94#[derive(Debug)]
95pub struct CreateSessionInput<'a> {
96    pub session_id: &'a SessionId,
97    pub user_id: Option<&'a UserId>,
98    pub analytics: &'a SessionAnalytics,
99    pub session_source: SessionSource,
100    pub is_bot: bool,
101    pub expires_at: DateTime<Utc>,
102}
103
104#[async_trait]
105pub trait AnalyticsProvider: Send + Sync {
106    fn extract_analytics(&self, headers: &HeaderMap, uri: Option<&Uri>) -> SessionAnalytics;
107
108    async fn create_session(&self, input: CreateSessionInput<'_>) -> AnalyticsResult<()>;
109
110    async fn find_recent_session_by_fingerprint(
111        &self,
112        fingerprint: &str,
113        max_age_seconds: i64,
114    ) -> AnalyticsResult<Option<AnalyticsSession>>;
115
116    async fn find_session_by_id(
117        &self,
118        session_id: &SessionId,
119    ) -> AnalyticsResult<Option<AnalyticsSession>>;
120
121    async fn migrate_user_sessions(
122        &self,
123        from_user_id: &UserId,
124        to_user_id: &UserId,
125    ) -> AnalyticsResult<u64>;
126}
127
128#[async_trait]
129pub trait FingerprintProvider: Send + Sync {
130    async fn count_active_sessions(&self, fingerprint: &str) -> AnalyticsResult<i64>;
131
132    async fn find_reusable_session(&self, fingerprint: &str) -> AnalyticsResult<Option<String>>;
133
134    async fn upsert_fingerprint(
135        &self,
136        fingerprint: &str,
137        ip_address: Option<&str>,
138        user_agent: Option<&str>,
139        screen_info: Option<&str>,
140    ) -> AnalyticsResult<()>;
141}
142
143pub type DynAnalyticsProvider = Arc<dyn AnalyticsProvider>;
144pub type DynFingerprintProvider = Arc<dyn FingerprintProvider>;
systemprompt_traits/analytics.rs

systemprompt_traits/
analytics.rs
