Skip to main content

ash_log/
file.rs

1//! Writing audit events to a file, with rotation.
2//!
3//! # Durability
4//!
5//! Each event is written and flushed to the OS before [`log_audit`] returns, so
6//! a crashed process does not lose entries already accepted. It is *not*
7//! `fsync`ed by default: a power loss can still lose recently written lines.
8//! Enable [`FileBackendBuilder::sync_on_write`] where that matters, at a
9//! substantial cost in throughput.
10//!
11//! # Rotation
12//!
13//! Rotation is driven by size, by age, or both, and is checked before each
14//! write. The current file is renamed with a numeric suffix and a fresh one
15//! opened, oldest files being removed once the retention limit is reached.
16//!
17//! Because rotation renames the *file*, a chain spanning several files is still
18//! one chain: `chain_index` continues across the boundary and
19//! [`HmacChainIntegrity::verify_chain`](crate::HmacChainIntegrity::verify_chain)
20//! accepts the concatenation of the rotated files in order.
21//!
22//! Reassemble those files by sorting the *entries* on `chain_index`, not by
23//! filename. Rotated names embed a timestamp, but two rotations within the same
24//! second fall back to a numeric suffix that does not sort lexicographically
25//! (`.10` orders before `.2`). The chain carries its own order; use it.
26//!
27//! # `logrotate` and other external rotators
28//!
29//! [`FileBackend::reopen`] closes and reopens the path, which is what an
30//! external rotator needs after moving the file aside. Wire it to `SIGHUP`.
31//! Without it the process keeps writing to the renamed inode and the new file
32//! stays empty.
33//!
34//! [`log_audit`]: crate::AuditBackend::log_audit
35
36use 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/// When to start a new file.
45#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
46pub struct RotationPolicy {
47    /// Rotate once the file reaches this many bytes.
48    pub max_bytes: Option<u64>,
49    /// Rotate once the file has been open this long.
50    pub max_age: Option<Duration>,
51    /// How many rotated files to keep. `None` keeps every one.
52    pub keep: Option<usize>,
53}
54
55impl RotationPolicy {
56    /// Never rotate.
57    #[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    /// Rotate at `bytes`.
67    #[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    /// Rotate at `age`.
77    #[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    /// Keep at most `n` rotated files, deleting the oldest beyond that.
87    #[must_use]
88    pub const fn keeping(mut self, n: usize) -> Self {
89        self.keep = Some(n);
90        self
91    }
92
93    /// Whether a file of `size` bytes opened at `opened_at` should rotate.
94    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
103/// The open file and the state rotation decisions depend on.
104struct OpenFile {
105    writer: BufWriter<File>,
106    bytes: u64,
107    opened_at: SystemTime,
108}
109
110/// Appends audit events to a file as JSON lines.
111///
112/// # Examples
113///
114/// ```rust,no_run
115/// use ash_log::*;
116/// use std::sync::Arc;
117///
118/// let backend = FileBackend::builder("/var/log/audit.jsonl")
119///     .rotation(RotationPolicy::size(64 * 1024 * 1024).keeping(10))
120///     .errors(Arc::new(StderrErrorSink))
121///     .build()
122///     .expect("open the audit log");
123///
124/// let logger = Logger::builder(Arc::new(backend)).build();
125/// logger.info("started");
126/// ```
127pub 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    /// Start building a backend writing to `path`.
137    #[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    /// Open `path` for appending with no rotation and no error reporting.
148    ///
149    /// # Errors
150    ///
151    /// Returns the underlying error if the file cannot be opened or created.
152    pub fn new<P: Into<PathBuf>>(path: P) -> std::io::Result<Self> {
153        Self::builder(path).build()
154    }
155
156    /// The path being written to.
157    #[must_use]
158    pub fn path(&self) -> &Path {
159        &self.path
160    }
161
162    /// Close and reopen the file at its original path.
163    ///
164    /// Call this from a `SIGHUP` handler when an external rotator such as
165    /// `logrotate` moves the file aside. Without it the process keeps writing
166    /// to the renamed inode.
167    ///
168    /// # Errors
169    ///
170    /// Returns the underlying error if the path cannot be reopened. The old
171    /// handle is dropped either way, so a failure leaves the backend unable to
172    /// write rather than writing to the wrong place.
173    pub fn reopen(&self) -> std::io::Result<()> {
174        let mut guard = self.lock();
175        // Flush the outgoing handle first: buffered lines belong to the file
176        // being rotated away, not the new one.
177        drop(guard.writer.flush());
178        *guard = open_at(&self.path)?;
179        Ok(())
180    }
181
182    /// Number of bytes written to the current file.
183    #[must_use]
184    pub fn current_size(&self) -> u64 {
185        self.lock().bytes
186    }
187
188    /// Rotate now, regardless of policy.
189    ///
190    /// # Errors
191    ///
192    /// Returns the underlying error if the rename or reopen fails.
193    pub fn rotate(&self) -> std::io::Result<()> {
194        let mut guard = self.lock();
195        self.rotate_locked(&mut guard)
196    }
197
198    /// Lock the file, recovering from a poisoned mutex.
199    ///
200    /// A panic elsewhere must not stop the audit log: the file handle is still
201    /// valid, and refusing to write because an unrelated thread panicked would
202    /// be the worse failure.
203    fn lock(&self) -> std::sync::MutexGuard<'_, OpenFile> {
204        self.file
205            .lock()
206            .unwrap_or_else(std::sync::PoisonError::into_inner)
207    }
208
209    /// Rename the current file aside and open a fresh one.
210    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    /// A free path to rename the current file to.
224    ///
225    /// Uses a timestamp so rotated names sort chronologically and no rename can
226    /// clobber an earlier archive, with a counter to break ties when two
227    /// rotations land in the same second.
228    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    /// Delete the oldest rotated files beyond `keep`.
248    ///
249    /// Failures are ignored: being unable to delete an old file is not a reason
250    /// to stop recording new events.
251    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        // Names embed a sortable timestamp, so lexicographic order is
277        // chronological and the oldest are at the front.
278        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    /// Write one serialized line, rotating first if the policy calls for it.
286    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        // Flush every line: an audit event still sitting in a userspace buffer
296        // is an event that a crash loses.
297        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    /// Serialize and write, reporting any failure to the error sink.
308    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
331/// Open `path` for appending, creating it if absent.
332fn 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
380/// Builder for [`FileBackend`].
381pub struct FileBackendBuilder {
382    path: PathBuf,
383    rotation: RotationPolicy,
384    sync_on_write: bool,
385    errors: Arc<dyn ErrorSink>,
386}
387
388impl FileBackendBuilder {
389    /// Set when to rotate. Defaults to never.
390    #[must_use]
391    pub const fn rotation(mut self, rotation: RotationPolicy) -> Self {
392        self.rotation = rotation;
393        self
394    }
395
396    /// `fsync` after every event.
397    ///
398    /// Without this an event survives a process crash but not a power loss.
399    /// With it, throughput drops by roughly an order of magnitude.
400    #[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    /// Where to report writes that fail. Defaults to discarding them.
407    #[must_use]
408    pub fn errors(mut self, errors: Arc<dyn ErrorSink>) -> Self {
409        self.errors = errors;
410        self
411    }
412
413    /// Open the file.
414    ///
415    /// # Errors
416    ///
417    /// Returns the underlying error if the path cannot be created or opened for
418    /// appending.
419    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    /// A scratch directory removed when the test ends.
436    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        // Truncating on open would silently destroy the audit record on every
494        // restart, which is the worst possible failure mode here.
495        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        // The property that matters: rotation moves lines between files, it
543        // never drops them.
544        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        // The logrotate case: an external tool renames the file, and `reopen`
608        // is what makes the process write to the new one.
609        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        // A rotation into a directory that has been made read-only fails at the
631        // rename, which is a real OS-reported error rather than a simulated one.
632        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        // The first write rotates (size limit 1), which needs to rename inside
642        // the directory. Make that impossible.
643        #[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); // r-x: no creation or rename
648            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        // Restore permissions so the scratch directory can be cleaned up.
655        #[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        // Documents the Unix behaviour above so it is not mistaken for a bug:
676        // writes to an unlinked handle succeed silently. `reopen` is the fix,
677        // which is exactly why external rotators need SIGHUP wired to it.
678        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        // Interleaved partial writes would corrupt the log irrecoverably, so
703        // every line must arrive whole.
704        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}