1#[cfg(feature = "lineage")]
23pub mod lineage;
24
25use serde::{Deserialize, Serialize};
26
27use crate::manifest::{NoFetcher, delete_manifest};
28use crate::schema::{
29 Hash, ManifestId, ModerationState, PrivacyClass, ProvenanceOrigin, ProvenanceRecord, SchemaRef,
30 Timestamp, TrustEnvelope, TrustLevel,
31};
32use crate::typed::{TypedPayload, list_typed, load_typed, save_typed};
33use crate::{Result, Store};
34
35const BROWSING_TRACE_SCHEMA_PAYLOAD: &[u8] = br#"{"format":"mere-native","schema_id":"eidetic.BrowsingTrace/v1","body":{"version":1,"description":"A chronological segment of one owner's browsing traversals.","required":["owner","events","started_at_ms","ended_at_ms"],"fields":{"owner":{"type":"string"},"events":{"type":"array"},"started_at_ms":{"type":"integer"},"ended_at_ms":{"type":"integer"}}}}"#;
39
40pub static BROWSING_TRACE_SCHEMA_REF: std::sync::LazyLock<SchemaRef> =
42 std::sync::LazyLock::new(|| {
43 SchemaRef::from_id(ManifestId::from_hash(Hash::of(
44 BROWSING_TRACE_SCHEMA_PAYLOAD,
45 )))
46 });
47
48pub async fn bootstrap_browsing_schema(store: &mut dyn Store) -> Result<()> {
52 let id = BROWSING_TRACE_SCHEMA_REF.0;
53 if crate::manifest::load_manifest(store, id).await?.is_some() {
54 return Ok(());
55 }
56 let local_key = format!("blob:{}", Hash::of(BROWSING_TRACE_SCHEMA_PAYLOAD).to_hex());
59 store.put(&local_key, BROWSING_TRACE_SCHEMA_PAYLOAD).await?;
60 let manifest = crate::manifest::BlobManifest {
61 id,
62 schema: *crate::schema_def::META_SCHEMA_REF,
63 content_hash: Hash::of(BROWSING_TRACE_SCHEMA_PAYLOAD),
64 byte_size: BROWSING_TRACE_SCHEMA_PAYLOAD.len() as u64,
65 created_at: Timestamp::ZERO,
66 last_accessed: None,
67 sources: vec![crate::manifest::BlobSource::Local { key: local_key }],
68 privacy: PrivacyClass::PublicPortable,
69 provenance: ProvenanceRecord {
70 origin: ProvenanceOrigin::Generated,
71 upstream: Vec::new(),
72 tooling: Some(format!("eidetic/{}", env!("CARGO_PKG_VERSION"))),
73 generated_at: Timestamp::ZERO,
74 },
75 trust: TrustEnvelope {
76 level: TrustLevel::CheckpointAccepted,
77 signatures: Vec::new(),
78 moderation_state: ModerationState::Accepted,
79 },
80 schema_metadata: serde_json::Value::Null,
81 manifest_version: crate::manifest::BlobManifest::CURRENT_VERSION,
82 };
83 crate::manifest::save_manifest(store, &manifest).await
84}
85
86#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
88pub struct PageRef {
89 pub url: String,
90 pub title: Option<String>,
91}
92
93#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
96pub enum TraceTransition {
97 LinkClick,
98 UrlTyped,
99 Back,
100 Forward,
101 Reload,
102 Redirect,
103 TabSpawn,
104 Restore,
105 Imported,
108 Unknown,
109}
110
111#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
113pub struct TraceEvent {
114 pub from: Option<PageRef>,
117 pub to: PageRef,
118 pub transition: TraceTransition,
119 pub at_ms: u64,
120 pub dwell_ms: Option<u64>,
123 #[serde(default)]
129 pub candidates: Vec<PageRef>,
130}
131
132#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
137pub struct BrowsingTrace {
138 pub owner: String,
139 pub events: Vec<TraceEvent>,
141 pub started_at_ms: u64,
142 pub ended_at_ms: u64,
143}
144
145impl BrowsingTrace {
146 pub fn from_events(owner: impl Into<String>, events: Vec<TraceEvent>) -> Self {
149 let started_at_ms = events.first().map(|e| e.at_ms).unwrap_or(0);
150 let ended_at_ms = events.last().map(|e| e.at_ms).unwrap_or(0);
151 Self {
152 owner: owner.into(),
153 events,
154 started_at_ms,
155 ended_at_ms,
156 }
157 }
158}
159
160impl TypedPayload for BrowsingTrace {
161 fn schema_ref() -> SchemaRef {
162 *BROWSING_TRACE_SCHEMA_REF
163 }
164}
165
166pub async fn save_trace(
169 store: &mut dyn Store,
170 trace: &BrowsingTrace,
171 now_ms: u64,
172) -> Result<ManifestId> {
173 save_typed(
174 store,
175 trace,
176 Vec::new(),
177 PrivacyClass::LocalOnly,
178 ProvenanceRecord {
179 origin: ProvenanceOrigin::Generated,
180 upstream: Vec::new(),
181 tooling: Some(format!("eidetic-browsing/{}", env!("CARGO_PKG_VERSION"))),
182 generated_at: Timestamp(now_ms),
183 },
184 TrustEnvelope {
185 level: TrustLevel::SelfAsserted,
186 signatures: Vec::new(),
187 moderation_state: ModerationState::Unreviewed,
188 },
189 Timestamp(now_ms),
190 )
191 .await
192}
193
194#[derive(Clone)]
197pub struct BrowsingMemory {
198 traces: Vec<(Option<ManifestId>, BrowsingTrace)>,
201 open: std::collections::BTreeMap<String, Vec<TraceEvent>>,
203 segment_size: usize,
207}
208
209impl BrowsingMemory {
210 pub fn new(segment_size: usize) -> Self {
213 Self {
214 traces: Vec::new(),
215 open: std::collections::BTreeMap::new(),
216 segment_size: segment_size.max(1),
217 }
218 }
219
220 pub async fn load(store: &mut dyn Store, segment_size: usize) -> Result<Self> {
222 let mut memory = Self::new(segment_size);
223 let mut fetcher = NoFetcher;
224 for manifest in list_typed::<BrowsingTrace>(store).await? {
225 if let Some(trace) =
226 load_typed::<BrowsingTrace>(store, &mut fetcher, manifest.id).await?
227 {
228 memory.traces.push((Some(manifest.id), trace));
229 }
230 }
231 memory.sort_traces();
232 Ok(memory)
233 }
234
235 fn sort_traces(&mut self) {
236 self.traces.sort_by_key(|(_, t)| t.ended_at_ms);
237 }
238
239 pub fn record_traversal(&mut self, owner: &str, event: TraceEvent) -> bool {
243 let segment = self.open.entry(owner.to_string()).or_default();
244 segment.push(event);
245 segment.len() >= self.segment_size
246 }
247
248 pub async fn flush(&mut self, store: &mut dyn Store, now_ms: u64) -> Result<Vec<ManifestId>> {
251 let mut ids = Vec::new();
252 let owners: Vec<String> = self.open.keys().cloned().collect();
253 for owner in owners {
254 let events = self.open.remove(&owner).unwrap_or_default();
255 if events.is_empty() {
256 continue;
257 }
258 let trace = BrowsingTrace::from_events(owner, events);
259 let id = save_trace(store, &trace, now_ms).await?;
260 ids.push(id);
261 self.traces.push((Some(id), trace));
262 }
263 self.sort_traces();
264 Ok(ids)
265 }
266
267 pub fn adopt(&mut self, trace: BrowsingTrace) {
271 self.traces.push((None, trace));
272 self.sort_traces();
273 }
274
275 fn all_events(&self) -> impl Iterator<Item = &TraceEvent> {
278 self.traces
279 .iter()
280 .flat_map(|(_, t)| t.events.iter())
281 .chain(self.open.values().flatten())
282 }
283
284 pub fn recent_corridor(&self, n: usize) -> Vec<TraceEvent> {
287 let all: Vec<&TraceEvent> = self.all_events().collect();
288 let start = all.len().saturating_sub(n);
289 all[start..].iter().map(|e| (*e).clone()).collect()
290 }
291
292 pub fn nodes_visited_in_window(&self, start_ms: u64, end_ms: u64) -> Vec<PageRef> {
295 let mut seen = std::collections::HashSet::new();
296 let mut out = Vec::new();
297 for event in self.all_events() {
298 if event.at_ms < start_ms || event.at_ms > end_ms {
299 continue;
300 }
301 if seen.insert(event.to.url.clone()) {
302 out.push(event.to.clone());
303 }
304 }
305 out
306 }
307
308 pub fn co_occurrence(&self, a: &str, b: &str) -> u32 {
314 self.all_events()
315 .filter(|e| {
316 let Some(from) = &e.from else { return false };
317 (from.url == a && e.to.url == b) || (from.url == b && e.to.url == a)
318 })
319 .count() as u32
320 }
321
322 pub fn traces(&self) -> impl Iterator<Item = &BrowsingTrace> {
324 self.traces.iter().map(|(_, t)| t)
325 }
326
327 pub async fn apply_quota(&mut self, store: &mut dyn Store, keep_n: usize) -> Result<usize> {
332 let stored: Vec<ManifestId> = self.traces.iter().filter_map(|(id, _)| *id).collect();
333 if stored.len() <= keep_n {
334 return Ok(0);
335 }
336 let overflow: Vec<ManifestId> = stored[..stored.len() - keep_n].to_vec();
338 let mut deleted = 0;
339 for id in &overflow {
340 if delete_manifest(store, *id).await? {
341 deleted += 1;
342 }
343 }
344 self.traces
345 .retain(|(id, _)| id.is_none_or(|id| !overflow.contains(&id)));
346 Ok(deleted)
347 }
348
349 pub async fn forget_url(&mut self, store: &mut dyn Store, url: &str) -> Result<usize> {
355 let mentions = |trace: &BrowsingTrace| {
356 trace
357 .events
358 .iter()
359 .any(|e| e.to.url == url || e.from.as_ref().is_some_and(|f| f.url == url))
360 };
361 let mut forgotten = 0;
362 let mut remaining = Vec::with_capacity(self.traces.len());
363 for (id, trace) in std::mem::take(&mut self.traces) {
364 if mentions(&trace) {
365 if let Some(id) = id {
366 delete_manifest(store, id).await?;
367 }
368 forgotten += 1;
369 } else {
370 remaining.push((id, trace));
371 }
372 }
373 self.traces = remaining;
374 for events in self.open.values_mut() {
376 events.retain(|e| !(e.to.url == url || e.from.as_ref().is_some_and(|f| f.url == url)));
377 }
378 Ok(forgotten)
379 }
380}
381
382#[cfg(test)]
383mod tests;