json_archive/

atomic_file.rs

// json-archive is a tool for tracking JSON file changes over time
// Copyright (C) 2025  Peoples Grocers LLC
//
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU Affero General Public License as published
// by the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU Affero General Public License for more details.
//
// You should have received a copy of the GNU Affero General Public License
// along with this program.  If not, see <https://www.gnu.org/licenses/>.
//
// To purchase a license under different terms contact admin@peoplesgrocers.com
// To request changes, report bugs, or give user feedback contact
// marxism@peoplesgrocers.com
//

//! Problem: how do you append data to a compressed archive without losing data?
//!
//! Gzip and similar formats don't support in-place append. To add one record
//! to a 20GB archive, you decompress it all, add the record, and recompress.
//!
//! You have two options:
//!
//! Option A: Overwrite in place. Seek to byte 0 of the existing file and start
//! writing the new compressed stream. No extra disk space needed. But if you
//! fail mid-write (out of space, crash, power loss), you've corrupted the
//! original and lost everything. With a 20GB file, that's a lot of time spent
//! in the danger zone.
//!
//! Option B: Write to a new file, then swap. Requires 2x disk space temporarily,
//! but the original stays intact until the new file is complete. If writing
//! fails, you just delete the partial temp file.
//!
//! This module implements option B. I'm not comfortable with option A.
//!
//! The swap sequence:
//! 1. Write new archive to `.archive.json.gz.a7bX2q`
//! 2. Rename original to `.archive.json.gz.a7bX2q.old` (backup)
//! 3. Rename temp to `archive.json.gz` (atomic on same filesystem)
//! 4. Delete backup
//!
//! If writing fails, original is untouched. If the swap fails, we restore
//! from backup. Data loss requires a kernel crash between steps 2 and 3.
//!
//! Assumes everything is on one filesystem. Cross-filesystem renames aren't
//! atomic and we don't handle them.

use std::path::{Path, PathBuf};
use uuid::Uuid;

use crate::diagnostics::{Diagnostic, DiagnosticCode, DiagnosticLevel};

/// Generate a rsync-style temporary filename with dot prefix and random suffix
///
/// For example: "archive.json.gz" -> ".archive.json.gz.a7bX2q"
///
/// The naming convention follows rsync's pattern:
/// - Prefix with `.` to hide the file on Unix systems
/// - Append a 6-character random suffix for uniqueness
pub fn generate_temp_filename<P: AsRef<Path>>(path: P) -> PathBuf {
    let path = path.as_ref();

    // Generate 6-character random suffix using first 6 hex chars of a uuid
    let uuid = Uuid::new_v4();
    let hex = format!("{:x}", uuid.as_u128());
    let random_suffix = &hex[..6];

    // Get the filename
    if let Some(filename) = path.file_name() {
        if let Some(filename_str) = filename.to_str() {
            // Create new filename: .{original}.{random}
            let temp_filename = format!(".{}.{}", filename_str, random_suffix);

            // Return path with new filename
            if let Some(parent) = path.parent() {
                return parent.join(temp_filename);
            } else {
                return PathBuf::from(temp_filename);
            }
        }
    }

    // Fallback: just add prefix and suffix to entire path
    let mut temp_path = path.to_path_buf();
    temp_path.set_file_name(format!(".{}.{}", path.display(), random_suffix));
    temp_path
}

