Skip to main content

rs_zero/core/logging/
writer.rs

1use std::{
2    fs::{self, File, OpenOptions},
3    io::{self, Write},
4    path::{Path, PathBuf},
5    sync::{
6        Arc, Mutex,
7        mpsc::{self, Receiver, Sender},
8    },
9    thread::{self, JoinHandle},
10};
11
12use chrono::{Local, NaiveDate};
13use serde::Deserialize;
14
15use crate::core::logging::rotation::{cleanup_rotated_files, compress_file, rotate_files};
16use crate::core::{CoreError, CoreResult};
17
18/// Log writer destination.
19#[derive(Debug, Clone, PartialEq, Eq)]
20pub enum LogWriterConfig {
21    /// Standard output.
22    Stdout,
23    /// Standard error.
24    Stderr,
25    /// Append to one file.
26    File(PathBuf),
27    /// Append to one file and rotate while the process is running.
28    RollingFile(RollingFileConfig),
29}
30
31/// Rolling policy for file-backed logs.
32#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Default)]
33#[serde(rename_all = "snake_case")]
34pub enum RotationPolicy {
35    /// Rotate when local date changes.
36    #[default]
37    Daily,
38    /// Rotate when configured size boundary is exceeded.
39    Size,
40}
41
42/// Rolling file configuration.
43#[derive(Debug, Clone, PartialEq, Eq)]
44pub struct RollingFileConfig {
45    /// Active log file path.
46    pub path: PathBuf,
47    /// Rotation policy.
48    pub rotation: RotationPolicy,
49    /// Maximum bytes before the active file is rotated at runtime. Used by size rotation.
50    pub max_bytes: Option<u64>,
51    /// Number of rotated files to retain. `0` disables count-based cleanup.
52    pub max_files: usize,
53    /// Number of days to retain rotated files. `None` disables age-based cleanup.
54    pub keep_days: Option<u64>,
55    /// Compress rotated files as gzip.
56    pub compress: bool,
57}
58
59impl RollingFileConfig {
60    /// Creates a runtime rolling file config with a size boundary.
61    pub fn by_size(path: impl Into<PathBuf>, max_bytes: u64, max_files: usize) -> Self {
62        Self {
63            path: path.into(),
64            rotation: RotationPolicy::Size,
65            max_bytes: Some(max_bytes),
66            max_files,
67            keep_days: None,
68            compress: false,
69        }
70    }
71
72    /// Creates a runtime rolling file config with a daily boundary.
73    pub fn daily(path: impl Into<PathBuf>, max_files: usize) -> Self {
74        Self {
75            path: path.into(),
76            rotation: RotationPolicy::Daily,
77            max_bytes: None,
78            max_files,
79            keep_days: None,
80            compress: false,
81        }
82    }
83}
84
85/// Prepared writer information.
86#[derive(Debug, Clone, PartialEq, Eq)]
87pub struct PreparedLogWriter {
88    /// File path for file-backed writers.
89    pub path: Option<PathBuf>,
90    /// Whether rotation is configured.
91    pub rotation_enabled: bool,
92}
93
94impl LogWriterConfig {
95    /// Creates a file writer.
96    pub fn file(path: impl Into<PathBuf>) -> Self {
97        Self::File(path.into())
98    }
99}
100
101/// Validates the writer and prepares file paths when necessary.
102pub fn validate_writer(config: &LogWriterConfig) -> CoreResult<PreparedLogWriter> {
103    match config {
104        LogWriterConfig::Stdout | LogWriterConfig::Stderr => Ok(PreparedLogWriter {
105            path: None,
106            rotation_enabled: false,
107        }),
108        LogWriterConfig::File(path) => {
109            open_append_file(path)?;
110            Ok(PreparedLogWriter {
111                path: Some(path.clone()),
112                rotation_enabled: false,
113            })
114        }
115        LogWriterConfig::RollingFile(rolling) => {
116            open_append_file(&rolling.path)?;
117            Ok(PreparedLogWriter {
118                path: Some(rolling.path.clone()),
119                rotation_enabled: true,
120            })
121        }
122    }
123}
124
125/// Shared writer that rotates the active file while the process is running.
126#[derive(Clone)]
127pub struct RuntimeRollingFileWriter {
128    inner: Arc<Mutex<RuntimeRollingFileState>>,
129    compression_worker: Option<CompressionWorker>,
130}
131
132impl RuntimeRollingFileWriter {
133    /// Opens a rolling writer from config.
134    pub fn new(config: RollingFileConfig) -> CoreResult<Self> {
135        if let Some(parent) = config.path.parent() {
136            fs::create_dir_all(parent).map_err(|error| CoreError::Logging(error.to_string()))?;
137        }
138        cleanup_rotated_files(&config).map_err(|error| CoreError::Logging(error.to_string()))?;
139        let file = open_append_file(&config.path)?;
140        let bytes_written = file
141            .metadata()
142            .map_err(|error| CoreError::Logging(error.to_string()))?
143            .len();
144        let compression_worker = config.compress.then(CompressionWorker::spawn);
145        Ok(Self {
146            inner: Arc::new(Mutex::new(RuntimeRollingFileState {
147                current_day: current_day(),
148                config,
149                file,
150                bytes_written,
151                compression_sender: compression_worker.as_ref().map(CompressionWorker::sender),
152            })),
153            compression_worker,
154        })
155    }
156}
157
158impl Drop for RuntimeRollingFileWriter {
159    fn drop(&mut self) {
160        if Arc::strong_count(&self.inner) == 1 {
161            if let Ok(mut state) = self.inner.lock() {
162                state.compression_sender = None;
163            }
164            self.compression_worker.take();
165        }
166    }
167}
168
169impl Write for RuntimeRollingFileWriter {
170    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
171        let mut state = self
172            .inner
173            .lock()
174            .map_err(|_| io::Error::other("rolling log writer mutex poisoned"))?;
175        state.write(buf)
176    }
177
178    fn flush(&mut self) -> io::Result<()> {
179        let mut state = self
180            .inner
181            .lock()
182            .map_err(|_| io::Error::other("rolling log writer mutex poisoned"))?;
183        state.file.flush()
184    }
185}
186
187pub(crate) fn open_append_file(path: &Path) -> CoreResult<File> {
188    if let Some(parent) = path.parent() {
189        fs::create_dir_all(parent).map_err(|error| CoreError::Logging(error.to_string()))?;
190    }
191    OpenOptions::new()
192        .create(true)
193        .append(true)
194        .open(path)
195        .map_err(|error| CoreError::Logging(error.to_string()))
196}
197
198struct RuntimeRollingFileState {
199    config: RollingFileConfig,
200    file: File,
201    bytes_written: u64,
202    current_day: NaiveDate,
203    compression_sender: Option<Sender<PathBuf>>,
204}
205
206impl RuntimeRollingFileState {
207    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
208        self.rotate_if_needed(buf.len() as u64)?;
209        self.file.write_all(buf)?;
210        self.bytes_written = self.bytes_written.saturating_add(buf.len() as u64);
211        Ok(buf.len())
212    }
213
214    fn rotate_if_needed(&mut self, incoming_bytes: u64) -> io::Result<()> {
215        match self.config.rotation {
216            RotationPolicy::Size => self.rotate_by_size_if_needed(incoming_bytes),
217            RotationPolicy::Daily => self.rotate_by_day_if_needed(),
218        }
219    }
220
221    fn rotate_by_size_if_needed(&mut self, incoming_bytes: u64) -> io::Result<()> {
222        let Some(max_bytes) = self.config.max_bytes else {
223            return Ok(());
224        };
225        if max_bytes == 0 || self.bytes_written.saturating_add(incoming_bytes) <= max_bytes {
226            return Ok(());
227        }
228        self.rotate_active_file()
229    }
230
231    fn rotate_by_day_if_needed(&mut self) -> io::Result<()> {
232        let today = current_day();
233        if today <= self.current_day {
234            return Ok(());
235        }
236        self.current_day = today;
237        self.rotate_active_file()
238    }
239
240    fn rotate_active_file(&mut self) -> io::Result<()> {
241        self.file.flush()?;
242        let rotated = rotate_files(&self.config)?;
243        self.file = OpenOptions::new()
244            .create(true)
245            .append(true)
246            .open(&self.config.path)?;
247        self.bytes_written = 0;
248        if let Some(rotated) = rotated {
249            self.compress_rotated_file(rotated);
250        }
251        cleanup_rotated_files(&self.config)
252    }
253
254    fn compress_rotated_file(&mut self, rotated: PathBuf) {
255        let Some(sender) = &self.compression_sender else {
256            return;
257        };
258        if sender.send(rotated).is_err() {
259            self.compression_sender = None;
260        }
261    }
262}
263
264struct CompressionWorker {
265    inner: Arc<CompressionWorkerInner>,
266}
267
268struct CompressionWorkerInner {
269    sender: Mutex<Option<Sender<PathBuf>>>,
270    handle: Mutex<Option<JoinHandle<()>>>,
271}
272
273impl CompressionWorker {
274    fn spawn() -> Self {
275        let (sender, receiver) = mpsc::channel();
276        let handle = thread::Builder::new()
277            .name("rs-zero-log-compressor".to_string())
278            .spawn(move || compress_paths(receiver))
279            .expect("spawn log compression worker");
280        Self {
281            inner: Arc::new(CompressionWorkerInner {
282                sender: Mutex::new(Some(sender)),
283                handle: Mutex::new(Some(handle)),
284            }),
285        }
286    }
287
288    fn sender(&self) -> Sender<PathBuf> {
289        self.inner
290            .sender
291            .lock()
292            .expect("compression worker sender mutex")
293            .as_ref()
294            .expect("compression worker sender open")
295            .clone()
296    }
297}
298
299impl Clone for CompressionWorker {
300    fn clone(&self) -> Self {
301        Self {
302            inner: Arc::clone(&self.inner),
303        }
304    }
305}
306
307impl Drop for CompressionWorkerInner {
308    fn drop(&mut self) {
309        self.sender
310            .lock()
311            .expect("compression worker sender mutex")
312            .take();
313        let handle = self
314            .handle
315            .lock()
316            .expect("compression worker handle mutex")
317            .take();
318        if let Some(handle) = handle {
319            let _ = handle.join();
320        }
321    }
322}
323
324fn compress_paths(receiver: Receiver<PathBuf>) {
325    for path in receiver {
326        let _ = compress_file(&path);
327    }
328}
329
330fn current_day() -> NaiveDate {
331    #[cfg(test)]
332    {
333        Local::now().date_naive()
334            + chrono::Duration::days(crate::core::logging::test_hooks::current_day_offset() as i64)
335    }
336    #[cfg(not(test))]
337    {
338        Local::now().date_naive()
339    }
340}
341
342#[cfg(test)]
343mod tests {
344    use std::{
345        fs,
346        io::Write,
347        thread,
348        time::{Duration, Instant},
349    };
350
351    use super::{RollingFileConfig, RotationPolicy, RuntimeRollingFileWriter};
352    use crate::core::logging::test_hooks;
353
354    #[test]
355    fn compresses_rotated_files_asynchronously() {
356        let temp = tempfile::tempdir().expect("tempdir");
357        let path = temp.path().join("service.log");
358        let pause = test_hooks::pause_compression_for_dir(temp.path());
359        let mut writer = RuntimeRollingFileWriter::new(RollingFileConfig {
360            path: path.clone(),
361            rotation: RotationPolicy::Size,
362            max_bytes: Some(64),
363            max_files: 2,
364            keep_days: None,
365            compress: true,
366        })
367        .expect("writer");
368
369        writer
370            .write_all(
371                b"first rotated payload with enough bytes to cross the configured size limit\n",
372            )
373            .expect("first write");
374        writer
375            .write_all(b"second payload reopens the active file before gzip can finish\n")
376            .expect("second write");
377
378        assert!(
379            path.exists(),
380            "active log file should be reopened before compression finishes"
381        );
382        assert!(
383            has_uncompressed_rotated_file(temp.path()),
384            "rotated file should remain uncompressed while compression is paused"
385        );
386        assert!(
387            !has_gzip_rotated_file(temp.path()),
388            "compression should not run synchronously on the logging path"
389        );
390
391        pause.resume();
392        drop(writer);
393        wait_until(Duration::from_secs(2), || {
394            has_gzip_rotated_file(temp.path())
395        });
396    }
397
398    #[test]
399    fn rotates_daily_when_day_advances() {
400        let temp = tempfile::tempdir().expect("tempdir");
401        let path = temp.path().join("service.log");
402        let clock = test_hooks::set_current_day_offset(-1);
403        let mut writer = RuntimeRollingFileWriter::new(RollingFileConfig {
404            path: path.clone(),
405            rotation: RotationPolicy::Daily,
406            max_bytes: None,
407            max_files: 2,
408            keep_days: None,
409            compress: false,
410        })
411        .expect("writer");
412
413        writer.write_all(b"before-day-advance\n").expect("before");
414        clock.set_offset_days(0);
415        writer.write_all(b"after-day-advance\n").expect("after");
416        drop(writer);
417
418        let active = fs::read_to_string(&path).expect("active log");
419        assert!(active.contains("after-day-advance"));
420        assert!(!active.contains("before-day-advance"));
421        let rotated = fs::read_dir(temp.path())
422            .expect("log dir")
423            .filter_map(|entry| entry.ok().map(|entry| entry.path()))
424            .find(|candidate| {
425                candidate
426                    .file_name()
427                    .and_then(|name| name.to_str())
428                    .is_some_and(|name| name.starts_with("service.log.20"))
429            })
430            .expect("dated rotated log");
431        let rotated_output = fs::read_to_string(rotated).expect("rotated log");
432        assert!(rotated_output.contains("before-day-advance"));
433    }
434
435    fn wait_until(timeout: Duration, condition: impl Fn() -> bool) {
436        let start = Instant::now();
437        while start.elapsed() < timeout {
438            if condition() {
439                return;
440            }
441            thread::sleep(Duration::from_millis(10));
442        }
443        assert!(condition(), "condition was not met before timeout");
444    }
445
446    fn has_gzip_rotated_file(dir: &std::path::Path) -> bool {
447        fs::read_dir(dir)
448            .expect("log dir")
449            .filter_map(|entry| entry.ok().map(|entry| entry.path()))
450            .any(|path| {
451                path.file_name()
452                    .and_then(|name| name.to_str())
453                    .is_some_and(|name| name.starts_with("service.log.") && name.ends_with(".gz"))
454            })
455    }
456
457    fn has_uncompressed_rotated_file(dir: &std::path::Path) -> bool {
458        fs::read_dir(dir)
459            .expect("log dir")
460            .filter_map(|entry| entry.ok().map(|entry| entry.path()))
461            .any(|path| {
462                path.file_name()
463                    .and_then(|name| name.to_str())
464                    .is_some_and(|name| name.starts_with("service.log.") && !name.ends_with(".gz"))
465            })
466    }
467}