apoc 0.5.0

Agentic process control for LLMs
Documentation
//! Fail-closed managed-run log storage.

use std::io::{Read, Seek};
use std::path::Path;

const REDACTION_MARKER: &str = "redaction.required";

pub(crate) fn require_redaction(directory: &Path) -> Result<(), String> {
    std::fs::write(directory.join(REDACTION_MARKER), []).map_err(|error| error.to_string())
}

pub(crate) fn redaction_pending(path: Option<&str>) -> bool {
    path.and_then(|path| Path::new(path).parent())
        .is_some_and(|directory| directory.join(REDACTION_MARKER).exists())
}

pub(crate) fn finalize_redaction(paths: &[&Path], secrets: &[&String]) -> Result<(), String> {
    let marker = paths
        .first()
        .and_then(|path| path.parent())
        .map(|directory| directory.join(REDACTION_MARKER));
    let required = marker.as_ref().is_some_and(|path| path.exists());
    if !required {
        return Ok(());
    }
    if paths.iter().all(|path| !path.exists()) {
        if let Some(marker) = marker {
            std::fs::remove_file(marker).map_err(|error| error.to_string())?;
        }
        return Ok(());
    }

    let result = if secrets.iter().all(|secret| secret.is_empty()) {
        rewrite_or_remove(paths, |_| {
            Err("resolved secrets are unavailable after recovery".to_string())
        })
    } else {
        rewrite_or_remove(paths, |path| redact(path, secrets))
    };
    if (result.is_ok() || paths.iter().all(|path| !path.exists()))
        && let Some(marker) = marker
    {
        std::fs::remove_file(marker).map_err(|error| error.to_string())?;
    }
    result
}

pub(crate) fn read_tail(path: Option<&str>, bytes: usize) -> Result<(String, bool), String> {
    let Some(path) = path else {
        return Ok((String::new(), false));
    };
    let mut file = match std::fs::File::open(path) {
        Ok(file) => file,
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
            return Ok((String::new(), false));
        }
        Err(error) => return Err(error.to_string()),
    };
    let length = file.metadata().map_err(|error| error.to_string())?.len();
    file.seek(std::io::SeekFrom::Start(
        length.saturating_sub(bytes as u64),
    ))
    .map_err(|error| error.to_string())?;
    let mut value = Vec::new();
    file.read_to_end(&mut value)
        .map_err(|error| error.to_string())?;
    Ok((
        String::from_utf8_lossy(&value).into_owned(),
        length > bytes as u64,
    ))
}

/// Returns numbered lines matching a pattern, with bounded surrounding context.
///
/// Matching runs where the log lives so an oversized file is never shipped whole to a caller
/// that only wants a handful of lines.
pub(crate) fn read_matches(
    path: Option<&str>,
    stream: &str,
    pattern: &regex::Regex,
    context: usize,
    max_matches: usize,
) -> Result<(Vec<crate::run::LogLine>, usize, usize), String> {
    let (text, total) = read_all(path)?;
    let lines = text.lines().collect::<Vec<_>>();
    let mut selected = std::collections::BTreeSet::new();
    let mut matches = 0;
    for (index, line) in lines.iter().enumerate() {
        if !pattern.is_match(line) {
            continue;
        }
        matches += 1;
        if matches > max_matches {
            continue;
        }
        let start = index.saturating_sub(context);
        let end = (index + context).min(lines.len().saturating_sub(1));
        for number in start..=end {
            selected.insert(number);
        }
    }
    Ok((
        selected
            .into_iter()
            .map(|index| crate::run::LogLine {
                number: index + 1,
                stream: stream.to_string(),
                text: lines[index].to_string(),
            })
            .collect(),
        matches,
        total,
    ))
}

/// Returns one inclusive, one-based line range.
pub(crate) fn read_lines(
    path: Option<&str>,
    stream: &str,
    start: usize,
    end: usize,
) -> Result<(Vec<crate::run::LogLine>, usize), String> {
    let (text, total) = read_all(path)?;
    let lines = text
        .lines()
        .enumerate()
        .filter(|(index, _)| {
            let number = index + 1;
            number >= start && number <= end
        })
        .map(|(index, line)| crate::run::LogLine {
            number: index + 1,
            stream: stream.to_string(),
            text: line.to_string(),
        })
        .collect();
    Ok((lines, total))
}