/// Atomically replace a file using rsync-style temp files
///
/// This performs the following sequence:
/// 1. Write new content to temp_path (caller's responsibility - already done)
/// 2. Move original_path -> .original_path.{random}.old (backup)
/// 3. Move temp_path -> original_path (replace)
/// 4. Delete .original_path.{random}.old (cleanup)
///
/// If any step fails, attempts to recover by restoring the backup.
///
/// # Arguments
///
/// * `original_path` - The file to be replaced
/// * `temp_path` - The temporary file containing the new content
///
/// # Errors
///
/// Returns diagnostics if any step of the operation fails. The function
/// attempts automatic recovery by restoring the backup if the replacement fails.
pub fn atomic_replace_file<P: AsRef<Path>>(original_path: P, temp_path: P) -> Result<(), Vec<Diagnostic>> {
    let original = original_path.as_ref();
    let temp = temp_path.as_ref();

    // Generate backup filename with same random suffix as temp file
    let backup_path = if let Some(filename) = original.file_name() {
        if let Some(filename_str) = filename.to_str() {
            // Extract random suffix from temp filename if it follows our pattern
            let temp_filename = temp.file_name().and_then(|f| f.to_str()).unwrap_or("");
            let random_suffix = if temp_filename.starts_with('.') && temp_filename.contains(filename_str) {
                // Extract suffix after the original filename
                temp_filename.rsplit('.').next().unwrap_or("backup")
            } else {
                "backup"
            };

            let backup_filename = format!(".{}.{}.old", filename_str, random_suffix);
            if let Some(parent) = original.parent() {
                parent.join(backup_filename)
            } else {
                PathBuf::from(backup_filename)
            }
        } else {
            original.with_extension("old")
        }
    } else {
        original.with_extension("old")
    };

    // Step 1: Move original to backup
    if let Err(e) = std::fs::rename(original, &backup_path) {
        return Err(vec![Diagnostic::new(
            DiagnosticLevel::Fatal,
            DiagnosticCode::PathNotFound,
            format!("I couldn't create backup of the original archive: {}", e),
        )
        .with_advice(
            "Make sure you have write permission in this directory and sufficient disk space."
                .to_string()
        )]);
    }

    // Step 2: Move temp to original
    if let Err(e) = std::fs::rename(temp, original) {
        // Recovery: Try to restore backup
        let recovery_error = if std::fs::rename(&backup_path, original).is_ok() {
            format!(
                "I couldn't move the new archive into place: {}\nI've restored the original archive from backup.",
                e
            )
        } else {
            format!(
                "I couldn't move the new archive into place: {}\nWARNING: I also failed to restore the backup. Your original is at: {}",
                e,
                backup_path.display()
            )
        };

        return Err(vec![Diagnostic::new(
            DiagnosticLevel::Fatal,
            DiagnosticCode::PathNotFound,
            recovery_error,
        )
        .with_advice(
            "Check filesystem permissions and disk space. If the backup exists, you can manually restore it."
                .to_string()
        )]);
    }

    // Step 3: Delete backup
    // This is non-critical - if it fails, we just leave the backup around
    let _ = std::fs::remove_file(&backup_path);

    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::fs::File;
    use std::io::Write;
    use tempfile::NamedTempFile;

    #[test]
    fn test_generate_temp_filename() {
        let temp = generate_temp_filename("archive.json.gz");
        let filename = temp.file_name().unwrap().to_str().unwrap();

        // Should start with dot
        assert!(filename.starts_with('.'));

        // Should contain original filename
        assert!(filename.contains("archive.json.gz"));

        // Should have a random suffix (dot followed by 6 chars)
        assert!(filename.matches('.').count() >= 3); // .archive.json.gz has 2, plus 1 before random
    }

    #[test]
    fn test_atomic_replace_file() -> Result<(), Box<dyn std::error::Error>> {
        // Create original file
        let mut original = NamedTempFile::new()?;
        writeln!(original, "original content")?;
        original.flush()?;
        let original_path = original.path().to_path_buf();

        // Create temp file with new content
        let temp_path = generate_temp_filename(&original_path);
        {
            let mut temp_file = File::create(&temp_path)?;
            writeln!(temp_file, "new content")?;
        }

        // Perform atomic replace
        atomic_replace_file(&original_path, &temp_path)
            .map_err(|e| format!("Failed to replace file: {:?}", e))?;

        // Verify new content
        let content = std::fs::read_to_string(&original_path)?;
        assert_eq!(content.trim(), "new content");

        // Verify temp file is gone
        assert!(!temp_path.exists());

        // Verify backup is cleaned up
        let backup_pattern = format!(".{}.", original_path.file_name().unwrap().to_str().unwrap());
        let parent = original_path.parent().unwrap();
        let backups: Vec<_> = std::fs::read_dir(parent)?
            .filter_map(|e| e.ok())
            .filter(|e| {
                e.file_name()
                    .to_str()
                    .map(|s| s.contains(&backup_pattern) && s.ends_with(".old"))
                    .unwrap_or(false)
            })
            .collect();
        assert_eq!(backups.len(), 0, "Backup file should be cleaned up");

        Ok(())
    }
}