1use super::{AuditBackend, AuditEvent, ErrorSink, IgnoreErrors, WriteError};
37use std::fs::{File, OpenOptions};
38use std::io::{BufWriter, Write};
39use std::path::{Path, PathBuf};
40use std::sync::Arc;
41use std::sync::Mutex;
42use std::time::{Duration, SystemTime};
43
44#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
46pub struct RotationPolicy {
47 pub max_bytes: Option<u64>,
49 pub max_age: Option<Duration>,
51 pub keep: Option<usize>,
53}
54
55impl RotationPolicy {
56 #[must_use]
58 pub const fn never() -> Self {
59 Self {
60 max_bytes: None,
61 max_age: None,
62 keep: None,
63 }
64 }
65
66 #[must_use]
68 pub const fn size(bytes: u64) -> Self {
69 Self {
70 max_bytes: Some(bytes),
71 max_age: None,
72 keep: None,
73 }
74 }
75
76 #[must_use]
78 pub const fn age(age: Duration) -> Self {
79 Self {
80 max_bytes: None,
81 max_age: Some(age),
82 keep: None,
83 }
84 }
85
86 #[must_use]
88 pub const fn keeping(mut self, n: usize) -> Self {
89 self.keep = Some(n);
90 self
91 }
92
93 fn should_rotate(self, size: u64, opened_at: SystemTime) -> bool {
95 if self.max_bytes.is_some_and(|limit| size >= limit) {
96 return true;
97 }
98 self.max_age
99 .is_some_and(|limit| opened_at.elapsed().is_ok_and(|elapsed| elapsed >= limit))
100 }
101}
102
103struct OpenFile {
105 writer: BufWriter<File>,
106 bytes: u64,
107 opened_at: SystemTime,
108}
109
110pub struct FileBackend {
128 path: PathBuf,
129 file: Mutex<OpenFile>,
130 rotation: RotationPolicy,
131 sync_on_write: bool,
132 errors: Arc<dyn ErrorSink>,
133}
134
135impl FileBackend {
136 #[must_use]
138 pub fn builder<P: Into<PathBuf>>(path: P) -> FileBackendBuilder {
139 FileBackendBuilder {
140 path: path.into(),
141 rotation: RotationPolicy::never(),
142 sync_on_write: false,
143 errors: Arc::new(IgnoreErrors),
144 }
145 }
146
147 pub fn new<P: Into<PathBuf>>(path: P) -> std::io::Result<Self> {
153 Self::builder(path).build()
154 }
155
156 #[must_use]
158 pub fn path(&self) -> &Path {
159 &self.path
160 }
161
162 pub fn reopen(&self) -> std::io::Result<()> {
174 let mut guard = self.lock();
175 drop(guard.writer.flush());
178 *guard = open_at(&self.path)?;
179 Ok(())
180 }
181
182 #[must_use]
184 pub fn current_size(&self) -> u64 {
185 self.lock().bytes
186 }
187
188 pub fn rotate(&self) -> std::io::Result<()> {
194 let mut guard = self.lock();
195 self.rotate_locked(&mut guard)
196 }
197
198 fn lock(&self) -> std::sync::MutexGuard<'_, OpenFile> {
204 self.file
205 .lock()
206 .unwrap_or_else(std::sync::PoisonError::into_inner)
207 }
208
209 fn rotate_locked(&self, guard: &mut OpenFile) -> std::io::Result<()> {
211 guard.writer.flush()?;
212
213 let rotated = self.rotated_path();
214 std::fs::rename(&self.path, &rotated)?;
215 *guard = open_at(&self.path)?;
216
217 if let Some(keep) = self.rotation.keep {
218 self.prune(keep);
219 }
220 Ok(())
221 }
222
223 fn rotated_path(&self) -> PathBuf {
229 let stamp = SystemTime::now()
230 .duration_since(SystemTime::UNIX_EPOCH)
231 .map_or(0, |d| d.as_secs());
232
233 let base = self.path.as_os_str().to_string_lossy().into_owned();
234 for counter in 0..u32::MAX {
235 let candidate = if counter == 0 {
236 PathBuf::from(format!("{base}.{stamp}"))
237 } else {
238 PathBuf::from(format!("{base}.{stamp}.{counter}"))
239 };
240 if !candidate.exists() {
241 return candidate;
242 }
243 }
244 PathBuf::from(format!("{base}.{stamp}.overflow"))
245 }
246
247 fn prune(&self, keep: usize) {
252 let Some(dir) = self.path.parent() else {
253 return;
254 };
255 let Some(name) = self.path.file_name().and_then(|n| n.to_str()) else {
256 return;
257 };
258 let prefix = format!("{name}.");
259
260 let Ok(entries) = std::fs::read_dir(dir) else {
261 return;
262 };
263 let mut rotated: Vec<PathBuf> = entries
264 .flatten()
265 .map(|entry| entry.path())
266 .filter(|path| {
267 path.file_name()
268 .and_then(|n| n.to_str())
269 .is_some_and(|n| n.starts_with(&prefix))
270 })
271 .collect();
272
273 if rotated.len() <= keep {
274 return;
275 }
276 rotated.sort();
279 let excess = rotated.len() - keep;
280 for path in rotated.into_iter().take(excess) {
281 drop(std::fs::remove_file(path));
282 }
283 }
284
285 fn write_line(&self, line: &str) -> std::io::Result<()> {
287 let mut guard = self.lock();
288
289 if self.rotation.should_rotate(guard.bytes, guard.opened_at) {
290 self.rotate_locked(&mut guard)?;
291 }
292
293 guard.writer.write_all(line.as_bytes())?;
294 guard.writer.write_all(b"\n")?;
295 guard.writer.flush()?;
298
299 if self.sync_on_write {
300 guard.writer.get_ref().sync_data()?;
301 }
302
303 guard.bytes += line.len() as u64 + 1;
304 Ok(())
305 }
306
307 fn write_value<T: serde::Serialize>(&self, value: &T) {
309 let line = match serde_json::to_string(value) {
310 Ok(line) => line,
311 Err(e) => {
312 self.errors.on_error(&WriteError {
313 backend: "FileBackend",
314 source: std::io::Error::other(e),
315 events_lost: 1,
316 });
317 return;
318 }
319 };
320
321 if let Err(source) = self.write_line(&line) {
322 self.errors.on_error(&WriteError {
323 backend: "FileBackend",
324 source,
325 events_lost: 1,
326 });
327 }
328 }
329}
330
331fn open_at(path: &Path) -> std::io::Result<OpenFile> {
333 if let Some(parent) = path.parent()
334 && !parent.as_os_str().is_empty()
335 {
336 std::fs::create_dir_all(parent)?;
337 }
338
339 let file = OpenOptions::new().create(true).append(true).open(path)?;
340 let bytes = file.metadata().map_or(0, |m| m.len());
341
342 Ok(OpenFile {
343 writer: BufWriter::new(file),
344 bytes,
345 opened_at: SystemTime::now(),
346 })
347}
348
349impl AuditBackend for FileBackend {
350 fn log_audit(&self, event: &AuditEvent) {
351 self.write_value(event);
352 }
353
354 fn security_log(&self, event: &serde_json::Value) {
355 self.write_value(event);
356 }
357
358 fn flush(&self) {
359 let mut guard = self.lock();
360 if let Err(source) = guard.writer.flush() {
361 self.errors.on_error(&WriteError {
362 backend: "FileBackend",
363 source,
364 events_lost: 0,
365 });
366 }
367 }
368}
369
370impl std::fmt::Debug for FileBackend {
371 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
372 f.debug_struct("FileBackend")
373 .field("path", &self.path)
374 .field("rotation", &self.rotation)
375 .field("sync_on_write", &self.sync_on_write)
376 .finish_non_exhaustive()
377 }
378}
379
380pub struct FileBackendBuilder {
382 path: PathBuf,
383 rotation: RotationPolicy,
384 sync_on_write: bool,
385 errors: Arc<dyn ErrorSink>,
386}
387
388impl FileBackendBuilder {
389 #[must_use]
391 pub const fn rotation(mut self, rotation: RotationPolicy) -> Self {
392 self.rotation = rotation;
393 self
394 }
395
396 #[must_use]
401 pub const fn sync_on_write(mut self, sync: bool) -> Self {
402 self.sync_on_write = sync;
403 self
404 }
405
406 #[must_use]
408 pub fn errors(mut self, errors: Arc<dyn ErrorSink>) -> Self {
409 self.errors = errors;
410 self
411 }
412
413 pub fn build(self) -> std::io::Result<FileBackend> {
420 Ok(FileBackend {
421 file: Mutex::new(open_at(&self.path)?),
422 path: self.path,
423 rotation: self.rotation,
424 sync_on_write: self.sync_on_write,
425 errors: self.errors,
426 })
427 }
428}
429
430#[cfg(test)]
431mod tests {
432 use super::*;
433 use crate::{AuditEventType, AuditResult, CountingErrorSink};
434
435 struct TempDir(PathBuf);
437
438 impl TempDir {
439 fn new(name: &str) -> Self {
440 let mut path = std::env::temp_dir();
441 path.push(format!("ash-log-test-{name}-{}", std::process::id()));
442 drop(std::fs::remove_dir_all(&path));
443 std::fs::create_dir_all(&path).expect("create scratch dir");
444 Self(path)
445 }
446
447 fn join(&self, name: &str) -> PathBuf {
448 self.0.join(name)
449 }
450 }
451
452 impl Drop for TempDir {
453 fn drop(&mut self) {
454 drop(std::fs::remove_dir_all(&self.0));
455 }
456 }
457
458 fn event(n: usize) -> AuditEvent {
459 AuditEvent::builder()
460 .event_type(AuditEventType::AdminAction)
461 .method(format!("action{n}"))
462 .result(AuditResult::Success)
463 .build()
464 }
465
466 fn lines(path: &Path) -> Vec<String> {
467 std::fs::read_to_string(path)
468 .unwrap_or_default()
469 .lines()
470 .map(ToString::to_string)
471 .collect()
472 }
473
474 #[test]
475 fn test_events_are_written_as_json_lines() {
476 let dir = TempDir::new("write");
477 let path = dir.join("audit.jsonl");
478 let backend = FileBackend::new(&path).expect("open");
479
480 backend.log_audit(&event(0));
481 backend.log_audit(&event(1));
482
483 let written = lines(&path);
484 assert_eq!(written.len(), 2, "one line per event");
485 for line in &written {
486 let parsed: AuditEvent = serde_json::from_str(line).expect("each line parses");
487 assert_eq!(parsed.event_type, AuditEventType::AdminAction);
488 }
489 }
490
491 #[test]
492 fn test_reopening_appends_rather_than_truncating() {
493 let dir = TempDir::new("append");
496 let path = dir.join("audit.jsonl");
497
498 {
499 let backend = FileBackend::new(&path).expect("open");
500 backend.log_audit(&event(0));
501 }
502 {
503 let backend = FileBackend::new(&path).expect("reopen");
504 backend.log_audit(&event(1));
505 }
506
507 assert_eq!(
508 lines(&path).len(),
509 2,
510 "the earlier event survives a restart"
511 );
512 }
513
514 #[test]
515 fn test_size_rotation_starts_a_new_file() {
516 let dir = TempDir::new("rotate-size");
517 let path = dir.join("audit.jsonl");
518 let backend = FileBackend::builder(&path)
519 .rotation(RotationPolicy::size(200))
520 .build()
521 .expect("open");
522
523 for n in 0..10 {
524 backend.log_audit(&event(n));
525 }
526
527 assert!(
528 backend.current_size() < 400,
529 "the live file stays near the limit rather than growing without bound"
530 );
531
532 let rotated: Vec<_> = std::fs::read_dir(&dir.0)
533 .expect("read dir")
534 .flatten()
535 .filter(|e| e.file_name() != "audit.jsonl")
536 .collect();
537 assert!(!rotated.is_empty(), "at least one file was rotated aside");
538 }
539
540 #[test]
541 fn test_no_events_are_lost_across_rotation() {
542 let dir = TempDir::new("rotate-complete");
545 let path = dir.join("audit.jsonl");
546 let backend = FileBackend::builder(&path)
547 .rotation(RotationPolicy::size(150))
548 .build()
549 .expect("open");
550
551 for n in 0..20 {
552 backend.log_audit(&event(n));
553 }
554 backend.flush();
555
556 let mut total = 0;
557 for entry in std::fs::read_dir(&dir.0).expect("read dir").flatten() {
558 total += lines(&entry.path()).len();
559 }
560 assert_eq!(total, 20, "every event is in one file or another");
561 }
562
563 #[test]
564 fn test_keep_prunes_the_oldest_files() {
565 let dir = TempDir::new("prune");
566 let path = dir.join("audit.jsonl");
567 let backend = FileBackend::builder(&path)
568 .rotation(RotationPolicy::size(120).keeping(2))
569 .build()
570 .expect("open");
571
572 for n in 0..30 {
573 backend.log_audit(&event(n));
574 }
575
576 let rotated = std::fs::read_dir(&dir.0)
577 .expect("read dir")
578 .flatten()
579 .filter(|e| e.file_name() != "audit.jsonl")
580 .count();
581 assert!(
582 rotated <= 2,
583 "retention keeps at most 2 rotated files, found {rotated}"
584 );
585 }
586
587 #[test]
588 fn test_explicit_rotate_renames_the_current_file() {
589 let dir = TempDir::new("manual");
590 let path = dir.join("audit.jsonl");
591 let backend = FileBackend::new(&path).expect("open");
592
593 backend.log_audit(&event(0));
594 backend.rotate().expect("rotate");
595 backend.log_audit(&event(1));
596
597 assert_eq!(
598 lines(&path).len(),
599 1,
600 "the live file holds only what followed"
601 );
602 assert_eq!(backend.current_size(), lines(&path)[0].len() as u64 + 1);
603 }
604
605 #[test]
606 fn test_reopen_recreates_a_file_moved_aside() {
607 let dir = TempDir::new("reopen");
610 let path = dir.join("audit.jsonl");
611 let moved = dir.join("audit.jsonl.1");
612 let backend = FileBackend::new(&path).expect("open");
613
614 backend.log_audit(&event(0));
615 std::fs::rename(&path, &moved).expect("external rotation");
616
617 backend.reopen().expect("reopen");
618 backend.log_audit(&event(1));
619
620 assert_eq!(lines(&moved).len(), 1, "the archived file keeps its event");
621 assert_eq!(
622 lines(&path).len(),
623 1,
624 "the new file receives the next event"
625 );
626 }
627
628 #[test]
629 fn test_write_failures_reach_the_error_sink() {
630 let dir = TempDir::new("errors");
633 let path = dir.join("audit.jsonl");
634 let sink = Arc::new(CountingErrorSink::new());
635 let backend = FileBackend::builder(&path)
636 .rotation(RotationPolicy::size(1))
637 .errors(sink.clone())
638 .build()
639 .expect("open");
640
641 #[cfg(unix)]
644 {
645 use std::os::unix::fs::PermissionsExt;
646 let mut perms = std::fs::metadata(&dir.0).expect("stat").permissions();
647 perms.set_mode(0o500); std::fs::set_permissions(&dir.0, perms).expect("chmod");
649 }
650
651 backend.log_audit(&event(0));
652 backend.log_audit(&event(1));
653
654 #[cfg(unix)]
656 {
657 use std::os::unix::fs::PermissionsExt;
658 let mut perms = std::fs::metadata(&dir.0).expect("stat").permissions();
659 perms.set_mode(0o700);
660 std::fs::set_permissions(&dir.0, perms).expect("chmod");
661 }
662
663 #[cfg(unix)]
664 {
665 assert!(
666 sink.had_failures(),
667 "a failed write is reported rather than silently dropped"
668 );
669 assert!(sink.events_lost() >= 1, "lost events are counted");
670 }
671 }
672
673 #[test]
674 fn test_a_deleted_file_does_not_look_like_a_write_failure() {
675 let dir = TempDir::new("unlinked");
679 let path = dir.join("audit.jsonl");
680 let sink = Arc::new(CountingErrorSink::new());
681 let backend = FileBackend::builder(&path)
682 .errors(sink.clone())
683 .build()
684 .expect("open");
685
686 std::fs::remove_file(&path).expect("unlink");
687 backend.log_audit(&event(0));
688
689 assert!(
690 !sink.had_failures(),
691 "the OS accepts the write, so no error is reported"
692 );
693 assert!(!path.exists(), "but the event is not in the log");
694
695 backend.reopen().expect("reopen recreates the path");
696 backend.log_audit(&event(1));
697 assert_eq!(lines(&path).len(), 1, "events land again after reopen");
698 }
699
700 #[test]
701 fn test_concurrent_writers_produce_intact_lines() {
702 let dir = TempDir::new("concurrent");
705 let path = dir.join("audit.jsonl");
706 let backend = Arc::new(FileBackend::new(&path).expect("open"));
707
708 let mut handles = Vec::new();
709 for _ in 0..8 {
710 let backend = backend.clone();
711 handles.push(std::thread::spawn(move || {
712 for n in 0..25 {
713 backend.log_audit(&event(n));
714 }
715 }));
716 }
717 for handle in handles {
718 handle.join().expect("worker panicked");
719 }
720 backend.flush();
721
722 let written = lines(&path);
723 assert_eq!(written.len(), 200);
724 for line in &written {
725 serde_json::from_str::<AuditEvent>(line).expect("no interleaved line");
726 }
727 }
728
729 #[test]
730 fn test_rotation_policy_predicates() {
731 let now = SystemTime::now();
732 assert!(!RotationPolicy::never().should_rotate(u64::MAX, now));
733 assert!(RotationPolicy::size(100).should_rotate(100, now));
734 assert!(!RotationPolicy::size(100).should_rotate(99, now));
735
736 let old = now - Duration::from_secs(120);
737 assert!(RotationPolicy::age(Duration::from_secs(60)).should_rotate(0, old));
738 assert!(!RotationPolicy::age(Duration::from_secs(600)).should_rotate(0, old));
739 }
740}