/// Returns the whole log and its line count, or empty when it does not exist.
fn read_all(path: Option<&str>) -> Result<(String, usize), String> {
    let Some(path) = path else {
        return Ok((String::new(), 0));
    };
    let bytes = match std::fs::read(path) {
        Ok(bytes) => bytes,
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
            return Ok((String::new(), 0));
        }
        Err(error) => return Err(error.to_string()),
    };
    let text = String::from_utf8_lossy(&bytes).into_owned();
    let total = text.lines().count();
    Ok((text, total))
}

fn redact(path: &Path, secrets: &[&String]) -> Result<(), String> {
    let bytes = match std::fs::read(path) {
        Ok(bytes) => bytes,
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(()),
        Err(error) => return Err(error.to_string()),
    };
    let mut output = String::from_utf8_lossy(&bytes).into_owned();
    for secret in secrets {
        if !secret.is_empty() {
            output = output.replace(secret.as_str(), "[REDACTED]");
        }
    }
    std::fs::write(path, output).map_err(|error| error.to_string())
}

fn rewrite_or_remove(
    paths: &[&Path],
    mut rewrite: impl FnMut(&Path) -> Result<(), String>,
) -> Result<(), String> {
    let errors = paths
        .iter()
        .filter_map(|path| {
            rewrite(path)
                .err()
                .map(|error| format!("{}: {error}", path.display()))
        })
        .collect::<Vec<_>>();
    if errors.is_empty() {
        return Ok(());
    }

    let cleanup_errors = paths
        .iter()
        .filter_map(|path| match std::fs::remove_file(path) {
            Ok(()) => None,
            Err(error) if error.kind() == std::io::ErrorKind::NotFound => None,
            Err(error) => Some(format!("{}: {error}", path.display())),
        })
        .collect::<Vec<_>>();
    if cleanup_errors.is_empty() {
        Err(errors.join("; "))
    } else {
        Err(format!(
            "{}; cleanup failed: {}",
            errors.join("; "),
            cleanup_errors.join("; ")
        ))
    }
}

#[cfg(test)]
mod tests {
    use tempfile::tempdir;

    use super::*;

    #[test]
    fn sanitizes_every_log() {
        let directory = tempdir().unwrap();
        let stdout = directory.path().join("stdout.log");
        let stderr = directory.path().join("stderr.log");
        let secret = "synthetic-secret".to_string();
        std::fs::write(&stdout, format!("before {secret} after")).unwrap();
        std::fs::write(&stderr, format!("{secret} twice {secret}")).unwrap();

        require_redaction(directory.path()).unwrap();
        finalize_redaction(&[&stdout, &stderr], &[&secret]).unwrap();

        assert_eq!(
            std::fs::read_to_string(stdout).unwrap(),
            "before [REDACTED] after"
        );
        assert_eq!(
            std::fs::read_to_string(stderr).unwrap(),
            "[REDACTED] twice [REDACTED]"
        );
        assert!(!directory.path().join(REDACTION_MARKER).exists());
    }

    #[test]
    fn missing_logs_complete_redaction() {
        let directory = tempdir().unwrap();
        let stdout = directory.path().join("stdout.log");
        let stderr = directory.path().join("stderr.log");
        require_redaction(directory.path()).unwrap();

        finalize_redaction(&[&stdout, &stderr], &[]).unwrap();

        assert!(!directory.path().join(REDACTION_MARKER).exists());
    }

    #[test]
    fn rewrite_failure_removes_every_log() {
        let directory = tempdir().unwrap();
        let stdout = directory.path().join("stdout.log");
        let stderr = directory.path().join("stderr.log");
        std::fs::write(&stdout, "secret").unwrap();
        std::fs::write(&stderr, "secret").unwrap();

        let error = rewrite_or_remove(&[&stdout, &stderr], |_| Err("synthetic failure".into()))
            .unwrap_err();

        assert!(error.contains("synthetic failure"));
        assert!(!stdout.exists());
        assert!(!stderr.exists());
    }

    #[test]
    fn recovery_without_secret_values_removes_every_log() {
        let directory = tempdir().unwrap();
        let stdout = directory.path().join("stdout.log");
        let stderr = directory.path().join("stderr.log");
        std::fs::write(&stdout, "secret").unwrap();
        std::fs::write(&stderr, "secret").unwrap();
        require_redaction(directory.path()).unwrap();

        let error = finalize_redaction(&[&stdout, &stderr], &[]).unwrap_err();

        assert!(error.contains("unavailable after recovery"));
        assert!(!stdout.exists());
        assert!(!stderr.exists());
        assert!(!directory.path().join(REDACTION_MARKER).exists());
    }
}