1use std::fs::{self, OpenOptions};
2use std::io::{Read, Write};
3use std::path::{Path, PathBuf};
4use std::sync::atomic::{AtomicU64, Ordering};
5use std::time::{SystemTime, UNIX_EPOCH};
6
7use anyhow::{Context, Result, ensure};
8
9use crate::{AgentId, FileEvent, SessionKey};
10
11pub(crate) const MAX_BATCH_BYTES: u64 = 16 * 1024 * 1024;
12
13#[derive(Debug, Default)]
14pub struct ReadReport {
15 pub events: Vec<FileEvent>,
16 pub warnings: Vec<BatchWarning>,
17}
18
19#[derive(Debug, Default)]
20pub struct SessionReport {
21 pub sessions: Vec<SessionKey>,
22 pub warnings: Vec<BatchWarning>,
23}
24
25#[derive(Debug)]
26pub struct BatchWarning {
27 pub path: PathBuf,
28 pub message: String,
29}
30
31static NEXT_BATCH: AtomicU64 = AtomicU64::new(0);
32
33#[derive(Clone, Debug)]
37pub struct Store {
38 root: PathBuf,
39}
40
41impl Store {
42 pub fn new(root: impl Into<PathBuf>) -> Self {
43 Self { root: root.into() }
44 }
45
46 pub(crate) fn directory(&self, session: &SessionKey) -> Result<PathBuf> {
47 session.validate()?;
48 Ok(self.root.join(session.agent.as_str()).join(&session.session_id))
49 }
50
51 pub fn sessions(&self) -> SessionReport {
54 let mut report = SessionReport::default();
55 let namespaces = match fs::read_dir(&self.root) {
56 Ok(entries) => entries,
57 Err(e) if e.kind() == std::io::ErrorKind::NotFound => return report,
58 Err(e) => {
59 report.warnings.push(BatchWarning { path: self.root.clone(), message: e.to_string() });
60 return report;
61 }
62 };
63 for entry in namespaces {
64 let entry = match entry {
65 Ok(entry) => entry,
66 Err(error) => {
67 report.warnings.push(BatchWarning { path: self.root.clone(), message: error.to_string() });
68 continue;
69 }
70 };
71 let namespace = (|| -> Result<Option<AgentId>> {
72 let kind = entry.file_type()?;
73 ensure!(!kind.is_symlink(), "agent namespace must be a directory, not a symlink");
74 if !kind.is_dir() {
75 return Ok(None);
76 }
77 let name = entry.file_name().into_string().map_err(|_| anyhow::anyhow!("invalid agent namespace"))?;
78 Ok(Some(AgentId::new(name)?))
79 })();
80 match namespace {
81 Ok(Some(agent)) => self.sessions_in(agent, &entry.path(), &mut report),
82 Ok(None) => {}
83 Err(error) => report.warnings.push(BatchWarning { path: entry.path(), message: format!("{error:#}") }),
84 }
85 }
86 report.sessions.sort_by(|a, b| a.agent.cmp(&b.agent).then_with(|| a.session_id.cmp(&b.session_id)));
87 report
88 }
89
90 fn sessions_in(&self, agent: AgentId, path: &Path, report: &mut SessionReport) {
91 let entries = match fs::read_dir(path) {
92 Ok(entries) => entries,
93 Err(error) => {
94 report.warnings.push(BatchWarning { path: path.to_path_buf(), message: error.to_string() });
95 return;
96 }
97 };
98 for entry in entries {
99 let entry = match entry {
100 Ok(entry) => entry,
101 Err(error) => {
102 report.warnings.push(BatchWarning { path: path.to_path_buf(), message: error.to_string() });
103 continue;
104 }
105 };
106 let result = (|| -> Result<Option<SessionKey>> {
107 let kind = entry.file_type()?;
108 ensure!(!kind.is_symlink(), "session directory symlinks are not followed");
109 if !kind.is_dir() {
110 return Ok(None);
111 }
112 let session_id =
113 entry.file_name().into_string().map_err(|_| anyhow::anyhow!("invalid session directory name"))?;
114 let key = SessionKey { agent: agent.clone(), session_id };
115 key.validate()?;
116 Ok(Some(key))
117 })();
118 match result {
119 Ok(Some(key)) => report.sessions.push(key),
120 Ok(None) => {}
121 Err(error) => report.warnings.push(BatchWarning { path: entry.path(), message: format!("{error:#}") }),
122 }
123 }
124 }
125
126 pub fn read_all(&self) -> ReadReport {
130 let sessions = self.sessions();
131 let mut report = ReadReport { events: Vec::new(), warnings: sessions.warnings };
132 for key in sessions.sessions {
133 match self.read(&key) {
134 Ok(mut read) => {
135 report.events.append(&mut read.events);
136 report.warnings.append(&mut read.warnings);
137 }
138 Err(error) => report.warnings.push(BatchWarning {
139 path: self.root.join(key.agent.as_str()).join(&key.session_id),
140 message: format!("{error:#}"),
141 }),
142 }
143 }
144 report.events.sort_by_key(|e| e.timestamp);
145 report
146 }
147
148 pub fn append(&self, session: &SessionKey, events: &[FileEvent]) -> Result<()> {
149 let Some(dir) = self.prepare(session, events)? else { return Ok(()) };
150 let _lock = crate::lock::Lock::acquire(&dir, false)?;
151 self.append_unlocked(&dir, events)
152 }
153
154 pub fn append_new(&self, session: &SessionKey, events: &[FileEvent]) -> Result<usize> {
159 let Some(dir) = self.prepare(session, events)? else { return Ok(0) };
160 let _lock = crate::lock::Lock::acquire(&dir, true)?;
161 let report = self.read_unlocked(session)?;
162 let mut seen: std::collections::HashSet<_> = report.events.iter().map(identity).collect();
163 let fresh: Vec<_> = events.iter().filter(|e| seen.insert(identity(e))).cloned().collect();
164 self.append_unlocked(&dir, &fresh)?;
165 Ok(fresh.len())
166 }
167
168 fn prepare(&self, session: &SessionKey, events: &[FileEvent]) -> Result<Option<PathBuf>> {
169 let dir = self.directory(session)?;
170 if events.is_empty() {
171 return Ok(None);
172 }
173 validate_batch(session, events)?;
174 let missing: Vec<_> =
175 dir.ancestors().take_while(|p| !p.as_os_str().is_empty() && !p.exists()).map(Path::to_path_buf).collect();
176 let mut builder = fs::DirBuilder::new();
177 builder.recursive(true);
178 #[cfg(unix)]
179 {
180 use std::os::unix::fs::DirBuilderExt;
181 builder.mode(0o700);
182 }
183 builder.create(&dir)?;
184 for path in missing {
186 sync_directory(&path)?;
187 if let Some(parent) = path.parent() {
188 sync_directory(if parent.as_os_str().is_empty() { Path::new(".") } else { parent })?;
189 }
190 }
191 Ok(Some(dir))
192 }
193
194 fn append_unlocked(&self, dir: &Path, events: &[FileEvent]) -> Result<()> {
195 let cutoff = crate::maintenance::retained_from(dir)?;
196 let retained: Vec<_> = events.iter().filter(|e| cutoff.is_none_or(|at| e.timestamp >= at)).collect();
197 if retained.is_empty() {
198 return Ok(());
199 }
200 let bytes = serde_json::to_vec(&retained)?;
201 ensure!(bytes.len() as u64 <= MAX_BATCH_BYTES, "activity batch exceeds 16 MiB limit");
202 let nonce = SystemTime::now().duration_since(UNIX_EPOCH)?.as_nanos();
203 let name = format!("{nonce:039}-{}-{}", std::process::id(), NEXT_BATCH.fetch_add(1, Ordering::Relaxed));
204 let temporary = dir.join(format!("{name}.tmp"));
205 let destination = dir.join(format!("{name}.json"));
206 let result = write_batch(&temporary, &bytes).and_then(|()| {
207 fs::rename(&temporary, destination).context("publishing activity batch")?;
208 sync_directory(dir)
209 });
210 if result.is_err() {
211 let _ = fs::remove_file(&temporary);
212 }
213 result
214 }
215
216 pub fn events(&self, session: &SessionKey) -> Result<Vec<FileEvent>> {
218 let report = self.read(session)?;
219 ensure!(
220 report.warnings.is_empty(),
221 "incomplete activity history: {}",
222 report
223 .warnings
224 .iter()
225 .map(|w| format!("{}: {}", w.path.display(), w.message))
226 .collect::<Vec<_>>()
227 .join("; ")
228 );
229 Ok(report.events)
230 }
231
232 pub fn read(&self, session: &SessionKey) -> Result<ReadReport> {
235 let dir = self.directory(session)?;
236 if !dir.try_exists()? {
237 return Ok(ReadReport::default());
238 }
239 let _lock = crate::lock::Lock::acquire(&dir, false)?;
240 self.read_unlocked(session)
241 }
242
243 pub(crate) fn read_unlocked(&self, session: &SessionKey) -> Result<ReadReport> {
244 let dir = self.directory(session)?;
245 let paths = crate::maintenance::active_paths(&dir)?;
246 let mut report = ReadReport::default();
247 for path in paths {
248 match read_batch(&path, session) {
249 Ok(batch) => report.events.extend(batch),
250 Err(error) => report.warnings.push(BatchWarning { path, message: format!("{error:#}") }),
251 }
252 }
253 report.events.sort_by_key(|e| e.timestamp);
254 if let Some(cutoff) = crate::maintenance::retained_from(&dir)? {
255 report.events.retain(|event| event.timestamp >= cutoff);
256 }
257 Ok(report)
258 }
259}
260
261type Identity<'a> =
262 (i64, &'a Path, Option<&'a Path>, &'a Path, crate::Operation, crate::Source, crate::Outcome, Option<&'a str>);
263
264fn identity(event: &FileEvent) -> Identity<'_> {
265 (
266 event.timestamp,
267 &event.path,
268 event.previous_path.as_deref(),
269 &event.cwd,
270 event.operation,
271 event.source,
272 event.outcome,
273 event.tool_call_id.as_deref(),
274 )
275}
276
277pub(crate) fn write_batch(path: &Path, bytes: &[u8]) -> Result<()> {
278 let mut options = OpenOptions::new();
279 options.write(true).create_new(true);
280 #[cfg(unix)]
281 {
282 use std::os::unix::fs::OpenOptionsExt;
283 options.mode(0o600);
284 }
285 let mut file = options.open(path)?;
286 file.write_all(bytes)?;
287 file.sync_all()?;
288 Ok(())
289}
290
291fn validate_batch(session: &SessionKey, events: &[FileEvent]) -> Result<()> {
292 for event in events {
293 ensure!(&event.session == session, "event belongs to a different session");
294 ensure!((1..=crate::SCHEMA_VERSION).contains(&event.schema_version), "unsupported activity schema");
295 ensure!(event.path.is_absolute() && event.cwd.is_absolute(), "event paths must be absolute");
296 ensure!(event.previous_path.as_ref().is_none_or(|p| p.is_absolute()), "rename origin must be absolute");
297 ensure!(
298 (event.operation == crate::Operation::Rename) == event.previous_path.is_some(),
299 "rename operation and origin must agree"
300 );
301 }
302 Ok(())
303}
304
305fn read_batch(path: &Path, session: &SessionKey) -> Result<Vec<FileEvent>> {
306 ensure!(fs::symlink_metadata(path)?.file_type().is_file(), "batch must be a regular file");
307 let mut bytes = Vec::new();
308 fs::File::open(path)?.take(MAX_BATCH_BYTES + 1).read_to_end(&mut bytes)?;
309 ensure!(bytes.len() as u64 <= MAX_BATCH_BYTES, "activity batch exceeds 16 MiB limit");
310 let events = serde_json::from_slice::<Vec<FileEvent>>(&bytes)?;
311 validate_batch(session, &events)?;
312 Ok(events)
313}
314
315pub(crate) fn sync_directory(path: &Path) -> Result<()> {
316 #[cfg(unix)]
317 fs::File::open(path)?.sync_all().with_context(|| format!("syncing {}", path.display()))?;
318 #[cfg(not(unix))]
319 let _ = path;
320 Ok(())
321}