second-brain-api 0.13.3

HTTP API server for second-brain: REST endpoints for recall, remember, and ingest
Documentation
use std::ffi::OsString;
use std::path::{Path, PathBuf};

use tracing_appender::rolling::{RollingFileAppender, Rotation};
use tracing_subscriber::EnvFilter;
use tracing_subscriber::fmt::writer::BoxMakeWriter;

pub const LOG_DIR_ENV: &str = "SECOND_BRAIN_LOG_DIR";
pub const FILE_PREFIX: &str = "second-brain";
pub const KEPT_FILES: usize = 7;
const DEFAULT_DIRECTIVES: &str = "error,second_brain=info,tower_http=debug";

/// A non-blank `RUST_LOG` replaces the defaults instead of extending them,
/// because a bare level in it would only replace the `error` catch-all and
/// leave `tower_http=debug` in force.
pub fn filter(rust_log: Option<&str>) -> EnvFilter {
    let directives = rust_log
        .filter(|v| !v.trim().is_empty())
        .unwrap_or(DEFAULT_DIRECTIVES);
    EnvFilter::builder().parse_lossy(directives)
}

pub fn log_dir(value: Option<OsString>) -> Option<PathBuf> {
    value.filter(|v| !v.is_empty()).map(PathBuf::from)
}

pub fn file_writer(dir: &Path) -> anyhow::Result<RollingFileAppender> {
    Ok(RollingFileAppender::builder()
        .rotation(Rotation::DAILY)
        .filename_prefix(FILE_PREFIX)
        .filename_suffix("log")
        .max_log_files(KEPT_FILES)
        .build(dir)?)
}

/// Logs to a daily file under `SECOND_BRAIN_LOG_DIR` when it is set, because
/// launchd never rotates the stdout and stderr files it was given; otherwise
/// to stderr.
pub fn init() {
    let filter = filter(std::env::var("RUST_LOG").ok().as_deref());
    let file = log_dir(std::env::var_os(LOG_DIR_ENV)).and_then(|dir| {
        file_writer(&dir)
            .inspect_err(|e| eprintln!("cannot log to {}: {e:#}; logging to stderr", dir.display()))
            .ok()
    });
    let builder = tracing_subscriber::fmt().with_env_filter(filter);
    match file {
        Some(appender) => builder
            .with_ansi(false)
            .with_writer(BoxMakeWriter::new(appender))
            .init(),
        None => builder.with_writer(std::io::stderr).init(),
    }
}

#[cfg(test)]
mod tests {
    use std::io::Write;
    use std::sync::{Arc, Mutex};

    use tracing_subscriber::fmt::MakeWriter;

    use super::*;

    #[derive(Clone, Default)]
    struct Captured(Arc<Mutex<Vec<u8>>>);

    impl Write for Captured {
        fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
            self.0.lock().unwrap().extend_from_slice(buf);
            Ok(buf.len())
        }
        fn flush(&mut self) -> std::io::Result<()> {
            Ok(())
        }
    }

    impl<'a> MakeWriter<'a> for Captured {
        type Writer = Captured;
        fn make_writer(&'a self) -> Self::Writer {
            self.clone()
        }
    }

    fn emit_all() {
        tracing::debug!(target: "tower_http::trace::on_request", "tower-debug");
        tracing::warn!(target: "tower_http::trace::on_failure", "tower-warn");
        tracing::info!(target: "second_brain_api::ingest", "brain-info");
        tracing::debug!(target: "second_brain_api::ingest", "brain-debug");
        tracing::info!(target: "hyper::proto", "hyper-info");
        tracing::error!(target: "hyper::proto", "hyper-error");
    }

    fn logged(rust_log: Option<&str>) -> String {
        let out = Captured::default();
        let subscriber = tracing_subscriber::fmt()
            .with_env_filter(filter(rust_log))
            .without_time()
            .with_writer(out.clone())
            .finish();
        tracing::subscriber::with_default(subscriber, emit_all);
        String::from_utf8(out.0.lock().unwrap().clone()).unwrap()
    }

    #[test]
    fn defaults_log_requests_at_debug_and_other_crates_only_on_error() {
        let out = logged(None);
        for line in ["tower-debug", "tower-warn", "brain-info", "hyper-error"] {
            assert!(out.contains(line), "{line} missing from:\n{out}");
        }
        for line in ["brain-debug", "hyper-info"] {
            assert!(!out.contains(line), "{line} leaked into:\n{out}");
        }
    }

    #[test]
    fn rust_log_overrides_the_tower_http_default() {
        let out = logged(Some("info,tower_http=warn"));
        for line in ["tower-warn", "brain-info", "hyper-info", "hyper-error"] {
            assert!(out.contains(line), "{line} missing from:\n{out}");
        }
        for line in ["tower-debug", "brain-debug"] {
            assert!(!out.contains(line), "{line} leaked into:\n{out}");
        }
    }

    #[test]
    fn bare_rust_log_level_replaces_every_default() {
        let out = logged(Some("warn"));
        for line in ["tower-warn", "hyper-error"] {
            assert!(out.contains(line), "{line} missing from:\n{out}");
        }
        for line in ["tower-debug", "brain-info", "hyper-info"] {
            assert!(!out.contains(line), "{line} leaked into:\n{out}");
        }
    }

    #[test]
    fn blank_rust_log_keeps_the_defaults() {
        assert_eq!(logged(Some("  ")), logged(None));
    }

    fn log_files(dir: &Path) -> Vec<String> {
        let mut names: Vec<String> = std::fs::read_dir(dir)
            .unwrap()
            .map(|e| e.unwrap().file_name().into_string().unwrap())
            .filter(|n| n.starts_with(FILE_PREFIX))
            .collect();
        names.sort();
        names
    }

    #[test]
    fn log_dir_gets_a_daily_file_and_keeps_seven() {
        let dir = tempfile::tempdir().unwrap();
        for day in 1..=10 {
            std::fs::write(
                dir.path()
                    .join(format!("{FILE_PREFIX}.2020-01-{day:02}.log")),
                "old\n",
            )
            .unwrap();
        }
        std::fs::write(dir.path().join("launchd.log"), "panic\n").unwrap();

        let subscriber = tracing_subscriber::fmt()
            .with_env_filter(filter(None))
            .with_ansi(false)
            .with_writer(file_writer(dir.path()).unwrap())
            .finish();
        tracing::subscriber::with_default(subscriber, emit_all);

        let files = log_files(dir.path());
        assert_eq!(files.len(), KEPT_FILES, "{files:?}");
        let today = chrono::Utc::now().format("%Y-%m-%d");
        let current =
            std::fs::read_to_string(dir.path().join(format!("{FILE_PREFIX}.{today}.log"))).unwrap();
        assert!(current.contains("brain-info"), "{current}");
        assert!(dir.path().join("launchd.log").exists());
    }

    #[test]
    fn log_dir_is_unset_when_the_variable_is_missing_or_empty() {
        assert_eq!(log_dir(None), None);
        assert_eq!(log_dir(Some(OsString::new())), None);
        assert_eq!(
            log_dir(Some(OsString::from("/var/log/sb"))),
            Some(PathBuf::from("/var/log/sb"))
        );
    }
}